Merge branch 'codex/simp-unify-agent-session-id' into codex/simp-ui-identity-residue

# Conflicts: # docs/config-catalog.md # docs/event-producer-consumer.md # docs/rfc/implemented/feature/2026-07-06-approval-seam.md # packages/ui/acp/README.md # packages/ui/acp/src/index.ts # packages/ui/jsonrpc/README.md # packages/ui/jsonrpc/src/server.ts
2026-07-14 18:55:51 +08:00
parent e3767c64d9 83271191d1
commit 8a5ebb1cde
508 changed files with 3487 additions and 9370 deletions
--- a/packages/ui/acp/acp-feature-support.md
+++ b/packages/ui/acp/acp-feature-support.md
@@ -111,7 +111,7 @@ Tool-call presentation is **owned by each tool** (`presentCall` / `presentResult

 ## 6. Session modes / config options / models

-Config options ✅ (the [sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)): when `ctx.permission` is composed, the bridge advertises one `permission` select whose values come from the deployment preset table and whose current value derives from the session log; `session/set_config_option` switches the preset end to end, with idle switches anchoring at the next turn under the turn-enclosure contract. Session modes stay deliberately unmodeled because config options replace them in ACP v2. Runtime model selection is still not modeled — the harness fixes the model per bridge via `AcpConfig.model` (both reference adapters ship a model selector).
+Config options ✅ (the [sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)): when `ctx.permission` is composed, the bridge advertises one `permission` select whose values come from the deployment preset table and whose current value derives from the session log; `session/set_config_option` switches the preset end to end, with idle switches anchoring at the next `agent/prompt-submit` inside its open turn. Session modes stay deliberately unmodeled because config options replace them in ACP v2. Runtime model selection is still not modeled — the harness fixes the model per bridge via `AcpConfig.model` (both reference adapters ship a model selector).

 ## 7. Content blocks

--- a/packages/ui/acp/src/codec.ts
+++ b/packages/ui/acp/src/codec.ts
@@ -1,11 +1,5 @@
 /**
- * Pure translation between harness vocabulary and ACP wire types. No I/O, no
- * Cordis context — every function here is total and unit-testable in isolation.
- * Keeping the mapping pure is deliberate: the SDK rejects an unknown
- * `stopReason`, so the {@link turnEndToStopReason} total function (with its
- * exhaustive test over every `TurnEndReason` kind) is the guard that a turn
- * always settles to a legal wire value.
- *
+ * Pure, total translation between harness vocabulary and ACP wire types.
 * @module @deepseek-ai/dsh-acp/codec
 */

@@ -16,29 +10,11 @@ import type { ContentBlock as AcpContentBlock, StopReason } from '@agentclientpr
 /**
 * Map a harness {@link TurnEndReason} to the ACP `StopReason` wire enum.
 *
- * The mapping is total over the kinds the loop actually produces today
- * (`completed`/`aborted`/`error`/`disposed`/`max-tokens`/`rejected`).
- * `TurnEndReason` is
- * merge-extensible, so an unknown future kind falls through to `end_turn` —
- * the safest default (the turn DID end; we just lack a more specific wire
- * reason) — rather than throwing into the SDK, which would reject an unknown
- * `stopReason` and break the prompt RPC. When a new kind gains a dedicated ACP
- * reason (e.g. a future `refusal` → `refusal`), add an explicit case here.
- *
- * - `completed` → `end_turn` (the model chose to stop)
- * - `max-tokens` → `max_tokens` (cut off at the output-token ceiling)
- * - `aborted`   → `cancelled` (a step abort or a queue-aware `agent.cancel()`, e.g. from `session/cancel`)
- * - `error`     → `end_turn` (defensive fallback only: the bridge REJECTS the
- *                 `session/prompt` RPC on an error turn BEFORE calling this, so
- *                 a client sees a JSON-RPC error, not a stop reason — see
- *                 `rejectPrompt` in index.ts. This case keeps the function total
- *                 for any non-bridge caller / property test.)
- * - `disposed`  → `cancelled` (the agent was torn down mid-turn — closest to a
- *                 cancellation from the client's perspective)
- * - `rejected`  → `cancelled` (the prompt was blocked by an `agent/prompt-submit`
- *                 hook before any step ran — ACP has no "rejected" reason, and a
- *                 blocked prompt is, from the client's view, the prompt not being
- *                 carried out; `cancelled` is the closest legal wire reason)
+ * `completed` and the defensive `error` case map to `end_turn`;
+ * `max-tokens` maps to `max_tokens`; `aborted`, `disposed`, and `rejected` map
+ * to `cancelled`. The bridge rejects error turns before this mapping. Unknown
+ * merge-extensible kinds use legal fallback `end_turn` rather than breaking
+ * the prompt RPC.
 * @param reason - the harness turn-end reason to translate.
 * @returns the legal ACP wire value per the mapping above.
 */
@@ -56,23 +32,17 @@ export function turnEndToStopReason(reason: TurnEndReason): StopReason {
      return 'cancelled'
    case 'error':
      return 'end_turn'
-    // Merge-extensible: an unknown future TurnEndReason kind still has to
-    // produce a legal wire value (the SDK rejects unknown stopReason), so
-    // default to end_turn rather than assertNever. Add an explicit case when a
-    // new kind gains a dedicated ACP reason.
+    // Merge-extensible: an unknown future TurnEndReason kind still has to produce a legal wire
+    // value (the SDK rejects unknown stopReason), so default to end_turn rather than
+    // assertNever.
    default:
      return 'end_turn'
  }
 }

 /**
- * Translate a harness {@link ContentBlock} from a prompt into ACP content for
- * replay, or `undefined` for block kinds the bridge does not surface to the
- * client as message content. Today only `text` maps; `resource_link` is an
- * ACP prompt-only input rendered into text by {@link acpPromptToText};
- * `reasoning` is surfaced via `agent_thought_chunk`
- * streaming rather than as a message block, and `tool-call`/`tool-result`
- * are handled by the tool-call update path.
+ * Map replayable text to ACP message content. Other block kinds use their
+ * prompt, thought-stream, or tool-update paths.
 * @param block - the harness content block to translate.
 * @returns the ACP block, or `undefined` for a kind with no message-content mapping.
 */
--- a/packages/ui/acp/tests/config-options.spec.ts
+++ b/packages/ui/acp/tests/config-options.spec.ts
@@ -1,10 +1,6 @@
 /**
- * Session config options over the bridge: ONE user-facing `Permissions`
- * select (`ctx.permission`'s preset table — each choice bundles a sandbox
- * mode and an approval policy), its current value folded from each session's
- * own log, switching via `session/set_config_option` (the preset event plus
- * its knob write-throughs — the log is the store), and a resumed session
- * reporting its preset back on `session/load` with no catch-up machinery.
+ * Exercises the bridge's per-session Permissions option: validation, idle
+ * turn anchoring, isolation, and persistence through `session/load`.
 */

 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
@@ -20,12 +16,8 @@ import PermissionService from '@deepseek-ai/dsh-permission'
 import { makeBridgeHarness, textResponse, type BridgeHarness } from './harness.ts'

 /**
- * The REAL local executor reporting a confining default — `sandboxMode` is
- * the documented capability override point (`dsh-bash-sandbox` overrides it
- * the same way), so the bridge sees exactly what a sandboxing composition
- * advertises without this suite dragging in a kernel sandbox stack. It
- * reports `workspace-write`: the shipped preset's bundle, which
- * the permission service validates the composition defaults against.
+ * Advertises the real executor through the `sandboxMode` capability without
+ * loading a kernel sandbox, which these bridge tests do not exercise.
 */
 class SandboxedLocalExecutor extends LocalBashExecutor {
  override get sandboxMode(): SandboxMode {
@@ -33,7 +25,6 @@ class SandboxedLocalExecutor extends LocalBashExecutor {
  }
 }

-/** The exact option payload the bridge advertises (pinned verbatim). */
 function permissionOption(currentValue: string): object {
  return {
    id: 'permission',
@@ -43,8 +34,8 @@ function permissionOption(currentValue: string): object {
    type: 'select',
    currentValue,
    options: [
-      { value: 'workspace-write', name: 'workspace-write', description: 'Write inside the workspace; anything wider asks for your approval.' },
-      { value: 'danger-full-access', name: 'danger-full-access', description: 'Full file access, no approval prompts.' },
+      { value: 'workspace-write', name: 'workspace-write', description: 'Write inside the workspace and permitted temporary directories; wider retries require approval.' },
+      { value: 'danger-full-access', name: 'danger-full-access', description: 'Full file access without approval prompts.' },
    ],
  }
 }
@@ -62,11 +53,9 @@ describe('acp bridge — session config options', () => {
    await rm(storageDir, { recursive: true, force: true })
  })

-  /** A harness composing the full preset stack (confining executor + approval seam + permission presets). */
  async function presetStack(options: { script?: NonNullable<Parameters<typeof makeBridgeHarness>[0]>['script'] } = {}): Promise<BridgeHarness> {
    const harness = await makeBridgeHarness({ storageDir, ...options.script !== undefined ? { script: options.script } : {} })
-    // The dev invariants police turn-enclosure: an idle switch that appended
-    // outside a turn would throw right here in the suite, not in production.
+    // Make an out-of-turn switch fail in this suite.
    await harness.ctx.plugin(Invariants)
    await harness.ctx.plugin(SandboxedLocalExecutor, { timeoutMs: 10_000 })
    await harness.ctx.plugin(ApprovalService)
@@ -90,14 +79,13 @@ describe('acp bridge — session config options', () => {
    expect(res.configOptions).toEqual([permissionOption('workspace-write')])
  })

-  it('an idle switch is pending (overlaid, not yet logged), then anchors INSIDE the next turn', async () => {
+  it('an idle switch is pending (overlaid, not yet logged), then anchors inside the next prompt\'s turn', async () => {
    h = await presetStack({ script: [textResponse('ok')] })
    const { sessionId } = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] })

    const after = await h.client.setSessionConfigOption({ sessionId, configId: 'permission', value: 'danger-full-access' })
    expect(after.configOptions).toEqual([permissionOption('danger-full-access')])

-    // Idle: nothing in the log yet — turn-enclosure forbids a bare append.
    const session = h.ctx.agents.list()[0]?.session
    expect(session?.events.some(e => e.type === 'permission/preset' || e.type === 'bash/sandbox-mode' || e.type === 'approval/policy')).toBe(false)

@@ -112,7 +100,7 @@ describe('acp bridge — session config options', () => {
    expect(anchored).toBeGreaterThan(turnStart)
  })

-  it('an idle flip-flop anchors as ONE switch (last write wins)', async () => {
+  it('an idle flip-flop anchors as one switch (last write wins)', async () => {
    h = await presetStack({ script: [textResponse('ok')] })
    const { sessionId } = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] })
    await h.client.setSessionConfigOption({ sessionId, configId: 'permission', value: 'danger-full-access' })
@@ -121,13 +109,12 @@ describe('acp bridge — session config options', () => {
    await h.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'anchor' }] })
    const events = h.ctx.agents.list()[0]?.session.events ?? []
    expect(events.filter(e => e.type === 'permission/preset')).toHaveLength(1)
-    // Between turns (a closed turn in the log) a switch still pends — the
-    // enclosure fold walks past the turn/end — and anchors with the NEXT turn.
+    // A closed turn does not make a later idle switch appendable.
    await h.client.setSessionConfigOption({ sessionId, configId: 'permission', value: 'workspace-write' })
    expect(h.ctx.agents.list()[0]?.session.events.filter(e => e.type === 'permission/preset')).toHaveLength(1)
  })

-  it('a net-zero idle flip-flop anchors NOTHING (switches are recorded, select clicks are not)', async () => {
+  it('a net-zero idle flip-flop anchors nothing (switches are recorded, select clicks are not)', async () => {
    h = await presetStack({ script: [textResponse('ok')] })
    const { sessionId } = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] })
    await h.client.setSessionConfigOption({ sessionId, configId: 'permission', value: 'danger-full-access' })
@@ -177,7 +164,7 @@ describe('acp bridge — session config options', () => {

    await expect(h.client.setSessionConfigOption({ sessionId, configId: 'reasoning-effort', value: 'max' }))
      .rejects.toThrow(/unknown config option/)
-    // `permission` exists as a concept but THIS composition never advertised it.
+    // This composition never advertised `permission`.
    await expect(h.client.setSessionConfigOption({ sessionId, configId: 'permission', value: 'danger-full-access' }))
      .rejects.toThrow(/unknown permission value/)
    await expect(h.client.setSessionConfigOption({ sessionId, configId: 'permission', type: 'boolean', value: true }))
@@ -196,10 +183,8 @@ describe('acp bridge — session config options', () => {
    const a = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] })
    const b = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] })
    await h.client.setSessionConfigOption({ sessionId: a.sessionId, configId: 'permission', value: 'danger-full-access' })
-    // B sees the composition default, not A's pending switch...
    const bAfter = await h.client.setSessionConfigOption({ sessionId: b.sessionId, configId: 'permission', value: 'workspace-write' })
    expect(bAfter.configOptions).toEqual([permissionOption('workspace-write')])
-    // ...and A keeps its own state, untouched by B's.
    const aAfter = await h.client.setSessionConfigOption({ sessionId: a.sessionId, configId: 'permission', value: 'danger-full-access' })
    expect(aAfter.configOptions).toEqual([permissionOption('danger-full-access')])
  })
@@ -207,22 +192,17 @@ describe('acp bridge — session config options', () => {
  it('a knob drifted outside the table derives a visible-but-untargetable custom current', async () => {
    h = await presetStack()
    const { sessionId } = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    // Drift a knob out from under the table (a plugin writing the knob
-    // directly — the raw setters remain public mechanism), inside its own
-    // turn: the dev invariants enforce turn-enclosure here too.
+    // Simulate a plugin calling the public knob setter inside a valid turn.
    const agent = h.ctx.agents.list()[0]
    if (agent === undefined) throw new Error('expected an agent')
    agent.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    agent.session.append('bash/sandbox-mode', { mode: 'read-only' })
    agent.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    // The echo of the derived current is a no-op, not an unknown-value error…
    const echo = await h.client.setSessionConfigOption({ sessionId, configId: 'permission', value: 'custom' })
    const option = echo.configOptions?.[0]
    expect(option).toMatchObject({ currentValue: 'custom' })
    if (option === undefined || !('options' in option)) throw new Error('expected a select option')
    expect(option.options.map(o => 'value' in o ? o.value : o)).toEqual(['workspace-write', 'danger-full-access', 'custom'])
-    // …while custom as a TARGET from a real preset stays rejected: switching
-    // away is ordinary, and the custom entry disappears from the options.
    const away = await h.client.setSessionConfigOption({ sessionId, configId: 'permission', value: 'danger-full-access' })
    const afterOption = away.configOptions?.[0]
    expect(afterOption).toMatchObject({ currentValue: 'danger-full-access' })
--- a/packages/ui/acp/tests/harness.ts
+++ b/packages/ui/acp/tests/harness.ts
@@ -1,12 +1,7 @@
 /**
- * Shared test fixtures for the ACP bridge specs. A plain module (NOT a
- * *.spec.ts) so importing it does not re-register a describe block.
- *
- * `makeBridgeHarness` builds a full in-memory cordis context (llm + session +
- * system-prompt + tools + agents + agent-loop + persistence) with the ACP
- * bridge wired to an in-memory transport, plus a `ClientSideConnection` on the
- * other end — so a test drives the bridge exactly as an editor would, with no
- * subprocess and no real stdio.
+ * Shared non-spec fixture that mounts the full in-memory agent/persistence stack and connects the
+ * ACP bridge to a real SDK client over memory streams. Tests exercise the same protocol path as an
+ * editor without a subprocess or stdio.
 */

 import { Context } from 'cordis'
@@ -218,13 +213,10 @@ export async function makeBridgeHarness(options: {
  }
  ctx.llm.registerAdapter(['mock'], adapter)

-  // Two identity byte pipes cross-wired into the two ndJsonStreams: bytes the
-  // agent writes flow to the client's reader and vice versa. (ndJsonStream
-  // takes (output, input): the agent writes to a2c and reads from c2a; the
-  // client writes to c2a and reads from a2c.) The client→agent path (c2a) runs
-  // through a hand-held writer so a test can close it (`closeClientTransport`)
-  // to simulate the editor disconnecting — closing it EOFs the agent's reader
-  // and resolves the bridge's `conn.closed`.
+  // Two identity byte pipes cross-wired into the two ndJsonStreams: bytes the agent writes flow
+  // to the client's reader and vice versa. (ndJsonStream takes (output, input): the agent
+  // writes to a2c and reads from c2a; the client writes to c2a and reads from a2c.) Holding the c2a
+  // writer lets tests EOF the agent reader and simulate editor disconnect.
  const a2c = new TransformStream<Uint8Array, Uint8Array>()
  const c2a = new TransformStream<Uint8Array, Uint8Array>()
  const c2aWriter = c2a.writable.getWriter()
@@ -253,11 +245,9 @@ export async function makeBridgeHarness(options: {
    onSessionUpdateError: undefined,
    client: undefined as unknown as ClientSideConnection,
    acpFiber: undefined as unknown as BridgeHarness['acpFiber'],
-    // Close the writable the CLIENT writes to (c2a) — its readable, which the
-    // agent's ndJsonStream consumes, then EOFs cleanly, so the bridge's
-    // `conn.closed` resolves and it sees the client disconnect. If the client
-    // connection holds a writer lock on it, abort the connection's signal path
-    // instead by closing through the underlying stream.
+    // Close the writable the CLIENT writes to (c2a) — its readable, which the agent's
+    // ndJsonStream consumes, then EOFs cleanly, so the bridge's `conn.closed` resolves and it
+    // sees the client disconnect.
    closeClientTransport: async () => { await c2aWriter.close() },
    dispose: async () => { await ctx.fiber.dispose() },
    storageDir: options.storageDir,
@@ -281,27 +271,19 @@ export async function makeBridgeHarness(options: {
    },
  })

-  // Wire the bridge (agent side) and the client (test side). The test config
-  // can override `model` (including to undefined): default to 'mock' unless the
-  // caller explicitly set the key (even to undefined), so a `{ model: undefined }`
-  // override means "no model at all".
+  // Default to `mock` only when the caller omitted the key; explicit `model: undefined` means no
+  // model and must survive the object spread.
  const cfg: AcpConfig = { stream: agentStream, ...options.config }
  if (!(options.config && 'model' in options.config)) cfg.model = 'mock'
-  // Mount the bridge the way production does: as a cordis PLUGIN (via
-  // `ctx.plugin` with the real `inject`), NOT `AcpPlugin.apply(ctx, cfg)`
-  // directly on the root ctx. The plugin fiber is the faithful reproduction —
-  // the bridge's `apply` runs inside the fiber's injection scope, and its ACP
-  // handlers later run from the JSON-RPC read loop OUTSIDE that scope, exactly
-  // as under the example's cordis.yml. (Mounting directly on root made every
-  // service an ungated property and hid the "cannot get property … without
-  // inject" failure that bit a real Zed session.) `harness.acpFiber.dispose()`
-  // tears down JUST the bridge (its listeners + effect) for the HMR test.
+  // Mount the bridge the way production does: as a cordis plugin (via `ctx.plugin` with the
+  // real `inject`), not `AcpPlugin.apply(ctx, cfg)` on the ungated root. Later JSON-RPC callbacks run
+  // outside apply's injection scope, matching production and exposing missing-inject failures.
  harness.acpFiber = await ctx.plugin({
    name: 'acp-test',
-    // Use the bridge's REAL exported `inject` so this never drifts from the
-    // plugin's actual dependency list (adding a service to the bridge must not
-    // require editing the harness — a hardcoded list silently broke when `tools`
-    // was added). The bridge programs against the interface packages only.
+    // Use the bridge's real exported `inject` so this never drifts from the plugin's actual
+    // dependency list (adding a service to the bridge must not require editing the harness — a
+    // hardcoded list silently broke when `tools` was added). The returned fiber permits ACP-only
+    // disposal while root services remain live for HMR assertions.
    inject: [...AcpPlugin.inject],
    apply: (inner: Context) => { AcpPlugin.apply(inner, cfg) },
  })
--- a/packages/ui/acp/tests/load.spec.ts
+++ b/packages/ui/acp/tests/load.spec.ts
@@ -57,12 +57,8 @@ describe('acp bridge — session/load replay', () => {
  })

  it('replays a persisted tool call with the TOOL-OWNED presentation (title/rawInput/console output)', async () => {
-    // A turn with a REAL bash tool call is persisted, then loaded by a fresh
-    // bridge. The replayed tool_call/tool_call_update must carry the tool's OWN
-    // presentation — identical to how it streamed live — via a throwaway
-    // presenter that pairs call→result as the log replays in order. Uses the
-    // shipping tool (withBash), not a stand-in (docs/testing.md "prefer the real
-    // implementation over a mock in tests").
+    // Persist a real bash call, then replay it through a fresh bridge. A throwaway presenter pairs
+    // call and result in log order so replay uses the shipping tool's same cards as live streaming.
    live = await makeBridgeHarness({
      storageDir,
      withBash: true,
@@ -94,10 +90,8 @@ describe('acp bridge — session/load replay', () => {
  })

  it('replays a persisted todo/write as a plan sessionUpdate on load', async () => {
-    // A turn whose model called todo_write persists a todo/write event. A fresh
-    // bridge loading the session must re-emit the ACP `plan` update from the log
-    // (the load replay runs every event through streamSessionEventUpdate), so an
-    // editor reopening the session sees the current plan.
+    // A persisted `todo/write` must replay as an ACP plan update so a reopened editor sees the
+    // current plan, not just the tool transcript.
    live = await makeBridgeHarness({
      storageDir,
      withTodo: true,
@@ -168,11 +162,8 @@ describe('acp bridge — session/load replay', () => {
  })

  it('a load whose resume finishes after a client disconnect leaks no live session', async () => {
-    // A session/load is mid-resume() when the client transport closes. The load
-    // must NOT end up with a live registered agent for the connection that is
-    // already gone. (The bridge's post-await `closed` guard backs this on real
-    // stdio; here the SDK rejects the in-flight request on close — either way no
-    // agent survives.) Stall persistence so resume() is pending across the close.
+    // Stall persistence so transport closes while resume is pending. Whether the SDK rejects first
+    // or the bridge's post-await guard fires, no agent may survive for the dead connection.
    live = await makeBridgeHarness({ storageDir, script: [textResponse('x')] })
    await live.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await live.client.newSession({ cwd: process.cwd(), mcpServers: [] })
@@ -197,10 +188,9 @@ describe('acp bridge — session/load replay', () => {
  })

  it('rejects load when the requested cwd does not match the persisted session cwd', async () => {
-    // Seed a session on disk whose header.cwd is a DIFFERENT absolute path than
-    // the server's launch dir. The bridge must LOAD it (per-session cwd is
-    // honored — the resumed session keeps header.cwd, and bash routes there), no
-    // longer reject on a mismatch.
+    // Seed a session on disk whose header.cwd is a DIFFERENT absolute path than the server's
+    // launch dir. Resume must retain the header cwd and route bash there rather than reject the
+    // mismatch or substitute the server cwd.
    loader = await makeBridgeHarness({ storageDir, script: [] })
    const otherCwd = '/some/other/workspace'
    await loader.ctx.sessionPersistence.create({
@@ -236,9 +226,8 @@ describe('acp bridge — session/load replay', () => {
  })

  it('rejects loading a persisted session that has NO cwd (would silently run in the launch dir)', async () => {
-    // A legacy / externally-created session log with no header.cwd. The bridge
-    // must reject the load rather than accept it and let bash silently fall back
-    // to the server's launch dir (the request cwd does not override the header).
+    // A legacy/external log without `header.cwd` must be rejected; the request cwd does not override
+    // it, and accepting would let bash silently fall back to the server launch directory.
    loader = await makeBridgeHarness({ storageDir, script: [] })
    await loader.ctx.sessionPersistence.create({
      version: SESSION_FORMAT_VERSION, id: SessionId('legacy'), createdAt: 1, // no cwd
--- a/packages/ui/acp/tests/properties.spec.ts
+++ b/packages/ui/acp/tests/properties.spec.ts
@@ -1,17 +1,9 @@
 /**
- * Property-based protocol-shape tests for the ACP update stream (RFC 001 →
- * ADR 0013 precedent). Fuzz arbitrary harness `SessionEvent` sequences through
- * the pure `streamSessionEventUpdate` translator and assert the invariants an
- * ACP client relies on:
- *
- *  - every emitted update is a legal `SessionUpdate` variant;
- *  - a `tool_call_update` for a given id is never emitted before a `tool_call`
- *    for that id (the client must see the pending call before its completion);
- *  - the translator is a pure function of the event (same event → same updates),
- *    so live streaming and `session/load` replay produce identical streams.
- *
- * Pure-function fuzzing (no live loop) keeps these deterministic — a failure is
- * a real finding, not timing noise.
+ * Property-based protocol-shape tests for the ACP update stream (RFC 001 → ADR 0013
+ * precedent). Fuzz arbitrary harness `SessionEvent` sequences through the pure
+ * `streamSessionEventUpdate` translator and assert legal update variants, call-before-result order
+ * per tool id, and deterministic event-to-update translation. Keeping this pure makes live and
+ * replay equivalence deterministic rather than a timing property.
 */

 import { describe, expect, it } from 'vitest'
--- a/packages/ui/acp/tests/stream-update.spec.ts
+++ b/packages/ui/acp/tests/stream-update.spec.ts
@@ -297,10 +297,9 @@ describe('ToolPresenter (tool-owned presentation via the tool registry)', () =>
  })

  it('a THROWING presentCall/presentResult is contained: generic fallback + onError, never propagates', () => {
-    // A buggy tool whose display callbacks throw must NOT fail a live turn or a
-    // session/load replay (docs/defensive-patterns.md "contain callback exceptions at the
-    // boundary"). The presenter swallows the throw, reports via onError, and
-    // falls back to the generic presentation.
+    // A buggy tool whose display callbacks throw must not fail a live turn or a session/load
+    // replay (docs/defensive-patterns.md "contain callback exceptions at the boundary"). The
+    // presenter reports the error and falls back to generic rendering.
    const boom: ToolDefinition = {
      name: 'boom',
      description: 'b',
@@ -630,12 +629,10 @@ describe('diff-card mapping', () => {
 })

 describe('result-time diff card (REAL fs edit tool → tool_call_update diff blocks)', () => {
-  // Drive the SHIPPING fs edit tool through the bridge: the pending tool/call
-  // installs the call-time snippet, then the tool/result carries the tool's
-  // computed applied-hunk `meta`, which presentResult narrows into a `diff`
-  // result card the bridge forwards as `{ type: 'diff' }` content blocks. Uses
-  // the REAL tool (not a stand-in) per the anti-mock convention, mirroring the
-  // call-side diff test above.
+  // Drive the SHIPPING fs edit tool through the bridge: the pending tool/call installs the
+  // call-time snippet, then the tool/result carries the tool's computed applied-hunk `meta`,
+  // which presentResult narrows into a `diff` result card the bridge forwards as `{ type:
+  // 'diff' }` content blocks. The real tool is required because its result metadata is the contract.
  it('forwards the applied-hunk meta onto the wire as tool_call_update diff content', async () => {
    const ctx = await fsCtx()
    const presenter = new ToolPresenter(ctx.tools)
@@ -672,11 +669,10 @@ describe('result-time diff card (REAL fs edit tool → tool_call_update diff blo
  })

  it('the completed diff TITLE relativizes against the session cwd (the result title replaces the card header)', async () => {
-    // A `tool_call_update.title` replaces the card header, so the result-side
-    // diff must relativize its title exactly as the pending card did — otherwise
-    // a completed absolute-path edit flips `Edit src/b.ts` back to the raw
-    // absolute path. The diff/location paths stay absolute (the editor opens the
-    // real path). Drive the REAL fs edit tool with an absolute in-workspace path.
+    // A `tool_call_update.title` replaces the card header, so the result-side diff must
+    // relativize its title exactly as the pending card did — otherwise a completed
+    // absolute-path edit flips `Edit src/b.ts` back to the raw absolute path. Diff and location
+    // paths remain absolute so the editor can open the real file.
    const ctx = await fsCtx()
    const presenter = new ToolPresenter(ctx.tools)
    const args = JSON.stringify({ file_path: '/work/proj/src/b.ts', old_string: 'OLD', new_string: 'NEW' })
@@ -698,11 +694,8 @@ describe('result-time diff card (REAL fs edit tool → tool_call_update diff blo
  })

  it('a diff result with an EMPTY diffs array and no title omits both keys (nothing to send)', () => {
-    // A synthetic tool whose presentResult yields a `diff` card with no hunks and
-    // no title — the shipping fs tools never emit this (edit always has a hunk;
-    // write always falls back to a whole-file diff), so a stand-in is the only way
-    // to exercise the empty-content AND absent-title branches of the result-side
-    // diff arm.
+    // Shipping edit always has a hunk and write falls back to a whole-file diff, so a synthetic
+    // tool is required to cover both absent-title and empty-content result branches.
    const emptyDiffTool: ToolDefinition = {
      name: 'writer',
      description: 'writes a file',
@@ -728,11 +721,9 @@ describe('result-time diff card (REAL fs edit tool → tool_call_update diff blo
 })

 describe('relative-path display titles (bridge relativizes the title against the session cwd)', () => {
-  // The bridge relativizes a file card's TITLE against the session workspace cwd
-  // (mirroring the reference adapter's toDisplayPath), while leaving locations/
-  // diff paths RAW. Drive it with the REAL fs tools so the title/locations come
-  // from the shipping presentCall, and pass an ABSOLUTE file path (which a real
-  // editor forwards). The presenter is pure/args-only; the cwd is known only here.
+  // The bridge relativizes a file card's TITLE against the session workspace cwd (mirroring the
+  // reference adapter's `toDisplayPath`), while leaving location/diff paths raw. Use real fs tools
+  // and the absolute paths an editor supplies; presentation itself is args-only and lacks cwd.
  function callUpdate(ctx: Context, sessionCwd: string | undefined, name: string, args: unknown): SessionNotification['update'] {
    const presenter = new ToolPresenter(ctx.tools)
    const out: SessionNotification['update'][] = []
@@ -775,10 +766,9 @@ describe('relative-path display titles (bridge relativizes the title against the
  })

  it('an in-workspace file whose relative form starts with `..` chars (a sibling name) still relativizes', async () => {
-    // `/work/proj/..cache/x` is INSIDE the workspace — its relative form
-    // `..cache/x` begins with the chars `..` but is NOT a parent segment. The
-    // guard tests for a `..` SEGMENT, so this relativizes (matching the reference
-    // adapter, which accepts any target under `cwd + sep`).
+    // `/work/proj/..cache/x` is inside the workspace — its relative form `..cache/x` begins
+    // with the chars `..` but is not a parent segment. Segment-aware guarding must relativize it,
+    // matching targets under `cwd + sep` in the reference adapter.
    const ctx = await fsCtx()
    const update = callUpdate(ctx, '/work/proj', 'read', { file_path: '/work/proj/..cache/x.ts' })
    expect((update as { title: string }).title).toBe('Read ..cache/x.ts')
--- a/packages/ui/acp/tests/turns.spec.ts
+++ b/packages/ui/acp/tests/turns.spec.ts
@@ -124,11 +124,9 @@ describe('acp bridge — turn outcomes', () => {
  })

  it('with the terminal_output capability ON, a real bash call renders as a TERMINAL card (content + _meta + exit)', async () => {
-    // Drive the REAL bash tool, and advertise the Zed `_meta.terminal_output`
-    // capability in initialize. The bridge must then emit the terminal CARD: the
-    // description content block THEN a terminal content block + `_meta.terminal_info`
-    // (cwd header) on the call, and `_meta.terminal_output`/`terminal_exit` on the
-    // result — and OMIT the update's text content (it would clobber the card).
+    // With terminal output advertised, a real bash call emits description then terminal content
+    // plus cwd metadata; its result uses terminal output/exit metadata and omits text that would
+    // clobber the card.
    harness = await makeBridgeHarness({
      storageDir,
      withBash: true,
@@ -164,11 +162,8 @@ describe('acp bridge — turn outcomes', () => {
  })

  it('the terminal capability is snapshotted per-session: a later initialize cannot desync a call/result', async () => {
-    // The session is created with the capability ON. A SECOND initialize then
-    // turns it OFF at the connection level — but this session keeps its snapshot,
-    // so its bash call STILL renders as a terminal card (call + result agree).
-    // Without the snapshot, the result path would re-read the now-OFF capability
-    // and either clobber the card (content sent) or be inconsistent with the call.
+    // Create the session with terminal support, then disable it connection-wide. The session's
+    // snapshot must keep call and result rendering consistent instead of re-reading changed state.
    harness = await makeBridgeHarness({
      storageDir,
      withBash: true,
@@ -324,11 +319,9 @@ describe('acp bridge — turn outcomes', () => {
  })

  it('cancel right after prompt settles cancelled and leaves the agent idle, no leaked turn', async () => {
-    // Over the async JSON-RPC transport the loop usually wakes before cancel
-    // arrives, so this is a running/mid-step cancel (the synchronous pre-step
-    // DROP is unit-tested in agent-loop/cancel.spec.ts). The ACP-level guarantee:
-    // the prompt settles cancelled, the agent reaches idle, and no second/leaked
-    // turn runs afterward.
+    // JSON-RPC timing normally makes this a running mid-step cancellation; pre-step dropping is
+    // covered in agent-loop. Here the prompt must settle cancelled, return idle, and clear queued
+    // work so the scripted second response cannot leak into another turn.
    harness = await makeBridgeHarness({ storageDir, script: [textResponse('answer'), textResponse('leaked')] })
    const sessionId = await newSession(harness)
    const promptDone = harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })
@@ -337,18 +330,13 @@ describe('acp bridge — turn outcomes', () => {
    expect(res.stopReason).toBe('cancelled')
    const agent = harness.ctx.agents.get(SessionId(sessionId))!
    await agent.whenIdle()
-    // At most ONE turn ran (the cancelled one) — the cancel cleared the queue, so
-    // no second turn was batched or leaked. (A best-effort abort that left queued
-    // work could have started a second turn.)
    const turnStarts = agent.session.events.filter(e => e.type === 'turn/start').length
    expect(turnStarts).toBeLessThanOrEqual(1)
  })

  it('idle session/cancel then session/prompt runs the prompt (no intervening whenIdle)', async () => {
-    // The ACP bridge settles the cancel RPC synchronously and accepts the next
-    // prompt WITHOUT awaiting quiescence — so this drives cancel→prompt with NO
-    // whenIdle() between, the production race. An idle cancel must be a no-op that
-    // does NOT drop the following prompt.
+    // The bridge settles cancel synchronously, so exercise the production cancel→prompt race with
+    // no `whenIdle()`. An idle cancel must not mark or drop the following prompt.
    harness = await makeBridgeHarness({ storageDir, script: [textResponse('real answer')] })
    const sessionId = await newSession(harness)
    // Cancel while idle (no prompt in flight) — a no-op.
@@ -364,9 +352,8 @@ describe('acp bridge — turn outcomes', () => {
  })

  it('mid-stream cancel then an IMMEDIATE next prompt runs (no intervening whenIdle)', async () => {
-    // Cancel a running turn, then send the next prompt WITHOUT awaiting quiescence
-    // (the synchronous-settle path). The new prompt must run — the cancel marker
-    // must not leak onto it.
+    // Cancel a running turn and immediately send another prompt without awaiting quiescence. The
+    // cancellation marker belongs only to the first turn and must not drop the next request.
    harness = await makeBridgeHarness({ storageDir, script: ['hang', textResponse('next answer')] })
    const sessionId = await newSession(harness)
    const a = harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'A' }] })
@@ -384,10 +371,8 @@ describe('acp bridge — turn outcomes', () => {
  })

  it('a cancelled turn\'s late turn/end does not settle the NEXT prompt', async () => {
-    // Regression: prompt A runs; cancel settles A and frees the slot; A's
-    // aborted turn/end is still pending in the loop. Prompt B is sent before
-    // A's turn/end arrives. A's late turn/end (an EARLIER turn number) must NOT
-    // settle B — B owns a later turn. B then completes on its OWN turn/end.
+    // Cancellation frees A's slot before its aborted turn/end is appended. Send B in that window;
+    // correlation by turn number must prevent A's late closer from settling B as cancelled.
    harness = await makeBridgeHarness({ storageDir, script: ['hang', textResponse('B answer')] })
    const sessionId = await newSession(harness)

@@ -396,8 +381,7 @@ describe('acp bridge — turn outcomes', () => {
    await harness.client.cancel({ sessionId })
    expect((await a).stopReason).toBe('cancelled')

-    // Immediately send B; its turn (2) is distinct from A's (1). If A's late
-    // turn/end leaked onto B, B would settle 'cancelled' instead of 'end_turn'.
+    // B owns the later turn and must complete on its own turn/end.
    const b = await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'B' }] })
    expect(b.stopReason).toBe('end_turn')
    const text = harness.updates