Merge remote-tracking branch 'origin/master' into feat/send-unify

# Conflicts:
#	docs/persistence-catalog.md
#	examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl
#	packages/context/time-context/tests/time-context.spec.ts
#	packages/cordis/tool-cordis/src/api-catalog.ts

packages/client/runtime/tests/fake-api.ts

@@ -2,7 +2,7 @@
 // data source on a real clock; behavior tests need per-case responses and
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type {
-  HostFrame, IApiClient, MuxFrame, RpcError, RpcRequest, RpcResponse, SessionId,
+  ClientResponse, HostFrame, IApiClient, MuxFrame, RpcError, RpcReceipt, RpcRequest, RpcResponse, SessionId,
 } from '@deepseek-ai/dsh-client-connection/client'
 import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
 
@@ -93,8 +93,10 @@ export class FakeApiClient implements IApiClient {
     host: (_payload: unknown, signal: AbortSignal, onOpen?: () => void) => this.openStream(this.hostConns, signal, onOpen),
   }
 
-  respond(): Promise<{ accepted: false; reason: 'not-pending' }> {
-    return Promise.resolve({ accepted: false, reason: 'not-pending' })
+  onRespond: (message: ClientResponse) => Promise<RpcReceipt> = () => Promise.resolve({ accepted: true })
+
+  respond(message: ClientResponse): Promise<RpcReceipt> {
+    return this.record('respond', message, this.onRespond(message))
   }
 
   /** Push one mux frame to every open mux stream (rpcId minted unless pinned by the case). */

packages/client/runtime/tests/manager.spec.ts

@@ -34,7 +34,7 @@ describe('instances', () => {
     manager.handleMuxEnvelope({ rpcId: 'ra' as never, payload: { type: 'approval/requested', sessionId: S1, approvalId: 'ap1' as never, toolName: 'rm' } })
     manager.handleMuxEnvelope({ rpcId: 're' as never, payload: { type: 'session/event', sessionId: S1, event: plainTurn(0, 0, 'x', 'y')[0] as never } })
     const session = manager.get(S1)
-    expect(session.getSnapshot().pending).toMatchObject([{ kind: 'approval', approvalId: 'ap1' }])
+    expect(session.getSnapshot().pending).toMatchObject([{ kind: 'approval', payload: { approvalId: 'ap1' } }])
     // Buffer cleared: a second instantiation of another id gets nothing.
     expect(manager.get(S2).getSnapshot().pending).toEqual([])
   })
@@ -48,7 +48,7 @@ describe('instances', () => {
     }
     const pending = manager.get(S1).getSnapshot().pending
     expect(pending).toHaveLength(32)
-    expect(pending.map(p => p.rpcId)).toEqual(Array.from({ length: 32 }, (_, i) => `q${i + 8}`)) // oldest 8 dropped
+    expect(pending.map(p => p.key)).toEqual(Array.from({ length: 32 }, (_, i) => `q:q${i + 8}`)) // oldest 8 dropped
     // Removed session: buffered frames must not replay on a future instantiation.
     manager.handleMuxEnvelope({ rpcId: 'qz' as never, payload: { type: 'question/requested', sessionId: S2, questions: [] } })
     manager.handleHostEnvelope({ rpcId: 'hz' as never, payload: { type: 'host/session-removed', sessionId: S2 } })

packages/client/runtime/tests/session.spec.ts

@@ -251,6 +251,36 @@ describe('pending interactions', () => {
     session.handleMuxEnvelope('ry' as never, { type: 'question/resolved', sessionId: SID, questionRpcId: 'rq' as never, outcome: 'answered' })
     expect(session.getSnapshot().pending).toEqual([])
   })
+
+  it('mints waits whose respond() backfills the requested rpcId into the client-response envelope', async () => {
+    const { api, session } = makeSession()
+    session.handleMuxEnvelope('rq-answer' as never, { type: 'question/requested', sessionId: SID, questions: [] })
+    const wait = session.getSnapshot().pending[0]!
+    expect(wait).toMatchObject({ kind: 'question', key: 'q:rq-answer', sessionId: SID, payload: { questions: [] } })
+    const receipt = await wait.respond({
+      ok: true,
+      value: { sessionId: SID, answer: { answers: [{ id: 'mode', selected: ['Fast'] }] } },
+    })
+    expect(receipt).toEqual({ accepted: true })
+    expect(api.callsOf('respond')).toEqual([{
+      type: 'client-response', rpcId: 'rq-answer',
+      result: {
+        ok: true,
+        value: { sessionId: SID, answer: { answers: [{ id: 'mode', selected: ['Fast'] }] } },
+      },
+    }])
+  })
+
+  it('settles the wait on the authoritative resolved frame: respond() then throws synchronously', async () => {
+    const { api, session } = makeSession()
+    session.handleMuxEnvelope('rq1' as never, { type: 'question/requested', sessionId: SID, questions: [] })
+    const wait = session.getSnapshot().pending[0]!
+    session.handleMuxEnvelope('ry' as never, { type: 'question/resolved', sessionId: SID, questionRpcId: 'rq1' as never, outcome: 'answered' })
+    expect(session.getSnapshot().pending).toEqual([])
+    expect(() => wait.respond({ ok: false, error: { code: 'internal', message: 'x', details: {} } }))
+      .toThrow('already settled')
+    expect(api.callsOf('respond')).toEqual([])
+  })
 })
 
 describe('remaining branches', () => {
@@ -355,7 +385,7 @@ describe('remaining branches', () => {
     session.handleMuxEnvelope('ra' as never, {
       type: 'approval/requested', sessionId: SID, approvalId: 'ap2' as never, toolName: 'rm', callId: 'c1' as never, reason: '危险',
     })
-    expect(session.getSnapshot().pending[0]).toMatchObject({ kind: 'approval', callId: 'c1', reason: '危险' })
+    expect(session.getSnapshot().pending[0]).toMatchObject({ kind: 'approval', payload: { callId: 'c1', reason: '危险' } })
     session.handleMuxEnvelope('rx' as never, { type: 'approval/resolved', sessionId: SID, approvalId: 'ap2' as never, outcome: 'approved' as never })
     session.handleMuxEnvelope('rx2' as never, { type: 'approval/resolved', sessionId: SID, approvalId: 'ap2' as never, outcome: 'approved' as never })
     session.handleMuxEnvelope('ry2' as never, { type: 'question/resolved', sessionId: SID, questionRpcId: 'never-was' as never, outcome: 'cancelled' })
@@ -568,6 +598,22 @@ describe('resync', () => {
     expect(cold.api.calls).toEqual([]) // never opened: no traffic
   })
 
+  it('re-mints a replayed requested frame as a fresh wait with the same key (old reference superseded)', async () => {
+    const { api, session } = makeSession()
+    api.onHistory = () => histResponse(plainTurn(0, 0, 'a', 'b'))
+    await session.open()
+    session.handleMuxEnvelope('rq-replay' as never, { type: 'question/requested', sessionId: SID, questions: [] })
+    const before = session.getSnapshot().pending[0]!
+    await session.resync()
+    session.handleMuxEnvelope('rq-replay' as never, { type: 'question/requested', sessionId: SID, questions: [] })
+    const after = session.getSnapshot().pending[0]!
+    expect(after).not.toBe(before)
+    expect(after.key).toBe(before.key)
+    // Superseded ≠ settled: an in-flight respond on the stale reference still reaches the host.
+    await before.respond({ ok: false, error: { code: 'internal', message: 'x', details: {} } })
+    expect(api.callsOf('respond')).toMatchObject([{ rpcId: 'rq-replay' }])
+  })
+
   it('drops a stale in-flight open superseded by resync (generation guard)', async () => {
     const { api, session } = makeSession()
     const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()

packages/client/runtime/tests/sessions-service.spec.ts

@@ -2,8 +2,9 @@
  * SessionsService: list store projection (manager → {ids, byId, current}
  * with derived titles), the migrated current-selection account (open
  * validation, persisted mask semantics, cell resolution), scope-tree
- * lifecycle (lazy mint / frozen survival / removed teardown with watch
- * deferral), binding identity, ancestry walk, create.
+ * lifecycle (lazy mint / frozen survival / removed teardown with staged
+ * deferral — the stage follows list.current), binding identity, ancestry
+ * walk, create.
  */
 import { Context } from 'cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -76,21 +77,21 @@ describe('scope tree', () => {
     expect(binding?.ctx).toBe(scoped)
   })
 
-  it('tears down an unwatched removed session but defers the watched one until the watch moves', async () => {
+  it('tears down an off-stage removed session but defers the staged one until the stage moves', async () => {
     const b = bench()
     await feedList(b, [{ id: 's1' }, { id: 's2' }])
     const ctx1 = b.svc.scope(sid('s1'))
-    b.svc.binding(sid('s1')) // s1 is watched
-    b.svc.scope(sid('s2')) // s2 scoped but not watched
+    b.svc.open(sid('s1')) // s1 staged (current)
+    b.svc.scope(sid('s2')) // s2 scoped but off stage
 
-    await feedList(b, [{ id: 's1' }]) // s2 removed, unwatched: torn down
+    await feedList(b, [{ id: 's1' }]) // s2 removed, off stage: torn down
     expect(b.svc.scope(sid('s2'))).toBeUndefined()
 
-    await feedList(b, []) // s1 removed while watched: deferred, scope survives
+    await feedList(b, []) // s1 removed while staged (current masks): deferred, scope survives
     expect(b.svc.scope(sid('s1'))).toBe(ctx1)
 
     await feedList(b, [{ id: 's3' }])
-    b.svc.binding(sid('s3')) // watch moves: deferred teardown sweeps s1
+    b.svc.open(sid('s3')) // stage moves: deferred teardown sweeps s1
     expect(b.svc.scope(sid('s1'))).toBeUndefined()
   })
 
@@ -106,10 +107,10 @@ describe('scope tree', () => {
     const b = bench()
     await feedList(b, [{ id: 's1' }])
     const scoped = b.svc.scope(sid('s1'))
-    b.svc.binding(sid('s1'))
-    await feedList(b, []) // removed while watched → deferred
-    await feedList(b, [{ id: 's1' }, { id: 's2' }]) // reappears
-    b.svc.binding(sid('s2')) // watch moves; sweep must NOT tear down the re-listed s1
+    b.svc.open(sid('s1'))
+    await feedList(b, []) // removed while staged → deferred
+    await feedList(b, [{ id: 's1' }, { id: 's2' }]) // reappears (current resurfaces, stage unchanged)
+    b.svc.open(sid('s2')) // stage moves; sweep must NOT tear down the re-listed s1
     expect(b.svc.scope(sid('s1'))).toBe(scoped)
   })
 })
@@ -168,15 +169,52 @@ describe('cell (render-layer session kit)', () => {
     expect(b.svc.cell('ghost')).toBeUndefined()
   })
 
-  it('moves the watch like binding(): switching cells sweeps a deferred removal', async () => {
+  it('cell()/binding() are pure resolution: no staging, no deferred sweep', async () => {
     const b = bench()
-    await feedList(b, [{ id: 's1' }])
-    b.svc.cell('s1') // watched
-    await feedList(b, []) // removed while watched → deferred, scope survives
+    await feedList(b, [{ id: 's1' }, { id: 's2' }])
+    b.svc.open(sid('s1')) // staged
+    b.svc.cell('s2') // resolution only — must NOT move the stage
+    b.svc.binding(sid('s2'))
+    await feedList(b, [{ id: 's2' }]) // s1 removed: still staged → deferred, scope survives
     expect(b.svc.scope(sid('s1'))).toBeDefined()
-    await feedList(b, [{ id: 's2' }])
-    b.svc.cell('s2') // watch moves → sweep tears s1 down
-    expect(b.svc.scope(sid('s1'))).toBeUndefined()
+  })
+
+  it('staging (current write) opens the session event window; resolution and re-staging do not re-pull', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 's1' }, { id: 's2' }])
+    const historyCalls = () => b.api.calls.filter(c => c.method === 'session.history')
+    // Resolution is addressing, not staging: no window pull.
+    b.svc.scope(sid('s1'))
+    b.svc.cell('s1')
+    b.svc.binding(sid('s1'))
+    expect(historyCalls()).toHaveLength(0)
+    b.svc.open(sid('s1'))
+    expect(historyCalls().map(c => (c.payload as { sessionId: string }).sessionId)).toEqual(['s1'])
+    // Same current again: no second pull.
+    b.svc.open(sid('s1'))
+    expect(historyCalls()).toHaveLength(1)
+    // Stage moves: the new occupant opens.
+    b.svc.open(sid('s2'))
+    expect(historyCalls().map(c => (c.payload as { sessionId: string }).sessionId)).toEqual(['s1', 's2'])
+  })
+
+  it('startup restore: a persisted selection validated by the first projection opens its window unprompted', async () => {
+    const storage = new Map<string, string>([
+      ['dsh.sessions.current', JSON.stringify({ sessionId: 's1' })],
+    ])
+    vi.stubGlobal('localStorage', {
+      getItem: (k: string) => storage.get(k) ?? null,
+      setItem: (k: string, v: string) => { storage.set(k, v) },
+    })
+    try {
+      const b = bench()
+      expect(b.api.calls.filter(c => c.method === 'session.history')).toHaveLength(0)
+      await feedList(b, [{ id: 's1' }]) // projection validates the persisted id → current lands → stage follows
+      const historyCalls = b.api.calls.filter(c => c.method === 'session.history')
+      expect(historyCalls.map(c => (c.payload as { sessionId: string }).sessionId)).toEqual(['s1'])
+    } finally {
+      vi.unstubAllGlobals()
+    }
   })
 })
 
@@ -187,12 +225,13 @@ describe('slot-store scope prune hook', () => {
     b.ctx.reflect.provide('slots', { pruneStoreScope })
     await feedList(b, [{ id: 's1' }, { id: 's2' }])
     b.svc.scope(sid('s1'))
-    b.svc.binding(sid('s2')) // s2 watched
-    await feedList(b, []) // s1 unwatched → immediate drop; s2 watched → deferred
+    b.svc.scope(sid('s2'))
+    b.svc.open(sid('s2')) // s2 staged
+    await feedList(b, []) // s1 off stage → immediate drop; s2 staged → deferred
     expect(pruneStoreScope).toHaveBeenCalledWith('s1')
     expect(pruneStoreScope).not.toHaveBeenCalledWith('s2')
     await feedList(b, [{ id: 's3' }])
-    b.svc.binding(sid('s3')) // watch moves → deferred sweep drops s2
+    b.svc.open(sid('s3')) // stage moves → deferred sweep drops s2
     expect(pruneStoreScope).toHaveBeenCalledWith('s2')
   })
 
@@ -242,44 +281,46 @@ describe('coverage tails (branch duals)', () => {
     expect(byId[sid('empty-cwd')]?.title).toBe('empty-cwd')
   })
 
-  it('binding for an unknown session returns undefined without moving the watch', async () => {
+  it('binding for an unknown session returns undefined and leaves the staged scope intact', async () => {
     const b = bench()
     await feedList(b, [{ id: 's1' }])
-    b.svc.binding(sid('s1'))
+    b.svc.open(sid('s1'))
     expect(b.svc.binding(sid('ghost'))).toBeUndefined()
-    // Watch unchanged: removing s1 defers (still watched), proving the ghost lookup did not steal the watch.
+    // Stage unchanged: removing s1 defers (still staged), proving the ghost lookup touched nothing.
     await feedList(b, [])
     expect(b.svc.scope(sid('s1'))).toBeDefined()
   })
 
-  it('sweep skips the id that is itself still watched and tolerates a scope record already gone', async () => {
+  it('a masked current gap holds the stage (no teardown, no re-open) until the stage moves', async () => {
     const b = bench()
     await feedList(b, [{ id: 's1' }])
-    b.svc.binding(sid('s1'))
-    await feedList(b, []) // deferred removal of the watched id
-    // Re-resolving the SAME watched id: sweep runs but must skip it (watched-continue branch).
-    expect(b.svc.binding(sid('s1'))).toBeDefined()
+    b.svc.open(sid('s1'))
+    const historyCalls = () => b.api.calls.filter(c => c.method === 'session.history')
+    expect(historyCalls()).toHaveLength(1)
+    await feedList(b, []) // removed while staged: current masks to undefined, stage holds → deferred
     expect(b.svc.scope(sid('s1'))).toBeDefined()
+    // Resurfacing re-projects current = s1: same stage occupant, no second pull.
+    await feedList(b, [{ id: 's1' }])
+    expect(historyCalls()).toHaveLength(1)
+    expect(b.svc.list.getSnapshot().current).toBe('s1')
   })
 
-  it('sweep hits both deferral edges: watched-id skip and an already-vacated scope record', async () => {
+  it('sweep hits both deferral edges: staged-id skip and an already-vacated scope record', async () => {
     const b = bench()
     await feedList(b, [{ id: 'a' }, { id: 'b' }])
-    b.svc.binding(sid('a'))
-    b.svc.binding(sid('b')) // watch: b; both scoped
-    await feedList(b, []) // a removed unwatched → torn immediately; b removed watched → deferred
-    // Move the watch to a THIRD id while b stays deferred: sweep now walks a
-    // set containing b (torn) — and the watched-continue branch fires when the
-    // deferral set still holds the current watch target.
+    b.svc.scope(sid('a'))
+    b.svc.open(sid('b')) // stage: b; both scoped
+    await feedList(b, []) // a removed off stage → torn immediately; b removed staged → deferred
+    // Move the stage to a THIRD id while b stays deferred: sweep walks a set
+    // containing b (torn).
     await feedList(b, [{ id: 'c' }])
-    b.svc.binding(sid('c'))
+    b.svc.open(sid('c'))
     expect(b.svc.scope(sid('b'))).toBeUndefined()
-    // Deferral for an id whose record was never minted: force-add via removed
-    // list state (scope teardown raced) — sweep must tolerate the missing record.
-    await feedList(b, [])
-    b.svc.binding(sid('c')) // c now watched+removed → deferred
+    // Deferral for an id whose record was never minted: force the deferral
+    // via removed list state — sweep must tolerate the missing record.
+    await feedList(b, []) // c removed while staged → deferred (scope exists)
     await feedList(b, [{ id: 'd' }])
-    b.svc.binding(sid('d')) // sweep tears c
+    b.svc.open(sid('d')) // sweep tears c
     expect(b.svc.scope(sid('c'))).toBeUndefined()
   })