Merge remote-tracking branch 'origin/master' into codex/pr335-merge-master-20260719

# Conflicts: # packages/support/acp-snapshot/README.md # packages/support/acp-snapshot/src/harness.ts # packages/support/acp-snapshot/src/suite.ts # packages/support/acp-snapshot/tests/harness.spec.ts # packages/support/acp-snapshot/tests/suite.spec.ts
2026-07-19 11:41:10 +08:00
parent 64f64724e5 383a305bd4
commit 39c1c3df4f
330 changed files with 7947 additions and 4450 deletions
--- a/packages/subagent/subagent-acp/README.md
+++ b/packages/subagent/subagent-acp/README.md
@@ -6,6 +6,8 @@ The ACP provider runs each subagent in a fresh subprocess and drives it as an Ag

 `start(request)` performs `spawn` → ACP `initialize` → `newSession` before it fulfills. Fulfillment therefore means a remote session is ready and ownership has transferred to the caller. A spawn, initialization, new-session, or pre-publication cancellation failure rejects only after the subprocess has been reaped.

+The returned run id is minted in the parent namespace. The child server's session id remains private to ACP wire calls because ACP guarantees it only within that fresh child process; using it as the parent lifecycle id could collide with another remote run or a local agent.
+
 After publication, the provider sends the prompt and collects streamed `agent_message_chunk` text into `SubagentResult.output`. A prompt/transport failure resolves with `stopReason: 'error'`, or `aborted` when the required request signal or disposal requested cancellation.

 `dispose()` is idempotent. It removes the signal listener, requests ACP cancellation when possible, closes stdin, and waits `disposeEofGraceMs`. POSIX then escalates through SIGTERM and `disposeGraceMs` before SIGKILL; Windows force-terminates directly because Node maps both signals to `TerminateProcess`. Disposal resolves only after child exit. Every run uses a fresh process; process pooling is not implemented.
--- a/packages/subagent/subagent-acp/package.json
+++ b/packages/subagent/subagent-acp/package.json
@@ -24,6 +24,7 @@
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
    "@deepseek-ai/dsh-subagent": "^0.0.1",
    "@deepseek-ai/dsh-subagent-subprocess": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
@@ -36,6 +37,7 @@
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-loader-smoke": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-subagent": "workspace:^",
    "@deepseek-ai/dsh-subagent-subprocess": "workspace:^",
    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
--- a/packages/subagent/subagent-acp/src/run.ts
+++ b/packages/subagent/subagent-acp/src/run.ts
@@ -23,8 +23,8 @@ import {
  type SessionNotification,
  type StopReason,
 } from '@agentclientprotocol/sdk'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { SessionId } from '@deepseek-ai/dsh-session'
 import type { SubagentResult, SubagentRun, SubagentStartRequest, SubagentStopReason } from '@deepseek-ai/dsh-subagent'
 import { buildChildEnv, disposeChildProcess, spawnFailure } from '@deepseek-ai/dsh-subagent-subprocess'

@@ -149,9 +149,11 @@ function toError(value: unknown): Error {
 * @returns the ready run handle for the child subprocess.
 */
 export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpec): Promise<SubagentRun> {
-  const id = AgentId(randomUUID())
-
  if (request.signal.aborted) throw new Error('subagent request was aborted before the ACP child started')
+  // ACP session ids are unique only within the child server. The lifecycle id
+  // is minted in the parent namespace so fresh processes cannot collide with
+  // each other or with a local agent that happens to use the same session id.
+  const id = SessionId(randomUUID())

  // Keep diagnostics on parent stderr; only ACP output contributes to the result.
  const child = spawn(spec.command, spec.args, {
@@ -241,7 +243,9 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe
          clientCapabilities: {},
        })
        const session = await conn.newSession({ cwd: spec.cwd, mcpServers: [] })
-        sessionId = session.sessionId
+        const returnedSessionId: unknown = Reflect.get(session, 'sessionId')
+        if (typeof returnedSessionId !== 'string') throw new Error('ACP child published without a session id')
+        sessionId = returnedSessionId
        if (flags.cancelled) throw new Error('subagent cancelled before the ACP session started')
      })(),
      spawnFailed.then((err): never => { throw err }),
@@ -253,13 +257,18 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe
    if (flags.cancelled) throw new Error('subagent request was aborted before the ACP child started')
    throw toError(error)
  }
+  // The startup transaction validates the returned id before it can fulfill.
+  // This assertion carries that cross-closure invariant into TypeScript.
+  /* v8 ignore next */
+  if (sessionId === undefined) throw new Error('unreachable: ACP startup fulfilled without a session id')
+  const remoteSessionId = sessionId

  const result: Promise<SubagentResult> = (async (): Promise<SubagentResult> => {
    try {
      // Race the remote turn against local cancellation.
      const prompt = async (): Promise<SubagentResult> => {
        // The startup phase cannot fulfill without assigning the session id.
-        const promptResult = await conn.prompt({ sessionId: sessionId as string, prompt: toAcpPrompt(request.prompt) })
+        const promptResult = await conn.prompt({ sessionId: remoteSessionId, prompt: toAcpPrompt(request.prompt) })
        return { output: collectOutput(), stopReason: acpStopReason(promptResult.stopReason) }
      }
      return await Promise.race([
@@ -285,6 +294,7 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe
  let disposal: Promise<void> | undefined
  return {
    id,
+    localAgent: undefined,
    result,
    dispose(): Promise<void> {
      if (disposal !== undefined) return disposal
--- a/packages/subagent/subagent-acp/tests/mock-acp-server.ts
+++ b/packages/subagent/subagent-acp/tests/mock-acp-server.ts
@@ -1,9 +1,45 @@
 /**
- * Minimal no-network ACP child process for keyless backend tests. Environment variables script its
- * text and stop reason, a cancel-cooperative or cancel-ignoring hang, permission requests, and a
- * readiness marker. Disposal fixtures can delay an EOF flush, ignore EOF but exit and mark
- * SIGTERM, or trap SIGTERM to require SIGKILL. The specs run this protocol-only fixture directly
- * with Node's type stripping; it imports no harness code or workspace paths.
+ * A minimal mock ACP AGENT, run as a subprocess, for the keyless
+ * `dsh-subagent-acp` tests. It speaks the agent side of ACP over stdio and is
+ * fully scripted by environment variables — no model, no network:
+ *
+ * - `MOCK_TEXT`        — the assistant text it streams as one `agent_message_chunk`.
+ * - `MOCK_STOP`        — the ACP `StopReason` it returns from `prompt`
+ *                        (`end_turn` default, or `max_tokens`/`refusal`/…).
+ * - `MOCK_HANG`        — if `1`, `prompt` never resolves on its own (it waits for
+ *                        a `session/cancel`), to exercise the client's cancel path.
+ * - `MOCK_IGNORE_CANCEL` — if `1` (with MOCK_HANG), the agent receives
+ *                        `session/cancel` but NEVER resolves the pending prompt
+ *                        and never exits — a non-cooperative child. The backend's
+ *                        `result` must still settle `aborted` on its own and
+ *                        `dispose()` must still kill the process.
+ * - `MOCK_PERMISSION`  — if `1`, the agent calls `session/request_permission`
+ *                        before answering, to exercise the client's auto-answer.
+ * - `MOCK_READY_FILE`  — if set, the path the agent touches once its `prompt`
+ *                        handler is in flight (it has streamed its chunk). A test
+ *                        polls for this file to cancel on a CONDITION rather than
+ *                        an arbitrary timeout (subprocess cold-start is variable).
+ * - `MOCK_MISSING_SESSION_ID` — if `1`, return a malformed empty `session/new`
+ *                        response to exercise startup rollback.
+ * - `MOCK_FLUSH_ON_EOF` — if set, on stdin EOF the agent takes an async beat
+ *                         (MOCK_FLUSH_DELAY_MS, default 150) simulating the real
+ *                         acp-agent's EOF-driven quiesce+flush, then touches this
+ *                         path and exits ON ITS OWN — no signal. Stands in for a
+ *                         child whose durable flush completes only if dispose
+ *                         gives EOF a real window before escalating to SIGTERM.
+ * - `MOCK_IGNORE_EOF`   — if `1`, keep the event loop alive past stdin EOF (a bare
+ *                         timer) but install a SIGTERM handler that exits (and, if
+ *                         MOCK_SIGTERM_FILE is set, touches it as an observable
+ *                         proof the SIGTERM rung fired). The child ignores the
+ *                         graceful EOF window yet dies cooperatively on SIGTERM —
+ *                         exercising dispose's middle tier (exit during the SIGTERM
+ *                         grace, before the SIGKILL escalation). Touches
+ *                         MOCK_READY_FILE once armed.
+ *
+ * It is not a test spec: the specs launch this protocol-only fixture through
+ * the mode-aware example resolver (tsx in source mode, Node type stripping in
+ * built mode). It imports no harness code or workspace paths.
+ *
 * @module @deepseek-ai/dsh-subagent-acp/tests/mock-acp-server
 */

@@ -64,7 +100,8 @@ function makeAgent(conn: AgentSideConnection): Agent {
        writeFileSync(NEWSESSION_GATE.ready, 'at-newSession')
        while (!existsSync(NEWSESSION_GATE.go)) await new Promise(r => setTimeout(r, 10))
      }
-      return { sessionId: randomUUID() }
+      if (process.env.MOCK_MISSING_SESSION_ID === '1') return {} as NewSessionResponse
+      return { sessionId: process.env.MOCK_SESSION_ID ?? randomUUID() }
    },
    authenticate(_params: AuthenticateRequest): Promise<void> {
      // No auth methods advertised; nothing to do.
@@ -124,8 +161,11 @@ function makeAgent(conn: AgentSideConnection): Agent {
        process.exit(1)
      }
      if (IGNORE_CANCEL) {
-        // A non-cooperative child receives cancellation but neither resolves nor exits. The
-        // backend must still settle `aborted`, and disposal must kill the process.
+        // A NON-COOPERATIVE child: receive session/cancel but never resolve the
+        // pending prompt and never exit. The backend's `result` must still settle
+        // `aborted` on its own (the cancel-settle race), and `dispose()` must
+        // still kill the process — proving cancellation does not depend on the
+        // child cooperating.
        return Promise.resolve()
      }
      resolveCancel?.('cancelled')
@@ -142,9 +182,12 @@ new AgentSideConnection(
  ),
 )

-// Under MOCK_TRAP_SIGTERM, ignore SIGTERM and keep stdin open so the process neither quiesces
-// on EOF nor dies on the graceful signal — exercising the backend dispose path's SIGKILL
-// escalation. READY_FILE proves the trap was armed before the test disposes the run.
+// Under MOCK_TRAP_SIGTERM, ignore SIGTERM and keep stdin open so the process
+// neither quiesces on EOF nor dies on the graceful signal — exercising the
+// backend dispose path's SIGKILL escalation. Without this the process exits
+// normally on SIGTERM / stdin end. Touch READY_FILE once the trap is armed, so
+// a test waits for that CONDITION before disposing (the trap must be in place,
+// not merely the process spawned — otherwise SIGTERM hits the default handler).
 if (process.env.MOCK_TRAP_SIGTERM === '1') {
  process.on('SIGTERM', () => { /* trapped: refuse to exit on the graceful signal */ })
  // Keep the event loop alive (a bare timer) so nothing else lets it exit.
@@ -152,10 +195,13 @@ if (process.env.MOCK_TRAP_SIGTERM === '1') {
  if (READY_FILE !== undefined) writeFileSync(READY_FILE, 'trap-armed')
 }

-// Under MOCK_FLUSH_ON_EOF, model the real acp-agent's EOF-driven quiesce: on stdin 'end' (the
-// dispose path's `child.stdin.end()`), take an ASYNC beat to "flush", then touch the marker and
-// exit on its own. A signal sent before MOCK_FLUSH_DELAY_MS would suppress the marker, so it proves
-// the EOF grace window was long enough for durable flush.
+// Under MOCK_FLUSH_ON_EOF, model the real acp-agent's EOF-driven quiesce: on
+// stdin 'end' (the dispose path's `child.stdin.end()`), take an ASYNC beat to
+// "flush", then touch the marker and exit ON OUR OWN — no signal involved. The
+// beat is MOCK_FLUSH_DELAY_MS (default 150). A dispose that sends SIGTERM before
+// the beat completes (no graceful window, or an EOF grace shorter than the
+// flush) default-terminates this process and the marker is missing; a dispose
+// that gives the EOF quiesce enough window first lets the flush land.
 if (FLUSH_ON_EOF !== undefined) {
  const flushDelayMs = Number(process.env.MOCK_FLUSH_DELAY_MS ?? '150')
  process.stdin.on('end', () => {
@@ -166,9 +212,14 @@ if (FLUSH_ON_EOF !== undefined) {
  })
 }

-// Ignore EOF but exit on SIGTERM to exercise the middle disposal tier before SIGKILL. The signal
-// marker distinguishes that catchable rung from an immediate, uncatchable SIGKILL; READY_FILE
-// proves the handler was armed before disposal.
+// Under MOCK_IGNORE_EOF, keep the loop alive past stdin EOF (so the graceful EOF
+// window times out) but INSTALL A SIGTERM HANDLER that records it and exits — the
+// child ignores the graceful EOF window yet dies cooperatively on SIGTERM,
+// exercising dispose's MIDDLE tier (exit during the SIGTERM grace, before the
+// SIGKILL escalation). When MOCK_SIGTERM_FILE is set the handler touches it, an
+// OBSERVABLE proof that the SIGTERM rung fired: if dispose skipped the middle
+// rung and jumped EOF→SIGKILL, SIGKILL is uncatchable so the handler never runs
+// and the marker is missing. Touch READY_FILE once armed (a test waits on it).
 if (process.env.MOCK_IGNORE_EOF === '1') {
  const sigtermFile = process.env.MOCK_SIGTERM_FILE
  process.on('SIGTERM', () => {
--- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
+++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
@@ -6,7 +6,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import SubagentService from '@deepseek-ai/dsh-subagent'
-import { buildChildEnv, SENSITIVE_ENV_PATTERN } from '@deepseek-ai/dsh-subagent-subprocess'
+import { buildChildEnv } from '@deepseek-ai/dsh-subagent-subprocess'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import * as acp from '../src/index.ts'
 import { acpStopReason, acpContentText, DEFAULT_DISPOSE_EOF_GRACE_MS, DEFAULT_DISPOSE_GRACE_MS, startAcpRun, toAcpPrompt, type AcpRunSpec } from '../src/run.ts'
@@ -58,7 +58,7 @@ function text(blocks: { type: string; text?: string }[]): string {
 /**
 * Poll until `file` exists (the mock touches it once its prompt is in flight),
 * so a cancel test waits on a CONDITION rather than an arbitrary timeout — the
- * subprocess cold-start under tsx is variable, and a fixed sleep both flakes and
+ * subprocess cold-start is variable, and a fixed sleep both flakes and
 * slows the suite. Fails loud if the child never signals readiness.
 */
 async function waitForFile(file: string, timeoutMs = 5000): Promise<void> {
@@ -108,7 +108,6 @@ describe('buildChildEnv', () => {
      // The explicitly-supplied key survives (an opt-in for the child's creds).
      expect(env.DEEPSEEK_API_KEY).toBe('explicit')
      // A normal ambient var is forwarded.
-      expect(SENSITIVE_ENV_PATTERN.test('PATH')).toBe(false)
      expect(env.PATH).toBe(process.env.PATH)
    } finally {
      delete process.env.DSH_ACP_TEST_SECRET_TOKEN
@@ -117,15 +116,22 @@ describe('buildChildEnv', () => {
 })

 describe('dsh-subagent-acp', () => {
-  it('drives a child process to completion and returns its streamed output', async () => {
-    const ctx = await setup({ MOCK_TEXT: 'hello from acp child', MOCK_STOP: 'end_turn' })
+  it('drives child processes with parent-unique run ids and returns streamed output', async () => {
+    const ctx = await setup({ MOCK_TEXT: 'hello from acp child', MOCK_STOP: 'end_turn', MOCK_SESSION_ID: 'acp-child-session' })
    const run = await ctx.subagents.start('acp', request('do X'))
+    expect(run.id).not.toBe('acp-child-session')
    const result = await run.result
    expect(result.stopReason).toBe('completed')
    expect(text(result.output)).toBe('hello from acp child')
    const disposal = run.dispose()
    expect(run.dispose()).toBe(disposal)
    await disposal
+
+    const nextRun = await ctx.subagents.start('acp', request('do X again'))
+    expect(nextRun.id).not.toBe(run.id)
+    expect(nextRun.id).not.toBe('acp-child-session')
+    await nextRun.result
+    await nextRun.dispose()
  })

  it('maps a max_tokens stop reason', async () => {
@@ -184,6 +190,31 @@ describe('dsh-subagent-acp', () => {
    }
  })

+  it('reaps a child whose session/new response omits the session id', async () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'acp-malformed-session-'))
+    const flushed = join(tmp, 'flushed')
+    try {
+      await expect(startAcpRun(request(), {
+        command: process.execPath,
+        args: [mockServer],
+        cwd: process.cwd(),
+        permission: 'reject',
+        env: {
+          MOCK_MISSING_SESSION_ID: '1',
+          MOCK_FLUSH_ON_EOF: flushed,
+          MOCK_FLUSH_DELAY_MS: '20',
+        },
+        disposeEofGraceMs: 1000,
+        disposeGraceMs: 100,
+      })).rejects.toThrow('ACP child published without a session id')
+      // Startup rejects only after its private child reaches quiescence. The
+      // marker proves rollback closed stdin and allowed the child's EOF flush.
+      expect(existsSync(flushed)).toBe(true)
+    } finally {
+      rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+
  it('dispose escalates SIGTERM → SIGKILL for a child that traps SIGTERM (bounded quiescence)', async () => {
    // The child traps SIGTERM and keeps its event loop alive, so a graceful
    // term alone would hang dispose forever. With a short grace, dispose must
--- a/packages/subagent/subagent-fork/README.md
+++ b/packages/subagent/subagent-fork/README.md
@@ -6,7 +6,7 @@ The fork provider creates an in-process child seeded with the parent's completed

 The parent's current tool-calling turn is still open when a subagent starts: its log contains the assistant tool call but not the matching tool result or `turn/end`. Copying that raw log would give the child an invalid, unbalanced session.

-Fork therefore uses `completedTurnPrefix(parent.session.events)`: the contiguous prefix ending at the last `turn/end`. The child sees all completed parent turns and none of the in-flight turn. If the parent has not completed a turn yet, the seed is empty and the child behaves like a fresh spawn.
+Fork therefore computes the contiguous prefix ending at the last `turn/end`. The child sees all completed parent turns and none of the in-flight turn. If the parent has not completed a turn yet, the seed is empty and the child behaves like a fresh spawn.

 The seed transfers conversation history only. The child still receives a fresh flat registration scope; it does not inherit the parent's tool restrictions or authority.

--- a/packages/subagent/subagent-fork/src/index.ts
+++ b/packages/subagent/subagent-fork/src/index.ts
@@ -39,7 +39,7 @@ export const Config: z<Config> = z.object({
 * @param parent - the agent whose session log to slice.
 * @returns the seed events, contiguous from seq 0; empty when no turn has completed.
 */
-export function completedTurnPrefix(parent: Agent): SessionEvent[] {
+function completedTurnPrefix(parent: Agent): SessionEvent[] {
  const events = parent.session.events
  const lastEnd = events.findLast(e => e.type === 'turn/end')
  if (lastEnd === undefined) return []
--- a/packages/subagent/subagent-fork/tests/multi-subagent.spec.ts
+++ b/packages/subagent/subagent-fork/tests/multi-subagent.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import { AgentId } from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import * as Invariants from '@deepseek-ai/dsh-invariants'
@@ -30,7 +30,7 @@ async function setup(script: Script) {
  await ctx.plugin(Spawn, { providerName: 'spawn' })
  await ctx.plugin(fork, { providerName: 'fork' })
  ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
-  const parent = ctx.agentLoop.create(AgentId('parent'), { provider: 'mock', model: 'mock' })
+  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
  return { ctx, parent }
 }

--- a/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts
+++ b/packages/subagent/subagent-fork/tests/subagent-fork.spec.ts
@@ -1,7 +1,8 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import * as Invariants from '@deepseek-ai/dsh-invariants'
@@ -10,7 +11,6 @@ import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent
 import type { StreamChunk } from '@deepseek-ai/dsh-llm'
 import * as fork from '../src/index.ts'
 import { STRUCTURED_OUTPUT_TOOL } from '@deepseek-ai/dsh-subagent-inprocess'
-import { completedTurnPrefix } from '../src/index.ts'

 type Script = ConstructorParameters<typeof MockAdapter>[0]

@@ -36,7 +36,7 @@ async function setup(script: Script) {
  await ctx.plugin(SubagentService)
  await ctx.plugin(fork, { providerName: 'fork' })
  ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
-  const parent = ctx.agentLoop.create(AgentId('parent'), { provider: 'mock', model: 'mock' })
+  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
  return { ctx, parent }
 }

@@ -44,28 +44,6 @@ function text(blocks: { type: string; text?: string }[]): string {
  return blocks.filter(b => b.type === 'text').map(b => b.text).join('')
 }

-describe('completedTurnPrefix', () => {
-  it('returns an empty prefix for a parent that has never completed a turn', async () => {
-    const { parent } = await setup([])
-    expect(completedTurnPrefix(parent)).toEqual([])
-  })
-
-  it('returns the balanced prefix up to and including the last turn/end', async () => {
-    const { parent } = await setup([textResponse('first'), textResponse('second')])
-    parent.send([{ type: 'text', text: 'q1' }])
-    await parent.whenIdle()
-    parent.send([{ type: 'text', text: 'q2' }])
-    await parent.whenIdle()
-
-    const prefix = completedTurnPrefix(parent)
-    // Ends exactly at the last turn/end; seq is contiguous from 0.
-    expect(prefix.at(-1)?.type).toBe('turn/end')
-    expect(prefix.map(e => e.seq)).toEqual(prefix.map((_, i) => i))
-    // Both completed turns are present.
-    expect(prefix.filter(e => e.type === 'turn/end')).toHaveLength(2)
-  })
-})
-
 describe('dsh-subagent-fork', () => {
  it('emits subagent/start only after the seeded child is published', async () => {
    const { ctx, parent } = await setup([textResponse('child answer')])
@@ -88,7 +66,6 @@ describe('dsh-subagent-fork', () => {
    // The parent has never completed a turn → empty prefix → the provider omits
    // the seed → the child runs fresh. Exercises the `seed.length > 0` false arm.
    const { ctx, parent } = await setup([textResponse('fresh child')])
-    expect(completedTurnPrefix(parent)).toEqual([])
    const run = await start(ctx, 'fork', { prompt: [{ type: 'text', text: 'child q' }], parent })
    const result = await run.result
    expect(result.stopReason).toBe('completed')
@@ -96,6 +73,24 @@ describe('dsh-subagent-fork', () => {
    const child = ctx.agents.get(run.id)!
    // Only the child's own turn — no seeded parent turns.
    expect(child.session.events.filter(e => e.type === 'turn/end')).toHaveLength(1)
+    expect(child.session.header.seedLength).toBeUndefined()
+    await run.dispose()
+  })
+
+  it('seeds every completed parent turn through the last turn/end', async () => {
+    const { ctx, parent } = await setup([textResponse('first'), textResponse('second'), textResponse('child')])
+    parent.send([{ type: 'text', text: 'q1' }])
+    await parent.whenIdle()
+    parent.send([{ type: 'text', text: 'q2' }])
+    await parent.whenIdle()
+    const parentPrefixLen = parent.session.events.length
+
+    const run = await start(ctx, 'fork', { prompt: [{ type: 'text', text: 'child q' }], parent })
+    await run.result
+    const child = ctx.agents.get(run.id)!
+    expect(child.session.header.seedLength).toBe(parentPrefixLen)
+    expect(child.session.events.slice(0, parentPrefixLen).at(-1)?.type).toBe('turn/end')
+    expect(child.session.events.slice(0, parentPrefixLen).filter(e => e.type === 'turn/end')).toHaveLength(2)
    await run.dispose()
  })

--- a/packages/subagent/subagent-inprocess/README.md
+++ b/packages/subagent/subagent-inprocess/README.md
@@ -26,7 +26,7 @@ After fulfillment, the caller owns the run. Provider-plugin unload does not revo

 `InProcessRunOptions` is `{ seed?: SessionEvent[] }`. Spawn omits it. Fork supplies a balanced completed-turn prefix and records its length so the result reader never mistakes a seeded parent message for child output.

-`depthOf(agent)` reads `AgentOptions.subagentDepth`, treating absence as top-level depth zero and rejecting malformed stored values. `SubagentDepthError` reports an attempted child depth above `maxDepth`; an unrepresentable depth above the safe-integer domain is a `RangeError`.
+Depth enforcement is internal to `startInProcessRun`: it reads `AgentOptions.subagentDepth`, treats absence as top-level depth zero, rejects malformed stored values, and reports an attempted child depth above `maxDepth`. An unrepresentable depth above the safe-integer domain is a `RangeError`.

 ## Structured output

--- a/packages/subagent/subagent-inprocess/src/index.ts
+++ b/packages/subagent/subagent-inprocess/src/index.ts
@@ -9,7 +9,7 @@

 import { randomUUID } from 'node:crypto'
 import type { Context } from 'cordis'
-import { AgentId, type Agent, type AgentOptions } from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentOptions } from '@deepseek-ai/dsh-agent'
 import { SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { assertSubagentMaxDepth } from '@deepseek-ai/dsh-subagent'
@@ -36,7 +36,7 @@ declare module '@deepseek-ai/dsh-agent' {
 * @param agent - the agent whose options carry the depth.
 * @returns its non-negative safe-integer depth.
 */
-export function depthOf(agent: Agent): number {
+function depthOf(agent: Agent): number {
  const depth = agent.options.subagentDepth
  if (depth === undefined) return 0
  if (!Number.isSafeInteger(depth) || depth < 0 || Object.is(depth, -0)) {
@@ -46,7 +46,7 @@ export function depthOf(agent: Agent): number {
 }

 /** Thrown when starting a child would exceed the requested depth cap. */
-export class SubagentDepthError extends Error {
+class SubagentDepthError extends Error {
  constructor(public readonly attemptedDepth: number, public readonly maxDepth: number) {
    super(`subagent depth ${attemptedDepth} exceeds maxDepth ${maxDepth}`)
    this.name = 'SubagentDepthError'
@@ -104,7 +104,7 @@ export async function startInProcessRun(
    throw new SubagentDepthError(childDepth, request.maxDepth)
  }

-  const childId = AgentId(randomUUID())
+  const childId = SessionId(randomUUID())
  const seedLength = options.seed?.length ?? 0
  const parentHeader = parent.session.header
  const parentProvider = parent.options.provider
@@ -129,8 +129,7 @@ export async function startInProcessRun(

  const flags = { cancelled: false }
  const handle = await parent.ctx.agents.create({
-    agentId: childId,
-    sessionId: SessionId(randomUUID()),
+    sessionId: childId,
    meta: {
      ...parentHeader.cwd !== undefined ? { cwd: parentHeader.cwd } : {},
      parentSession: parentHeader.id,
@@ -176,6 +175,7 @@ export async function startInProcessRun(

  return {
    id: childId,
+    localAgent: child,
    result,
    dispose(): Promise<void> {
      request.signal.removeEventListener('abort', onAbort)
--- a/packages/subagent/subagent-inprocess/tests/structured.spec.ts
+++ b/packages/subagent/subagent-inprocess/tests/structured.spec.ts
@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { CallId, type ContentBlock, type GenerateOptions } from '@deepseek-ai/dsh-llm'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import type { ContinuationDecision } from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import * as Invariants from '@deepseek-ai/dsh-invariants'
@@ -61,7 +61,7 @@ async function setup(script: Script, options: SetupOptions = {}) {
    start: (request: SubagentStartRequest) => startInProcessRun(request, {}),
  })
  ctx.llm.registerAdapter(['mock'], adapter)
-  const parent = ctx.agentLoop.create(AgentId('parent'), { provider: 'mock', model: 'mock' })
+  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
  return { ctx, parent, adapter, disposeProvider }
 }

@@ -322,7 +322,7 @@ describe('in-process structured output', () => {
    await expect(ctx.subagents.start('spawn', structuredRequest(parent, {
      outputSchema: { type: 'object', oneOf: [] } as unknown as StructuredOutputSchema,
    }))).rejects.toThrow(/unsupported output schema/)
-    expect(ctx.agents.get(AgentId('parent'))).toBeDefined()
+    expect(ctx.agents.get(SessionId('parent'))).toBeDefined()
  })

  it('a schema carrying non-JSON values fails as OutputSchemaError at the validation boundary', async () => {
--- a/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts
+++ b/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts
@@ -1,12 +1,13 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import { AgentId, type Agent } from '@deepseek-ai/dsh-agent'
+import { type Agent } from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import * as Invariants from '@deepseek-ai/dsh-invariants'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
-import { depthOf, SubagentDepthError, startInProcessRun } from '../src/index.ts'
+import { startInProcessRun } from '../src/index.ts'

 type Script = ConstructorParameters<typeof MockAdapter>[0]

@@ -17,7 +18,7 @@ async function setup(script: Script) {
  await ctx.plugin(AgentLoop, { agents: [] })
  await ctx.plugin(SubagentService)
  ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
-  const parent = ctx.agentLoop.create(AgentId('parent'), { provider: 'mock', model: 'mock' })
+  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
  return { ctx, parent }
 }

@@ -29,19 +30,6 @@ function text(blocks: readonly { type: string; text?: string }[]): string {
  return blocks.filter(block => block.type === 'text').map(block => block.text).join('')
 }

-describe('depthOf', () => {
-  it('reads zero for a top-level agent and an explicit child depth', async () => {
-    const { parent } = await setup([])
-    expect(depthOf(parent)).toBe(0)
-    expect(depthOf({ options: { subagentDepth: 3 } } as unknown as Agent)).toBe(3)
-  })
-
-  it.each([Number.NaN, 1.5, -1, -0, Number.MAX_SAFE_INTEGER + 1])('rejects malformed depth %s', (value) => {
-    expect(() => depthOf({ options: { subagentDepth: value } } as unknown as Agent))
-      .toThrow('non-negative safe integer')
-  })
-})
-
 describe('startInProcessRun', () => {
  it('returns only after publication, drives a fresh child, and disposes it', async () => {
    const { ctx, parent } = await setup([textResponse('driver answer')])
@@ -50,7 +38,7 @@ describe('startInProcessRun', () => {
    const result = await run.result
    expect(result.stopReason).toBe('completed')
    expect(text(result.output)).toBe('driver answer')
-    expect(depthOf(ctx.agents.get(run.id)!)).toBe(1)
+    expect(ctx.agents.get(run.id)!.options.subagentDepth).toBe(1)
    await run.dispose()
    await run.dispose()
    expect(ctx.agents.get(run.id)).toBeUndefined()
@@ -75,7 +63,12 @@ describe('startInProcessRun', () => {
    await expect(startInProcessRun({ ...request(parent), maxDepth: -1 }, {}))
      .rejects.toThrow('non-negative safe integer')
    await expect(startInProcessRun({ ...request(parent), maxDepth: 0 }, {}))
-      .rejects.toBeInstanceOf(SubagentDepthError)
+      .rejects.toMatchObject({ name: 'SubagentDepthError' })
+    for (const value of [Number.NaN, 1.5, -1, -0, Number.MAX_SAFE_INTEGER + 1]) {
+      const malformed = { options: { subagentDepth: value } } as unknown as Agent
+      await expect(startInProcessRun(request(malformed), {}))
+        .rejects.toThrow('agent subagentDepth must be a non-negative safe integer')
+    }
    const maxParent = { options: { subagentDepth: Number.MAX_SAFE_INTEGER } } as unknown as Agent
    await expect(startInProcessRun(request(maxParent), {})).rejects.toBeInstanceOf(RangeError)
  })
--- a/packages/subagent/subagent-spawn/tests/spawn.e2e.ts
+++ b/packages/subagent/subagent-spawn/tests/spawn.e2e.ts
@@ -3,8 +3,8 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import type { Context } from 'cordis'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { spawnHarness, waitForIdle } from './harness.ts'
+import { SessionId } from '@deepseek-ai/dsh-session'

 /**
 * With-key smoke for the in-process spawn backend: a REAL parent agent delegates
@@ -29,7 +29,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('spawn backend with-key smoke', (
  it('a parent delegates to a child that writes a file on disk', async () => {
    workdir = await mkdtemp(join(tmpdir(), 'dsh-subagent-spawn-e2e-'))
    ctx = await spawnHarness(workdir)
-    const parent = ctx.agentLoop.create(AgentId('e2e-parent'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
+    const parent = ctx.agentLoop.create(SessionId('e2e-parent'), { provider: 'deepseek', model: 'deepseek-v4-flash' })

    parent.send([{ type: 'text', text:
      'Use the subagent tool to delegate this exact task: "Use the bash tool to write the text '
--- a/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts
+++ b/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
@@ -9,7 +9,7 @@ import * as Invariants from '@deepseek-ai/dsh-invariants'
 import SubagentService, { type SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
 import { MockAdapter, maxTokensResponse, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 import * as spawn from '../src/index.ts'
-import { depthOf, STRUCTURED_OUTPUT_TOOL, SubagentDepthError } from '@deepseek-ai/dsh-subagent-inprocess'
+import { STRUCTURED_OUTPUT_TOOL } from '@deepseek-ai/dsh-subagent-inprocess'

 type Script = ConstructorParameters<typeof MockAdapter>[0]

@@ -29,7 +29,7 @@ async function setup(script: Script) {
  await ctx.plugin(SubagentService)
  await ctx.plugin(spawn, { providerName: 'spawn' })
  ctx.llm.registerAdapter(['mock'], adapter)
-  const parent = ctx.agentLoop.create(AgentId('parent'), { provider: 'mock', model: 'mock' })
+  const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
  return { ctx, parent, adapter }
 }

@@ -110,11 +110,11 @@ describe('dsh-subagent-spawn', () => {

  it('stamps child depth = parent depth + 1 (via the merged AgentOptions field)', async () => {
    const { ctx, parent } = await setup([textResponse('x')])
-    expect(depthOf(parent)).toBe(0)
+    expect(parent.options.subagentDepth).toBeUndefined()
    const run = await start(ctx, 'spawn', { prompt: [{ type: 'text', text: 'p' }], parent })
    await run.result
    const child = ctx.agents.get(run.id)!
-    expect(depthOf(child)).toBe(1)
+    expect(child.options.subagentDepth).toBe(1)
    await run.dispose()
  })

@@ -122,7 +122,7 @@ describe('dsh-subagent-spawn', () => {
    const { ctx, parent } = await setup([])
    // parent is depth 0, child would be depth 1 — cap at 0 forbids any child.
    await expect(start(ctx, 'spawn', { prompt: [{ type: 'text', text: 'p' }], parent, maxDepth: 0 }))
-      .rejects.toThrow(SubagentDepthError)
+      .rejects.toThrow('subagent depth 1 exceeds maxDepth 0')
  })

  it('maps a child that hit its token ceiling to stopReason "max-tokens"', async () => {
@@ -225,7 +225,6 @@ describe('dsh-subagent-spawn', () => {
    const { ctx } = await setup([textResponse('x')])
    // A parent WITH a cwd (config agents have none, so create one explicitly).
    const parentHandle = await ctx.agents.create({
-      agentId: AgentId('cwd-parent'),
      sessionId: SessionId('cwd-parent-session'),
      meta: { cwd: '/tmp/parent-workspace' },
      agentOptions: { provider: 'mock', model: 'mock' },
@@ -242,7 +241,6 @@ describe('dsh-subagent-spawn', () => {
    const { ctx } = await setup([textResponse('explicit model child')])
    // A parent with NO model (its own turns would need one supplied per-request).
    const parentHandle = await ctx.agents.create({
-      agentId: AgentId('modelless-parent'),
      sessionId: SessionId('modelless-parent-session'),
      agentOptions: {},
    })
@@ -302,7 +300,7 @@ describe('dsh-subagent-spawn', () => {
    await ctx.plugin(SubagentService)
    const fiber = await ctx.plugin(spawn, { providerName: 'spawn' })
    ctx.llm.registerAdapter(['mock'], adapter)
-    const parent = ctx.agentLoop.create(AgentId('parent'), { provider: 'mock', model: 'mock' })
+    const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
    const controller = new AbortController()
    const run = await start(ctx, 'spawn', {
      prompt: [{ type: 'text', text: 'q' }],
@@ -329,7 +327,7 @@ describe('dsh-subagent-spawn', () => {
    await ctx.plugin(AgentLoop, { agents: [] })
    await ctx.plugin(SubagentService)
    const fiber = await ctx.plugin(spawn, { providerName: 'spawn' })
-    const parent = ctx.agentLoop.create(AgentId('parent'), { provider: 'mock', model: 'mock' })
+    const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
    const parentEffects = parent.ctx.fiber.getEffects().length
    const published: string[] = []
    ctx.on('session/created', () => void published.push('session/created'))
@@ -422,7 +420,6 @@ describe('dsh-subagent-spawn', () => {
    const { ctx } = await setup([])
    // A handle-owned parent we can dispose (config agents dispose with the loop fiber).
    const parentHandle = await ctx.agents.create({
-      agentId: AgentId('doomed-parent'),
      sessionId: SessionId('doomed-s'),
      agentOptions: { provider: 'mock', model: 'mock' },
    })
@@ -445,7 +442,6 @@ describe('dsh-subagent-spawn', () => {
  it('parent disposal during the child setup transaction prevents every publication notification', async () => {
    const { ctx } = await setup([])
    const parentHandle = await ctx.agents.create({
-      agentId: AgentId('setup-race-parent'),
      sessionId: SessionId('setup-race-parent-session'),
      agentOptions: { provider: 'mock', model: 'mock' },
    })
--- a/packages/subagent/subagent-subprocess/README.md
+++ b/packages/subagent/subagent-subprocess/README.md
@@ -6,7 +6,7 @@ Every tunable is a **parameter**: the dispose ladder takes its grace periods per

 ## What it exports

-### `SENSITIVE_ENV_PATTERN` / `buildChildEnv(extra)`
+### `buildChildEnv(extra)`

 The credential env scrub (same pattern as the [bash executor](../../bash/bash-local/README.md)): the child env is the ambient env minus credential-shaped vars (`/KEY|SECRET|TOKEN/i`), with `extra` layered on top AFTER the scrub. `PATH`, `HOME`, `TMPDIR`, locale, and proxy vars survive, so the child CLI runs normally; the parent's own secrets never leak implicitly, while an explicitly supplied credential (the child's OWN key in a backend's `env` config) still reaches the child.

@@ -14,10 +14,6 @@ The credential env scrub (same pattern as the [bash executor](../../bash/bash-lo

 Spawn-failure capture: a promise that resolves (never rejects) with the child's first `error` event. A spawn failure such as `ENOENT` is an event, not a thrown exception — without a listener Node crashes the parent process — so call this in the same tick as `spawn()` and race it in the run's result path; a bad command then settles as an ordinary child-level failure. For a child that spawns cleanly the promise never settles.

-### `waitForExit(child)` / `exitsWithin(child, ms)`
-
-Exit waits over a `ChildProcess`: resolve once the child exits by any code or signal (immediately if it is already gone), or race that against a timer (`true` = exited in time). The race cleans up after itself on both outcomes — the pending timer is `unref()`ed and cleared on exit, the exit listener removed on timeout — so repeated calls (the dispose ladder's tiers, a poll loop) never accumulate listeners on the child.
-
 ### `disposeChildProcess(child, graces)`

 The platform-aware dispose ladder resolves only once the child has ACTUALLY exited — quiescence reached, not merely requested (see [defensive patterns](../../../docs/defensive-patterns.md)):
@@ -28,6 +24,8 @@ The platform-aware dispose ladder resolves only once the child has ACTUALLY exit

 The two graces (`DisposeLadderGraces`) come from the consuming plugin's `disposeEofGraceMs`/`disposeGraceMs` Config fields; `disposeGraceMs` is unused on Windows because Node maps `SIGTERM` and `SIGKILL` to the same forced termination. The EOF window is deliberately separate and usually wider, since cooperative teardown may await a signal-trapping grandchild plus a final flush.

+The exit waits are internal to this ladder. They clean up their timer and listener on either outcome, so escalation never accumulates listeners on the child.
+
 ### `createIsolatedConfigDir(prefix, pinnedPath?)`

 A per-run isolated config directory for an external CLI child (the target of `CLAUDE_CONFIG_DIR` / `CODEX_HOME`-style redirection), so child behavior is a function of deployment config alone — never of whatever `~/.claude` / `~/.codex`-style state exists on the host. Returns an `IsolatedConfigDir` handle: `path` goes into the child env, `remove()` runs on dispose.
--- a/packages/subagent/subagent-subprocess/src/index.ts
+++ b/packages/subagent/subagent-subprocess/src/index.ts
@@ -20,13 +20,12 @@ import { join } from 'node:path'
 * the scrub, so an intended `DEEPSEEK_API_KEY` survives while an incidental
 * `AWS_SECRET_ACCESS_KEY` does not.
 */
-export const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i
+const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i

 /**
 * The ambient env minus credential-shaped vars, plus the caller's explicit
 * env. `PATH`, `HOME`, `TMPDIR`, locale, and proxy vars survive the scrub, so
- * a child CLI runs normally; only {@link SENSITIVE_ENV_PATTERN}-shaped names
- * are dropped.
+ * a child CLI runs normally; only credential-shaped names are dropped.
 * @param extra - explicit vars layered on top AFTER the scrub, so a
 * credential-shaped name supplied deliberately still reaches the child.
 * @returns the environment to spawn the child with.
@@ -57,7 +56,7 @@ export function spawnFailure(child: ChildProcess): Promise<Error> {
 * already gone.
 * @param child - the child process to await.
 */
-export function waitForExit(child: ChildProcess): Promise<void> {
+function waitForExit(child: ChildProcess): Promise<void> {
  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
  return new Promise<void>(resolve => child.once('exit', () => { resolve() }))
 }
@@ -72,7 +71,7 @@ export function waitForExit(child: ChildProcess): Promise<void> {
 * @returns `true` if the child exits within `ms` (immediately if it is
 * already gone), `false` on timeout.
 */
-export function exitsWithin(child: ChildProcess, ms: number): Promise<boolean> {
+function exitsWithin(child: ChildProcess, ms: number): Promise<boolean> {
  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true)
  return new Promise<boolean>((resolve) => {
    const onExit = (): void => {
--- a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
+++ b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts
@@ -9,10 +9,7 @@ import {
  buildChildEnv,
  createIsolatedConfigDir,
  disposeChildProcess,
-  exitsWithin,
-  SENSITIVE_ENV_PATTERN,
  spawnFailure,
-  waitForExit,
 } from '../src/index.ts'

 // `rm` is real-passthrough except for one deterministic failure. Permission-based recursive-rm
@@ -44,6 +41,8 @@ interface FakeChildScript {
  diesOn?: LethalTrigger
  /** Delay (ms) between the lethal trigger and the exit event. */
  delayMs?: number
+  /** Complete the scripted exit inside the triggering call. */
+  synchronousExit?: boolean
  /** `false` models a child spawned without a stdin pipe. */
  stdin?: boolean
 }
@@ -77,11 +76,13 @@ class FakeChild extends EventEmitter {
    // SIGKILL is uncatchable — it always fells the child; any other trigger
    // only when the scenario scripts it as the lethal one.
    if (trigger !== 'SIGKILL' && this.script.diesOn !== trigger) return
-    setTimeout(() => {
+    const exit = (): void => {
      if (trigger === 'eof') this.exitCode = 0
      else this.signalCode = trigger
      this.emit('exit', this.exitCode, this.signalCode)
-    }, this.script.delayMs ?? 0)
+    }
+    if (this.script.synchronousExit === true) exit()
+    else setTimeout(exit, this.script.delayMs ?? 0)
  }
 }

@@ -90,7 +91,7 @@ function asChild(fake: FakeChild): ChildProcess {
  return fake as unknown as ChildProcess
 }

-describe('buildChildEnv / SENSITIVE_ENV_PATTERN', () => {
+describe('buildChildEnv', () => {
  it('drops credential-shaped ambient vars (KEY/SECRET/TOKEN, case-insensitive)', () => {
    process.env.DSH_PROC_TEST_API_KEY = 'leak'
    process.env.dsh_proc_test_secret = 'leak'
@@ -108,7 +109,6 @@ describe('buildChildEnv / SENSITIVE_ENV_PATTERN', () => {
  })

  it('forwards normal ambient vars', () => {
-    expect(SENSITIVE_ENV_PATTERN.test('PATH')).toBe(false)
    expect(buildChildEnv({}).PATH).toBe(process.env.PATH)
  })

@@ -146,7 +146,7 @@ describe('spawnFailure', () => {
    const fake = new FakeChild({ diesOn: 'SIGTERM' })
    const failure = spawnFailure(asChild(fake))
    fake.kill('SIGTERM')
-    await waitForExit(asChild(fake))
+    await new Promise<void>(resolve => fake.once('exit', () => { resolve() }))
    // A clean lifecycle emits `exit`, never `error` — the capture stays
    // pending forever, so a race against it is decided by the other arms.
    const settled = await Promise.race([
@@ -157,51 +157,6 @@ describe('spawnFailure', () => {
  })
 })

-describe('waitForExit / exitsWithin', () => {
-  it('resolves immediately for a child that already exited by code', async () => {
-    const fake = new FakeChild()
-    fake.exitCode = 0
-    await expect(waitForExit(asChild(fake))).resolves.toBeUndefined()
-  })
-
-  it('resolves immediately for a child that already died by signal', async () => {
-    const fake = new FakeChild()
-    fake.signalCode = 'SIGTERM'
-    await expect(waitForExit(asChild(fake))).resolves.toBeUndefined()
-  })
-
-  it('resolves on the exit event of a live child', async () => {
-    const fake = new FakeChild({ diesOn: 'SIGTERM', delayMs: 5 })
-    const exited = waitForExit(asChild(fake))
-    fake.kill('SIGTERM')
-    await expect(exited).resolves.toBeUndefined()
-    expect(fake.signalCode).toBe('SIGTERM')
-  })
-
-  it('exitsWithin resolves true immediately for an already-exited child (no listener attached)', async () => {
-    const fake = new FakeChild()
-    fake.exitCode = 0
-    await expect(exitsWithin(asChild(fake), 1000)).resolves.toBe(true)
-    expect(fake.listenerCount('exit')).toBe(0)
-  })
-
-  it('exitsWithin resolves true when the child exits inside the window', async () => {
-    const fake = new FakeChild({ diesOn: 'SIGTERM', delayMs: 5 })
-    fake.kill('SIGTERM')
-    await expect(exitsWithin(asChild(fake), 1000)).resolves.toBe(true)
-    // The once-listener fired and the grace timer was cleared — nothing lingers.
-    expect(fake.listenerCount('exit')).toBe(0)
-  })
-
-  it('exitsWithin resolves false on timeout for a child that never exits', async () => {
-    const fake = new FakeChild() // nothing short of SIGKILL fells it; no signal sent
-    await expect(exitsWithin(asChild(fake), 20)).resolves.toBe(false)
-    // The timeout arm removed its exit listener: repeated waits (a poll loop,
-    // the ladder's tiers) never accumulate listeners on the same child.
-    expect(fake.listenerCount('exit')).toBe(0)
-  })
-})
-
 describe('disposeChildProcess', () => {
  it('returns immediately for an already-exited child (no EOF, no signals)', async () => {
    const fake = new FakeChild()
@@ -227,12 +182,28 @@ describe('disposeChildProcess', () => {
    expect(fake.exitCode).toBe(0)
  })

+  it('recognizes a child that exits synchronously on stdin EOF', async () => {
+    const fake = new FakeChild({ diesOn: 'eof', synchronousExit: true })
+    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 1000, disposeGraceMs: 1000 })
+    expect(fake.exitCode).toBe(0)
+    expect(fake.listenerCount('exit')).toBe(0)
+  })
+
  it('tier 2: a child that ignores EOF but honors SIGTERM dies on the middle rung', async () => {
    const fake = new FakeChild({ diesOn: 'SIGTERM', delayMs: 5 })
    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'linux')
    expect(fake.stdinEnded).toBe(true)
    expect(fake.kills).toEqual(['SIGTERM'])
    expect(fake.signalCode).toBe('SIGTERM')
+    expect(fake.listenerCount('exit')).toBe(0)
+  })
+
+  it('recognizes a child that exits synchronously on SIGTERM', async () => {
+    const fake = new FakeChild({ diesOn: 'SIGTERM', synchronousExit: true })
+    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 })
+    expect(fake.kills).toEqual(['SIGTERM'])
+    expect(fake.signalCode).toBe('SIGTERM')
+    expect(fake.listenerCount('exit')).toBe(0)
  })

  it('tier 3: a SIGTERM-trapping child is SIGKILLed, and dispose resolves only after the exit', async () => {
@@ -244,6 +215,13 @@ describe('disposeChildProcess', () => {
    expect(fake.signalCode).toBe('SIGKILL')
  })

+  it('recognizes a child already gone when the final exit wait begins', async () => {
+    const fake = new FakeChild({ synchronousExit: true })
+    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 20 })
+    expect(fake.kills).toEqual(['SIGTERM', 'SIGKILL'])
+    expect(fake.signalCode).toBe('SIGKILL')
+  })
+
  it('walks the ladder for a child spawned without a stdin pipe', async () => {
    const fake = new FakeChild({ stdin: false, diesOn: 'SIGTERM', delayMs: 5 })
    await disposeChildProcess(asChild(fake), { disposeEofGraceMs: 20, disposeGraceMs: 1000 }, 'linux')
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -50,7 +50,9 @@ Runtime features are optional methods on `SubagentRun`: `sendMessage?` steers a

 `SubagentRun.result` resolves to `{ output, structured?, stopReason }`. Child-level failures resolve with a non-`completed` reason; only an infrastructure fault that the seam cannot represent may reject. `dispose()` is idempotent, cancels remaining work, and waits for the child resources to quiesce.

-The service emits `subagent/start` only after `start()` has fulfilled. It attaches the result observer before that synchronous notification, so even an already-settled child still produces `subagent/start` before `subagent/end`. In-process start observers can resolve the published child through `ctx.agents.get(info.id)`; remote providers need not publish a local agent.
+A local run publishes an ordinary child agent/session before `start()` fulfills, returns that shared session id as `SubagentRun.id`, exposes the exact child as `SubagentRun.localAgent`, and records `request.parent.session.id` in the child's `parentSession` header. Remote providers instead mint a parent-scoped lifecycle id and return `localAgent: undefined`.
+
+The service emits `subagent/start` only after `start()` has fulfilled. It attaches the result observer before that synchronous notification, so even an already-settled child still produces `subagent/start` before `subagent/end`. The pair shares a service-minted `runId`; its `local` flag is snapshotted from the provider's exact `localAgent`, so observers never infer run identity or locality from reusable provider/session names.

 Run events are scoped to the delegating parent. Every listener is independently contained: a synchronous throw or rejected returned promise is logged without starving peer listeners or changing the run.

--- a/packages/subagent/subagent/package.json
+++ b/packages/subagent/subagent/package.json
@@ -23,15 +23,19 @@
  "license": "BSD-3-Clause",
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-brand": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-scope": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-brand": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-scope": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
    "cordis": "^4.0.0-rc.7"
  }
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -28,13 +28,15 @@
 * @module @deepseek-ai/dsh-subagent
 */

+import { randomUUID } from 'node:crypto'
 import { Context, Service } from 'cordis'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import { assertSupportedOutputSchema } from '@deepseek-ai/dsh-tools'
 import { HarnessError } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
-import type { Agent, AgentId } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { SessionId } from '@deepseek-ai/dsh-session'
 import type {
  SubagentCapabilities,
  SubagentProvider,
@@ -42,7 +44,9 @@ import type {
  SubagentRun,
  SubagentStartRequest,
 } from './types.ts'
+import { SubagentRunId } from './types.ts'

+export { SubagentRunId } from './types.ts'
 export type {
  SubagentCapabilities,
  SubagentProvider,
@@ -111,18 +115,26 @@ declare module 'cordis' {

 /** Observe-only identifying detail for a ready subagent run. */
 export interface SubagentRunInfo {
+  /** Unique identity shared with the paired terminal event. */
+  readonly runId: SubagentRunId
  /** The provider that established the run. */
  readonly provider: string
  /** The child agent's id. */
-  readonly id: AgentId
+  readonly id: SessionId
+  /** Snapshot of whether `SubagentRun.localAgent` was present when start fulfilled. */
+  readonly local: boolean
 }

 /** Observe-only outcome detail for a settled subagent run. */
 export interface SubagentRunEndInfo {
+  /** Unique identity shared with the paired start event. */
+  readonly runId: SubagentRunId
  /** The provider that ran it. */
  readonly provider: string
  /** The child agent's id. */
-  readonly id: AgentId
+  readonly id: SessionId
+  /** Snapshot of whether `SubagentRun.localAgent` was present when start fulfilled. */
+  readonly local: boolean
  /** The terminal stop reason. */
  readonly stopReason: SubagentResult['stopReason']
  /** The child's final assistant output, absent on infrastructure rejection. */
@@ -207,22 +219,28 @@ export class SubagentService extends Service {

    const parent = request.parent
    const run = await provider.start(request)
+    const runId = SubagentRunId(randomUUID())
+    const lifecycleIdentity = {
+      runId,
+      provider: name,
+      id: run.id,
+      local: run.localAgent !== undefined,
+    }
    // Attach the terminal observer before dispatching start. Promise reactions
    // still run after this synchronous start emission, preserving start → end.
    void run.result.then(
      (result) => {
        this.emitLifecycle('subagent/end', {
-          provider: name,
-          id: run.id,
+          ...lifecycleIdentity,
          stopReason: result.stopReason,
          lastAssistantMessage: result.output,
        }, parent)
      },
      () => {
-        this.emitLifecycle('subagent/end', { provider: name, id: run.id, stopReason: 'error' }, parent)
+        this.emitLifecycle('subagent/end', { ...lifecycleIdentity, stopReason: 'error' }, parent)
      },
    )
-    this.emitLifecycle('subagent/start', { provider: name, id: run.id }, parent)
+    this.emitLifecycle('subagent/start', lifecycleIdentity, parent)
    return run
  }

--- a/packages/subagent/subagent/src/types.ts
+++ b/packages/subagent/subagent/src/types.ts
@@ -6,10 +6,24 @@
 * @module @deepseek-ai/dsh-subagent/types
 */

-import type { Agent, AgentId, AgentOptions } from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentOptions } from '@deepseek-ai/dsh-agent'
+import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SessionId } from '@deepseek-ai/dsh-session'
 import type { StructuredOutputSchema, ToolRestriction } from '@deepseek-ai/dsh-tools'

+/** Identifies one accepted subagent run across its lifecycle event pair. */
+export type SubagentRunId = Branded<'SubagentRunId'>
+
+/**
+ * Brand a string as a {@link SubagentRunId}.
+ * @param id - the raw id string (the service mints UUIDs; tests may pass fixtures).
+ * @returns the same string, branded.
+ */
+export function SubagentRunId(id: string): SubagentRunId {
+  return id as SubagentRunId
+}
+
 /**
 * Which START-TIME features a provider supports. Checked by the service before delegating to
 * {@link SubagentProvider.start}: a request that needs a capability the chosen provider lacks
@@ -132,8 +146,18 @@ export interface SubagentResult {
 * capability discovery; narrow their presence before calling.
 */
 export interface SubagentRun {
-  /** The child agent's id (local in-process runs are already published in `ctx.agents`; remote transports need not publish locally). */
-  readonly id: AgentId
+  /**
+   * Parent-scoped run id. For a local run, this MUST equal the published child
+   * session id, whose `parentSession` records `request.parent.session.id`; a
+   * remote provider mints an id unique in the parent namespace.
+   */
+  readonly id: SessionId
+  /**
+   * The exact published in-process child, or `undefined` for a remote run.
+   * When present, its id is {@link id}; the provider retains no ownership
+   * implication beyond the run's ordinary {@link dispose} contract.
+   */
+  readonly localAgent: Agent | undefined
  /**
   * Resolves with the child's terminal {@link SubagentResult} when the run
   * settles. Does NOT reject on a child-level failure — a model/transport
--- a/packages/subagent/subagent/tests/service.spec.ts
+++ b/packages/subagent/subagent/tests/service.spec.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import { AgentId, type Agent } from '@deepseek-ai/dsh-agent'
+import { type Agent } from '@deepseek-ai/dsh-agent'
+
 import { HarnessError } from '@deepseek-ai/dsh-llm'
 import { carrierKeyOf } from '@deepseek-ai/dsh-scope'
 import SubagentService, {
@@ -12,9 +13,10 @@ import SubagentService, {
  type SubagentRun,
  type SubagentStartRequest,
 } from '@deepseek-ai/dsh-subagent'
+import { SessionId } from '@deepseek-ai/dsh-session'

 function fakeParent(id = 'parent-1'): Agent {
-  return { id: AgentId(id) } as unknown as Agent
+  return { id: SessionId(id) } as unknown as Agent
 }

 const ALL_CAPS: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: true, persona: true }
@@ -45,7 +47,8 @@ class StubProvider implements SubagentProvider {
  async start(request: SubagentStartRequest): Promise<SubagentRun> {
    this.startCount += 1
    return {
-      id: AgentId(`child:${this.name}:${request.parent.id}`),
+      id: SessionId(`child:${this.name}:${request.parent.id}`),
+      localAgent: undefined,
      result: Promise.resolve(this.outcome),
      async dispose() {},
    }
@@ -135,13 +138,14 @@ describe('SubagentService', () => {
    const parent = fakeParent('delegator')
    const events: string[] = []
    const keys: unknown[] = []
-    ctx.on('subagent/start', function () { events.push('start'); keys.push(carrierKeyOf(this)) })
-    ctx.on('subagent/end', function () { events.push('end'); keys.push(carrierKeyOf(this)) })
+    const runIds: string[] = []
+    ctx.on('subagent/start', function (info) { events.push('start'); keys.push(carrierKeyOf(this)); runIds.push(info.runId) })
+    ctx.on('subagent/end', function (info) { events.push('end'); keys.push(carrierKeyOf(this)); runIds.push(info.runId) })

    const starting = subagents.start('deferred', baseRequest({ parent }))
    await Promise.resolve()
    expect(events).toEqual([])
-    ready.resolve({ id: AgentId('child'), result: result.promise, async dispose() {} })
+    ready.resolve({ id: SessionId('child'), localAgent: undefined, result: result.promise, async dispose() {} })
    const run = await starting
    expect(events).toEqual(['start'])
    result.resolve({ output: [{ type: 'text', text: 'answer' }], stopReason: 'completed' })
@@ -149,6 +153,21 @@ describe('SubagentService', () => {
    await Promise.resolve()
    expect(events).toEqual(['start', 'end'])
    expect(keys).toEqual([parent, parent])
+    expect(runIds[0]).toBe(runIds[1])
+  })
+
+  it('mints distinct lifecycle identities when provider and child ids repeat', async () => {
+    const { ctx, subagents } = await service()
+    subagents.registerProvider(new StubProvider('reused'))
+    const runIds: string[] = []
+    ctx.on('subagent/start', info => void runIds.push(info.runId))
+
+    const first = await subagents.start('reused', baseRequest())
+    const second = await subagents.start('reused', baseRequest())
+    await Promise.all([first.result, second.result])
+
+    expect(runIds).toHaveLength(2)
+    expect(new Set(runIds).size).toBe(2)
  })

  it('emits no run lifecycle when provider startup rejects', async () => {
@@ -190,7 +209,7 @@ describe('SubagentService', () => {
      capabilities: NO_CAPS,
      inheritsParentContext: false,
      async start() {
-        return { id: AgentId('infra-child'), result: failure.promise, async dispose() {} }
+        return { id: SessionId('infra-child'), localAgent: undefined, result: failure.promise, async dispose() {} }
      },
    })
    const failedRun = await subagents.start('infra', baseRequest())
--- a/packages/subagent/tool-subagent/README.md
+++ b/packages/subagent/tool-subagent/README.md
@@ -24,6 +24,10 @@ With `run_in_background: true`, the tool registers the parent-owned task before
 | `toolFilter` | Per-child global-tool restriction; requires `toolFilter` capability. |
 | `maxDepth` | Absolute delegation-depth cap; requires `depthLimit` capability. |

+## Concurrency
+
+Foreground and background calls are exclusive. Children may share the parent's workspace or external resources, and a unary classifier cannot prove that sibling delegations have disjoint effects. See the [parallel tool-call RFC](../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md).
+
 ## Model Experience

 ### Tool schema
--- a/packages/subagent/tool-subagent/src/index.ts
+++ b/packages/subagent/tool-subagent/src/index.ts
@@ -161,13 +161,13 @@ export async function settleRun(run: SubagentRun): Promise<TaskOutcome> {
 * A fresh child needs a standalone prompt; a forked child already sees the
 * conversation's completed turns — telling the model to restate everything
 * (or, worse, that the child "does not see this conversation") would be false
- * for a fork. Exported for tests.
+ * for a fork.
 * @param inheritsConversation - whether the child's conversation is seeded
 *   with the parent's completed turns; this says nothing about tool, service,
 *   scope, or authority inheritance.
 * @returns the tool `description` and the `prompt` parameter description.
 */
-export function providerWording(inheritsConversation: boolean): { description: string; promptDescription: string } {
+function providerWording(inheritsConversation: boolean): { description: string; promptDescription: string } {
  if (inheritsConversation) {
    return {
      description:
--- a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
+++ b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
@@ -4,7 +4,7 @@ import Loader from '@cordisjs/plugin-loader'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
-import { AgentId, type Agent } from '@deepseek-ai/dsh-agent'
+import { type Agent } from '@deepseek-ai/dsh-agent'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import TaskService from '@deepseek-ai/dsh-tasks'
@@ -12,6 +12,7 @@ import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import * as mock from '@deepseek-ai/dsh-subagent-mock'
 import * as tool from '../src/index.ts'
 import { runOutcome, settleRun } from '../src/index.ts'
+import { SessionId } from '@deepseek-ai/dsh-session'

 /**
 * Drives the REAL plugin body: mounts `dsh-tool-subagent` on a real
@@ -24,7 +25,7 @@ import { runOutcome, settleRun } from '../src/index.ts'

 /** A minimal parent Agent — the tool reads `agent.id` for `parent`. */
 function fakeAgent(id = 'parent-1'): Agent {
-  return { id: AgentId(id) } as unknown as Agent
+  return { id: SessionId(id) } as unknown as Agent
 }

 async function setup(toolConfig: tool.Config, mockConfig: Partial<mock.Config> = {}) {
@@ -85,7 +86,7 @@ describe('dsh-tool-subagent', () => {
    // Schema omission is advertising, not enforcement: the arg validator
    // allows undeclared keys, so the opt-out must also hold in execute().
    const ctx = await setup({ provider: 'mock', enableRunInBackground: false })
-    const parent = { id: AgentId('agent-sess-off'), inject: () => {}, session: { header: { version: 0, id: 'sess-off', createdAt: 0 } } } as unknown as Agent
+    const parent = { id: SessionId('sess-off'), inject: () => {}, session: { header: { version: 0, id: 'sess-off', createdAt: 0 } } } as unknown as Agent

    const forced = await callSubagent(ctx, { description: 'd', prompt: 'p', run_in_background: true }, { agent: parent })
    expect(forced.isError).toBe(true)
@@ -96,6 +97,20 @@ describe('dsh-tool-subagent', () => {
    expect(foreground.isError).toBe(false)
  })

+  it('keeps foreground and background calls exclusive', async () => {
+    const ctx = await setup({ provider: 'mock' })
+    expect(ctx.tools.executionMode({
+      callId: CallId('subagent-foreground'),
+      name: 'subagent',
+      arguments: { description: 'do work', prompt: 'Reply OK' },
+    })).toEqual({ kind: 'exclusive' })
+    expect(ctx.tools.executionMode({
+      callId: CallId('subagent-background'),
+      name: 'subagent',
+      arguments: { description: 'do work', prompt: 'Reply OK', run_in_background: true },
+    })).toEqual({ kind: 'exclusive' })
+  })
+
  it.each([
    { stopReason: 'aborted' as const, fragment: 'cancelled' },
    { stopReason: 'error' as const, fragment: 'failed' },
@@ -142,7 +157,8 @@ describe('dsh-tool-subagent', () => {
      capabilities: { outputSchema: false, depthLimit: false, toolFilter: false, persona: false },
      inheritsParentContext: false,
      start: async () => ({
-        id: AgentId('weird-child'),
+        id: SessionId('weird-child'),
+        localAgent: undefined,
        result: Promise.resolve({ output: [{ type: 'text', text: 'partial' }], stopReason: 'frobnicated' as never }),
        dispose: async () => {},
      }),
@@ -169,7 +185,8 @@ describe('dsh-tool-subagent', () => {
      start: async (request) => {
        seen = request
        return {
-          id: AgentId('capture-child'),
+          id: SessionId('capture-child'),
+          localAgent: undefined,
          result: Promise.resolve({ output: [{ type: 'text', text: 'ok' }], stopReason: 'completed' as const }),
          dispose: async () => {},
        }
@@ -198,7 +215,8 @@ describe('dsh-tool-subagent', () => {
      start: async (request) => {
        seen = request
        return {
-          id: AgentId('bare-child'),
+          id: SessionId('bare-child'),
+          localAgent: undefined,
          result: Promise.resolve({ output: [{ type: 'text', text: 'ok' }], stopReason: 'completed' as const }),
          dispose: async () => {},
        }
@@ -325,7 +343,8 @@ describe('dsh-tool-subagent', () => {
      capabilities: { outputSchema: false, depthLimit: false, toolFilter: false, persona: false },
      inheritsParentContext: false,
      start: async () => ({
-        id: AgentId('spy-child'),
+        id: SessionId('spy-child'),
+        localAgent: undefined,
        result: Promise.resolve({ output: [{ type: 'text', text: 'ok' }], stopReason: 'completed' as const }),
        dispose: async () => void disposed(),
      }),
@@ -347,7 +366,8 @@ describe('dsh-tool-subagent', () => {
      capabilities: { outputSchema: false, depthLimit: false, toolFilter: false, persona: false },
      inheritsParentContext: false,
      start: async () => ({
-        id: AgentId('spy-child'),
+        id: SessionId('spy-child'),
+        localAgent: undefined,
        result: Promise.resolve({ output: [], stopReason: 'error' as const }),
        dispose: async () => void disposed(),
      }),
@@ -378,7 +398,8 @@ describe('dsh-tool-subagent', () => {
          resolveResult({ output: [], stopReason: 'aborted' })
        }, { once: true })
        return {
-          id: AgentId('spy-child'),
+          id: SessionId('spy-child'),
+          localAgent: undefined,
          result,
          dispose: async () => {},
        }
@@ -470,7 +491,8 @@ describe('dsh-tool-subagent', () => {
      start: async (request) => {
        seen = request
        return {
-          id: AgentId('capture2-child'),
+          id: SessionId('capture2-child'),
+          localAgent: undefined,
          result: Promise.resolve({ output: [{ type: 'text', text: 'ok' }], stopReason: 'completed' as const }),
          dispose: async () => {},
        }
@@ -527,7 +549,8 @@ describe('dsh-tool-subagent', () => {
      start: async (request) => {
        seen = request
        return {
-          id: AgentId('capture3-child'),
+          id: SessionId('capture3-child'),
+          localAgent: undefined,
          result: Promise.resolve({ output: [{ type: 'text', text: 'ok' }], stopReason: 'completed' as const }),
          dispose: async () => {},
        }
@@ -556,7 +579,8 @@ describe('dsh-tool-subagent', () => {
      start: async (request) => {
        seen = request
        return {
-          id: AgentId('capture4-child'),
+          id: SessionId('capture4-child'),
+          localAgent: undefined,
          result: Promise.resolve({ output: [{ type: 'text', text: 'ok' }], stopReason: 'completed' as const }),
          dispose: async () => {},
        }
@@ -588,11 +612,12 @@ describe('dsh-tool-subagent background mode', () => {
  /** A live parent with a dedicated scope fiber for structural task cleanup. */
  function ownerAgent(ctx: Context, sessionId: string, inject: (...args: unknown[]) => void = () => {}): Agent {
    const scopeFiber = ctx.plugin(() => {})
+    const id = SessionId(sessionId)
    const agent = {
-      id: AgentId(`agent-${sessionId}`),
+      id,
      ctx: scopeFiber.ctx,
      inject,
-      session: { header: { version: 0, id: sessionId, createdAt: 0 } },
+      session: { id, header: { version: 0, id, createdAt: 0 } },
    } as unknown as Agent
    ctx.agents.register(agent)
    return agent
@@ -722,7 +747,7 @@ describe('dsh-tool-subagent background mode', () => {
      inheritsParentContext: false,
      start: async (request) => {
        let settle!: (value: { output: { type: 'text'; text: string }[]; stopReason: 'aborted' }) => void
-        const id = AgentId(`hang-${++starts}`)
+        const id = SessionId(`hang-${++starts}`)
        const result = new Promise<{ output: { type: 'text'; text: string }[]; stopReason: 'aborted' }>((res) => { settle = res })
        request.signal.addEventListener('abort', () => {
          cancels.push(typeof request.signal.reason === 'string' ? request.signal.reason : undefined)
@@ -730,6 +755,7 @@ describe('dsh-tool-subagent background mode', () => {
        }, { once: true })
        return {
          id,
+          localAgent: undefined,
          result,
          dispose: () => Promise.resolve(),
        }
@@ -768,7 +794,8 @@ describe('dsh-tool-subagent background mode', () => {
  it('settleRun disposes the run before reporting, on both result paths', async () => {
    const order: string[] = []
    const completed = await settleRun({
-      id: AgentId('child-1'),
+      id: SessionId('child-1'),
+      localAgent: undefined,
      result: Promise.resolve({ output: [{ type: 'text' as const, text: 'ok' }], stopReason: 'completed' as const }),
      dispose() { order.push('dispose'); return Promise.resolve() },
    })
@@ -779,7 +806,8 @@ describe('dsh-tool-subagent background mode', () => {
    // An infrastructure rejection still disposes and reports failed.
    let disposed = false
    const failed = await settleRun({
-      id: AgentId('child-2'),
+      id: SessionId('child-2'),
+      localAgent: undefined,
      result: Promise.reject(new Error('transport gone')),
      dispose() { disposed = true; return Promise.resolve() },
    })
@@ -787,14 +815,16 @@ describe('dsh-tool-subagent background mode', () => {
    expect(disposed).toBe(true)

    const disposeFailed = await settleRun({
-      id: AgentId('child-3'),
+      id: SessionId('child-3'),
+      localAgent: undefined,
      result: Promise.resolve({ output: [], stopReason: 'completed' }),
      dispose: () => Promise.reject(new Error('reap failed')),
    })
    expect(disposeFailed).toEqual({ status: 'failed', detail: 'dispose failed: Error: reap failed' })

    const bothFailed = await settleRun({
-      id: AgentId('child-4'),
+      id: SessionId('child-4'),
+      localAgent: undefined,
      result: Promise.reject(new Error('result failed')),
      dispose: () => Promise.reject(new Error('reap failed')),
    })
@@ -812,11 +842,12 @@ describe('background preflight failure (no orphaned child, by construction)', ()
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(TaskService)
    const scopeFiber = ctx.plugin(() => {})
+    const id = SessionId('sess-p')
    const parent = {
-      id: AgentId('agent-sess-p'),
+      id,
      ctx: scopeFiber.ctx,
      inject: () => {},
-      session: { header: { version: 0, id: 'sess-p', createdAt: 0 } },
+      session: { id, header: { version: 0, id, createdAt: 0 } },
    } as unknown as Agent
    ctx.agents.register(parent)

@@ -828,7 +859,8 @@ describe('background preflight failure (no orphaned child, by construction)', ()
      start: async () => {
        starts += 1
        return {
-          id: AgentId('probe-child'),
+          id: SessionId('probe-child'),
+          localAgent: undefined,
          result: Promise.resolve({ output: [], stopReason: 'completed' as const }),
          dispose: () => Promise.resolve(),
        }