Merge remote-tracking branch 'origin/master' into codex/pr370-review-20260719

packages/AGENTS.md

@@ -6,12 +6,21 @@ These package-specific rules supplement the repo-wide [conventions](../AGENTS.md
 - **Optional services use `ctx.get(name)`.** Reserve `ctx.<name>` for declared injections; the property proxy is topology-sensitive, while strict `ctx.get` reads the global service store ([postmortem](../docs/postmortem/0001-acp-default-export-drops-inject.md)).
 - **Product-visible plugins require a non-unit REAL-composition test.** Hand-built `ctx.plugin(...)` suites are insufficient. Boot test-only `cordis.yml` through the Loader and app/process; mock only external/nondeterministic boundaries and assert model-visible, durable, or user-visible output. Keep opt-ins out of shipped defaults. [Policy](../docs/testing.md).
 - **Typed same-process service and plugin calls are contracts, not serialization boundaries.** Prefer readonly borrowed values; materialize or defensively validate only at parser/config, queued, model/tool JSON, durable/file, worker, process, or wire boundaries.
+- **Initiator-owned private chains derive, then capture.** Under `ctx.agents.withInitiator()`, recover the Agent at each orchestration entry, derive `agent.session`, and let operation-local helpers close over it. Keep `Agent` and `Session` explicit at lifecycle, session-log, service, authority, worker/process, persistence, and wire interfaces; do not widen a leaf helper from `Session` to `Context` merely to hide a parameter ([rationale](../docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.md)).
 - **Represent one asynchronous operation with one lifecycle controller or transaction.** Separate readiness, cancellation, disposal, reservation, or sentinel state requires an independent owner or settlement boundary; otherwise fold it while preserving rollback, callback containment, and quiescence.
+- **Shape capability interfaces around all current consumers.** Keep tool-schema, Loader, UI, transport, and backend-specific behavior in the consumer or adapter; do not let one consumer dictate the interface ([capability-seam rationale](../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)).
+- **Require a current owner and need.** Tie each abstraction, state machine, option, defensive copy, and compatibility path to a current contract or production consumer, and keep behavior in its owning plugin or service.
+- **Require evidence for public choices.** Configurability does not justify an unsupported default, public operation set, format, or imported external concept. Use current-consumer evidence or relevant prior art; otherwise require an explicit value or defer the choice.
+- **Write model-facing contracts from the model's perspective.** Prompts, tool schemas, results, and diagnostics contain only task-relevant concepts, not UI, transport, or implementation vocabulary. Pin stable model-visible text verbatim and dynamic behavior through snapshots or end-to-end coverage.
+- **Enforce at the operation boundary that owns the decision.** Schema omission, prompt filtering, facades, wrappers, and listener order are not enforcement when direct or alternate callers can bypass them; test denial through the executor.
+- **Publish state only at its commit point.** Emit each notification and update derived state only after the success boundary that makes it true; derive caches, prompts, UI echoes, replay, and query views from one authoritative source.
+- **Apply bounds to the complete result.** Enforce byte, token, item, and time limits where the complete emitted or retained value, including wrappers and metadata, is known; test tiny and exact limits, oversized single chunks, and multibyte byte limits.
+- **Registry contributions prove disposal.** Add the HMR-safety test required by the [testing policy](../docs/testing.md): dispose the contributing fiber and observe removal.
 
 Naming notes:
 
 - `src/types.ts` contains only types — no runtime code.
 - Tests live at package level under `tests/`, not `src/__tests__/`.
 - A package's README and JSDoc are part of the change: altered behavior (config keys, defaults, error codes, wire fields) updates them in the same commit. `doc-sync` gates what it can; apply [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for complete, concise prose and verify accuracy against code.
-- Package READMEs document model/token effects using the [canonical Model Experience format](../docs/cookbook/adding-a-package.md#4-write-the-package-readme).
+- Package READMEs document model, token, and KV-cache effects using the [canonical Model Experience format](../docs/cookbook/adding-a-package.md#4-write-the-package-readme).
 - Package READMEs put durable consumer gaps and non-obvious maintainer constraints under `## Known Limitations and Deferred Work`; ordinary cleanup stays in its TODO or RFC. Packages with none use a justified [allowlist entry](../scripts/verify-package-readme-limitations.ts) ([rationale](../docs/rfc/implemented/process/2026-07-10-readme-known-limitations-gate.md)).

packages/README.md

@@ -8,7 +8,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 
 | Group | Role | Release expectation |
 |---|---|---|
-| [`core/`](core/README.md) | Product API spine: session, system-prompt, tools, agent, and the concrete loop | Product — stable surface |
+| [`core/`](core/README.md) | Product API spine: sessions, prompts, tools, agent services, and the concrete loop | Product — stable surface |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: the executor seam, a local impl, and the model-facing tool | Product — stable surface |
 | [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the abstract runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
@@ -31,8 +31,8 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`session-query/`](session-query/README.md) | Session retrieval: logical corpus, bounded reads, lineage, and event relationships | Product — stable surface |
 | [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface |
 | [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, user-approval/user-interaction seams, ask-user tool | Product — stable surface |
-| [`examples/`](examples/README.md) | Demo bundles (agent-spine + stdio/ACP/JSON-RPC bins) the leaves load | Support — example infra |
-| [`support/`](support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes, subagent mock) | Support — lower compatibility expectations |
+| [`examples/`](examples/README.md) | Demo bundles (agent-spine + stdio/one-shot CLI/ACP/JSON-RPC bins) the leaves load | Support — example infra |
+| [`support/`](support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes) | Support — lower compatibility expectations |
 | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, Harness home/path helpers, timeout, retention) | Support — small, stable, harness-dep-free |
 
 Groups distinguish product API from support infrastructure. New packages join an existing group; a new group updates its README and this table.

packages/bash/bash-local/README.md

@@ -31,6 +31,10 @@ Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi;
 
 Indirectly, through `dsh-tool-bash`, which renders this executor's bounded stdout/stderr tails, background-process deltas, spill-file paths, and infrastructure failures.
 
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
 ## Known Limitations and Deferred Work
 
 - **Unconfined by itself** — this executor always runs commands with the harness process's authority; deployments needing confinement compose [`dsh-bash-sandbox`](../bash-sandbox/README.md), while per-call allow/deny/ask policy belongs on `tools/pre-execute`.

packages/bash/bash-sandbox/README.md

@@ -38,21 +38,45 @@ The keyless consumer-integration proofs are `tests/bwrap.e2e.ts`, `tests/landloc
 
 ### Bash tool schema, indirectly
 
-**What the model sees**: The generated [`dsh-tool-bash` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash) are the baseline. By advertising a confining `sandboxMode`, this backend augments `bash` with `sandbox_permissions` using enum `workspace-write` | `danger-full-access` and with `justification`. The backend adds no prompt prose, and the session's effective mode remains unstated.
+#### What the model sees
 
-**Token effect**: Small fixed schema increment on requests where `bash` is visible; mode switches add no context tokens.
+The generated [`dsh-tool-bash` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash) are the baseline. By advertising a confining `sandboxMode`, this backend augments `bash` with `sandbox_permissions` using enum `workspace-write` | `danger-full-access` and with `justification`. The backend adds no prompt prose, and the session's effective mode remains unstated.
+
+#### Token effect
+
+Small fixed schema increment on requests where `bash` is visible; mode switches add no context tokens.
+
+#### KV Cache effect
+
+Prefix-stable while the executor advertises the same sandbox capabilities. Changing those capabilities alters the `bash` schema and may invalidate reuse from that definition; per-session mode switches do not.
 
 ### Bash tool result, indirectly
 
-**What the model sees**: After ordinary bounded output, a denied call appends exactly `[sandbox: file access denied under <mode> mode]`. When escalation is available it next appends `[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]`. A settled background runner failure instead appends `[sandbox: the sandbox runner itself failed under <mode> mode — the command did not run; this is a sandbox problem, not a command failure]`.
+#### What the model sees
 
-**Token effect**: Zero additional tokens on an unremarkable allowed run beyond ordinary output. Denial or failure adds the quoted conditional marker, retained until compaction.
+After ordinary bounded output, a denied call appends exactly `[sandbox: file access denied under <mode> mode]`. When escalation is available it next appends `[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]`. A settled background runner failure instead appends `[sandbox: the sandbox runner itself failed under <mode> mode — the command did not run; this is a sandbox problem, not a command failure]`.
+
+#### Token effect
+
+Zero additional tokens on an unremarkable allowed run beyond ordinary output. Denial or failure adds the quoted conditional marker, retained until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
 ### Bash tool error, indirectly
 
-**What the model sees**: If no runner can enforce a confined mode, the foreground call propagates the [`SANDBOX_UNAVAILABLE` error owned by `dsh-sandbox`](../../sandbox/sandbox/README.md#confinement-error-indirectly). For an execution-time runner failure, this backend supplies the first stderr line as its detail.
+#### What the model sees
 
-**Token effect**: Conditional error text is visible for that call and retained in history until compaction.
+If no runner can enforce a confined mode, the foreground call propagates the [`SANDBOX_UNAVAILABLE` error owned by `dsh-sandbox`](../../sandbox/sandbox/README.md#confinement-error-indirectly). For an execution-time runner failure, this backend supplies the first stderr line as its detail.
+
+#### Token effect
+
+Conditional error text is visible for that call and retained in history until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
 ## Known Limitations and Deferred Work
 

packages/bash/bash/README.md

@@ -37,6 +37,10 @@ The seam also owns the per-session mode override vocabulary: the log-only `'bash
 
 Indirectly, through `dsh-tool-bash`, which turns executor output and sandbox facts into guidance and retained tool-result tokens.
 
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
 ## Known Limitations and Deferred Work
 
 - **No interactive-input vocabulary** — `stdin` is written once at spawn and closed; the seam has no channel to feed a running task and no PTY session concept.

packages/bash/tool-bash/README.md

@@ -73,39 +73,79 @@ For sandboxing executors, each call resolves mode as one-shot escalation, then s
 
 ### System prompt
 
-**What the model sees**: Every request in this plugin's registration scope contains the bash guidance below. A sandboxing executor adds no mode statement or switch notice. Scoped tool restrictions can hide the schemas without removing this independently registered section.
+#### What the model sees
 
-**Token effect**: Small fixed input cost per request while the plugin is active, unchanged by sandbox mode or mode switches.
+Every request in this plugin's registration scope contains the bash guidance below. A sandboxing executor adds no mode statement or switch notice. Scoped tool restrictions can hide the schemas without removing this independently registered section.
 
-#### Bash guidance
+##### Bash guidance
 
 ```markdown
 Check the [exit code: N] marker on every bash result; investigate failures before moving on.
 ```
 
+#### Token effect
+
+Small fixed input cost per request while the plugin is active, unchanged by sandbox mode or mode switches.
+
+#### KV Cache effect
+
+Prefix-stable while the registration scope and prompt text are unchanged. Plugin activation or disposal may invalidate reuse from this prompt section; sandbox mode switches do not.
+
 ### Tool schemas
 
-**What the model sees**: The model sees the generated [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash). `run_in_background` appears only when this producer enables it; `sandbox_permissions` and `justification` appear only when the mounted executor advertises sandboxing. Agent-scoped tool restrictions can remove the definition for that agent.
+#### What the model sees
 
-**Token effect**: Fixed schema cost on every request where the tools are visible; sandbox support adds the escalation fields and its conditional description paragraph.
+The model sees the generated [`bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash). `run_in_background` appears only when this producer enables it; `sandbox_permissions` and `justification` appear only when the mounted executor advertises sandboxing. Agent-scoped tool restrictions can remove the definition for that agent.
+
+#### Token effect
+
+Fixed schema cost on every request where the tools are visible; sandbox support adds the escalation fields and its conditional description paragraph.
+
+#### KV Cache effect
+
+Prefix-stable while visibility, background support, and executor sandbox capabilities are unchanged. A restriction, config change, or executor change may invalidate reuse from the first changed tool definition.
 
 ### Foreground result
 
-**What the model sees**: The renderer emits the data-dependent stdout tail, then optional `[stderr]` and the stderr tail. With no output it emits exactly `(no output)`. Conditional lines are exactly `[output truncated; full output: <path-or-(unavailable)>]`, `[sandbox: file access denied under <mode> mode]`, `[timed out after <timeoutMs>ms]`, `[killed by signal: <signal>]`, and `[exit code: <exitCode>]`; the sandbox escalation and runner-failure lines are quoted in [`dsh-bash-sandbox`](../bash-sandbox/README.md).
+#### What the model sees
 
-**Token effect**: Zero result tokens before a call. Output is bounded per stream, while each emitted line remains in history until compaction.
+The renderer emits the data-dependent stdout tail, then optional `[stderr]` and the stderr tail. With no output it emits exactly `(no output)`. Conditional lines are exactly `[output truncated; full output: <path-or-(unavailable)>]`, `[sandbox: file access denied under <mode> mode]`, `[timed out after <timeoutMs>ms]`, `[killed by signal: <signal>]`, and `[exit code: <exitCode>]`; the sandbox escalation and runner-failure lines are quoted in [`dsh-bash-sandbox`](../bash-sandbox/README.md).
+
+#### Token effect
+
+Zero result tokens before a call. Output is bounded per stream, while each emitted line remains in history until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
 ### Background task context and results
 
-**What the model sees**: Start returns exactly `started background task <taskId>`. This producer supplies incremental process output, optional `[some output was dropped from memory; full output: <paths-or-(unavailable)>]`, sandbox facts, and terminal detail such as `exit code: <exitCode>` or `signal: <signal>` to the generic task runtime. [`dsh-tool-tasks`](../../tasks/tool-tasks/README.md) owns the visible status line, completion notice, listing, and cancellation response.
+#### What the model sees
 
-**Token effect**: The start acknowledgement is small and retained; collected output is data-dependent and bounded by the executor's stream buffers. Consuming reads do not repeat prior output.
+Start returns exactly `started background task <taskId>`. This producer supplies incremental process output, optional `[some output was dropped from memory; full output: <paths-or-(unavailable)>]`, sandbox facts, and terminal detail such as `exit code: <exitCode>` or `signal: <signal>` to the generic task runtime. [`dsh-tool-tasks`](../../tasks/tool-tasks/README.md) owns the visible status line, completion notice, listing, and cancellation response.
+
+#### Token effect
+
+The start acknowledgement is small and retained; collected output is data-dependent and bounded by the executor's stream buffers. Consuming reads do not repeat prior output.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
 ### Tool errors
 
-**What the model sees**: Validation and policy failures are normalized as `Error: <message>`. This package's stable messages are `invalid command: expected a non-empty string`, `invalid description: expected a non-empty string`, `invalid timeoutMs: expected a positive number, got <value>`, `invalid escalation: sandbox_permissions requires a justification`, `invalid escalation: justification is only valid together with sandbox_permissions`, `invalid justification: expected a non-empty sentence`, `background execution is disabled for this bash tool`, `background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks`, `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`, `sandbox escalation to "<mode>" is not strictly wider than this call's current "<mode>" mode`, the approval-availability/rejection/cancellation variants, and `command aborted`.
+#### What the model sees
 
-**Token effect**: Only the failing call adds these retained tokens; a rejected escalation does not add command output because the command does not run.
+Validation and policy failures are normalized as `Error: <message>`. This package's stable messages are `invalid command: expected a non-empty string`, `invalid description: expected a non-empty string`, `invalid timeoutMs: expected a positive number, got <value>`, `invalid escalation: sandbox_permissions requires a justification`, `invalid escalation: justification is only valid together with sandbox_permissions`, `invalid justification: expected a non-empty sentence`, `background execution is disabled for this bash tool`, `background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks`, `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`, `sandbox escalation to "<mode>" is not strictly wider than this call's current "<mode>" mode`, the approval-availability/rejection/cancellation variants, and `command aborted`.
+
+#### Token effect
+
+Only the failing call adds these retained tokens; a rejected escalation does not add command output because the command does not run.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
 ## Known Limitations and Deferred Work
 

packages/bash/tool-bash/tests/integration.spec.ts

@@ -5,8 +5,8 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
-import { AgentId } from '@deepseek-ai/dsh-agent'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import TaskService from '@deepseek-ai/dsh-tasks'
 import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
@@ -39,7 +39,7 @@ afterEach(() => {
   for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
 })
 
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') {
@@ -50,7 +50,7 @@ function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
   })
 }
 
-function events(agent: ReactLoopAgent): SessionEvent[] {
+function events(agent: Agent): SessionEvent[] {
   return [...agent.session.events]
 }
 
@@ -100,11 +100,10 @@ describe('bash tool through the agent loop', () => {
     ])
     const ctx = await harness(adapter, root, dshHome)
     const handle = await ctx.agents.create({
-      agentId: AgentId('session-env'),
       sessionId: SessionId('session-env-id'),
       agentOptions: { provider: 'mock', model: 'mock' },
     })
-    const agent = handle.agent as ReactLoopAgent
+    const agent = handle.agent
     const location = ctx.sessionPersistence.locate(agent.session.header)
     expect(location?.kind).toBe('jsonl')
 
@@ -125,7 +124,7 @@ describe('bash tool through the agent loop', () => {
       textResponse('The command printed integration-ok.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('it-fg'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('it-fg'), { provider: 'mock', model: 'mock' })
 
     agent.send([{ type: 'text', text: 'run echo integration-ok' }])
     await waitForIdle(ctx, agent)
@@ -157,7 +156,7 @@ describe('bash tool through the agent loop', () => {
       textResponse('It failed with code 9.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('it-exit'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('it-exit'), { provider: 'mock', model: 'mock' })
 
     agent.send([{ type: 'text', text: 'run exit 9' }])
     await waitForIdle(ctx, agent)
@@ -177,7 +176,7 @@ describe('bash tool through the agent loop', () => {
       textResponse('Background task finished.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('it-bg'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('it-bg'), { provider: 'mock', model: 'mock' })
 
     agent.send([{ type: 'text', text: 'run echo bg-ok in the background' }])
     await waitForIdle(ctx, agent)

packages/bash/tool-bash/tests/tools.spec.ts

@@ -10,7 +10,7 @@ import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import SessionStore from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import TaskService from '@deepseek-ai/dsh-tasks'
 import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
@@ -50,18 +50,17 @@ async function setupWithTasks() {
 }
 
 /**
- * Build a fake {@link Agent} whose session token is `sessionId`, give it a
+ * Build a fake {@link Agent} with the shared agent/session identity, give it a
  * dedicated lifecycle fiber for `Agent.ctx`, and register it in `ctx.agents`.
- * The agent id is deliberately different from the session token so a
- * wrong-field ownership match fails the test.
  */
 function registerFakeAgent(ctx: Context, sessionId: string, inject: (...args: unknown[]) => void = () => {}): Agent {
   const scopeFiber = ctx.plugin(() => {})
+  const id = SessionId(sessionId)
   const agent = {
-    id: `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
@@ -183,11 +182,13 @@ async function setupSandboxed(withApproval = false) {
 function sandboxAgent(mode?: 'read-only' | 'workspace-write' | 'danger-full-access', ctx?: Context): Agent {
   const events: Array<{ type: string; data?: Record<string, unknown> }> = [{ type: 'turn/start' }]
   if (mode !== undefined) events.push({ type: 'bash/sandbox-mode', data: { mode } })
+  const id = SessionId('sandbox-session')
   return {
-    id: 'sandbox-agent',
+    id,
     ...ctx === undefined ? {} : { ctx: ctx.plugin(() => {}).ctx },
     session: {
-      header: { version: 0, id: 'sandbox-session', createdAt: 0 },
+      id,
+      header: { version: 0, id, createdAt: 0 },
       events,
       append: (type: string, data: Record<string, unknown>) => {
         const event = { type, data }

packages/code-runtime/code-runtime-worker/README.md

@@ -37,6 +37,10 @@ The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. Th
 
 Indirectly, through Code Mode in [`dsh-tools`](../../core/tools/README.md), which renders this worker's capped printed or returned data and exact `[dsh-code-runtime-worker] log capture truncated at <maxLogBytes> bytes` and `… [truncated]` markers into a retained `run_code` result. Binding traffic and worker internals stay outside context.
 
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
 ## Known Limitations and Deferred Work
 
 - **OS processes a program spawns survive termination** — `worker.terminate()` ends the thread only, weaker than bash-local's process-group kill; orphan cleanup is a deployment concern until a container backend exists.

packages/code-runtime/code-runtime/README.md

@@ -22,6 +22,10 @@ Semantics every implementation must honor (contract details in the class JSDoc):
 
 Indirectly, through Code Mode in `dsh-tools`, which exposes `run_code` and returns program logs, values, or failures as retained tool-result tokens.
 
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
 ## Known Limitations and Deferred Work
 
 - **`run()` is one-shot** — `logs` arrive only on the resolved `CodeRunResult`; the seam exposes no streaming-log or progress surface for a live program's output.

packages/compact/compact-basic/README.md

@@ -8,15 +8,16 @@ This is the implementation tier of the compaction capability — see the [interf
 
 This backend owns the compaction policy:
 
-- **Measurement** — the singleton `ctx.tokenMeter` prices the provisional request envelope and current surface at one consumed-log revision. The current prompt and prefix override their logged values; the pre-step boundary reuses logged tools and call config.
+- **Measurement** — the singleton `ctx.tokenMeter` prices the latest canonical logged envelope and current surface at one consumed-log revision. Post-step pressure therefore includes the actual system prompt, tools, prefix, routing, assistant completion, tool results, buffered context, and steering.
 - **Retention** — compact the oldest whole surface units while preserving a recent tail and balanced tool-call/result cuts through the [`dsh-compact` boundary helpers](../compact/README.md#tool-pairing-boundaries). Turn boundaries do not protect old steps inside a runaway turn. An open indivisible tail declines until it closes; a single unit larger than the budget remains out of scope.
 - **Convergence** — retry head-checkpoint compaction up to `compactionRetries`; reject a summary that does not shrink its source, and throw if retries cannot return below threshold.
 - **Summarization** — a direct `llm/stream` call uses the configured provider/model pair and cap, falling back to the latest logged request target and then the agent target, without running the loop-only `agent/request` seam. The input transcript preserves non-text blocks as tagged placeholders; only returned text enters the checkpoint, excluding reasoning and tool calls that would leak private reasoning or create an orphaned call.
 - **Framing** — the replacement user message marks established checkpoint context with `<compacted-summary>` tags. The raw summary remains on the provenance event, and later automatic cycles merge the prior checkpoint.
-- **Lifecycle** — `compactRegion()` requires its agent to own the exact target session and rejects mismatch before resolution or mutation; a valid call records its start, summary, replacement, and end. The serial `agent/pre-step` listener checks pressure before every step, outside an open step, so a tool-heavy turn remains compactable and the loop derives history once after mutation.
-- **Failure handling** — an unmatched `compact/start` is an inert crash marker because no replacement landed. Recoverable failure records an error end and leaves the surface unchanged.
+- **Lifecycle** — `compactRegion()` mutates `agent.session` and records its start, summary, replacement, and end. The serial `agent/post-step` listener checks pressure after successful output and tool work are durable but before `step/end`. Canonical provider overflow is handled through `agent/request-error` after the failed step closes.
+- **Overflow recovery** — below-threshold overflow bypasses normal retention and attempts one maximal balanced head reduction while leaving the newest indivisible unit. Retry is authorized only when `surface.replaceGeneration` advances; no range, no replacement, recovery failure, an exhausted cap, cancellation, or an unknown/noncanonical error preserves the original provider failure.
+- **Failure handling** — an unmatched `compact/start` is an inert crash marker because no replacement landed. A region failure records an error end and leaves the surface unchanged. Operational post-step failures warn and continue; overflow-recovery failure preserves the original provider error.
 
-`summarize()` is the sole subclass hook. A template- or remote-summarizer subclass can override it while pressure, retention, provenance, shrink validation, and shadowed-token accounting stay on `ctx.tokenMeter`. The hook returns the summary blocks together with the call envelope it used (`{ summary, provider, model, maxTokens? }`), which is logged on `compact/summary`.
+The protected `summarize()` method is the sole subclass hook. A template- or remote-summarizer subclass can override it while pressure, retention, provenance, shrink validation, and shadowed-token accounting stay on `ctx.tokenMeter`. The hook returns the summary blocks together with the call envelope it used (`{ summary, provider, model, maxTokens? }`), which is logged on `compact/summary`.
 
 ## Config (`BasicCompactConfig`)
 
@@ -30,7 +31,8 @@ Every setting is optional. The pressure and retention policy applies to the toke
 | `summarizationModel` | no (default `''`) | Set together with `summarizationProvider`; an empty pair resolves the latest logged request target, then the `AgentOptions` pair. |
 | `maxTokens` | no (default `8192`) | Provider generation cap for the summarization call; may include reasoning tokens. |
 | `compactionRetries` | no (default `1`) | Extra attempts after the first when pressure remains above threshold. |
-| `auto` | no (default `true`) | Register the `agent/pre-step` automatic listener. Set `false` for manual-only. |
+| `maxOverflowRetries` | no (default `1`) | Maximum retries after canonical context-window overflow; `0` disables recovery only. |
+| `auto` | no (default `true`) | Register post-step pressure and overflow-recovery listeners. Set `false` for manual-only. |
 
 ## Usage
 
@@ -40,7 +42,7 @@ import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 
 export const name = 'compact-basic'
-export const inject = ['llm']
+export const inject = ['llm', 'tokenMeter']
 
 export function apply(ctx: Context): void {
   ctx.plugin(TokenMeterService)
@@ -54,29 +56,45 @@ Loading the plugin registers `ctx.compact`. With `auto: true` (the default) it c
 
 ### Conversation history
 
-**What the model sees**: Before a step whose estimated envelope and history exceed the threshold, the conversation model receives the checkpoint preamble below, a blank line, `<compacted-summary>`, the data-dependent summary, and `</compacted-summary>`. This one checkpoint replaces the selected older range and is followed by the retained recent units.
+#### What the model sees
 
-**Token effect**: The replacement reduces future input history rather than appending a second copy. The summary remains until a later compaction replaces it; one oversized indivisible unit can still exceed the budget.
+After a successful step crosses the threshold, the next request receives the checkpoint preamble below, a blank line, `<compacted-summary>`, the data-dependent summary, and `</compacted-summary>`. Overflow recovery rebuilds the immediate retry from that replacement. This one checkpoint replaces the selected older range and is followed by the retained recent units.
 
-#### Conversation checkpoint preamble
+##### Conversation checkpoint preamble
 
 ```markdown
 This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.
 ```
 
+#### Token effect
+
+The replacement reduces future input history rather than appending a second copy. The summary remains until a later compaction replaces it; one oversized indivisible unit can still exceed the budget.
+
+#### KV Cache effect
+
+Replacing rather than append-only. Each checkpoint invalidates reuse from the first replaced history token; the unchanged request prefix before that range remains reusable.
+
 ### Auxiliary summarizer user message
 
-**What the model sees**: The summarization model receives exactly `Summarize this conversation history:` followed by a blank line, the data-dependent [`renderTranscript()`](../compact/README.md) output, another blank line, and `Summary:`. The conversation model never sees this private request or its reasoning; only returned text is stored.
+#### What the model sees
 
-**Token effect**: This is a separate model call with data-dependent input and `maxTokens`-capped output. Convergence retries can pay this cost more than once.
+The summarization model receives exactly `Summarize this conversation history:` followed by a blank line, the data-dependent [`renderTranscript()`](../compact/README.md) output, another blank line, and `Summary:`. The conversation model never sees this private request or its reasoning; only returned text is stored.
+
+#### Token effect
+
+This is a separate model call with data-dependent input and `maxTokens`-capped output. Convergence retries can pay this cost more than once.
+
+#### KV Cache effect
+
+Independent of the conversation request cache. An auxiliary call can reuse an exact transcript prefix, while a different selected range or rendering invalidates reuse from its first changed token.
 
 ### Auxiliary summarizer system prompt
 
-**What the model sees**: The summarization model receives the checkpoint-writing instruction below.
+#### What the model sees
 
-**Token effect**: Fixed auxiliary input cost plus the data-dependent transcript on every summarization attempt.
+The summarization model receives the checkpoint-writing instruction below.
 
-#### Auxiliary summarizer system prompt
+##### Auxiliary summarizer system prompt
 
 ```markdown
 You are a compaction engine for an AI coding assistant. Condense the conversation transcript into a structured checkpoint that lets another model resume the work with no loss of essential context.
@@ -114,10 +132,19 @@ Rules:
 - If the transcript already contains a <compacted-summary> block, it is a PRIOR checkpoint. Do not copy it forward verbatim: preserve still-true facts, drop stale ones, and merge newer information into a single consolidated summary under the same structure.
 ```
 
+#### Token effect
+
+Fixed auxiliary input cost plus the data-dependent transcript on every summarization attempt.
+
+#### KV Cache effect
+
+Prefix-stable for auxiliary calls while this instruction and the summarizer route are unchanged. Changing either starts a different prefix; transcript changes occur after the instruction.
+
 ## Known Limitations and Deferred Work
 
-- **Pre-step sees a provisional request envelope** — the current prompt and prefix are exact, but routing and tool changes made later in `agent/request` are not logged yet. A router-only agent with no provisional provider/model pair skips that check.
 - **Meter accuracy follows the fixed heuristic** — missing reusable provider usage falls back to character count plus structural overhead rather than exact tokenization.
+- **Overflow classification is adapter-maintained** — provider wording can change; both DeepSeek adapters normalize currently recognized context-limit failures to `CONTEXT_WINDOW_EXCEEDED`.
+- **Single-unit and envelope-only overflow remain outside surface compaction** — recovery cannot split one indivisible message/tool unit or shrink system/tools/prefix.
 - **`compactRegion` requires an open turn** — a manual call on a fully-closed session throws ("no open turn") rather than compacting.
 - **Summarization failure fails closed with full, over-budget history** — including truncation at the summarization `maxTokens`, which hidden reasoning tokens can consume; the auto path logs a warning and proceeds.
 - **The summarization call has no transcript-snapshot coverage** — `dsh-llm-replay` derives calls from `assistant/chunk` events, so this chunk-less direct `ctx.llm.stream()` call cannot replay (named deferred replay infrastructure in [the seam RFC](../../../docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md)).

packages/compact/compact-basic/src/automatic.ts

@@ -1,52 +0,0 @@
-/**
- * Automatic pre-step pressure listener for compact-basic.
- *
- * @module @deepseek-ai/dsh-compact-basic/automatic
- */
-
-import type { Context } from 'cordis'
-import type { CompactionResult } from '@deepseek-ai/dsh-compact'
-import type { Message } from '@deepseek-ai/dsh-llm'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-
-interface AutomaticCompactor {
-  compactIfNeeded(
-    agent: Agent,
-    fullSystemPrompt: string,
-    sessionPrefix: readonly Message[],
-    signal: AbortSignal,
-  ): Promise<CompactionResult | null>
-}
-
-/**
- * Register the implementation-owned automatic compaction listener.
- * @param ctx - context owning the listener effect and logger.
- * @param service - compactor whose public methods remain dynamically dispatched.
- */
-export function registerAutomaticCompaction(
-  ctx: Context,
-  service: AutomaticCompactor,
-): void {
-  ctx.on('agent/pre-step', async (
-    agent: Agent,
-    _turn: number,
-    _step: number,
-    fullSystemPrompt: string,
-    sessionPrefix: readonly Message[],
-    signal: AbortSignal,
-  ) => {
-    try {
-      const result = await service.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)
-      if (result !== null) {
-        ctx.logger.info(
-          `compaction: shadowed ${result.shadowedSeqs.length} surface nodes `
-          + `(seqs ${result.shadowedRange.start}-${result.shadowedRange.end}, `
-          + `~${result.shadowedTokenCount} tokens)`,
-        )
-      }
-    } catch (error: unknown) {
-      const message = error instanceof Error ? error.message : String(error)
-      ctx.logger.warn(`compaction failed: ${message}; proceeding with full history`)
-    }
-  })
-}

packages/compact/compact-basic/src/config.ts

@@ -22,6 +22,7 @@ const BASIC_COMPACT_CONFIG_KEYS: ReadonlySet<string> = new Set([
   'summarizationModel',
   'maxTokens',
   'compactionRetries',
+  'maxOverflowRetries',
   'auto',
 ])
 
@@ -31,7 +32,8 @@ function validateConfigKeys(config: BasicCompactConfig): void {
     if (!BASIC_COMPACT_CONFIG_KEYS.has(key)) {
       throw new Error(
         `BasicCompactConfig: unknown key "${key}" `
-        + '(allowed: thresholdRatio, retainTokens, summarizationProvider, summarizationModel, maxTokens, compactionRetries, auto)',
+        + '(allowed: thresholdRatio, retainTokens, summarizationProvider, summarizationModel, '
+        + 'maxTokens, compactionRetries, maxOverflowRetries, auto)',
       )
     }
   }
@@ -58,6 +60,7 @@ export function resolveConfig(
     summarizationModel: config.summarizationModel ?? '',
     maxTokens: config.maxTokens ?? 8192,
     compactionRetries: config.compactionRetries ?? 1,
+    maxOverflowRetries: config.maxOverflowRetries ?? 1,
     auto: config.auto ?? true,
   }
 
@@ -71,6 +74,7 @@ export function resolveConfig(
   }
   assertPositiveInteger('maxTokens', resolved.maxTokens)
   assertNonNegativeInteger('compactionRetries', resolved.compactionRetries)
+  assertNonNegativeInteger('maxOverflowRetries', resolved.maxOverflowRetries)
   if (typeof resolved.summarizationProvider !== 'string') {
     throw new Error('BasicCompactConfig: summarizationProvider must be a string')
   }

packages/compact/compact-basic/src/index.ts

@@ -7,12 +7,11 @@
 import { Context } from 'cordis'
 import z from 'schemastery'
 import { CompactService } from '@deepseek-ai/dsh-compact'
-import type { CompactionResult } from '@deepseek-ai/dsh-compact'
-import { canonicalHeader } from '@deepseek-ai/dsh-session'
-import type { EpochHeader, Session } from '@deepseek-ai/dsh-session'
-import type { ContentBlock, Message } from '@deepseek-ai/dsh-llm'
+import type { CompactionResult, CompactionTrigger } from '@deepseek-ai/dsh-compact'
+import type { Session } from '@deepseek-ai/dsh-session'
+import { CONTEXT_WINDOW_EXCEEDED_CODE, assertNever } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { registerAutomaticCompaction } from './automatic.ts'
 import { resolveConfig } from './config.ts'
 import { compactSurfaceRegion, selectCompactableRange } from './region.ts'
 import { summarizeWithLlm } from './summarizer.ts'
@@ -21,41 +20,15 @@ import type {
   ResolvedConfig,
 } from './types.ts'
 
-export { resolveConfig } from './config.ts'
 export type {
   BasicCompactConfig,
   ResolvedConfig,
 } from './types.ts'
 
-/** Resolve the latest actual routed provider/model, then the complete agent fallback pair. */
-function effectiveTarget(agent: Agent): { provider: string; model: string } | undefined {
-  const latest = agent.session.requestHeader()?.config
-  if (latest !== undefined) return { provider: latest.provider, model: latest.model }
-  const { provider, model } = agent.options
-  if (provider === undefined || provider.length === 0 || model === undefined || model.length === 0) {
-    return undefined
-  }
-  return { provider, model }
-}
-
-/**
- * Build the provisional pre-step request envelope. Prompt and prefix are exact;
- * tools and non-model call config come from the latest logged request because
- * later request middleware has not run yet.
- */
-function provisionalHeader(
-  target: { provider: string; model: string },
-  session: Session,
-  fullSystemPrompt: string,
-  sessionPrefix: readonly Message[],
-): EpochHeader {
-  const latest = session.requestHeader()
-  return canonicalHeader({
-    config: latest === undefined ? target : { ...latest.config, ...target },
-    ...fullSystemPrompt.length === 0 ? {} : { system: fullSystemPrompt },
-    ...latest?.tools === undefined ? {} : { tools: latest.tools },
-    ...sessionPrefix.length === 0 ? {} : { messagePrefix: [...sessionPrefix] },
-  })
+/** Resolve the exact model durably routed for the latest provider request. */
+function routedModel(session: Session): string | undefined {
+  const model = session.requestHeader()?.config.model
+  return model === undefined || model.length === 0 ? undefined : model
 }
 
 /**
@@ -76,6 +49,7 @@ export class BasicCompactService extends CompactService {
     summarizationModel: z.string().default(''),
     maxTokens: z.number().step(1).min(1).default(8192),
     compactionRetries: z.number().step(1).min(0).default(1),
+    maxOverflowRetries: z.number().step(1).min(0).default(1),
     auto: z.boolean().default(true),
   })
 
@@ -85,7 +59,63 @@ export class BasicCompactService extends CompactService {
   constructor(ctx: Context, config: BasicCompactConfig = {}) {
     super(ctx)
     this.config = resolveConfig(config, ctx.tokenMeter)
-    if (this.config.auto) registerAutomaticCompaction(ctx, this)
+    if (this.config.auto) this._registerAutomaticCompaction()
+  }
+
+  /**
+   * Register the automatic post-step pressure and context-overflow recovery
+   * listeners. `compactIfNeeded` stays dynamically dispatched so subclass
+   * overrides are honored at event time.
+   */
+  private _registerAutomaticCompaction(): void {
+    const { ctx } = this
+    const logResult = (result: CompactionResult, trigger: string): void => {
+      ctx.logger.info(
+        `compaction (${trigger}): shadowed ${result.shadowedSeqs.length} surface nodes `
+        + `(seqs ${result.shadowedRange.start}-${result.shadowedRange.end}, `
+        + `~${result.shadowedTokenCount} tokens)`,
+      )
+    }
+
+    ctx.on('agent/post-step', async (
+      agent: Agent,
+      _turn: number,
+      _step: number,
+      signal: AbortSignal,
+    ) => {
+      if (signal.aborted) return
+      try {
+        const result = await this.compactIfNeeded(agent, 'pressure', signal)
+        if (result !== null) logResult(result, 'post-step pressure')
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error)
+        ctx.logger.warn(`post-step compaction failed: ${message}; continuing the turn`)
+      }
+    })
+
+    ctx.on('agent/request-error', async (agent, _turn, _step, error, retryAttempt, signal, next) => {
+      if (error.code !== CONTEXT_WINDOW_EXCEEDED_CODE
+        || retryAttempt >= this.config.maxOverflowRetries
+        || signal.aborted) return next()
+
+      let generation: number
+      let result: CompactionResult | null
+      try {
+        generation = agent.session.surface.replaceGeneration
+        result = await this.compactIfNeeded(agent, 'context-overflow', signal)
+      } catch (recoveryError: unknown) {
+        const message = recoveryError instanceof Error ? recoveryError.message : String(recoveryError)
+        ctx.logger.warn(
+          `context-overflow compaction failed: ${message}; preserving the original request error`,
+        )
+        return next()
+      }
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- signal can abort while compaction is awaited.
+      if (signal.aborted || result === null
+        || agent.session.surface.replaceGeneration <= generation) return next()
+      logResult(result, 'context overflow recovery')
+      return { action: 'retry' }
+    })
   }
 
   /**
@@ -96,7 +126,7 @@ export class BasicCompactService extends CompactService {
    * @param signal - optional cancellation forwarded to the adapter.
    * @returns safe text summary blocks and exact auxiliary-call provenance.
    */
-  async summarize(
+  protected async summarize(
     text: string,
     agent: Agent,
     signal?: AbortSignal,
@@ -105,27 +135,39 @@ export class BasicCompactService extends CompactService {
   }
 
   /**
-   * Check replayed pressure for the provisional pre-step envelope and compact
-   * a tool-balanced head until it falls below the service-wide threshold.
-   * A genuinely model-less router-first step skips this provisional check.
-   * @param agent - agent whose session and provisional provider/model are measured.
-   * @param fullSystemPrompt - current assembled system prompt override.
-   * @param sessionPrefix - current request-only prefix override.
-   * @param signal - live step cancellation signal forwarded to summarization.
+   * Compact for replayed post-step pressure or one provider-confirmed context
+   * overflow. Both triggers price the latest durable routed request envelope;
+   * overflow bypasses the normal threshold and retained-tail policy so it can
+   * force one useful balanced reduction.
+   * @param agent - agent whose latest durable routed request is measured.
+   * @param trigger - normal post-step pressure or context-overflow recovery.
+   * @param signal - live turn cancellation signal forwarded to summarization.
    * @returns the latest compaction result, or `null` when no check/work applies.
    */
   override async compactIfNeeded(
     agent: Agent,
-    fullSystemPrompt: string,
-    sessionPrefix: readonly Message[],
+    trigger: CompactionTrigger,
     signal: AbortSignal,
   ): Promise<CompactionResult | null> {
-    const target = effectiveTarget(agent)
-    if (target === undefined) return null
+    const model = routedModel(agent.session)
+    if (model === undefined) return null
     const meter = this.ctx.tokenMeter
-    const requestHeader = provisionalHeader(target, agent.session, fullSystemPrompt, sessionPrefix)
+    switch (trigger) {
+      case 'context-overflow': {
+        const measurement = meter.measure(agent.session)
+        const range = selectCompactableRange(agent.session, measurement, 0)
+        if (range === null) return null
+        return this.compactRegion(range.start, range.end, agent, signal)
+      }
+      case 'pressure':
+        break
+      /* v8 ignore next -- closed-union exhaustiveness guard */
+      default:
+        assertNever(trigger, 'compaction trigger')
+    }
+
     const threshold = Math.floor(meter.contextWindow * this.config.thresholdRatio)
-    let measurement = meter.measure(agent.session, requestHeader)
+    let measurement = meter.measure(agent.session)
     if (measurement.totalTokens < threshold) return null
 
     let result: CompactionResult | null = null
@@ -137,8 +179,8 @@ export class BasicCompactService extends CompactService {
         /* v8 ignore next -- paired with the defensive post-success branch above. */
         break
       }
-      result = await this.compactRegion(agent.session, range.start, range.end, agent, signal)
-      measurement = meter.measure(agent.session, requestHeader)
+      result = await this.compactRegion(range.start, range.end, agent, signal)
+      measurement = meter.measure(agent.session)
       if (measurement.totalTokens < threshold) return result
     }
 
@@ -149,10 +191,8 @@ export class BasicCompactService extends CompactService {
   }
 
   /**
-   * Compact one inclusive positional surface range using the effective
-   * token meter for all retention and shrink pricing. Reject an agent that does
-   * not own the exact target before any mutation.
-   * @param session - session whose surface is mutated; must equal `agent.session`.
+   * Compact one inclusive positional range from the agent-owned surface using
+   * the effective token meter for all retention and shrink pricing.
    * @param start - inclusive first surface-node seq.
    * @param end - inclusive last surface-node seq.
    * @param agent - owner of the target session, used by the summarizer.
@@ -160,15 +200,12 @@ export class BasicCompactService extends CompactService {
    * @returns the successful durable compaction result.
    */
   override async compactRegion(
-    session: Session,
     start: number,
     end: number,
     agent: Agent,
     signal?: AbortSignal,
   ): Promise<CompactionResult> {
-    if (session !== agent.session) {
-      throw new Error('compactRegion: agent.session must be the exact target session')
-    }
+    const session = agent.session
     return compactSurfaceRegion({
       meter: this.ctx.tokenMeter,
       summarize: (text, owner, abort) => this.summarize(text, owner, abort),

packages/compact/compact-basic/src/summarizer.ts

@@ -119,8 +119,8 @@ export async function summarizeWithLlm(
   }
   return {
     summary,
-    provider: target.provider,
-    model: target.model,
+    provider: options.provider,
+    model: options.model,
     maxTokens: config.maxTokens,
   }
 }

packages/compact/compact-basic/src/types.ts

@@ -18,7 +18,9 @@ export interface BasicCompactConfig {
   maxTokens?: number
   /** Extra attempts after the first compaction when pressure remains above threshold. Defaults to `1`. */
   compactionRetries?: number
-  /** Enable the automatic `agent/pre-step` pressure listener. Defaults to `true`. */
+  /** Maximum retries after canonical context overflow; `0` disables recovery. Defaults to `1`. */
+  maxOverflowRetries?: number
+  /** Enable automatic post-step pressure and overflow-recovery listeners. Defaults to `true`. */
   auto?: boolean
 }
 
@@ -30,5 +32,6 @@ export interface ResolvedConfig {
   readonly summarizationModel: string
   readonly maxTokens: number
   readonly compactionRetries: number
+  readonly maxOverflowRetries: number
   readonly auto: boolean
 }

packages/compact/compact-basic/tests/compact-basic.spec.ts

@@ -1,11 +1,13 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import BasicCompactService, { resolveConfig } from '@deepseek-ai/dsh-compact-basic'
+import BasicCompactService from '@deepseek-ai/dsh-compact-basic'
 import type { BasicCompactConfig } from '@deepseek-ai/dsh-compact-basic'
 import { selectCompactableRange } from '@deepseek-ai/dsh-compact-basic/src/region.ts'
+import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compact'
+import { resolveConfig } from '@deepseek-ai/dsh-compact-basic/src/config.ts'
 import type { CompactionResult } from '@deepseek-ai/dsh-compact'
-import LlmService, { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, GenerateOptions, Message, StreamChunk } from '@deepseek-ai/dsh-llm'
+import LlmService, { CallId, CONTEXT_WINDOW_EXCEEDED_CODE, LlmAdapter } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -33,6 +35,12 @@ function conversation(turns = 4, text = 'fixture '.repeat(40).trim()): Session {
       source: { kind: 'user' },
     }, { surfaceOp: 'append' })
     session.append('step/start', { turn, step: 1 })
+    if (turn === 1) {
+      session.append('request/header', {
+        header: { config: { provider: MODEL, model: MODEL } },
+        reason: 'initial',
+      })
+    }
     session.append('assistant/message', {
       provenance: { provider: MODEL, model: MODEL },
       turn,
@@ -59,6 +67,12 @@ function toolConversation(): Session {
       source: { kind: 'user' },
     }, { surfaceOp: 'append' })
     session.append('step/start', { turn, step: 1 })
+    if (turn === 1) {
+      session.append('request/header', {
+        header: { config: { provider: MODEL, model: MODEL } },
+        reason: 'initial',
+      })
+    }
     session.append('assistant/message', {
       provenance: { provider: MODEL, model: MODEL },
       turn,
@@ -118,11 +132,10 @@ function service(
 async function compactIfNeeded(
   compact: BasicCompactService,
   session: Session,
+  trigger: 'pressure' | 'context-overflow' = 'pressure',
   model: string | undefined = MODEL,
-  system = '',
-  prefix: readonly Message[] = [],
 ): Promise<CompactionResult | null> {
-  return compact.compactIfNeeded(agent(session, model), system, prefix, SIGNAL)
+  return compact.compactIfNeeded(agent(session, model), trigger, SIGNAL)
 }
 
 describe('compact configuration and defaults', () => {
@@ -137,6 +150,7 @@ describe('compact configuration and defaults', () => {
       summarizationModel: '',
       maxTokens: 8192,
       compactionRetries: 1,
+      maxOverflowRetries: 1,
       auto: true,
     })
     expect(Object.isFrozen(resolved)).toBe(true)
@@ -166,6 +180,7 @@ describe('compact configuration and defaults', () => {
     const bad = [
       [{ maxTokens: 0 }, /maxTokens/],
       [{ compactionRetries: -1 }, /compactionRetries/],
+      [{ maxOverflowRetries: -1 }, /maxOverflowRetries/],
       [{ auto: 'yes' }, /auto must be a boolean/],
       [{ summarizationProvider: 1 }, /summarizationProvider must be a string/],
       [{ summarizationModel: 1 }, /summarizationModel must be a string/],
@@ -192,19 +207,58 @@ describe('pressure measurement and retention', () => {
     retainTokens: 180,
   }
 
-  it('skips the provisional check only when no routed or fallback model exists', async () => {
+  it('skips when no durable routed model exists instead of using AgentOptions fallback', async () => {
     const compact = service(compactConfig)
-    const session = conversation()
-    expect(await compact.compactIfNeeded(agent(session), '', [], SIGNAL)).toBeNull()
+    const session = new Session(SessionId('headerless'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    await expect(compact.compactIfNeeded(agent(session, MODEL), 'pressure', SIGNAL))
+      .resolves.toBeNull()
     expect(compact.calls).toHaveLength(0)
   })
 
   it('meters any routed model without profile resolution', async () => {
     const compact = service(compactConfig)
-    await expect(compactIfNeeded(compact, conversation(), 'unlisted-model'))
+    const session = conversation()
+    session.append('request/header', {
+      header: { config: { provider: 'unlisted-provider', model: 'unlisted-model' } },
+      reason: 'resume',
+    })
+    await expect(compactIfNeeded(compact, session))
       .resolves.not.toBeNull()
   })
 
+  it('declines forced overflow when the whole surface is one indivisible tool pair', async () => {
+    const compact = service(compactConfig)
+    const session = new Session(SessionId('single-tool-pair'))
+    const callId = CallId('single-call')
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('step/start', { turn: 1, step: 1 })
+    session.append('request/header', {
+      header: { config: { provider: MODEL, model: MODEL } },
+      reason: 'initial',
+    })
+    session.append('assistant/message', {
+      provenance: { provider: MODEL, model: MODEL },
+      turn: 1,
+      step: 1,
+      content: [{ type: 'tool-call', id: callId, name: 'read', arguments: '{}' }],
+    }, { surfaceOp: 'append' })
+    session.append('tool/call', { turn: 1, step: 1, callId, name: 'read', arguments: '{}' })
+    session.append('tool/result', {
+      turn: 1,
+      step: 1,
+      callId,
+      content: [{ type: 'text', text: 'result' }],
+      isError: false,
+    }, { surfaceOp: 'append' })
+    session.append('step/end', { turn: 1, step: 1 })
+    const generation = session.surface.replaceGeneration
+
+    await expect(compactIfNeeded(compact, session, 'context-overflow')).resolves.toBeNull()
+    expect(session.surface.replaceGeneration).toBe(generation)
+    expect(session.events.some(event => event.type === 'compact/start')).toBe(false)
+  })
+
   it('does nothing below threshold and compacts a priced head above threshold', async () => {
     const compact = service(compactConfig)
     expect(await compactIfNeeded(compact, conversation(2))).toBeNull()
@@ -216,26 +270,31 @@ describe('pressure measurement and retention', () => {
     expect(session.surface.nodes.length).toBeLessThan(8)
   })
 
-  it('counts the current prompt and request prefix without putting either on the surface', async () => {
+  it('counts the durable routed request envelope without putting its prefix on the surface', async () => {
     const compact = service({
       auto: false,
-      thresholdRatio: 0.7,
+      thresholdRatio: 0.9,
       retainTokens: 50,
     })
-    const session = conversation(2, 'x'.repeat(200))
+    const session = conversation(2, 'x'.repeat(600))
     expect(await compactIfNeeded(compact, session)).toBeNull()
 
-    const prefix: Message[] = [{
-      role: 'user',
-      content: [{ type: 'text', text: 'p'.repeat(1_000) }],
-    }]
-    const result = await compactIfNeeded(compact, session, MODEL, 's'.repeat(1_000), prefix)
+    const prefix = [{ role: 'user' as const, content: [{ type: 'text' as const, text: 'p'.repeat(600) }] }]
+    session.append('request/header', {
+      header: {
+        config: { provider: MODEL, model: MODEL },
+        system: 's'.repeat(600),
+        messagePrefix: prefix,
+      },
+      reason: 'resume',
+    })
+    const result = await compactIfNeeded(compact, session)
     expect(result).not.toBeNull()
     expect(prefix).toHaveLength(1)
     expect(session.events.some(event => event.type === 'context/message')).toBe(false)
   })
 
-  it('uses the latest logged routed model in the provisional request envelope', async () => {
+  it('uses the latest logged request envelope without an AgentOptions override', async () => {
     const ctx = createContext()
     const compact = service({
       auto: false,
@@ -249,19 +308,28 @@ describe('pressure measurement and retention', () => {
     })
     const measure = vi.spyOn(ctx.tokenMeter, 'measure')
 
-    const result = await compactIfNeeded(compact, session, 'fallback')
+    const result = await compactIfNeeded(compact, session, 'pressure', 'fallback')
     expect(result).not.toBeNull()
-    expect(measure.mock.calls[0]?.[1]?.config.provider).toBe('actual')
-    expect(measure.mock.calls[0]?.[1]?.config.model).toBe('actual')
+    expect(session.requestHeader()?.config.model).toBe('actual')
+    expect(measure.mock.calls[0]).toEqual([session])
   })
 
   it('declines when envelope pressure is high but the surface has no compactable range', async () => {
     const compact = service(compactConfig)
     const empty = new Session(SessionId('empty'))
-    expect(await compactIfNeeded(compact, empty, MODEL, 'x'.repeat(100_000))).toBeNull()
+    empty.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    empty.append('request/header', {
+      header: { config: { provider: MODEL, model: MODEL }, system: 'x'.repeat(100_000) },
+      reason: 'initial',
+    })
+    expect(await compactIfNeeded(compact, empty)).toBeNull()
 
     const retained = conversation(1)
-    expect(await compactIfNeeded(compact, retained, MODEL, 'x'.repeat(100_000))).toBeNull()
+    retained.append('request/header', {
+      header: { config: { provider: MODEL, model: MODEL }, system: 'x'.repeat(100_000) },
+      reason: 'resume',
+    })
+    expect(await compactIfNeeded(compact, retained)).toBeNull()
   })
 
   it('uses one unified measurement for each pressure-and-retention decision', async () => {
@@ -349,32 +417,11 @@ describe('pressure measurement and retention', () => {
 })
 
 describe('compaction region transaction', () => {
-  it('rejects an agent that does not own the exact target session before mutation', async () => {
-    const compact = service()
-    const target = conversation(2)
-    const owner = conversation(1)
-    const targetEvents = [...target.events]
-    const ownerEvents = [...owner.events]
-    const nodes = target.surface.nodes
-
-    await expect(compact.compactRegion(
-      target,
-      nodes[0]!,
-      nodes[1]!,
-      agent(owner),
-    )).rejects.toThrow('compactRegion: agent.session must be the exact target session')
-
-    expect(target.events).toEqual(targetEvents)
-    expect(owner.events).toEqual(ownerEvents)
-    expect(compact.calls).toEqual([])
-  })
-
   it('lands a framed, replayable checkpoint with exact pricing provenance', async () => {
     const compact = service()
     const session = conversation(3)
-    const before = session.surface.nodes
+    const before = [...session.surface.nodes]
     const result = await compact.compactRegion(
-      session,
       before[0]!,
       before[3]!,
       agent(session, MODEL),
@@ -410,7 +457,6 @@ describe('compaction region transaction', () => {
     const session = conversation(2)
     const nodes = session.surface.nodes
     await expect(compact.compactRegion(
-      session,
       startOverride ?? nodes[0]!,
       endOverride ?? nodes[1]!,
       agent(session, MODEL),
@@ -422,7 +468,6 @@ describe('compaction region transaction', () => {
     const plain = conversation(2)
     const nodes = plain.surface.nodes
     await expect(compact.compactRegion(
-      plain,
       nodes[2]!,
       nodes[1]!,
       agent(plain, MODEL),
@@ -431,13 +476,11 @@ describe('compaction region transaction', () => {
     const tools = toolConversation()
     const toolNodes = tools.surface.nodes
     await expect(compact.compactRegion(
-      tools,
       toolNodes[2]!,
       toolNodes[4]!,
       agent(tools, MODEL),
     )).rejects.toThrow(/start seq .* not a balanced boundary/)
     await expect(compact.compactRegion(
-      tools,
       toolNodes[0]!,
       toolNodes[1]!,
       agent(tools, MODEL),
@@ -450,7 +493,6 @@ describe('compaction region transaction', () => {
     closed.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
     const nodes = closed.surface.nodes
     await expect(compact.compactRegion(
-      closed,
       nodes[0]!,
       nodes[1]!,
       agent(closed, MODEL),
@@ -460,7 +502,6 @@ describe('compaction region transaction', () => {
     locked.append('compact/start', { turn: 2 })
     const lockedNodes = locked.surface.nodes
     await expect(compact.compactRegion(
-      locked,
       lockedNodes[0]!,
       lockedNodes[1]!,
       agent(locked, MODEL),
@@ -477,7 +518,6 @@ describe('compaction region transaction', () => {
     const node = session.surface.nodes[0]!
 
     await expect(compact.compactRegion(
-      session,
       node,
       node,
       agent(session, MODEL),
@@ -497,7 +537,6 @@ describe('compaction region transaction', () => {
     const nodes = session.surface.nodes
 
     await expect(compact.compactRegion(
-      session,
       nodes[0]!,
       nodes[2]!,
       agent(session, MODEL),
@@ -511,7 +550,6 @@ describe('compaction region transaction', () => {
     const before = session.surface.nodes
 
     await expect(compact.compactRegion(
-      session,
       before[0]!,
       before[2]!,
       agent(session, MODEL),
@@ -527,7 +565,6 @@ describe('compaction region transaction', () => {
     const session = conversation(2)
     const nodes = session.surface.nodes
     await expect(compact.compactRegion(
-      session,
       nodes[0]!,
       nodes[2]!,
       agent(session, MODEL),
@@ -548,7 +585,6 @@ describe('compaction region transaction', () => {
     const nodes = session.surface.nodes
 
     await expect(compact.compactRegion(
-      session,
       nodes[0]!,
       nodes[2]!,
       agent(session, MODEL),
@@ -566,7 +602,6 @@ describe('compaction region transaction', () => {
     const nodes = session.surface.nodes
 
     await expect(compact.compactRegion(
-      session,
       nodes[0]!,
       nodes[2]!,
       agent(session, MODEL),
@@ -576,10 +611,22 @@ describe('compaction region transaction', () => {
 
   it('lets a model-independent custom summarizer compact without a conversation model', async () => {
     const compact = service()
-    const session = conversation(1)
+    const session = new Session(SessionId('model-less-region'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'history '.repeat(100) }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    session.append('step/start', { turn: 1, step: 1 })
+    session.append('assistant/message', {
+      provenance: { provider: 'historical', model: 'historical' },
+      turn: 1,
+      step: 1,
+      content: [{ type: 'text', text: 'answer '.repeat(100) }],
+    }, { surfaceOp: 'append' })
+    session.append('step/end', { turn: 1, step: 1 })
     const nodes = session.surface.nodes
     await expect(compact.compactRegion(
-      session,
       nodes[0]!,
       nodes[1]!,
       agent(session),
@@ -613,18 +660,28 @@ class ScriptedAdapter extends LlmAdapter {
   }
 }
 
+class ExposedCompactService extends BasicCompactService {
+  runSummarize(
+    text: string,
+    owner: Agent,
+    signal?: AbortSignal,
+  ): Promise<{ summary: ContentBlock[]; provider: string; model: string; maxTokens?: number }> {
+    return this.summarize(text, owner, signal)
+  }
+}
+
 async function summarizerHarness(
   blocks: readonly ContentBlock[],
   finish?: (StreamChunk & { type: 'finish' })['reason'],
   model = MODEL,
   config: BasicCompactConfig = { auto: false },
-): Promise<{ ctx: Context; adapter: ScriptedAdapter; compact: BasicCompactService }> {
+): Promise<{ ctx: Context; adapter: ScriptedAdapter; compact: ExposedCompactService }> {
   const ctx = new Context()
   await ctx.plugin(LlmService)
   void new TokenMeterService(ctx, { contextWindow: 1_000 })
   const adapter = new ScriptedAdapter(blocks, finish)
   ctx.llm.registerAdapter([model], adapter)
-  const compact = new BasicCompactService(ctx, config)
+  const compact = new ExposedCompactService(ctx, config)
   return { ctx, adapter, compact }
 }
 
@@ -641,7 +698,7 @@ describe('default one-shot summarizer', () => {
       maxTokens: 321,
     })
     const session = conversation(1)
-    const output = await compact.summarize('transcript', agent(session, 'fallback'), SIGNAL)
+    const output = await compact.runSummarize('transcript', agent(session, 'fallback'), SIGNAL)
 
     expect(output).toEqual({
       summary: [{ type: 'text', text: 'public summary' }],
@@ -666,19 +723,41 @@ describe('default one-shot summarizer', () => {
       header: { config: { provider: 'routed', model: 'routed' } },
       reason: 'initial',
     })
-    const output = await compact.summarize('history', agent(session, 'fallback'))
+    const output = await compact.runSummarize('history', agent(session, 'fallback'))
     expect(output.provider).toBe('routed')
     expect(output.model).toBe('routed')
     expect(adapter.lastOptions?.provider).toBe('routed')
     expect(adapter.lastOptions?.model).toBe('routed')
   })
 
+  it('records the model actually dispatched after one-shot stream routing', async () => {
+    const { ctx, compact } = await summarizerHarness([{ type: 'text', text: 'unused' }])
+    const routedAdapter = new ScriptedAdapter([{ type: 'text', text: 'routed summary' }])
+    ctx.llm.registerAdapter(['routed-summary-provider'], routedAdapter)
+    ctx.on('llm/stream', (options, next) => {
+      options.provider = 'routed-summary-provider'
+      options.model = 'routed-summary-model'
+      return next()
+    })
+
+    const session = conversation(3, 'large history '.repeat(500))
+    const nodes = session.surface.nodes
+    await compact.compactRegion(nodes[0]!, nodes[3]!, agent(session, MODEL), SIGNAL)
+    expect(session.events.findLast(event => event.type === 'compact/summary')?.data).toMatchObject({
+      summary: [{ type: 'text', text: 'routed summary' }],
+      provider: 'routed-summary-provider',
+      model: 'routed-summary-model',
+    })
+    expect(routedAdapter.lastOptions?.provider).toBe('routed-summary-provider')
+    expect(routedAdapter.lastOptions?.model).toBe('routed-summary-model')
+  })
+
   it('fails clearly when no complete summarization target can be resolved', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     void new TokenMeterService(ctx)
-    const compact = new BasicCompactService(ctx, { auto: false })
-    await expect(compact.summarize('history', agent(new Session(SessionId('model-less')))))
+    const compact = new ExposedCompactService(ctx, { auto: false })
+    await expect(compact.runSummarize('history', agent(new Session(SessionId('model-less')))))
       .rejects.toThrow(/no provider\/model available for summarization/)
   })
 
@@ -693,7 +772,7 @@ describe('default one-shot summarizer', () => {
       const { compact } = await summarizerHarness([], finish)
       let thrown: unknown
       try {
-        await compact.summarize('history', agent(conversation(1), MODEL))
+        await compact.runSummarize('history', agent(conversation(1), MODEL))
       } catch (error: unknown) {
         thrown = error
       }
@@ -705,32 +784,63 @@ describe('default one-shot summarizer', () => {
 
   it('rejects empty or reasoning-only successful output', async () => {
     const { compact } = await summarizerHarness([{ type: 'reasoning', text: 'private' }])
-    await expect(compact.summarize('history', agent(conversation(1), MODEL)))
+    await expect(compact.runSummarize('history', agent(conversation(1), MODEL)))
       .rejects.toThrow(/no text summary content/)
   })
 })
 
 describe('automatic listener and loader composition', () => {
-  function preStep(ctx: Context, owner: Agent): Promise<unknown> {
-    return ctx.serial('agent/pre-step', owner, 1, 1, '', [], SIGNAL)
+  function postStep(ctx: Context, owner: Agent, signal = SIGNAL): Promise<unknown> {
+    return ctx.serial('agent/post-step', owner, 1, 1, signal)
   }
 
-  it('compacts above threshold and remains idle below it', async () => {
+  function recover(
+    ctx: Context,
+    owner: Agent,
+    error: Error & { code?: string },
+    retryAttempt = 0,
+    signal = SIGNAL,
+    next: () => Promise<{ action: 'fail' | 'retry' }> = () => Promise.resolve({ action: 'fail' }),
+  ): Promise<{ action: 'fail' | 'retry' }> {
+    return ctx.waterfall('agent/request-error', owner, 1, 1, error, retryAttempt, signal, next)
+  }
+
+  function overflow(message = 'provider overflow'): Error & { code: string } {
+    return Object.assign(new Error(message), { code: CONTEXT_WINDOW_EXCEEDED_CODE })
+  }
+
+  it('compacts post-step above threshold using the durable routed model and remains idle below it', async () => {
     const ctx = createContext()
     const compact = new TestCompactService(ctx, {
       thresholdRatio: 0.5,
       retainTokens: 180,
     })
     const pressured = conversation(4)
-    await preStep(ctx, agent(pressured, MODEL))
+    await postStep(ctx, agent(pressured, 'unconfigured-agent-fallback'))
     expect(pressured.events.some(event => event.type === 'compact/summary')).toBe(true)
 
     const small = conversation(1)
-    await preStep(ctx, agent(small, MODEL))
+    await postStep(ctx, agent(small, MODEL))
     expect(small.events.some(event => event.type === 'compact/start')).toBe(false)
     expect(compact.calls).toHaveLength(1)
   })
 
+  it('skips post-step pressure when the step signal is already aborted', async () => {
+    const ctx = createContext()
+    const compact = new TestCompactService(ctx, {
+      thresholdRatio: 0.5,
+      retainTokens: 180,
+    })
+    const pressured = conversation(4)
+    const compactIfNeeded = vi.spyOn(compact, 'compactIfNeeded')
+
+    await expect(postStep(ctx, agent(pressured, MODEL), AbortSignal.abort('step aborted')))
+      .resolves.toBeUndefined()
+
+    expect(compactIfNeeded).not.toHaveBeenCalled()
+    expect(pressured.events.some(event => event.type === 'compact/start')).toBe(false)
+  })
+
   it('warns and continues after operational failures, including non-Errors', async () => {
     const ctx = createContext()
     const warnings: string[] = []
@@ -742,12 +852,187 @@ describe('automatic listener and loader composition', () => {
     compact.error = 'temporary failure'
     const session = conversation(4)
 
-    await expect(preStep(ctx, agent(session, MODEL))).resolves.toBeUndefined()
+    await expect(postStep(ctx, agent(session, MODEL))).resolves.toBeUndefined()
     expect(warnings).toContainEqual(expect.stringContaining('temporary failure'))
     expect(session.events.some(event => event.type === 'compact/summary')).toBe(false)
   })
 
-  it('auto:false installs no listener', async () => {
+  it('force-compacts below normal pressure for canonical overflow and retries only after replacement', async () => {
+    const ctx = createContext(10_000)
+    void new TestCompactService(ctx, {
+      thresholdRatio: 1,
+      retainTokens: 900,
+    })
+    const session = conversation(3)
+    const beforeGeneration = session.surface.replaceGeneration
+    const retainedSeq = session.surface.nodes.at(-1)!
+    const threshold = 10_000
+    expect(ctx.tokenMeter.measure(session).totalTokens).toBeLessThan(threshold)
+    const decision = await recover(ctx, agent(session, 'unconfigured-agent-fallback'), overflow())
+
+    expect(decision).toEqual({ action: 'retry' })
+    expect(session.surface.replaceGeneration).toBe(beforeGeneration + 1)
+    expect(session.events.some(event => event.type === 'compact/summary')).toBe(true)
+    expect(session.surface.nodes).toContain(retainedSeq)
+  })
+
+  it('preserves the newest whole tool-call/result pair during forced overflow compaction', async () => {
+    const ctx = createContext()
+    void new TestCompactService(ctx, {
+      thresholdRatio: 1,
+      retainTokens: 90,
+    })
+    const session = toolConversation()
+    const newestAssistant = session.surface.nodes.at(-2)!
+    const newestResult = session.surface.nodes.at(-1)!
+
+    expect(await recover(ctx, agent(session, MODEL), overflow())).toEqual({ action: 'retry' })
+    const currentAssistant = session.surface.nodes.find(node => node === newestAssistant)
+    const currentResult = session.surface.nodes.find(node => node === newestResult)
+    expect(currentAssistant).toBeDefined()
+    expect(currentResult).toBeDefined()
+    expect(toolPairingBalancedBefore(session, currentAssistant!)).toBe(true)
+    expect(toolPairingBalancedAfter(session, currentResult!)).toBe(true)
+  })
+
+  it('does not retry when a backend reports success without replacing the surface', async () => {
+    const ctx = createContext()
+    const compact = new TestCompactService(ctx)
+    const session = conversation(2)
+    const fakeResult: CompactionResult = {
+      startSeq: 1,
+      summarySeq: 2,
+      endSeq: 3,
+      summary: [{ type: 'text', text: 'fake' }],
+      shadowedRange: { start: 1, end: 2 },
+      shadowedSeqs: [1, 2],
+      shadowedTokenCount: 10,
+    }
+    vi.spyOn(compact, 'compactIfNeeded').mockResolvedValue(fakeResult)
+
+    expect(await recover(ctx, agent(session, MODEL), overflow())).toEqual({ action: 'fail' })
+    expect(session.surface.replaceGeneration).toBe(0)
+  })
+
+  it('delegates downstream exactly once when no replacement is available', async () => {
+    const ctx = createContext()
+    const compact = new TestCompactService(ctx)
+    vi.spyOn(compact, 'compactIfNeeded').mockResolvedValue(null)
+    const downstream = new Error('downstream recovery failed')
+    let calls = 0
+
+    await expect(recover(
+      ctx,
+      agent(conversation(2), MODEL),
+      overflow(),
+      0,
+      SIGNAL,
+      () => {
+        calls += 1
+        return Promise.reject(downstream)
+      },
+    )).rejects.toBe(downstream)
+    expect(calls).toBe(1)
+  })
+
+  it('preserves the original provider error when recovery throws', async () => {
+    const ctx = createContext()
+    const warnings: string[] = []
+    ctx.logger.warn = ((message: string) => void warnings.push(message)) as typeof ctx.logger.warn
+    const compact = new TestCompactService(ctx)
+    compact.error = new Error('summary unavailable')
+    const original = overflow('original provider overflow')
+
+    expect(await recover(ctx, agent(conversation(3), MODEL), original)).toEqual({ action: 'fail' })
+    expect(original).toMatchObject({
+      message: 'original provider overflow',
+      code: CONTEXT_WINDOW_EXCEEDED_CODE,
+    })
+    expect(warnings).toContainEqual(expect.stringContaining('preserving the original request error'))
+  })
+
+  it('delegates once when overflow recovery throws a non-Error value', async () => {
+    const ctx = createContext()
+    const warnings: string[] = []
+    ctx.logger.warn = ((message: string) => void warnings.push(message)) as typeof ctx.logger.warn
+    const compact = new TestCompactService(ctx)
+    compact.error = 'non-error recovery failure'
+    const session = conversation(3)
+    const generation = session.surface.replaceGeneration
+    const original = overflow('original provider failure')
+    let delegations = 0
+
+    const decision = await recover(ctx, agent(session, MODEL), original, 0, SIGNAL, () => {
+      delegations += 1
+      return Promise.resolve({ action: 'fail' })
+    })
+
+    expect(decision).toEqual({ action: 'fail' })
+    expect(delegations).toBe(1)
+    expect(session.surface.replaceGeneration).toBe(generation)
+    expect(original).toMatchObject({
+      message: 'original provider failure',
+      code: CONTEXT_WINDOW_EXCEEDED_CODE,
+    })
+    expect(warnings).toContainEqual(expect.stringContaining('non-error recovery failure'))
+  })
+
+  it('recovers an overflow for an unlisted routed model', async () => {
+    const ctx = createContext()
+    void new TestCompactService(ctx)
+    const session = conversation(2)
+    session.append('request/header', {
+      header: { config: { provider: 'unknown-routed-provider', model: 'unknown-routed-model' } },
+      reason: 'resume',
+    })
+    expect(await recover(ctx, agent(session, MODEL), overflow('unlisted-model overflow')))
+      .toEqual({ action: 'retry' })
+  })
+
+  it('honors retry caps, non-context failures, and cancellation', async () => {
+    const ctx = createContext()
+    const compact = new TestCompactService(ctx, { maxOverflowRetries: 1 })
+    const compactSpy = vi.spyOn(compact, 'compactIfNeeded')
+    const owner = agent(conversation(3), MODEL)
+    expect(await recover(ctx, owner, Object.assign(new Error('rate limit'), { code: 'RATE_LIMIT' })))
+      .toEqual({ action: 'fail' })
+    expect(await recover(ctx, owner, overflow(), 1)).toEqual({ action: 'fail' })
+
+    const controller = new AbortController()
+    controller.abort('cancelled')
+    expect(await recover(ctx, owner, overflow(), 0, controller.signal)).toEqual({ action: 'fail' })
+    expect(compactSpy).not.toHaveBeenCalled()
+  })
+
+  it('does not retry when cancellation lands during an awaited compaction', async () => {
+    const ctx = createContext()
+    const compact = new TestCompactService(ctx)
+    const controller = new AbortController()
+    compact.mutateDuringSummary = () => { controller.abort('cancelled during summary') }
+    const session = conversation(3)
+    const generation = session.surface.replaceGeneration
+
+    expect(await recover(ctx, agent(session, MODEL), overflow(), 0, controller.signal))
+      .toEqual({ action: 'fail' })
+    expect(session.surface.replaceGeneration).toBe(generation + 1)
+  })
+
+  it('maxOverflowRetries:0 disables recovery without disabling post-step pressure', async () => {
+    const ctx = createContext()
+    void new TestCompactService(ctx, {
+      maxOverflowRetries: 0,
+      thresholdRatio: 0.5,
+      retainTokens: 180,
+    })
+    const session = conversation(4)
+    await postStep(ctx, agent(session, MODEL))
+    const summaries = session.events.filter(event => event.type === 'compact/summary').length
+    expect(summaries).toBe(1)
+    expect(await recover(ctx, agent(session, MODEL), overflow())).toEqual({ action: 'fail' })
+    expect(session.events.filter(event => event.type === 'compact/summary')).toHaveLength(summaries)
+  })
+
+  it('auto:false installs neither automatic listener', async () => {
     const ctx = createContext()
     void new TestCompactService(ctx, {
       auto: false,
@@ -755,8 +1040,9 @@ describe('automatic listener and loader composition', () => {
       retainTokens: 180,
     })
     const session = conversation(4)
-    await preStep(ctx, agent(session, MODEL))
+    await postStep(ctx, agent(session, MODEL))
     expect(session.events.some(event => event.type === 'compact/start')).toBe(false)
+    expect(await recover(ctx, agent(session, MODEL), overflow())).toEqual({ action: 'fail' })
   })
 
   it('loads and disposes the real zero-config service stack', async () => {
@@ -784,7 +1070,8 @@ describe('automatic listener and loader composition', () => {
     await fiber.dispose()
 
     const session = conversation(4)
-    await preStep(ctx, agent(session, MODEL))
+    await postStep(ctx, agent(session, MODEL))
     expect(session.events.some(event => event.type === 'compact/start')).toBe(false)
+    expect(await recover(ctx, agent(session, MODEL), overflow())).toEqual({ action: 'fail' })
   })
 })

packages/compact/compact-basic/tests/compact-loop-repro.spec.ts

@@ -1,16 +1,17 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compact'
+import { CONTEXT_WINDOW_EXCEEDED_CODE, LlmError } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { AgentId } from '@deepseek-ai/dsh-agent'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+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 { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
 import TokenMeterService from '@deepseek-ai/dsh-token-meter'
-import type { SurfaceEvent } from '@deepseek-ai/dsh-session'
+import { SessionId, type SurfaceEvent } from '@deepseek-ai/dsh-session'
 
 /**
  * CBR-001 regression through the real loop. A replacement checkpoint has a high
@@ -55,6 +56,45 @@ class StepwiseToolAdapter extends LlmAdapter {
   }
 }
 
+/** First conversation request overflows, then the rebuilt retry succeeds. */
+class OverflowRecoveryAdapter extends LlmAdapter {
+  readonly conversationRequests: GenerateOptions[] = []
+  readonly summaryRequests: GenerateOptions[] = []
+
+  constructor(private readonly delivery: 'thrown' | 'in-band') {
+    super()
+  }
+
+  override async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    if (options.system?.includes('You are a compaction engine')) {
+      this.summaryRequests.push(options)
+      yield { type: 'block-start', index: 0, blockType: 'text' }
+      yield { type: 'block-end', index: 0, block: { type: 'text', text: 'RECOVERY CHECKPOINT' } }
+      yield { type: 'finish', reason: { kind: 'stop' } }
+      return
+    }
+
+    this.conversationRequests.push(options)
+    if (this.conversationRequests.length === 1) {
+      if (this.delivery === 'thrown') {
+        throw new LlmError('request too large for model context', CONTEXT_WINDOW_EXCEEDED_CODE)
+      }
+      yield {
+        type: 'finish',
+        reason: {
+          kind: 'error',
+          message: 'request too large for model context',
+          code: CONTEXT_WINDOW_EXCEEDED_CODE,
+        },
+      }
+      return
+    }
+    yield { type: 'block-start', index: 0, blockType: 'text' }
+    yield { type: 'block-end', index: 0, block: { type: 'text', text: 'recovered' } }
+    yield { type: 'finish', reason: { kind: 'stop' } }
+  }
+}
+
 async function harness(toolSteps: number): Promise<{ ctx: Context; compact: ReproCompactService }> {
   const ctx = new Context()
   await mountAgentLoopTestDependencies(ctx)
@@ -83,7 +123,7 @@ async function harness(toolSteps: number): Promise<{ ctx: Context; compact: Repr
   return { ctx, compact }
 }
 
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') {
@@ -95,10 +135,58 @@ function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
 }
 
 describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', () => {
+  it('uses the model actually routed by agent/request for post-step pressure', async () => {
+    const { ctx } = await harness(8)
+    ctx.on('agent/request', async (_agent, _turn, _step, config) => ({ ...config, provider: 'mock', model: 'mock' }))
+    try {
+      const agent = ctx.agentLoop.create(SessionId('routed-pressure'), {
+        provider: 'unconfigured-agent-fallback',
+        model: 'unconfigured-agent-fallback',
+      })
+      agent.send([{ type: 'text', text: 'do a routed multi-step task' }])
+      await waitForIdle(ctx, agent)
+
+      expect(agent.session.requestHeader()?.config.model).toBe('mock')
+      expect(agent.session.events.some(event => event.type === 'compact/summary')).toBe(true)
+      expect(agent.session.events.at(-1)).toMatchObject({
+        type: 'turn/end',
+        data: { reason: { kind: 'completed' } },
+      })
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('runs automatic pressure after the current tool result and before step/end', async () => {
+    const { ctx } = await harness(8)
+    try {
+      const agent = ctx.agentLoop.create(SessionId('post-step-order'), { provider: 'mock', model: 'mock' })
+      agent.send([{ type: 'text', text: 'do tool work' }])
+      await waitForIdle(ctx, agent)
+
+      const events = [...agent.session.events]
+      const compactStart = events.find(event => event.type === 'compact/start')
+      expect(compactStart).toBeDefined()
+      const precedingResult = events.findLast(event =>
+        event.type === 'tool/result' && event.seq < compactStart!.seq,
+      )
+      if (precedingResult?.type !== 'tool/result') throw new Error('expected a durable tool result before compaction')
+      const stepEnd = events.find(event =>
+        event.type === 'step/end'
+        && event.data.step === precedingResult.data.step
+        && event.seq > compactStart!.seq,
+      )
+      expect(precedingResult.seq).toBeLessThan(compactStart!.seq)
+      expect(compactStart!.seq).toBeLessThan(stepEnd!.seq)
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
   it('the head checkpoint the loop lands is a balanced cut on both sides', async () => {
     const { ctx } = await harness(8)
     try {
-      const agent = ctx.agentLoop.create(AgentId('repro'), { provider: 'mock', model: 'mock' })
+      const agent = ctx.agentLoop.create(SessionId('repro'), { provider: 'mock', model: 'mock' })
       agent.send([{ type: 'text', text: 'do a long multi-step task' }])
       await waitForIdle(ctx, agent)
 
@@ -127,3 +215,88 @@ describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', ()
     }
   })
 })
+
+describe('context-overflow recovery across the real loop and compact-basic', () => {
+  it.each(['thrown', 'in-band'] as const)(
+    'force-compacts a %s overflow between failed and retry steps',
+    async (delivery) => {
+      const ctx = new Context()
+      const adapter = new OverflowRecoveryAdapter(delivery)
+      await mountAgentLoopTestDependencies(ctx)
+      await ctx.plugin(Invariants)
+      await ctx.plugin(AgentLoop, { agents: [] })
+      await ctx.plugin(TokenMeterService, { contextWindow: 128 })
+      ctx.llm.registerAdapter(['mock'], adapter)
+      ctx.on('agent/request', async (_agent, _turn, _step, config) => ({ ...config, provider: 'mock', model: 'mock' }))
+      await ctx.plugin(BasicCompactService, {
+        thresholdRatio: 1,
+        retainTokens: 100,
+        maxTokens: 64,
+        compactionRetries: 0,
+        maxOverflowRetries: 1,
+      })
+
+      try {
+        const agent = ctx.agentLoop.create(SessionId(`overflow-${delivery}`), {
+          provider: 'unconfigured-agent-fallback',
+          model: 'unconfigured-agent-fallback',
+        })
+        for (let turn = 1; turn <= 2; turn += 1) {
+          const sentinel = turn === 1 ? 'OLD HISTORY SENTINEL' : 'RECENT HISTORY'
+          agent.session.append('turn/start', {
+            turn,
+            trigger: { kind: 'message', source: { kind: 'user' } },
+          })
+          agent.session.append('user/message', {
+            content: [{ type: 'text', text: `${sentinel} ${'old context '.repeat(200)}` }],
+            source: { kind: 'user' },
+          }, { surfaceOp: 'append' })
+          agent.session.append('step/start', { turn, step: 1 })
+          agent.session.append('assistant/message', {
+            provenance: { provider: 'mock', model: 'mock' },
+            turn,
+            step: 1,
+            content: [{ type: 'text', text: `historical response ${turn} ${'detail '.repeat(200)}` }],
+          }, { surfaceOp: 'append' })
+          agent.session.append('step/end', { turn, step: 1 })
+          agent.session.append('turn/end', { turn, reason: { kind: 'completed' } })
+        }
+
+        agent.send([{ type: 'text', text: 'continue from history' }])
+        await agent.whenIdle()
+
+        expect(adapter.conversationRequests).toHaveLength(2)
+        expect(adapter.summaryRequests).toHaveLength(1)
+        expect(JSON.stringify(adapter.conversationRequests[0]!.messages)).toContain('OLD HISTORY SENTINEL')
+        const retry = JSON.stringify(adapter.conversationRequests[1]!.messages)
+        expect(retry).toContain('RECOVERY CHECKPOINT')
+        expect(retry).not.toContain('OLD HISTORY SENTINEL')
+
+        const events = [...agent.session.events]
+        const failedEnd = events.find(event =>
+          event.type === 'step/end' && event.data.turn === 3 && event.data.step === 1,
+        )!
+        const retryStart = events.find(event =>
+          event.type === 'step/start' && event.data.turn === 3 && event.data.step === 2,
+        )!
+        const compaction = events.filter(event =>
+          event.type === 'compact/start'
+          || event.type === 'compact/summary'
+          || event.type === 'compact/end',
+        )
+        expect(compaction.map(event => event.type)).toEqual([
+          'compact/start',
+          'compact/summary',
+          'compact/end',
+        ])
+        expect(compaction.every(event => event.seq > failedEnd.seq && event.seq < retryStart.seq)).toBe(true)
+        expect(events.at(-1)).toMatchObject({
+          type: 'turn/end',
+          data: { reason: { kind: 'completed' } },
+        })
+      } finally {
+        await ctx.fiber.dispose()
+      }
+    },
+  )
+})

packages/compact/compact/README.md

@@ -18,8 +18,10 @@ Both methods are **abstract** — the backend owns trigger policy, retention, ev
 
 | Member | Semantics |
 |---|---|
-| `compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)` | Estimate the surface-derived history size; if over the backend's threshold, compact an older range via `compactRegion`, keeping recent context intact. Returns the `CompactionResult`, or `null` if nothing needed compacting. All parameters required — the loop's `agent/pre-step` checkpoint supplies the agent, assembled `fullSystemPrompt`, composed `sessionPrefix` (request-only messages every request carries but the derived history omits — the pressure estimate must count them), and turn `signal`. A backend's summarization request is a direct `ctx.llm.stream()` call (not a loop step), so per-call interception happens at `llm/stream`. |
-| `compactRegion(session, start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) into a single replacement node. The agent must own the exact target (`session === agent.session`); a backend rejects mismatch before model resolution, lock acquisition, summarization, or log mutation. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. |
+| `compactIfNeeded(agent, trigger, signal)` | Consider automatic compaction for `trigger: 'pressure' \| 'context-overflow'`. A pressure trigger may apply the backend's threshold and retained-tail policy; a confirmed overflow may force a useful balanced reduction. Returns the `CompactionResult`, or `null` when no safe range exists. A backend's summarization request is a direct `ctx.llm.stream()` call (not a loop step), so per-call interception happens at `llm/stream`. |
+| `compactRegion(start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) from `agent.session` into a single replacement node. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. |
+
+`CompactionResult` keeps the raw summary and bookkeeping-event seqs available to callers alongside the shadowed range and token accounting; its drift-checked shape lives in the [compaction data-structure reference](../../../docs/core-data-structures/compaction.md#compactionresult).
 
 `compactIfNeeded` takes a required `signal`; `compactRegion`'s is optional. A backend that summarizes via `ctx.llm.stream()` **must** forward it into the call's `GenerateOptions.signal`, so an abort or fiber dispose tears down the in-flight summarization instead of leaving an orphaned model call running past the cancellation. The turn that the `compact/*` events belong to is recoverable from the owned session's log (the currently-open turn), so the backend stamps it from the log rather than trusting a caller-supplied value.
 
@@ -59,19 +61,34 @@ Subclass `CompactService`, implement `compactIfNeeded` and `compactRegion`, and
 
 ### Conversation history, when a backend is invoked
 
-**What the model sees**: A successful implementation replaces an older surface range with one user-role summary checkpoint; the raw events stay logged but stop appearing in derived model messages. The seam itself performs no rewrite.
+#### What the model sees
 
-**Token effect**: Zero direct tokens from this interface. A backend trades many retained history tokens for one summary and leaves the recent tail unchanged.
+A successful implementation replaces an older surface range with one user-role summary checkpoint; the raw events stay logged but stop appearing in derived model messages. The seam itself performs no rewrite.
+
+#### Token effect
+
+Zero direct tokens from this interface. A backend trades many retained history tokens for one summary and leaves the recent tail unchanged.
+
+#### KV Cache effect
+
+A successful backend replacement invalidates reuse from the first shadowed history token; the seam itself does not alter a request.
 
 ### Transcript supplied to a compaction consumer
 
-**What the model sees**: `renderTranscript()` joins entries with one blank line and renders them exactly as `User: <content>`, `Assistant: <content>`, `Tool result (call <callId>): <content>`, `Tool error (call <callId>): <content>`, `[Context: <content>]`, or `[Steering: <content>]`. Non-text blocks render exactly as `[reasoning: <text>]`, `[tool-call: <name>(<arguments>)]`, `[tool-result: <content>]`, `[tool-result]`, or `[<block-type>]`.
+#### What the model sees
 
-**Token effect**: Data-dependent input tokens are paid only by the auxiliary model or consumer that requests this transcript; the conversation model does not receive a duplicate transcript.
+`renderTranscript()` joins entries with one blank line and renders them exactly as `User: <content>`, `Assistant: <content>`, `Tool result (call <callId>): <content>`, `Tool error (call <callId>): <content>`, `[Context: <content>]`, or `[Steering: <content>]`. Non-text blocks render exactly as `[reasoning: <text>]`, `[tool-call: <name>(<arguments>)]`, `[tool-result: <content>]`, `[tool-result]`, or `[<block-type>]`.
+
+#### Token effect
+
+Data-dependent input tokens are paid only by the auxiliary model or consumer that requests this transcript; the conversation model does not receive a duplicate transcript.
+
+#### KV Cache effect
+
+No conversation-cache invalidation. A consumer's auxiliary request can reuse only the exact prefix produced by this rendering; changed or compacted entries invalidate reuse from their first difference.
 
 ## Known Limitations and Deferred Work
 
 - **No model-facing consumer tier yet** — `@deepseek-ai/dsh-tool-compact` (the `/compact` tool) is deferred; compaction is reachable only via direct `ctx.compact` calls or a backend's auto listener.
-- **Single-unit overflow is out of contract** — one retained unit (a closed step or a large pasted `user/message`) alone exceeding the budget cannot be compacted; the call may go out over-budget.
-- **A session prefix that alone approaches the window is a configuration error no backend fixes** — compaction shrinks derived history, never the prefix.
-- **Request context injected by downstream `agent/request` listeners sits outside pressure accounting** — `compactIfNeeded` counts prefix, derived history, and system prompt only.
+- **Single-unit overflow is out of contract** — one indivisible unit (a closed tool pair or a large pasted `user/message`) alone exceeding the budget cannot be compacted.
+- **An envelope that alone approaches the window is not surface-compaction work** — compaction shrinks derived history, never the system prompt, tools, or session prefix.

packages/compact/compact/src/index.ts

@@ -8,7 +8,6 @@
  */
 
 import { Context, Service } from 'cordis'
-import type { Message } from '@deepseek-ai/dsh-llm'
 import type { Session } from '@deepseek-ai/dsh-session'
 import type { CompactionResult } from './types.ts'
 
@@ -16,10 +15,13 @@ export type { CompactionResult } from './types.ts'
 export { renderContentBlocks, renderTranscript } from './render.ts'
 export { toolPairingBalancedAfter, toolPairingBalancedBefore } from './tool-pairing.ts'
 
+/** Why automatic policy is asking a backend to consider compaction. */
+export type CompactionTrigger = 'pressure' | 'context-overflow'
+
 /** Minimal agent context compaction needs without depending on the agent package. */
 export interface CompactAgentContext {
   session: Session
-  options: { model?: string }
+  options: { provider?: string; model?: string }
 }
 
 declare module 'cordis' {
@@ -41,24 +43,20 @@ export abstract class CompactService extends Service {
   }
 
   /**
-   * Check token pressure and compact if the conversation is too large.
-   * Estimate the next request, including its session prefix, derived history,
-   * and system prompt. Above threshold, compact a head-anchored range ending at
-   * a balanced tool boundary and reconsolidate any prior automatic checkpoint.
-   * Return `null` when no compaction is needed or an open tail leaves no safe
-   * cutoff. A single oversized retained unit or prefix cannot be repaired here.
+   * Consider automatic compaction for one explicit trigger. Pressure policy
+   * uses the latest durable routed request, while context-overflow policy may
+   * force a useful balanced reduction even below the normal threshold. Return
+   * `null` when no safe range can be compacted. A single oversized retained
+   * unit or request envelope cannot be repaired through surface compaction.
    *
-   * @param agent - agent context owning the session surface and model options.
-   * @param fullSystemPrompt - assembled system prompt, counted toward the estimate.
-   * @param sessionPrefix - the instance's composed session prefix, counted toward the
-   *   estimate.
+   * @param agent - agent context owning the session surface and routing options.
+   * @param trigger - normal pressure or provider-confirmed context overflow.
    * @param signal - cancellation signal; model-backed implementations must forward it.
    * @returns the compaction result, or `null` if no compaction was needed.
    */
   abstract compactIfNeeded(
     agent: CompactAgentContext,
-    fullSystemPrompt: string,
-    sessionPrefix: readonly Message[],
+    trigger: CompactionTrigger,
     signal: AbortSignal,
   ): Promise<CompactionResult | null>
 
@@ -67,23 +65,19 @@ export abstract class CompactService extends Service {
    * `start` and `end` name an inclusive span by surface position, not numeric seq
    * order; replacements can make visible seqs non-monotonic. Both edges must be
    * balanced so assistant tool calls remain paired with their results. A model-
-   * backed implementation forwards cancellation. The agent must own the exact
-   * target session object; implementations reject an ownership mismatch before
-   * model resolution, lock acquisition, summarization, or log mutation, and
-   * reject active, missing, reversed, or unbalanced ranges.
+   * backed implementation forwards cancellation and rejects active, missing,
+   * reversed, or unbalanced ranges. The target session is `agent.session`.
    * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
    * for the edge checks.
    *
-   * @param session - session to mutate; must be identical to `agent.session`.
    * @param start - first surface seq, inclusive.
    * @param end - last surface seq, inclusive.
-   * @param agent - owner of the target session and summarizer context.
+   * @param agent - context whose session is mutated and whose routing options guide summarization.
    * @param signal - optional cancellation; model-backed implementations must forward it.
-   * @throws when the agent does not own `session`, compaction is active, or the range is missing, reversed, or unbalanced.
-   * @returns the replaced range and summary.
+   * @throws when compaction is active or the range is missing, reversed, or unbalanced.
+   * @returns the appended event seqs, summary, replaced range, and token accounting.
    */
   abstract compactRegion(
-    session: Session,
     start: number,
     end: number,
     agent: CompactAgentContext,

packages/compact/compact/tests/compact.spec.ts

@@ -1,8 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { CompactService } from '@deepseek-ai/dsh-compact'
-import type { CompactionResult } from '@deepseek-ai/dsh-compact'
-import type { Message } from '@deepseek-ai/dsh-llm'
+import type { CompactionResult, CompactionTrigger } from '@deepseek-ai/dsh-compact'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type { CompactAgentContext } from '@deepseek-ai/dsh-compact'
 
@@ -18,8 +17,7 @@ class StubCompactService extends CompactService {
 
   override async compactIfNeeded(
     _agent: CompactAgentContext,
-    _fullSystemPrompt: string,
-    _sessionPrefix: readonly Message[],
+    _trigger: CompactionTrigger,
     signal: AbortSignal,
   ): Promise<CompactionResult | null> {
     this.lastSignal = signal
@@ -27,17 +25,18 @@ class StubCompactService extends CompactService {
   }
 
   override async compactRegion(
-    session: Session,
     start: number,
     end: number,
-    _agent: CompactAgentContext,
+    agent: CompactAgentContext,
     signal?: AbortSignal,
   ): Promise<CompactionResult> {
     this.lastSignal = signal
+    const session = agent.session
+    const summary = [{ type: 'text' as const, text: 'stub' }]
     // Minimal stub honoring the lock + log-only event contract.
     const startEvent = session.append('compact/start', { turn: 0 })
     const summaryEvent = session.append('compact/summary', {
-      summary: [{ type: 'text', text: 'stub' }],
+      summary,
       shadowedRange: { start, end },
       shadowedSeqs: [],
       shadowedTokenCount: 0,
@@ -49,7 +48,7 @@ class StubCompactService extends CompactService {
       startSeq: startEvent.seq,
       summarySeq: summaryEvent.seq,
       endSeq: endEvent.seq,
-      summary: [{ type: 'text', text: 'stub' }],
+      summary,
       shadowedRange: { start, end },
       shadowedSeqs: [],
       shadowedTokenCount: 0,
@@ -81,7 +80,7 @@ describe('CompactService seam', () => {
     const ctx = new Context()
     const svc = new StubCompactService(ctx)
     const session = new Session(SessionId('s'))
-    expect(await svc.compactIfNeeded(stubAgent(session), '', [], new AbortController().signal)).toBeNull()
+    expect(await svc.compactIfNeeded(stubAgent(session), 'pressure', new AbortController().signal)).toBeNull()
   })
 
   it('compact/* events merge into SessionEventMap and are log-only', async () => {
@@ -89,7 +88,7 @@ describe('CompactService seam', () => {
     const svc = new StubCompactService(ctx)
     const session = new Session(SessionId('s'))
 
-    const result = await svc.compactRegion(session, 0, 0, stubAgent(session, 'm'))
+    const result = await svc.compactRegion(0, 0, stubAgent(session, 'm'))
 
     const startEvent = session.events.find(e => e.type === 'compact/start')
     expect(startEvent).toBeDefined()
@@ -97,8 +96,12 @@ describe('CompactService seam', () => {
     // verify the runtime value is absent.
     const raw = startEvent as unknown as { surfaceOp?: unknown }
     expect(raw.surfaceOp).toBeUndefined()
+    expect(result.summary).toEqual([{ type: 'text', text: 'stub' }])
     expect(result.summarySeq).toBeGreaterThan(result.startSeq)
     expect(result.endSeq).toBeGreaterThan(result.summarySeq)
+    expect(result.shadowedRange).toEqual({ start: 0, end: 0 })
+    expect(session.events.filter(e => e.type.startsWith('compact/')).map(e => e.type))
+      .toEqual(['compact/start', 'compact/summary', 'compact/end'])
   })
 
   it('threads the cancellation signal through to the backend', async () => {
@@ -107,10 +110,10 @@ describe('CompactService seam', () => {
     const session = new Session(SessionId('s'))
     const controller = new AbortController()
 
-    await svc.compactRegion(session, 0, 0, stubAgent(session, 'm'), controller.signal)
+    await svc.compactRegion(0, 0, stubAgent(session, 'm'), controller.signal)
     expect(svc.lastSignal).toBe(controller.signal)
 
-    await svc.compactIfNeeded(stubAgent(session), '', [], controller.signal)
+    await svc.compactIfNeeded(stubAgent(session), 'context-overflow', controller.signal)
     expect(svc.lastSignal).toBe(controller.signal)
   })
 })

packages/context/time-context/README.md

@@ -32,24 +32,32 @@ The time reading stays in derived conversation history until a later compaction
 
 ### Preparation-time temporal context
 
-**What the model sees**: On each preparation attempt that injects, one source-tagged context message containing the two lines below. `<timestamp>` is an ISO-shaped local timestamp with numeric offset and IANA zone; durations use compact whole-second units. Positive intervals can leave an attempted step without a new reading.
+#### What the model sees
 
-**Token effect**: Each injected two-line message accumulates until compaction shadows it. A positive interval reduces additions; omission or `0` adds one for every eligible preparation attempt.
+On each preparation attempt that injects, one source-tagged context message containing the two lines below. `<timestamp>` is an ISO-shaped local timestamp with numeric offset and IANA zone; durations use compact whole-second units. Positive intervals can leave an attempted step without a new reading.
 
-#### First step
+##### First step
 
 ```markdown
 Time sampled while preparing turn <turn>, step 1: <timestamp>
 Elapsed since the preceding model-visible message: <duration-or-unavailable>.
 ```
 
-#### Later steps
+##### Later steps
 
 ```markdown
 Time sampled while preparing turn <turn>, step <step>: <timestamp>
 Elapsed since the preceding step context: <duration-or-unavailable>.
 ```
 
+#### Token effect
+
+Each injected two-line message accumulates until compaction shadows it. A positive interval reduces additions; omission or `0` adds one for every eligible preparation attempt.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
 ## Known Limitations and Deferred Work
 
 - **Whole-second display** — timestamps and durations omit sub-second precision even though durable event times retain milliseconds.

packages/context/time-context/src/index.ts

@@ -8,7 +8,6 @@
 import type { Context } from 'cordis'
 import z from 'schemastery'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import type { Message } from '@deepseek-ai/dsh-llm'
 
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'time-context'
@@ -162,8 +161,6 @@ export function apply(ctx: Context, config: Config): void {
     agent: Agent,
     turn: number,
     step: number,
-    _fullSystemPrompt: string,
-    _sessionPrefix: readonly Message[],
     signal: AbortSignal,
   ) => {
     if (signal.aborted) return

packages/context/time-context/tests/time-context.spec.ts

@@ -4,7 +4,7 @@ import Loader from '@cordisjs/plugin-loader'
 import { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
 import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -38,7 +38,7 @@ async function mount(config: Config = {}) {
 
 function sessionAgent(session: Session, id = 'agent'): Agent {
   return {
-    id: AgentId(id),
+    id: SessionId(id),
     options: {},
     session,
     status: 'running',
@@ -83,7 +83,7 @@ async function fire(
   step: number,
   signal: AbortSignal = SIGNAL,
 ): Promise<void> {
-  await ctx.serial('agent/pre-step', agent, turn, step, '', [], signal)
+  await ctx.serial('agent/pre-step', agent, turn, step, signal)
 }
 
 function textResponse(text: string): StreamChunk[] {
@@ -370,7 +370,7 @@ describe('real agent-loop request history', () => {
       if (mode === 'throws') throw new Error('later pre-step failure')
       subject.cancel('later pre-step cancellation')
     })
-    const agent = ctx.agentLoop.create(AgentId(`late-${mode}`), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId(`late-${mode}`), { provider: 'mock', model: 'mock' })
 
     agent.send([{ type: 'text', text: 'start' }])
     await agent.whenIdle()
@@ -396,7 +396,7 @@ describe('real agent-loop request history', () => {
         return [{ type: 'text' as const, text: 'advanced' }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('loop'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('loop'), { provider: 'mock', model: 'mock' })
 
     agent.send([{ type: 'text', text: 'start' }])
     await agent.whenIdle()

packages/context/workspace-context/README.md

@@ -78,11 +78,11 @@ Instruction content is read through `streamText()` under `maxSourceBytes`, even
 
 ### Baseline session prefix
 
-**What the model sees**: At the first request of each loop instance, the model receives one user-role prefix message containing the bounded user-global and project instruction chain in broad-to-specific order.
+#### What the model sees
 
-**Token effect**: The rendered baseline is frozen and resent on every request in that loop instance. `maxBytes` bounds the complete message, broader files are omitted before the most-specific file is truncated, and an empty chain contributes zero tokens.
+At the first request of each loop instance, the model receives one user-role prefix message containing the bounded user-global and project instruction chain in broad-to-specific order.
 
-#### Baseline instruction template
+##### Baseline instruction template
 
 ```markdown
 <system-reminder>
@@ -98,13 +98,21 @@ Instructions from: AGENTS.md
 </system-reminder>
 ```
 
+#### Token effect
+
+The rendered baseline is frozen and resent on every request in that loop instance. `maxBytes` bounds the complete message, broader files are omitted before the most-specific file is truncated, and an empty chain contributes zero tokens.
+
+#### KV Cache effect
+
+Prefix-stable within one loop instance because the baseline is frozen. A new or resumed instance recomposes it, so instruction, precedence, cwd, candidate, or byte-budget changes may invalidate reuse from the first changed baseline token.
+
 ### Newly discovered scope context
 
-**What the model sees**: After a successful first-party filesystem call reaches a deeper directory, the next request includes one retained raw `context/message` with the newly applicable instruction file.
+#### What the model sees
 
-**Token effect**: Each discovered scope adds bounded history tokens until compaction. Unchanged content is suppressed by visible session state plus version/digest comparison, and Code Mode defers the same message until after the outer `run_code` result.
+After a successful first-party filesystem call reaches a deeper directory, the next request includes one retained raw `context/message` with the newly applicable instruction file.
 
-#### Additional instruction template
+##### Additional instruction template
 
 ```markdown
 <system-reminder>
@@ -116,13 +124,21 @@ These instructions apply to work under `packages/app`. Use them as guidance when
 </system-reminder>
 ```
 
+#### Token effect
+
+Each discovered scope adds bounded history tokens until compaction. Unchanged content is suppressed by visible session state plus version/digest comparison, and Code Mode defers the same message until after the outer `run_code` result.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
 ### Changed or removed instruction context
 
-**What the model sees**: A changed file produces `Updated instructions from: <path>` plus its replacement content; a candidate switch also names the previous path. A removed final candidate produces the removal notice below.
+#### What the model sees
 
-**Token effect**: Each confirmed change or removal is one retained history message bounded by `maxBytes`. Provider failures add no message, and an update omitted by the budget remains eligible for a later filesystem touch.
+A changed file produces `Updated instructions from: <path>` plus its replacement content; a candidate switch also names the previous path. A removed final candidate produces the removal notice below.
 
-#### Removal notice
+##### Removal notice
 
 ```markdown
 <system-reminder>
@@ -132,6 +148,14 @@ The previously loaded instructions from this file no longer apply.
 </system-reminder>
 ```
 
+#### Token effect
+
+Each confirmed change or removal is one retained history message bounded by `maxBytes`. Provider failures add no message, and an update omitted by the budget remains eligible for a later filesystem touch.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
 ## Known Limitations and Deferred Work
 
 - **Discovery follows structured fs tools, not shell navigation** — a `bash` command that changes directories does not trigger nested instruction discovery because shell syntax and per-call shell state are not a reliable filesystem seam.

packages/context/workspace-context/tests/workspace-context.e2e.ts

@@ -7,7 +7,7 @@ import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
@@ -46,7 +46,6 @@ async function harness(): Promise<{ ctx: Context; agent: Agent }> {
   await ctx.plugin(AgentLoop, { agents: [] })
   await ctx.plugin(LlmDeepSeek, { models: [{ id: 'deepseek-v4-flash' }] })
   const handle = await ctx.agents.create({
-    agentId: AgentId('workspace-context-e2e'),
     sessionId: SessionId('workspace-context-e2e-session'),
     meta: { cwd: workdir },
     agentOptions: { provider: 'deepseek', model: 'deepseek-v4-flash' },

packages/context/workspace-context/tests/workspace-context.spec.ts

@@ -7,7 +7,7 @@ import Loader from '@cordisjs/plugin-loader'
 import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
 import LlmService, { CallId, type Message, type StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionId, SESSION_FORMAT_VERSION, type SessionEvent } from '@deepseek-ai/dsh-session'
-import AgentRegistry, { AgentId, type Agent, type HookContext } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { type Agent, type HookContext } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { FileSystem, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
 import type {
@@ -163,7 +163,7 @@ function stubAgent(cwd?: string, seed: SessionEvent[] = []): Agent {
   const session = new Session(id, seed, cwd === undefined ? undefined : { version: SESSION_FORMAT_VERSION, id, createdAt: 0, cwd })
   return {
     ctx: new Context(),
-    id: AgentId('a1'),
+    id: SessionId('a1'),
     options: {},
     session,
     status: 'idle',
@@ -1591,7 +1591,7 @@ describe('dynamic nested workspace context injection', () => {
       await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
       await ctx.plugin(AgentLoop, { agents: [] })
       ctx.llm.registerAdapter(['mock'], adapter)
-      const agent = ctx.agentLoop.create(AgentId('workspace-context-abort'), { provider: 'mock', model: 'mock' }, { cwd: root })
+      const agent = ctx.agentLoop.create(SessionId('workspace-context-abort'), { provider: 'mock', model: 'mock' }, { cwd: root })
       ctx.tools.register(defineTool({
         name: 'abort_step',
         description: 'Abort the current test step.',

packages/cordis/tool-cordis/README.md

@@ -4,7 +4,7 @@ The self-referential cordis toolset: three model-facing tools over the live runt
 
 ## What it does
 
-- `cordis_inspect` — read-only report over the runtime: services, the loaded-plugin list, registered tools, the dynamic-mount table, and the catalog-backed `api` / `events` references.
+- `cordis_inspect` — read-only report over the runtime: services, the loaded-plugin list, registered tools, the dynamic-mount table, and the catalog-backed `api` / `events` references. An exact `name` with `what: "api"` or `what: "events"` narrows the report and adds the original source JSDoc.
 - `cordis_mount` — evaluates model-written JavaScript (the body of an async function) in a `node:vm` sandbox; the code must `return` a cordis plugin, which is mounted under the `cordis-dynamic` group fiber and tracked as `dyn-<n>`.
 - `cordis_unmount` — disposes one mount by id, returning only after quiescence.
 
@@ -22,7 +22,7 @@ The sandbox isolates globals but is not a security boundary. Node globals are ab
 
 ## The generated API catalog
 
-`src/api-catalog.ts` is generated by `scripts/gen-cordis-api.ts` from the same AST walk as [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) and freshness-gated by `pnpm run verify-cordis-api` (in `doc-sync`) — never edit it by hand. `cordis_inspect` intersects it with the live service store at call time.
+`src/api-catalog.ts` is generated by `scripts/gen-cordis-api.ts` from the same AST walk as [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) and freshness-gated by `pnpm run verify-cordis-api` (in `doc-sync`) — never edit it by hand. `cordis_inspect` intersects it with the live service store at call time. Broad `api` / `events` reports render summaries and signatures only; an exact `name` opts into the retained method/event JSDoc, and unknown or non-running service targets fail loud.
 
 ## Rendering
 
@@ -36,21 +36,45 @@ Namespace plugin: named exports `name` / `inject` / `Config` / `apply`, no defau
 
 ### Tool schemas
 
-**What the model sees**: The conversation model sees the generated [`cordis_inspect`, `cordis_mount`, and `cordis_unmount` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-cordis) whenever this plugin is visible.
+#### What the model sees
 
-**Token effect**: Fixed schema cost on every request in that tool view.
+The conversation model sees the generated [`cordis_inspect`, `cordis_mount`, and `cordis_unmount` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-cordis) whenever this plugin is visible.
+
+#### Token effect
+
+Fixed schema cost on every request in that tool view.
+
+#### KV Cache effect
+
+Prefix-stable while this tool view is unchanged. Scoping or plugin lifecycle changes that hide these definitions may invalidate reuse from the first changed schema token.
 
 ### Tool-call history and results
 
-**What the model sees**: Inspect joins selected sections exactly as `## <section>` then a newline and the data-dependent body, with one blank line between sections. Mount returns `mounted <id> (plugin "<name>", state: <state>)`, optionally inserting ` — waiting for service(s): <names> (activates when provided)` before the closing parenthesis. Unmount returns `unmounted <id> (plugin "<name>")`; an unknown id becomes `Error: no dynamic plugin with id "<id>" (list mounts with cordis_inspect what:"dynamic")`. The submitted mount program remains in the assistant tool-call history.
+#### What the model sees
 
-**Token effect**: Inspect output and mount code are data-dependent and resent until compaction; lifecycle acknowledgements are small.
+Inspect joins selected sections exactly as `## <section>` then a newline and the data-dependent body, with one blank line between sections. Its broad API/event reports omit JSDoc; `name` with `what: "api"` or `what: "events"` returns one exact target with its original JSDoc. Mount returns `mounted <id> (plugin "<name>", state: <state>)`, optionally inserting ` — waiting for service(s): <names> (activates when provided)` before the closing parenthesis. Unmount returns `unmounted <id> (plugin "<name>")`; an unknown id becomes `Error: no dynamic plugin with id "<id>" (list mounts with cordis_inspect what:"dynamic")`. The submitted mount program remains in the assistant tool-call history.
+
+#### Token effect
+
+Inspect output and mount code are data-dependent and resent until compaction; lifecycle acknowledgements are small.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
 ### Later requests after a mount
 
-**What the model sees**: A mounted plugin may register tools, prompt contributions, or listeners that change later requests for the scopes it targets; unmount removes those contributions after quiescence.
+#### What the model sees
 
-**Token effect**: Indirect token impact equals the mounted plugin's contributions and lasts only for the mount lifetime.
+A mounted plugin may register tools, prompt contributions, or listeners that change later requests for the scopes it targets; unmount removes those contributions after quiescence.
+
+#### Token effect
+
+Indirect token impact equals the mounted plugin's contributions and lasts only for the mount lifetime.
+
+#### KV Cache effect
+
+Mounting or unmounting a prompt or tool contribution changes later request prefixes and may invalidate reuse from the first changed contribution; an unchanged mount set remains prefix-stable.
 
 ## Known Limitations and Deferred Work
 

packages/cordis/tool-cordis/src/index.ts

@@ -12,9 +12,9 @@ import z from 'schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { STATE_LABELS } from './fiber-state.ts'
 import { isPlugin, pluginName } from './guard.ts'
+import { EVENT_API, INHERITED_CTX_API, SERVICE_API, TYPE_API } from './api-catalog.ts'
 import { describeApi, describeDynamic, describeEvents, describePlugins, describeServices, describeTools } from './inspect.ts'
-import { missingServices, mountDynamic } from './mount.ts'
-import type { DynamicMount } from './mount.ts'
+import { missingServices, mountDynamic, type DynamicMount } from './mount.ts'
 import { presentInspectCall, presentMountCall, presentUnmountCall } from './present.ts'
 import { createSandbox, evaluateMountCode } from './sandbox.ts'
 
@@ -63,15 +63,23 @@ export function apply(ctx: Context, config: Config): void {
       + '`dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), '
       + '`api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), '
       + '`events` (every harness event with its dispatch mode and exact signature — pick listener targets here). '
-      + 'Omit `what` to get all six sections.',
+      + 'Omit `what` to get all six sections. With `what:"api"` or `what:"events"`, pass an exact `name` '
+      + 'to narrow to one service/event and include its original source JSDoc.',
     parameters: {
       what: {
         type: 'string',
         enum: ['services', 'plugins', 'tools', 'dynamic', 'api', 'events'],
         description: 'Limit the report to one section. Omit for all sections.',
       },
+      name: {
+        type: 'string',
+        description: 'Exact service key or event name whose original JSDoc to include; valid only with what:"api" or what:"events".',
+      },
     },
     execute(args, exec): Promise<{ type: 'text'; text: string }[]> {
+      if (args.name !== undefined && args.what !== 'api' && args.what !== 'events') {
+        throw new Error('name is valid only with what:"api" or what:"events"')
+      }
       const sections: [heading: string, body: () => string[]][] = [
         ['services', () => describeServices(ctx)],
         ['plugins', () => describePlugins(ctx)],
@@ -79,8 +87,8 @@ export function apply(ctx: Context, config: Config): void {
         // globals absent — "what you can call", not the global registry.
         ['tools', () => describeTools(ctx, exec.agent)],
         ['dynamic', () => describeDynamic(ctx, mounts)],
-        ['api', () => describeApi(ctx)],
-        ['events', () => describeEvents()],
+        ['api', () => describeApi(ctx, SERVICE_API, INHERITED_CTX_API, TYPE_API, args.name)],
+        ['events', () => describeEvents(EVENT_API, args.name)],
       ]
       const selected = sections.filter(([heading]) => args.what === undefined || args.what === heading)
       const text = selected

packages/cordis/tool-cordis/src/inspect.ts

@@ -1,7 +1,8 @@
 /**
  * Read-only renderers over the live runtime for `cordis_inspect`: the service list, the flat
  * plugin list, the registered tools, the dynamic-mount table (with per-mount provides/waits),
- * and the catalog-backed `api` / `events` sections.
+ * and the catalog-backed `api` / `events` sections. Exact-name lookups add the
+ * original source JSDoc without inflating the default reports.
  * @module @deepseek-ai/dsh-tool-cordis/inspect
  */
 
@@ -126,6 +127,18 @@ function typeClosure(seeds: string[], types: readonly TypeApiEntry[]): TypeApiEn
   return [...included.values()].sort((a, b) => a.name.localeCompare(b.name))
 }
 
+/** Render one catalogued service, optionally including source-owned method JSDoc. */
+function serviceLines(entry: ServiceApiEntry, detailed: boolean): string[] {
+  const lines = [`- ${entry.key} — ${entry.summary}`]
+  for (const method of entry.methods) {
+    if (detailed) {
+      for (const docLine of method.jsDoc.split('\n')) lines.push(`    ${docLine}`)
+    }
+    lines.push(`    ${method.signature}`)
+  }
+  return lines
+}
+
 /**
  * Render the generated catalog against the live runtime: live catalogued services with methods,
  * uncatalogued live services with owners, absent loadable services, referenced type shapes, and
@@ -134,6 +147,7 @@ function typeClosure(seeds: string[], types: readonly TypeApiEntry[]): TypeApiEn
  * @param api - generated service entries, replaceable in tests.
  * @param inherited - inherited `ctx` entries, replaceable in tests.
  * @param types - public type shapes, replaceable in tests.
+ * @param name - exact live service key whose methods should include original JSDoc; omitted for the compact catalog.
  * @returns the section lines.
  */
 export function describeApi(
@@ -141,25 +155,33 @@ export function describeApi(
   api: readonly ServiceApiEntry[] = SERVICE_API,
   inherited: readonly InheritedApiEntry[] = INHERITED_CTX_API,
   types: readonly TypeApiEntry[] = TYPE_API,
+  name?: string,
 ): string[] {
   const live = new Map<string, string>()
   for (const impl of liveImpls(ctx)) live.set(impl.name, impl.fiber.name)
   const lines: string[] = []
   const liveMethodTexts: string[] = []
-  for (const entry of api) {
-    if (!live.has(entry.key)) continue
-    lines.push(`- ${entry.key} — ${entry.summary}`)
+  let selected = api.filter(entry => live.has(entry.key))
+  if (name !== undefined) {
+    const entry = api.find(candidate => candidate.key === name)
+    if (!entry) throw new Error(`no catalogued service named "${name}"`)
+    if (!live.has(name)) throw new Error(`catalogued service "${name}" is not running`)
+    selected = [entry]
+  }
+  for (const entry of selected) {
+    lines.push(...serviceLines(entry, name !== undefined))
     for (const method of entry.methods) {
-      lines.push(`    ${method}`)
-      liveMethodTexts.push(method)
+      liveMethodTexts.push(method.signature)
     }
   }
-  const catalogued = new Set(api.map(entry => entry.key))
-  for (const [name, fiber] of [...live].sort(([a], [b]) => a.localeCompare(b))) {
-    if (!catalogued.has(name)) lines.push(`- ${name} (provided by ${fiber}, no catalog entry)`)
+  if (name === undefined) {
+    const catalogued = new Set(api.map(entry => entry.key))
+    for (const [liveName, fiber] of [...live].sort(([a], [b]) => a.localeCompare(b))) {
+      if (!catalogued.has(liveName)) lines.push(`- ${liveName} (provided by ${fiber}, no catalog entry)`)
+    }
+    const notRunning = api.filter(entry => !live.has(entry.key)).map(entry => entry.key)
+    if (notRunning.length > 0) lines.push(`not running (loadable services with no live provider): ${notRunning.join(', ')}`)
   }
-  const notRunning = api.filter(entry => !live.has(entry.key)).map(entry => entry.key)
-  if (notRunning.length > 0) lines.push(`not running (loadable services with no live provider): ${notRunning.join(', ')}`)
   const shapes = typeClosure(liveMethodTexts, types)
   if (shapes.length > 0) {
     lines.push('type shapes (referenced by the signatures above — read these before assuming a field is a string):')
@@ -167,8 +189,10 @@ export function describeApi(
       for (const declLine of shape.declaration.split('\n')) lines.push(`    ${declLine}`)
     }
   }
-  lines.push('inherited ctx API:')
-  for (const entry of inherited) lines.push(`- ${entry.name} — ${entry.summary}`)
+  if (name === undefined) {
+    lines.push('inherited ctx API:')
+    for (const entry of inherited) lines.push(`- ${entry.name} — ${entry.summary}`)
+  }
   return lines
 }
 
@@ -176,13 +200,24 @@ export function describeApi(
  * The `events` section: every harness event with its dispatch mode, one-line
  * summary, and exact signature, closed by the waterfall caution.
  * @param events - the event catalog (the generated one by default; injectable for tests).
+ * @param name - exact event name whose signature should include original JSDoc; omitted for the compact catalog.
  * @returns the section lines.
  */
-export function describeEvents(events: readonly EventApiEntry[] = EVENT_API): string[] {
-  const lines = events.flatMap(event => [
-    `- ${event.name} [${event.mode}] — ${event.summary}`,
-    `    ${event.signature}`,
-  ])
+export function describeEvents(events: readonly EventApiEntry[] = EVENT_API, name?: string): string[] {
+  let selected = events
+  if (name !== undefined) {
+    const event = events.find(candidate => candidate.name === name)
+    if (!event) throw new Error(`no catalogued event named "${name}"`)
+    selected = [event]
+  }
+  const lines = selected.flatMap((event) => {
+    const entry = [`- ${event.name} [${event.mode}] — ${event.summary}`]
+    if (name !== undefined) {
+      for (const docLine of event.jsDoc.split('\n')) entry.push(`    ${docLine}`)
+    }
+    entry.push(`    ${event.signature}`)
+    return entry
+  })
   lines.push('waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain.')
   return lines
 }

packages/cordis/tool-cordis/src/present.ts

@@ -15,11 +15,12 @@ import type { GenericCallView } from '@deepseek-ai/dsh-tools'
  * @param args - the validated call arguments.
  * @returns the generic card the ACP bridge renders.
  */
-export function presentInspectCall(args: { what?: string }): GenericCallView {
+export function presentInspectCall(args: { what?: string; name?: string }): GenericCallView {
+  const target = args.name === undefined ? args.what : `${args.what}: ${args.name}`
   return {
     card: 'generic',
     kind: 'read',
-    title: args.what === undefined ? 'Inspect cordis runtime' : `Inspect cordis runtime: ${args.what}`,
+    title: target === undefined ? 'Inspect cordis runtime' : `Inspect cordis runtime: ${target}`,
   }
 }
 

packages/cordis/tool-cordis/tests/inspect.spec.ts

@@ -64,6 +64,24 @@ describe('cordis_inspect', () => {
     // The inherited ctx surface closes the section.
     expect(report).toContain('inherited ctx API:')
     expect(report).toContain('- ctx.effect — ')
+    // The broad report stays compact; exact-name lookup owns full JSDoc.
+    expect(report).not.toContain('/**')
+    expect(report).not.toContain('@param definition')
+  })
+
+  it('adds original method JSDoc only for an exact live api name', async () => {
+    const ctx = await setup()
+    const report = text(await call(ctx, 'cordis_inspect', { what: 'api', name: 'tools' }))
+    expect(report).toContain('## api')
+    expect(report).toContain('- tools — Tool registry and execution pipeline.')
+    expect(report).toContain('/**')
+    expect(report).toContain('Register globally or in the calling agent scope.')
+    expect(report).toContain('@param definition - the tool schema')
+    expect(report).toContain('@returns the exact disposer')
+    expect(report).toContain('register(definition: ToolDefinition)')
+    expect(report).toContain('type shapes (referenced by the signatures above')
+    expect(report).not.toContain('not running (loadable services')
+    expect(report).not.toContain('inherited ctx API:')
   })
 
   it('renders the events section with mode badges, signatures, and the waterfall caution', async () => {
@@ -73,6 +91,39 @@ describe('cordis_inspect', () => {
     expect(report).toContain('- tools/pre-execute [waterfall]')
     expect(report).toMatch(/'agent\/status'\(/)
     expect(report).toContain('returning without next() vetoes the chain')
+    expect(report).not.toContain('/**')
+    expect(report).not.toContain('@mode waterfall')
+  })
+
+  it('adds original event JSDoc only for an exact event name', async () => {
+    const ctx = await setup()
+    const report = text(await call(ctx, 'cordis_inspect', { what: 'events', name: 'tools/pre-execute' }))
+    expect(report).toContain('## events')
+    expect(report).toContain('- tools/pre-execute [waterfall]')
+    expect(report).toContain('/**')
+    expect(report).toContain('Allow, deny, or ask before dispatch.')
+    expect(report).toContain('@param exec - the pending call')
+    expect(report).toContain('@mode waterfall')
+    expect(report).not.toContain('- tools/change [emit]')
+  })
+
+  it('fails loud for incompatible, unknown, and non-running names', async () => {
+    const ctx = await setup()
+    const incompatible = await call(ctx, 'cordis_inspect', { what: 'tools', name: 'tools' })
+    expect(incompatible.isError).toBe(true)
+    expect(text(incompatible)).toContain('name is valid only with what:"api" or what:"events"')
+
+    const unknownService = await call(ctx, 'cordis_inspect', { what: 'api', name: 'not-a-service' })
+    expect(unknownService.isError).toBe(true)
+    expect(text(unknownService)).toContain('no catalogued service named "not-a-service"')
+
+    const nonRunning = await call(ctx, 'cordis_inspect', { what: 'api', name: 'bash' })
+    expect(nonRunning.isError).toBe(true)
+    expect(text(nonRunning)).toContain('catalogued service "bash" is not running')
+
+    const unknownEvent = await call(ctx, 'cordis_inspect', { what: 'events', name: 'not/an-event' })
+    expect(unknownEvent.isError).toBe(true)
+    expect(text(unknownEvent)).toContain('no catalogued event named "not/an-event"')
   })
 })
 
@@ -102,7 +153,11 @@ describe('inspect renderers (direct)', () => {
 
   it('describeApi omits the not-running line and type shapes when nothing applies', async () => {
     const ctx = await setup()
-    const lines = describeApi(ctx, [{ key: 'tools', summary: 'The registry.', methods: ['register(x): void'] }], [], [])
+    const lines = describeApi(ctx, [{
+      key: 'tools',
+      summary: 'The registry.',
+      methods: [{ signature: 'register(x): void', jsDoc: '/** Register x. */' }],
+    }], [], [])
     expect(lines[0]).toBe('- tools — The registry.')
     expect(lines[1]).toBe('    register(x): void')
     expect(lines.join('\n')).not.toContain('not running')

packages/cordis/tool-cordis/tests/integration.spec.ts

@@ -1,7 +1,8 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import { AgentId } from '@deepseek-ai/dsh-agent'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import * as ToolCordis from '../src/index.ts'
 import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
@@ -24,7 +25,7 @@ async function harness(adapter: MockAdapter): Promise<Context> {
   return ctx
 }
 
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') {
@@ -44,7 +45,7 @@ describe('cordis tools through the agent loop', () => {
       textResponse('Done.'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('it-cordis'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('it-cordis'), { provider: 'mock', model: 'mock' })
 
     agent.send([{ type: 'text', text: 'give yourself reverse_text, use it, clean up' }])
     await waitForIdle(ctx, agent)

packages/cordis/tool-cordis/tests/mount.spec.ts

@@ -175,9 +175,13 @@ describe('cordis_mount', () => {
     // The registered schema is canonical JSON Schema derived from the DSL:
     // the required array survived, integer became number, extra is optional.
     const schema = ctx.tools.schemas().find(s => s.name === 'json_schema_tool')!
-    const parameters = schema.parameters as { properties: Record<string, { type: string; enum?: string[] }>; required?: string[] }
+    const parameters = schema.parameters as {
+      properties: Record<string, { type: string; enum?: string[]; default?: unknown }>
+      required?: string[]
+    }
     expect(parameters.required).toEqual(['text'])
     expect(parameters.properties.count!.type).toBe('number')
+    expect(parameters.properties.count!.default).toBe(1)
     expect(parameters.properties.mode!.enum).toEqual(['fast', 'slow'])
     // Arg validation enforces the normalized spec: text required, extra not.
     expect((await call(ctx, 'json_schema_tool', { count: 2 })).isError).toBe(true)

packages/cordis/tool-cordis/tests/present.spec.ts

@@ -11,6 +11,11 @@ describe('presenters', () => {
   it('cordis_inspect renders a generic read card titled with the section', () => {
     expect(presentInspectCall({})).toEqual({ card: 'generic', kind: 'read', title: 'Inspect cordis runtime' })
     expect(presentInspectCall({ what: 'api' })).toEqual({ card: 'generic', kind: 'read', title: 'Inspect cordis runtime: api' })
+    expect(presentInspectCall({ what: 'events', name: 'tools/change' })).toEqual({
+      card: 'generic',
+      kind: 'read',
+      title: 'Inspect cordis runtime: events: tools/change',
+    })
   })
 
   it('cordis_mount renders a generic execute card carrying the code as raw input', () => {
@@ -33,6 +38,9 @@ describe('presenters', () => {
       kind: 'read',
       title: 'Inspect cordis runtime: tools',
     })
+    expect(ctx.tools.get('cordis_inspect')!.presentCall!({ what: 'api', name: 'tools' })).toMatchObject({
+      title: 'Inspect cordis runtime: api: tools',
+    })
     expect(ctx.tools.get('cordis_mount')!.presentCall!({ code: 'return 1' })).toMatchObject({ kind: 'execute' })
     expect(ctx.tools.get('cordis_unmount')!.presentCall!({ id: 'dyn-2' })).toMatchObject({ title: 'Unmount dyn-2' })
     // Soft validation: presenter args that fail the schema render as no card, never a throw.

packages/cordis/tool-cordis/tests/tool-cordis.spec.ts

@@ -32,8 +32,9 @@ describe('tool registration', () => {
     const names = ctx.tools.schemas().map(schema => schema.name)
     expect(names).toEqual(expect.arrayContaining(['cordis_inspect', 'cordis_mount', 'cordis_unmount']))
     const inspect = ctx.tools.schemas().find(schema => schema.name === 'cordis_inspect')!
-    const props = (inspect.parameters as { properties: Record<string, { enum?: string[] }> }).properties
+    const props = (inspect.parameters as { properties: Record<string, { enum?: string[]; type?: string }> }).properties
     expect(props.what?.enum).toEqual(['services', 'plugins', 'tools', 'dynamic', 'api', 'events'])
+    expect(props.name?.type).toBe('string')
   })
 })
 

packages/core/README.md

@@ -8,11 +8,11 @@ The session log, system-prompt assembly, tool registry, agent vocabulary, and co
 | `session/` | Event-sourced session log + in-memory store | `ctx.sessions` |
 | `system-prompt/` | Prompt-section + tool-schema assembly registry | `ctx.systemPrompt` |
 | `tools/` | Scoped tool registry + pre-policy, guards, around-dispatch, post-policy, and final-result observation | `ctx.tools` |
-| `agent/` | Agent interface, registry, `agent/*` event vocabulary | `ctx.agents` |
-| `agent-loop/` | The concrete loop plugin: `ReactLoopAgent` + the loop driver | `ctx.agentLoop` |
+| `agent/` | Agent interface, live registry, process-local initiator scope, `agent/*` event vocabulary | `ctx.agents` |
+| `agent-loop/` | Concrete plugin implementing the public `Agent` contract and owning the loop driver | `ctx.agentLoop` |
 
 `scope/` is the one non-service package here: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) the registries and the loop build per-agent scoping on — it sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle.
 
-`agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; everything else in `core/` is interface/vocabulary. Plugins depend on the `agent` vocabulary, never on `agent-loop` directly, so the loop stays swappable.
+`agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop. It runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent`, including when they need the initiating Agent, and never on `agent-loop` directly, so the loop stays swappable.
 
 The default composition that wires this spine into a runnable agent lives in [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md): one bundle plugin that loads the control spine plus selected default capabilities (`timer` + `llm` + sessions + system-prompt + tools + agents + invariants + the local [skill family](../skill/README.md) + `tool-bash` + workspace-context + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. It sits in `examples/` — ready-to-run demo/reference bundles — not in `core/`: `core/` ships the swappable spine pieces, while a demo bundle picks one concrete composition of them and adds a front door.

packages/core/agent-loop/README.md

@@ -1,6 +1,6 @@
 # dsh-agent-loop
 
-Concrete `ReactLoopAgent` implementation and loop driver.
+THE concrete agent plugin and loop driver. Its package-internal implementation satisfies the `Agent` interface and drives the session/turn/step lifecycle.
 
 This is the only package in the harness that contains concrete loop logic. Everything else is an abstract service or a plugin against extension seams — new behavior goes into plugins, not here.
 
@@ -8,16 +8,18 @@ This is the only package in the harness that contains concrete loop logic. Every
 
 ### Public API
 
-Creation and resume use one caller-owned transaction: compose while unpublished, enter both registries, announce lifecycle edges, then start the driver. Failure rolls back private resources; caller, handle, and provider teardown share one quiescence boundary. The interface contract and ownership order live in [`dsh-agent`](../agent/README.md) and the [agent-scope runtime RFC](../../../docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md).
+Creation and resume are one rollback-covered transaction: construct a private session, concrete agent, and scoped context; await optional setup; enter both registries; announce `session/created` then `agent/created`; emit `agent/session-start`; and only then start the driver. Setup receives the full scoped `Context` as trusted same-process composition code and must not drive the unpublished agent. Ordinary typed identity and option inputs are borrowed under their readonly contract, while seed events and session metadata are validated and snapshotted because they cross the durable session boundary. An optional `AbortSignal` cancels only load/setup/publication and is detached before the returned handle becomes visible.
 
-Caller-chosen ids arbitrate only at final registry entry, so concurrent contenders may prepare but every loser rolls back. Entry-bound detach capabilities cannot remove a later same-id replacement. Teardown stops and drains—including idle-injection flushes—before detaching agent, session, and scope; ids become reusable at detach.
+The caller fiber and the AgentLoop provider are co-owners. `AgentFactory.createAgent(ownerCtx, options)` and `resume(ownerCtx, options)` receive caller ownership explicitly, while the factory keeps its own dependency context for `sessions`/`llm`/`tools`/`systemPrompt`; this lets a caller inject only `agents` without shrinking the new agent's service surface. Caller unload, handle disposal, or provider unload converge on one memoized quiescence boundary. Provider shutdown waits both resource teardown and the public create/resume wrapper that observed deactivation, so no continuation can publish after dependencies disappear.
 
-- `ctx.agentLoop.create(id, options?, meta?)` synchronously creates a caller-fiber-owned agent with a fresh generated session id and optional cwd. Each call starts a new session rather than applying resume-or-create policy.
+Each agent and its session share one caller-chosen `SessionId`, assumed globally unique; accidental UUID collisions are outside the supported model. Two concurrent operations with the same id may both prepare, but the final `enter()` calls arbitrate publication and every loser rolls its private resources back. Each detach is bound to the exact entered object, so a stale disposer cannot remove a later same-id replacement. A detach requested during a synchronous creation notification waits for that dispatch to unwind, preserving created/disposed pairing. Teardown runs stop and drain (including outstanding idle-injection flushes) → detach agent → detach session → unwind scope; the id becomes reusable at detach even if private scope cleanup is still finishing. Ordinary non-vetoing `agent/*` notifications go through `agentEvents(ctx, agent)`, per-step assembly goes through `assembleContextFor(agent)`, and turn-end durability checkpoints go through `ctx.sessions.flush(session)`.
+
+- `ctx.agentLoop.create(id: SessionId, options?: AgentOptions, meta?: { cwd?: string }): Agent` — synchronous no-setup create under the exact shared agent/session id, disposed with the calling fiber. Declarative config treats `agents[].id` as a stable label and normally mints `${label}-session-<uuid>` before calling this boundary. An app may instead supply a stable exact `sessionId`: first use creates it, while a remount with persistence already present resumes its materialized history. `resumeSessionId` requires and loads an existing persisted id and is mutually exclusive with `sessionId`. This keeps default fresh restarts collision-free without retaining a second live routing identity.
 
 `AgentLoop` also implements the `AgentFactory` seam and registers itself via `ctx.agents.setFactory(this)`, so plugins create/resume agents through `ctx.agents` (the interface):
 
-- `ctx.agents.create({ agentId, sessionId, meta?, seed?, agentOptions?, setup?, signal? })` validates and snapshots durable seed and metadata, awaits optional composition while unpublished, creates on the supplied session id, and returns an owned [`AgentHandle`](../agent/README.md). Its signal applies only until publication.
-- `ctx.agents.resume({ agentId, resumeSessionId, agentOptions?, setup?, signal? })` loads through optional [session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md), continues stored history and turn numbering under the resumed session id, and follows the same unpublished setup and creation-only cancellation boundary. It rejects when no persistence backend is mounted.
+- `ctx.agents.create({ sessionId, meta?, seed?, agentOptions?, setup?, signal? }): Promise<AgentHandle>` — programmatic create under the caller-supplied shared id. It awaits the unpublished setup transaction before returning; `meta` carries cwd/lineage/seed-boundary metadata and `seed` reconstructs a forked child prefix after the session boundary validates and snapshots the durable values. `signal` applies only until this promise settles. The resolved [`AgentHandle`](../agent/README.md) owns exact teardown.
+- `ctx.agents.resume({ resumeSessionId, agentOptions?, setup?, signal? }): Promise<AgentHandle>` — load a persisted session via `ctx.sessionPersistence` ([session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md)), register the agent under that same id, reconstruct its history, then await setup against a fresh unpublished agent scope before rollback-covered publication. Turn numbering and derived history continue from the loaded log. Requires a session-persistence backend (NOT hard-injected — non-persistent demos still work; `resume` rejects with a clear error when persistence is absent). `signal` is creation-only. Returns an `AgentHandle`.
 
 The config-driven `ctx.agentLoop.create()` path keeps its agent owned by the loop fiber (it discards the handle). For a programmatic agent, the handle holder is the only consumer-facing teardown capability; AgentLoop provider unload is the independent structural teardown edge, not another handle exposed to application code.
 
@@ -29,6 +31,7 @@ The config-driven `ctx.agentLoop.create()` path keeps its agent owned by the loo
 
 ```ts
 interface Config {
+  maxParallelToolCalls?: number // default 10; 1 is serial
   agents: Array<{
     id: string                 // required
     provider?: string
@@ -39,27 +42,27 @@ interface Config {
 }
 ```
 
-Configured agents start automatically. A model call requires both `provider` and `model`; `agent/request` may supply a missing pair before dispatch. `cwd` applies only to fresh sessions, while `resumeSessionId` retains persisted metadata. Configured agents use the deployment persona, and programmatic setup can shadow it per agent. This plugin supplies the per-agent `provider`, `model`, and `cwd` prompt variables; harness identity and deployment persona belong to `dsh-system-prompt`.
+Configured agents start automatically. A model call requires both `provider` and `model`; `agent/request` may supply a missing pair before dispatch. `maxParallelToolCalls` bounds every agent's rolling pool for parallel-safe calls and defaults to `10`. `cwd` applies only to fresh sessions, while `resumeSessionId` retains persisted metadata. Configured agents use the deployment persona, and programmatic setup can shadow it per agent. This plugin supplies the per-agent `provider`, `model`, and `cwd` prompt variables; harness identity and deployment persona belong to `dsh-system-prompt`.
 
-### Exported concrete class
+### Internal concrete driver
 
-- `ReactLoopAgent` — the concrete `Agent` implementation. Its inbox is a JavaScript native-private field, and one prepared session can be claimed by only one concrete driver. Everything observable happens through session events and the `agent/*` event taxonomy.
-
-`Inbox`, `runLoop`, and the instance-bound publication/start controls are package-internal. The package root does not export them, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than constructing or starting the driver internals. `ReactLoopAgent.send()`, running `steer()`, and open-turn `inject()` materialize content plus resolved source once as detached, deeply frozen lossless JSON; malformed data throws before enqueue or append. An injection that arrives while the current step executes assistant tool calls stays in a FIFO until the batch settles; successful batches place it after the complete result batch, and interrupted batches drain it before the turn closes.
+The concrete `Agent` class, its `Inbox`, `runLoop`, and instance-bound publication/start controls are package-internal. The package root exports only the plugin/service/config contract, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than naming, constructing, or starting driver internals. The concrete `send()`, running `steer()`, and open-turn `inject()` materialize content plus resolved source once as detached, deeply frozen lossless JSON; malformed data throws before enqueue or append. An injection that arrives while the current step executes assistant tool calls stays in a FIFO until the batch settles; successful batches place it after the complete result batch, and interrupted batches drain it before the turn closes. One prepared session can be claimed by only one concrete driver, and everything observable happens through session events and the `agent/*` event taxonomy.
 
 ### Loop lifecycle (`loop.ts`)
 
-The driver owns one agent for its lifetime. It records turn, step, request, stream, and tool boundaries in the session log; live extension events coordinate policy around those durable facts. The [architecture turn flow](../../../docs/architecture.md#turn-flow) and generated [event catalog](../../../docs/cordis-catalog/events.md) are the authoritative sequence and signatures.
+The driver owns one agent for its lifetime and runs inside `ctx.agents.withInitiator(agent, ...)`. Package-private orchestration entry points recover the exact Agent, derive `agent.session` once, and let operation-local helpers capture it instead of forwarding the concrete driver or per-operation `Session` through shallow interfaces. A helper keeps an explicit `Session` when that is its actual interface, while creation, persistence load, unpublished setup, services, workers, processes, persistence, and wire protocols retain their explicit identities. The [agent service](../agent/README.md#initiating-agent-scope) owns propagation, teardown, and detached-work rules.
 
 Every provider call that reaches a successful finish appends exactly one `assistant/message` completion anchor, including content-less calls and `max-tokens` finishes. A successful `agent/step-result` stores its transformed content; a rejected result records empty content before the original failure continues. The anchor retains exact chunk provenance (`[]` for a stream with no chunks) and usage when available, while empty content stays out of derived message history.
 
-Plugin failure ends the current turn, not the loop. Cancellation clears pending work and aborts the current step without leaking to the next prompt. Terminal continuation stops remain authoritative through turn close and durability flush.
+Plugin failure ends the current turn, not the loop. Only final adapter dispatch/iteration failures and terminal in-band error or aborted finishes enter `agent/request-error`; middleware, result processing, tools, and `agent/post-step` remain ordinary turn failures. Recovery observes a closed failed step, and a retry rebuilds the request from the durable log in a new numbered step. Cancellation clears pending work and aborts the current step without leaking to the next prompt; undispatched model tool calls receive synthetic `tool/call` and aborted result pairs. Terminal continuation stops remain authoritative through turn close and durability flush.
+
+Within a step, exclusive calls form barriers; parallel-safe calls use a bounded rolling pool and are reclassified before start. Only dispatch/body overlaps. Policy, durable results, and result context remain model-ordered. Abort stops new calls, drains started results, then drains accepted batch context before the turn closes through the normal abort path.
 
 ### What belongs to plugins
 
 Everything that goes beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy:
 - Hooks and policy: the relevant `agent/*` checkpoints plus the guarded `tools/pre-execute` → `tools/execute` → `tools/post-execute` → `tools/result` pipeline; exact signatures and modes live in the [generated event catalog](../../../docs/cordis-catalog/events.md)
-- Compaction: `agent/pre-step`
+- Compaction: pressure on `agent/post-step`; canonical context overflow on `agent/request-error`
 - Sandbox, permission, plan mode: `tools/pre-execute` for extensible deny/ask, `tools.guard()` for monotonic owner policy, `tools/post-execute` for result decisions, and `tools/result` for final observation
 - Sub-agents: implemented outside the loop as `ctx.subagents` providers; in-process providers use `ctx.agents.create()` and owned `AgentHandle` teardown, while generic [`ctx.tasks`](../../tasks/tasks/) plus [`dsh-tool-subagent`](../../subagent/tool-subagent/) own background collection.
 - Persistence: `session/event` + `session/flush`
@@ -69,19 +72,49 @@ Everything that goes beyond "call the model, run the tools, repeat" belongs to p
 
 ### Complete conversation request
 
-**What the model sees**: For each step, the loop sends the rendered per-agent system prompt, visible tool schemas, the frozen session prefix, and the session's derived messages. It supplies `model` and `cwd` variable values but no additional fixed prose.
+#### What the model sees
 
-**Token effect**: System text, schemas, and prefix are paid again on every step. Per-agent scoping chooses the initial contributions, while the authoritative assembly waterfall can alter the final request and makes its listener responsible for protocol coherence.
+For each step, the loop sends the rendered per-agent system prompt, visible tool schemas, the frozen session prefix, and the session's derived messages. It supplies `model` and `cwd` variable values but no additional fixed prose.
+
+#### Token effect
+
+System text, schemas, and prefix are paid again on every step. Per-agent scoping chooses the initial contributions, while the authoritative assembly waterfall can alter the final request and makes its listener responsible for protocol coherence.
+
+#### KV Cache effect
+
+Append-only only while system text, schemas, session prefix, and earlier history remain byte-identical under the same provider and model route. A token-bearing assembly rewrite or composition change may invalidate reuse from the first altered request token.
 
 ### Retained message history
 
-**What the model sees**: Accepted user messages, assistant messages, tool calls and results, injected context, and steering are logged and sent on later steps. Raw stream chunks, lifecycle boundaries, and other log-only events are excluded.
+#### What the model sees
 
-**Token effect**: Input grows with every surface message until a compaction replacement shadows older nodes; a multi-step tool turn resends the accumulated prefix and history each step.
+Accepted user messages, assistant messages, tool calls and results, injected context, and steering are logged and sent on later steps. Raw stream chunks, lifecycle boundaries, and other log-only events are excluded.
+
+#### Token effect
+
+Input grows with every surface message until a compaction replacement shadows older nodes; a multi-step tool turn resends the accumulated prefix and history each step.
+
+#### KV Cache effect
+
+Ordinary history growth is append-only and preserves reusable entries. A surface replacement or compaction invalidates reuse from the first shadowed history token.
+
+### Undispatched calls after cancellation
+
+#### What the model sees
+
+If a later request replays an aborted step, each tool call that cancellation prevented from dispatching has the error result text `Error: tool call skipped because the step was aborted before execution`.
+
+#### Token effect
+
+One fixed error result per skipped call remains in history until compaction shadows it.
+
+#### KV Cache effect
+
+Append-only; each synthetic result follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
 ## Known Limitations and Deferred Work
 
-- **Tool calls within a step execute sequentially** — parallel execution waits on concurrency-safety metadata in the tool contract (see `dsh-tools`).
-- **No resume-or-create policy on the config path** — config-driven `create()` starts a fresh `${id}-session-<uuid>` every run (`TODO(demo)`), and a config `resumeSessionId` whose resume fails logs a warning and creates no agent.
+- **Classification is unary** — calls whose safety depends on comparing siblings or resources must remain exclusive ([rationale](../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md)).
+- **Config labels are fresh by default** — omitting `sessionId` creates a fresh `${id}-session-<uuid>` on every startup; exact resume-or-create behavior requires an explicit stable `sessionId`, while `resumeSessionId` requires existing persisted history.
 - **Config agents have no per-agent persona field or setup hook** — they use the deployment persona; scoped persona/tool composition is available only through the programmatic `ctx.agents.create()` / `resume()` factory options.
 - **No built-in turn budget** — the default continuation is `continue` whenever a step had tool calls or steering; bounding a runaway turn requires an `agent/turn-continuation` force-stop plugin.

packages/core/agent-loop/src/agent.ts

@@ -8,11 +8,11 @@
 
 import type { Context } from 'cordis'
 import { agentEvents } from '@deepseek-ai/dsh-agent'
-import type { AgentId, AgentOptions, AgentStatus, HookContext, InjectOptions, SendOptions } from '@deepseek-ai/dsh-agent'
+import type { AgentOptions, AgentStatus, HookContext, InjectOptions, SendOptions } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { deepFreeze } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
-import { snapshotJsonValue, type Session } from '@deepseek-ai/dsh-session'
+import { snapshotJsonValue, type Session, type SessionId } from '@deepseek-ai/dsh-session'
 import { Inbox, type InboxMessage } from './inbox.ts'
 import { isTurnOpen, lastTurnNumber, runLoop } from './loop.ts'
 
@@ -54,15 +54,20 @@ export interface PreparedReactLoopAgent {
  * @param id - the concrete agent identity.
  * @param options - loop options for the agent.
  * @param session - the prepared session the agent will own.
+ * @param maxParallelToolCalls - resolved in-flight cap for this agent.
  * @returns the agent and closures bound only to that exact instance.
  */
 export function prepareReactLoopAgent(
-  ctx: Context, id: AgentId, options: AgentOptions, session: Session,
+  ctx: Context,
+  id: SessionId,
+  options: AgentOptions,
+  session: Session,
+  maxParallelToolCalls: number,
 ): PreparedReactLoopAgent {
   if (claimedDriverSessions.has(session)) {
     throw new Error(`session "${session.id}" already has a concrete agent driver`)
   }
-  const agent = new ReactLoopAgent(ctx, id, options, session)
+  const agent = new ReactLoopAgent(ctx, id, options, session, maxParallelToolCalls)
   claimedDriverSessions.add(session)
   const dispose = () => agent[stopDriver]()
   return {
@@ -143,6 +148,8 @@ export class ReactLoopAgent implements Agent {
    * the `disposed` transition fires and leave the promise hanging.
    */
   private idleWaiters: (() => void)[] = []
+  /** Maximum parallel-safe calls allowed in one step. */
+  private readonly maxParallelToolCalls: number
   /**
    * Durability checkpoints started by idle {@link inject} calls. `inject()` is
    * synchronous, so it cannot await them itself; the driver disposer drains
@@ -156,10 +163,12 @@ export class ReactLoopAgent implements Agent {
 
   constructor(
     private loopCtx: Context,
-    public readonly id: AgentId,
+    public readonly id: SessionId,
     public readonly options: AgentOptions,
     public readonly session: Session,
+    maxParallelToolCalls: number,
   ) {
+    this.maxParallelToolCalls = maxParallelToolCalls
     const { promise, resolve } = Promise.withResolvers<void>()
     this.disposed = promise
     this.resolveDisposed = resolve
@@ -378,8 +387,9 @@ export class ReactLoopAgent implements Agent {
   [startDriver](): void {
     if (this._status === 'disposed') return
     this.driverStarted = true
-    this.done = runLoop(this.loopCtx, this, {
+    this.done = this.loopCtx.agents.withInitiator(this, () => runLoop(this.loopCtx, {
       inbox: this.#inbox,
+      maxParallelToolCalls: this.maxParallelToolCalls,
       setStatus: (status) => { this.setStatus(status) },
       setAbort: controller => void (this.currentAbort = controller),
       disposed: this.disposed,
@@ -390,7 +400,7 @@ export class ReactLoopAgent implements Agent {
       withToolBatch: run => this.withToolBatch(run),
       // Pre-step cancellation re-parks without emitting a status transition.
       settleIdle: () => { this.settleIdleWaiters() },
-    })
+    }))
   }
 
   /**

packages/core/agent-loop/src/constants.ts

@@ -0,0 +1,6 @@
+/** Shared agent-loop scheduler defaults.
+ * @module dsh-agent-loop/constants
+ */
+
+/** Default maximum in-flight parallel-safe calls per agent step. */
+export const DEFAULT_MAX_PARALLEL_TOOL_CALLS = 10

packages/core/agent-loop/src/index.ts

@@ -12,9 +12,9 @@ import { createScope } from '@deepseek-ai/dsh-scope'
 import type { Scope } from '@deepseek-ai/dsh-scope'
 import { agentEvents } from '@deepseek-ai/dsh-agent'
 import type {
+  Agent,
   AgentFactory,
   AgentHandle,
-  AgentId,
   AgentOptions,
   CreateAgentOptions,
   ResumeAgentOptions,
@@ -32,8 +32,7 @@ import {
   ReactLoopAgent,
 } from './agent.ts'
 import type { PreparedReactLoopAgent } from './agent.ts'
-
-export { ReactLoopAgent } from './agent.ts'
+import { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from './constants.ts'
 
 /** Fiber states that cannot own or serve a new lifecycle. */
 const INACTIVE_STATES: ReadonlySet<FiberState> = new Set([
@@ -42,10 +41,21 @@ const INACTIVE_STATES: ReadonlySet<FiberState> = new Set([
   FiberState.FAILED,
 ])
 
+/** Render an arbitrary thrown value without letting coercion escape containment. */
+function renderThrown(value: unknown): string {
+  try {
+    return String(value)
+  } catch {
+    return '<unrenderable thrown value>'
+  }
+}
+
 /** Factory-level ownership of every preparing or live transaction. */
 class FactoryOwnership {
   private accepting = true
+  private readonly inactive = Promise.withResolvers<void>()
   private transactions = new Set<AgentCreationTransaction>()
+  private startupTasks = new Set<Promise<void>>()
 
   constructor(private readonly fiber: Context['fiber']) {}
 
@@ -58,21 +68,44 @@ class FactoryOwnership {
     return () => { this.transactions.delete(transaction) }
   }
 
+  /** Join config startup work that begins before an agent transaction exists. */
+  trackStartup(task: Promise<void>): void {
+    this.startupTasks.add(task)
+    const forget = () => { this.startupTasks.delete(task) }
+    void task.then(forget, forget)
+  }
+
+  /** Resolve `task`, or stop waiting when factory teardown begins. */
+  async waitWhileActive(task: Promise<void>): Promise<void> {
+    await Promise.race([task, this.inactive.promise])
+  }
+
   async dispose(): Promise<void> {
     this.accepting = false
+    this.inactive.resolve()
     const reason = new Error('agent loop is not active')
-    await Promise.all(
-      [...this.transactions].map(transaction => transaction.disposeForFactory(reason)),
-    )
+    await Promise.all([
+      ...[...this.transactions].map(transaction => transaction.disposeForFactory(reason)),
+      ...this.startupTasks,
+    ])
   }
 }
 
 /** Build the public cancellation error while preserving a caller-supplied cause. */
-function signalAbortError(id: AgentId, signal: AbortSignal): Error {
+function signalAbortError(id: SessionId, signal: AbortSignal): Error {
   if (signal.reason instanceof Error) return signal.reason
   return new Error(`agent "${id}" creation aborted`, { cause: signal.reason })
 }
 
+/** Resolve the deployment-wide scheduler cap at the owning config boundary. */
+function resolveMaxParallelToolCalls(value: number | undefined): number {
+  const maxParallelToolCalls = value ?? DEFAULT_MAX_PARALLEL_TOOL_CALLS
+  if (!Number.isInteger(maxParallelToolCalls) || maxParallelToolCalls < 1) {
+    throw new Error('maxParallelToolCalls must be a positive integer')
+  }
+  return maxParallelToolCalls
+}
+
 /**
  * Caller-owned create/resume transaction through rollback-covered publication
  * and quiescent teardown. Resources remain private until the final registry
@@ -105,7 +138,7 @@ class AgentCreationTransaction {
     private readonly loopCtx: Context,
     private readonly ownerCtx: Context,
     private readonly ownership: FactoryOwnership,
-    readonly id: AgentId,
+    readonly id: SessionId,
     signal?: AbortSignal,
   ) {
     ownerCtx.fiber.assertActive()
@@ -163,13 +196,13 @@ class AgentCreationTransaction {
   }
 
   /** Construct the driver and scope, then install their complete ordered lifecycle. */
-  prepare(options: AgentOptions, session: Session): ReactLoopAgent {
+  prepare(options: AgentOptions, session: Session, maxParallelToolCalls: number): ReactLoopAgent {
     this.assertActive()
     const gate = Promise.withResolvers<void>()
     this.preparing = gate.promise
     try {
       this.session = session
-      const driver = prepareReactLoopAgent(this.loopCtx, this.id, options, session)
+      const driver = prepareReactLoopAgent(this.loopCtx, this.id, options, session, maxParallelToolCalls)
       this.driver = driver
       const agent = driver.agent
       const scope = createScope(this.loopCtx, agent)
@@ -227,7 +260,7 @@ class AgentCreationTransaction {
     this.publishing = true
     try {
       this.detachSession = agent.ctx.sessions.enter(session)
-      this.detachAgent = this.loopCtx.agents.enter(agent)
+      this.detachAgent = this.loopCtx.agents.enter(agent, this.ownerAgent)
 
       agent.ctx.sessions.announce(session)
       this.assertActive()
@@ -316,14 +349,35 @@ declare module 'cordis' {
   interface Context {
     agentLoop: AgentLoop
   }
+  interface Events {
+    /**
+     * A declarative agent entry failed before it could publish a live agent.
+     * Consumers that buffer work for the configured identity use this
+     * transient signal to reject that work instead of waiting forever. Normal
+     * factory teardown suppresses failures from the cancelled startup attempt.
+     * @param sessionId - exact shared agent/session identity that failed startup.
+     * @param error - persistence, setup, or publication failure.
+     * @mode emit
+     */
+    'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
+  }
 }
 
-/** Plugin configuration for declarative startup agents. */
+export { DEFAULT_MAX_PARALLEL_TOOL_CALLS }
+
+/** Agent-loop plugin configuration. */
 export interface Config {
+  /**
+   * Maximum parallel-safe calls in flight per agent step. `1` is serial;
+   * omission defaults to {@link DEFAULT_MAX_PARALLEL_TOOL_CALLS}.
+   */
+  maxParallelToolCalls?: number
   /** Agents created or resumed at plugin startup. */
   agents: (AgentOptions & {
-    /** Registry identity for the live agent. */
-    id: AgentId
+    /** Stable config label used in logs and as the fresh combined-id prefix. */
+    id: string
+    /** Optional stable identity; remounts resume its materialized history, while first use creates it fresh. */
+    sessionId?: SessionId
     /** Optional workspace for a fresh session. */
     cwd?: string
     /** Persisted session to resume instead of creating a fresh session. */
@@ -331,14 +385,34 @@ export interface Config {
   })[]
 }
 
-/** Concrete ReactLoopAgent factory and driver service. */
+/** Reject self-contained identity conflicts before any configured agent starts. */
+function validateConfiguredAgents(agents: Config['agents']): void {
+  const exactIdentities = new Map<SessionId, string>()
+  for (const { id, sessionId, resumeSessionId } of agents) {
+    const hasResumeId = resumeSessionId !== undefined && resumeSessionId !== ''
+    if (sessionId !== undefined && hasResumeId) {
+      throw new Error(`agent "${id}": sessionId and resumeSessionId are mutually exclusive`)
+    }
+    const exactIdentity = hasResumeId ? resumeSessionId : sessionId
+    if (exactIdentity === undefined) continue
+    const firstId = exactIdentities.get(exactIdentity)
+    if (firstId !== undefined) {
+      throw new Error(`agents "${firstId}" and "${id}" use duplicate exact session identity "${exactIdentity}"`)
+    }
+    exactIdentities.set(exactIdentity, id)
+  }
+}
+
+/** Concrete agent factory and driver service. */
 export class AgentLoop extends Service implements AgentFactory {
   static inject = ['agents', 'sessions', 'llm', 'tools', 'systemPrompt']
 
   /** Runtime schema for declarative agents. */
   static Config = z.object({
+    maxParallelToolCalls: z.number().step(1).min(1).default(DEFAULT_MAX_PARALLEL_TOOL_CALLS),
     agents: z.array(z.object({
       id: z.string().required(),
+      sessionId: z.string().min(1),
       provider: z.string(),
       model: z.string(),
       cwd: z.string(),
@@ -347,11 +421,15 @@ export class AgentLoop extends Service implements AgentFactory {
   }) as unknown as z<Config>
 
   private readonly ownership: FactoryOwnership
+  /** Resolved concurrency cap for every driver created by this factory. */
+  private readonly maxParallelToolCalls: number
   /** Plain holder prevents Cordis from re-tracing the factory's dependency context through a caller shadow. */
   private readonly runtime: { ctx: Context }
 
   constructor(ctx: Context, public config: Config) {
     super(ctx, 'agentLoop')
+    validateConfiguredAgents(config.agents)
+    this.maxParallelToolCalls = resolveMaxParallelToolCalls(config.maxParallelToolCalls)
     this.ownership = new FactoryOwnership(ctx.fiber)
     this.runtime = { ctx }
     ctx.effect(() => () => this.ownership.dispose(), 'agentLoop.transactions()')
@@ -360,19 +438,28 @@ export class AgentLoop extends Service implements AgentFactory {
     ctx.systemPrompt.variable('model', context => context.agent?.options.model)
     ctx.systemPrompt.variable('cwd', context => context.agent?.session.header.cwd)
 
-    for (const { id, cwd, resumeSessionId, ...options } of config.agents) {
+    for (const { id, sessionId, cwd, resumeSessionId, ...options } of config.agents) {
+      const meta = cwd === undefined ? {} : { cwd }
       if (resumeSessionId === undefined || resumeSessionId === '') {
-        this.create(id, options, cwd === undefined ? {} : { cwd })
+        const configuredId = sessionId ?? SessionId(`${id}-session-${randomUUID()}`)
+        const persistence = sessionId === undefined ? undefined : ctx.get('sessionPersistence')
+        if (persistence === undefined) {
+          this.create(configuredId, options, meta)
+        } else {
+          const startup = this.restoreOrCreateConfigured(ctx, persistence, configuredId, options, meta).catch((error: unknown) => {
+            this.reportConfiguredStartupFailure(id, 'restore', configuredId, error)
+          })
+          this.ownership.trackStartup(startup)
+        }
         continue
       }
       ctx.effect(() => {
         const fiber = ctx.inject(['sessionPersistence'], (childCtx: Context) => {
           void this.resumeWith(ctx, childCtx.sessionPersistence, {
-            agentId: id,
             resumeSessionId,
             agentOptions: options,
           }).catch((error: unknown) => {
-            ctx.logger.warn(`agent "${id}": config-driven resume of "${resumeSessionId}" failed: ${String(error)}`)
+            this.reportConfiguredStartupFailure(id, 'resume', resumeSessionId, error)
           })
         })
         return fiber.dispose
@@ -380,21 +467,84 @@ export class AgentLoop extends Service implements AgentFactory {
     }
   }
 
+  /** Report a contained declarative-start failure to identity-bound consumers. */
+  private reportConfiguredStartupFailure(
+    configId: string,
+    action: 'restore' | 'resume',
+    sessionId: SessionId,
+    error: unknown,
+  ): void {
+    if (!this.ownership.isActive()) return
+    this.ctx.logger.warn(`agent "${configId}": config-driven ${action} of "${sessionId}" failed: ${renderThrown(error)}`)
+    const args: unknown[] = ['agent-loop/config-start-failed', sessionId, error]
+    for (const callback of this.ctx.events.dispatch('emit', args)) {
+      try {
+        const returned: unknown = callback(...args)
+        void Promise.resolve(returned).catch((listenerError: unknown) => {
+          this.ctx.logger.warn(`agent "${configId}": config-start-failed listener rejected: ${renderThrown(listenerError)}`)
+        })
+      } catch (listenerError: unknown) {
+        this.ctx.logger.warn(`agent "${configId}": config-start-failed listener threw: ${renderThrown(listenerError)}`)
+      }
+    }
+  }
+
+  /** Restore a materialized exact config identity on remount, or create it on first use. */
+  private async restoreOrCreateConfigured(
+    ownerCtx: Context,
+    persistence: SessionPersistence,
+    sessionId: SessionId,
+    agentOptions: AgentOptions,
+    meta: Pick<SessionHeader, 'cwd'>,
+  ): Promise<void> {
+    await this.waitForDrainingConfiguredIdentity(ownerCtx, sessionId)
+    if (!this.ownership.isActive()) return
+    const exists = (await persistence.list()).some(header => header.id === sessionId)
+    if (!this.ownership.isActive()) return
+    if (exists) {
+      await this.resumeWith(ownerCtx, persistence, { resumeSessionId: sessionId, agentOptions })
+      return
+    }
+    this.create(sessionId, agentOptions, meta)
+  }
+
+  /** Wait for an already-disposed same-id lifecycle to finish registry teardown. */
+  private async waitForDrainingConfiguredIdentity(ownerCtx: Context, sessionId: SessionId): Promise<void> {
+    const current = ownerCtx.agents.get(sessionId)
+    if (current?.status !== 'disposed') return
+
+    const released = Promise.withResolvers<void>()
+    const checkReleased = (): void => {
+      if (ownerCtx.agents.get(sessionId) === undefined && ownerCtx.sessions.get(sessionId) === undefined) {
+        released.resolve()
+      }
+    }
+    const disposeAgentListener = ownerCtx.on('agent/disposed', checkReleased)
+    const disposeSessionListener = ownerCtx.on('session/disposed', checkReleased)
+    try {
+      checkReleased()
+      await this.ownership.waitWhileActive(released.promise)
+    } finally {
+      disposeAgentListener()
+      disposeSessionListener()
+    }
+  }
+
   /**
-   * Create an agent on a fresh per-run session, owned by the accessing fiber.
-   * Constructor-driven config calls use the loop fiber itself.
-   * @param id - agent registry id.
+   * Create an agent and session under one caller-supplied identity, owned by
+   * the accessing fiber. Constructor-driven config calls mint a fresh combined
+   * id before entering this boundary.
+   * @param id - shared agent/session identity.
    * @param options - concrete loop options.
    * @param meta - optional fresh-session workspace metadata.
    * @returns the published running agent.
    */
-  create(id: AgentId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): ReactLoopAgent {
+  create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Agent {
     const loopCtx = this.runtime.ctx
     const transaction = new AgentCreationTransaction(loopCtx, this.ctx, this.ownership, id)
     try {
-      const sessionId = SessionId(`${id}-session-${randomUUID()}`)
-      const session = loopCtx.sessions.prepare(sessionId, { meta })
-      const agent = transaction.prepare(options, session)
+      const session = loopCtx.sessions.prepare(id, { meta })
+      const agent = transaction.prepare(options, session, this.maxParallelToolCalls)
       transaction.publish('startup')
       return agent
     } catch (error: unknown) {
@@ -412,11 +562,12 @@ export class AgentLoop extends Service implements AgentFactory {
    * @returns the published handle.
    */
   async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle> {
+    const agentOptions = options.agentOptions ?? {}
     const transaction = new AgentCreationTransaction(
       this.runtime.ctx,
       ownerCtx,
       this.ownership,
-      options.agentId,
+      options.sessionId,
       options.signal,
     )
     try {
@@ -424,7 +575,7 @@ export class AgentLoop extends Service implements AgentFactory {
         ...options.seed === undefined ? {} : { seed: options.seed },
         ...options.meta === undefined ? {} : { meta: options.meta },
       })
-      const agent = transaction.prepare(options.agentOptions ?? {}, session)
+      const agent = transaction.prepare(agentOptions, session, this.maxParallelToolCalls)
       await transaction.waitFor(options.setup?.(agent.ctx))
       transaction.assertActive()
       return transaction.publish('startup')
@@ -456,11 +607,12 @@ export class AgentLoop extends Service implements AgentFactory {
     persistence: SessionPersistence,
     options: ResumeAgentOptions,
   ): Promise<AgentHandle> {
+    const agentOptions = options.agentOptions ?? {}
     const transaction = new AgentCreationTransaction(
       this.runtime.ctx,
       ownerCtx,
       this.ownership,
-      options.agentId,
+      options.resumeSessionId,
       options.signal,
     )
     try {
@@ -475,7 +627,7 @@ export class AgentLoop extends Service implements AgentFactory {
           ...loaded.meta.seedLength === undefined ? {} : { seedLength: loaded.meta.seedLength },
         },
       })
-      const agent = transaction.prepare(options.agentOptions ?? {}, session)
+      const agent = transaction.prepare(agentOptions, session, this.maxParallelToolCalls)
       await transaction.waitFor(options.setup?.(agent.ctx))
       transaction.assertActive()
       return transaction.publish('resume')

packages/core/agent-loop/src/loop.ts

@@ -8,9 +8,9 @@
 import type { Context } from 'cordis'
 import type { ContentBlock, FinishReason, GenerateOptions, LlmCallConfig, Message } from '@deepseek-ai/dsh-llm'
 import { isDeepStrictEqual } from 'node:util'
-import { BlockAssembler, HarnessError, deepFreeze } from '@deepseek-ai/dsh-llm'
+import { BlockAssembler, HarnessError, assertNever, deepFreeze, isLlmAdapterFailure } from '@deepseek-ai/dsh-llm'
 import { agentEvents, assembleContextFor } from '@deepseek-ai/dsh-agent'
-import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision } from '@deepseek-ai/dsh-agent'
+import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision, RequestError, RequestErrorDecision } from '@deepseek-ai/dsh-agent'
 import { canonicalHeader } from '@deepseek-ai/dsh-session'
 import type { Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session'
 import { createTransmissionLog, recordRequestHeader } from './request-log.ts'
@@ -18,27 +18,32 @@ import type { TransmissionLog } from './request-log.ts'
 import { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tools'
-import type { ReactLoopAgent } from './agent.ts'
+import { executeToolCalls } from './tool-calls.ts'
 import type { Inbox } from './inbox.ts'
 
-/** An Error with an optional machine-readable code (e.g., from LlmError or a throwing plugin). */
-type CodedError = Error & { code?: string }
-
 /** Normalize thrown values while preserving an existing error code. */
-function toError(error: unknown): CodedError {
+function toError(error: unknown): RequestError {
   return error instanceof Error ? error : new HarnessError(String(error), 'UNKNOWN', { cause: error })
 }
 
+/** Distinguishes final model-request failures from failures in later step processing. */
+class TerminalModelRequestFailure extends Error {
+  constructor(readonly requestError: RequestError) {
+    super(requestError.message, { cause: requestError })
+    this.name = 'TerminalModelRequestFailure'
+  }
+}
+
 /** Convert terminal failure finishes into step errors; unknown extensible finishes remain successful. */
-function finishError(finish: FinishReason): CodedError | undefined {
+function finishError(finish: FinishReason): RequestError | undefined {
   switch (finish.kind) {
     case 'error': {
-      const error: CodedError = new Error(finish.message)
+      const error: RequestError = new Error(finish.message)
       if (finish.code !== undefined) error.code = finish.code
       return error
     }
     case 'aborted': {
-      const error: CodedError = new Error('model stream aborted')
+      const error: RequestError = new Error('model stream aborted')
       error.code = 'ABORTED'
       return error
     }
@@ -52,7 +57,7 @@ function finishError(finish: FinishReason): CodedError | undefined {
  * Build the `{ message, code? }` part of an error payload, omitting the
  * `code` key entirely when absent (exactOptionalPropertyTypes-correct).
  */
-function errorData(err: CodedError): { message: string; code?: string } {
+function errorData(err: RequestError): { message: string; code?: string } {
   return { message: err.message, ...typeof err.code === 'string' ? { code: err.code } : {} }
 }
 
@@ -73,6 +78,8 @@ function stepFinishReason(finish: FinishReason): TurnEndReason | undefined {
 export interface LoopHandle {
   /** Native-private agent inbox handed to the driver only at internal startup. */
   readonly inbox: Inbox
+  /** Maximum parallel-safe calls allowed in one step. */
+  readonly maxParallelToolCalls: number
   setStatus(status: 'idle' | 'running'): void
   setAbort(controller: AbortController | undefined): void
   /** Resolves when the agent is disposed — unblocks the idle wait. */
@@ -92,12 +99,17 @@ export interface LoopHandle {
 
 /**
  * Drive queued batches as durable turns until disposal. Plugin failures end the
- * current turn without terminating the driver.
- * @param ctx - the plugin context the loop reaches events (agent/…, session/flush) and services (systemPrompt, llm, tools) through.
- * @param agent - the agent this invocation drives for its whole lifetime (its inbox, session, and options).
+ * current turn without terminating the driver. The caller establishes the
+ * `ctx.agents.withInitiator()` boundary before entry; package-private
+ * orchestration recovers that exact Agent and captures its Session locally.
+ * @param ctx - the plugin context the loop reaches its initiating Agent,
+ * events (agent/…, session/flush), and services (systemPrompt, llm, tools)
+ * through.
  * @param handle - the bridge to the agent's mutable state: status/abort setters plus the disposal and cancel-marker reads.
+ * @throws when no initiating Agent is active.
  */
-export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopHandle): Promise<void> {
+export async function runLoop(ctx: Context, handle: LoopHandle): Promise<void> {
+  const agent = ctx.agents.requireInitiator()
   // Per-instance prefix and request-header state; conversation history remains in the session log.
   const transmission = createTransmissionLog()
 
@@ -135,7 +147,7 @@ export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopH
     const turn = lastTurnNumber(session) + 1
     let terminalStopped = false
     try {
-      terminalStopped = await runTurn(ctx, events, agent, handle, turn, transmission)
+      terminalStopped = await runTurn(ctx, events, handle, turn, transmission)
     } catch (error: unknown) {
       // Pre-turn failure has no durable boundary to close; report it without appending outside a turn.
       const err = toError(error)
@@ -158,9 +170,17 @@ export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopH
 }
 
 async function runTurn(
-  ctx: Context, events: AgentEventDispatch, agent: ReactLoopAgent, handle: LoopHandle, turn: number, transmission: TransmissionLog,
+  ctx: Context, events: AgentEventDispatch, handle: LoopHandle, turn: number, transmission: TransmissionLog,
 ): Promise<boolean> {
+  const agent = ctx.agents.requireInitiator()
   const { session } = agent
+  const drainSteering = (): boolean => {
+    const messages = handle.inbox.drainSteering()
+    for (const message of messages) {
+      session.append('steering/message', { turn, content: message.content, source: message.source }, { surfaceOp: 'append' })
+    }
+    return messages.length > 0
+  }
 
   // Drain before opening the turn, but append only after `turn/start`.
   const queued = handle.inbox.drainQueued()
@@ -171,6 +191,7 @@ async function runTurn(
 
   let reason: TurnEndReason = { kind: 'completed' }
   let step = 0
+  let requestRetryAttempt = 0
   let stepOpen = false
   let errorReported = false
   let terminalStopped = false
@@ -183,7 +204,7 @@ async function runTurn(
   }
 
   // Record the durable turn failure once and contain the live error notification.
-  const failTurn = (err: CodedError): void => {
+  const failTurn = (err: RequestError): void => {
     if (errorReported) return
     errorReported = true
     reason = { kind: 'error', step, ...errorData(err) }
@@ -259,7 +280,7 @@ async function runTurn(
 
       // Steering from the previous round's continuation listeners joins before
       // the request.
-      drainSteering(agent, handle.inbox, turn)
+      drainSteering()
 
       // The step's AbortController exists BEFORE any async pre-step work so a
       // dispose() or cancel() — in a synchronous turn-start listener or an
@@ -269,7 +290,7 @@ async function runTurn(
       const abort = new AbortController()
       handle.setAbort(abort)
 
-      // Assemble once before pre-step so pressure checks and the request share the same prompt.
+      // Assemble once before pre-step so listener work and the request share one prompt value.
       const assembly = await ctx.systemPrompt.assemble(assembleContextFor(agent))
       const fullSystemPrompt = renderPrompt(assembly)
 
@@ -280,9 +301,9 @@ async function runTurn(
         break
       }
 
-      // Compose the request-only prefix once per loop instance before pressure
-      // checks. It precedes all derived history and is recorded only in the
-      // request header, not as session history.
+      // Compose the request-only prefix once per loop instance before the first
+      // request boundary. It precedes all derived history and is recorded only
+      // in the request header, not as session history.
       if (transmission.sessionPrefix === undefined) {
         const emptyPrefix: Message[] = deepFreeze([])
         const composed = await events.waterfall(
@@ -299,8 +320,8 @@ async function runTurn(
         transmission.sessionPrefix = deepFreeze(structuredClone(composed))
       }
 
-      // Await surface mutations outside the step; pressure checks receive the pending prefix.
-      await events.serial('agent/pre-step', turn, step, fullSystemPrompt, transmission.sessionPrefix, abort.signal)
+      // Await surface mutations outside the step before snapshotting history.
+      await events.serial('agent/pre-step', turn, step, abort.signal)
 
       // Interruption landing during the pre-step seam: do not open an empty step.
       if (handle.isCancelled() || handle.isDisposed()) {
@@ -330,14 +351,69 @@ async function runTurn(
         break
       }
 
-      let stepOutcome: { hadToolCalls: boolean; finish: FinishReason } | { error: Error }
+      let stepOutcome:
+        | { hadToolCalls: boolean; finish: FinishReason }
+        | { requestError: RequestError }
+        | { error: RequestError }
       try {
         stepOutcome = await runStep(
-          ctx, events, agent, handle, turn, step, assembly, fullSystemPrompt, boundaryMessages, transmission, abort.signal)
+          ctx, events, handle, turn, step, assembly, fullSystemPrompt, boundaryMessages, transmission, abort.signal)
       } catch (error: unknown) {
-        stepOutcome = { error: toError(error) }
-      } finally {
+        if (error instanceof TerminalModelRequestFailure) {
+          stepOutcome = { requestError: error.requestError }
+        } else {
+          stepOutcome = { error: toError(error) }
+        }
+      }
+
+      if ('requestError' in stepOutcome) {
+        // Recovery observes a balanced failed step and the original provider
+        // error while the failed step's signal remains the active owner.
+        closeStep()
+        if (handle.isDisposed() || abort.signal.aborted) {
+          handle.setAbort(undefined)
+          reason = handle.isDisposed()
+            ? { kind: 'disposed' }
+            : { kind: 'aborted', reason: String(abort.signal.reason) }
+          break
+        }
+
+        const defaultDecision: RequestErrorDecision = { action: 'fail' }
+        let recoveryDecision: RequestErrorDecision = defaultDecision
+        try {
+          recoveryDecision = await events.waterfall(
+            'agent/request-error', turn, step, stepOutcome.requestError,
+            requestRetryAttempt, abort.signal,
+            () => Promise.resolve(defaultDecision),
+          )
+        } catch (recoveryError: unknown) {
+          ctx.logger.warn(
+            `agent "${agent.id}": request recovery failed at turn ${turn}, step ${step}: ${toError(recoveryError).message}`,
+          )
+        }
         handle.setAbort(undefined)
+
+        // Cancellation and disposal always win over either a recovery decision
+        // or a recovery-listener failure.
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (handle.isDisposed() || abort.signal.aborted) {
+          reason = handle.isDisposed()
+            ? { kind: 'disposed' }
+            : { kind: 'aborted', reason: String(abort.signal.reason) }
+          break
+        }
+        switch (recoveryDecision.action) {
+          case 'retry':
+            requestRetryAttempt += 1
+            continue
+          case 'fail':
+            failTurn(stepOutcome.requestError)
+            break
+          /* v8 ignore next -- closed-union exhaustiveness guard */
+          default:
+            assertNever(recoveryDecision, 'agent request-error decision')
+        }
+        break
       }
 
       if ('error' in stepOutcome) {
@@ -345,7 +421,9 @@ async function runTurn(
         // runLoop re-enqueues it as a queued message, so an abort-then-steer
         // starts a fresh turn instead of being silently consumed.
         closeStep()
+        handle.setAbort(undefined)
         const { error } = stepOutcome
+        /* v8 ignore next -- narrow race: disposal while non-request step work throws. */
         if (handle.isDisposed()) {
           reason = { kind: 'disposed' }
         } else if (abort.signal.aborted) {
@@ -357,14 +435,47 @@ async function runTurn(
         break
       }
 
+      requestRetryAttempt = 0
+
       // Preserve max-token completion unless a later disposal, abort, or error wins.
       const stepReason = stepFinishReason(stepOutcome.finish)
       if (stepReason) reason = stepReason
 
       // Steering that arrived during streaming/tool execution.
-      const steered = drainSteering(agent, handle.inbox, turn)
+      const steered = drainSteering()
+
+      try {
+        await events.serial('agent/post-step', turn, step, abort.signal)
+      } catch (error: unknown) {
+        stepOutcome = { error: toError(error) }
+      }
+
+      if ('error' in stepOutcome) {
+        closeStep()
+        handle.setAbort(undefined)
+        /* v8 ignore next -- narrow race: disposal while a post-step listener throws. */
+        if (handle.isDisposed()) {
+          reason = { kind: 'disposed' }
+        } else if (abort.signal.aborted) {
+          /* v8 ignore next -- signal.reason always set by cancellation or disposal. */
+          reason = { kind: 'aborted', reason: String(abort.signal.reason ?? 'aborted') }
+        } else {
+          failTurn(stepOutcome.error)
+        }
+        break
+      }
+
+      if (handle.isDisposed() || abort.signal.aborted) {
+        reason = handle.isDisposed()
+          ? { kind: 'disposed' }
+          : { kind: 'aborted', reason: String(abort.signal.reason) }
+        closeStep()
+        handle.setAbort(undefined)
+        break
+      }
 
       closeStep()
+      handle.setAbort(undefined)
 
       const defaultDecision: ContinuationDecision = { action: stepOutcome.hadToolCalls || steered ? 'continue' : 'stop' }
       let decision: ContinuationDecision
@@ -451,15 +562,6 @@ async function runTurn(
   return terminalStopped
 }
 
-/** Drain the steering queue into the session. Returns whether any arrived. */
-function drainSteering(agent: ReactLoopAgent, inbox: Inbox, turn: number): boolean {
-  const messages = inbox.drainSteering()
-  for (const message of messages) {
-    agent.session.append('steering/message', { turn, content: message.content, source: message.source }, { surfaceOp: 'append' })
-  }
-  return messages.length > 0
-}
-
 /**
  * Run one committed step: transform call config, log the request header, build
  * the request from the cached prefix plus the step-boundary snapshot, stream and
@@ -469,7 +571,6 @@ function drainSteering(agent: ReactLoopAgent, inbox: Inbox, turn: number): boole
 async function runStep(
   ctx: Context,
   events: AgentEventDispatch,
-  agent: ReactLoopAgent,
   handle: LoopHandle,
   turn: number,
   step: number,
@@ -479,6 +580,7 @@ async function runStep(
   transmission: TransmissionLog,
   signal: AbortSignal,
 ): Promise<{ hadToolCalls: boolean; finish: FinishReason }> {
+  const agent = ctx.agents.requireInitiator()
   const { session, options } = agent
 
   // Seed the first request from agent options and later requests from the logged header;
@@ -523,27 +625,65 @@ async function runStep(
   // --- Model call (streaming-first; raw chunks are the replay record) ---
   const assembler = new BlockAssembler()
   const chunkSeqs: number[] = []
-  for await (const chunk of ctx.llm.stream(request)) {
-    /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */
-    if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
-    const chunkEvent = session.append('assistant/chunk', { turn, step, chunk })
-    chunkSeqs.push(chunkEvent.seq)
-    assembler.push(chunk)
+  const stream = ctx.llm.stream(request)
+  try {
+    for await (const chunk of stream) {
+      /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */
+      if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
+      const chunkEvent = session.append('assistant/chunk', { turn, step, chunk })
+      chunkSeqs.push(chunkEvent.seq)
+      assembler.push(chunk)
+    }
+  } catch (error: unknown) {
+    if (isLlmAdapterFailure(stream, error)) throw new TerminalModelRequestFailure(error)
+    throw error
   }
 
   // Normalize failure finish chunks into the same path as thrown stream errors.
   const stepError = finishError(assembler.finish)
-  if (stepError) throw stepError
+  if (stepError) throw new TerminalModelRequestFailure(stepError)
+
+  const recordAssistantMessage = (
+    assembledContent: ContentBlock[],
+    message: Message,
+    preserveReplayState = true,
+  ): void => {
+    session.append(
+      'assistant/message',
+      {
+        turn,
+        step,
+        content: message.content,
+        provenance: assistantProvenance(
+          header.config,
+          assembler.replayState,
+          preserveReplayState && isDeepStrictEqual(message.content, assembledContent),
+        ),
+        ...assembler.usage === undefined ? {} : { usage: assembler.usage },
+      },
+      { surfaceOp: 'append', sourceEventSeqs: chunkSeqs },
+    )
+  }
+
+  // A rejected result still records the successful provider call without retaining rejected output.
+  const processStepResult = async (assembledContent: ContentBlock[], message: Message): Promise<Message> => {
+    try {
+      return await events.waterfall(
+        'agent/step-result', turn, step, message, () => Promise.resolve(message),
+      )
+    } catch (error: unknown) {
+      recordAssistantMessage(assembledContent, { ...message, content: [] }, false)
+      throw error
+    }
+  }
 
   if (assembler.finish.kind === 'max-tokens') {
     const assembled = assembler.message()
     const assembledContent = structuredClone(assembled.content)
     let message: Message = withoutToolCalls(assembled)
-    message = withoutToolCalls(await processStepResult(
-      events, session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs,
-    ))
+    message = withoutToolCalls(await processStepResult(assembledContent, message))
     // Preserve usage even when max-token truncation produced no content.
-    recordAssistantMessage(session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs)
+    recordAssistantMessage(assembledContent, message)
     return { hadToolCalls: false, finish: assembler.finish }
   }
 
@@ -551,122 +691,23 @@ async function runStep(
   const assembled = assembler.message()
   const assembledContent = structuredClone(assembled.content)
   let message: Message = assembled
-  message = await processStepResult(
-    events, session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs,
-  )
+  message = await processStepResult(assembledContent, message)
 
   // Every successful call records its completion anchor, including explicit
   // empty chunk provenance for a contentless, usage-less provider response.
-  recordAssistantMessage(session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs)
+  recordAssistantMessage(assembledContent, message)
 
-  // Tool execution stays sequential; recheck abort around each normalized result.
+  // Dispatch may overlap; policy, durable results, and result context stay model-ordered.
   const toolCalls = message.content.filter(block => block.type === 'tool-call')
   if (toolCalls.length === 0) return { hadToolCalls: false, finish: assembler.finish }
   return handle.withToolBatch(async (acceptContext) => {
-    for (const call of toolCalls) {
-      /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */
-      if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
-      const callEvent = session.append('tool/call', { turn, step, callId: call.id, name: call.name, arguments: call.arguments })
-      let parsedArguments: unknown
-      try {
-        parsedArguments = call.arguments ? JSON.parse(call.arguments) : {}
-      } catch {
-        parsedArguments = call.arguments
-      }
-      // TODO(pre-tool-input-rewrite): Keep logged history and live presentation aligned;
-      // see docs/rfc/proposed/feature/2026-06-30-pre-tool-input-rewrite.md.
-      const result = await ctx.tools.execute({
-        callId: call.id,
-        name: call.name,
-        arguments: parsedArguments,
-        agent,
-        signal,
-      })
-      session.append('tool/result', {
-        turn, step,
-        // Correlation comes from the immutable execution input; the result does
-        // not duplicate this authoritative transcript identity.
-        callId: call.id,
-        content: result.content,
-        isError: result.isError,
-        ...result.error ? { error: result.error } : {},
-        // Persist tool-owned presentation data for replay.
-        ...result.meta !== undefined ? { meta: result.meta } : {},
-      }, { surfaceOp: 'append', sourceEventSeqs: [callEvent.seq] })
-      // Accept into the batch FIFO immediately; entries remain deferred until
-      // every recorded result settles and survive abort or disposal afterward.
-      for (const context of result.additionalContexts ?? []) acceptContext(context)
-      // The signal may flip while the tool is awaited.
-      /* v8 ignore start -- signal.reason default unreachable: cancel()/disposal always set it */
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-      if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
-      /* v8 ignore stop */
-    }
+    await executeToolCalls(
+      ctx, turn, step, toolCalls, signal, handle.maxParallelToolCalls, acceptContext,
+    )
     return { hadToolCalls: true, finish: assembler.finish }
   })
 }
 
-/** Preserve successful-call accounting without retaining output that result processing rejected. */
-async function processStepResult(
-  events: AgentEventDispatch,
-  session: Session,
-  turn: number,
-  step: number,
-  config: LlmCallConfig,
-  assembledContent: ContentBlock[],
-  message: Message,
-  assembler: BlockAssembler,
-  chunkSeqs: number[],
-): Promise<Message> {
-  try {
-    return await events.waterfall(
-      'agent/step-result', turn, step, message, () => Promise.resolve(message),
-    )
-  } catch (error: unknown) {
-    recordAssistantMessage(
-      session,
-      turn,
-      step,
-      config,
-      assembledContent,
-      { ...message, content: [] },
-      assembler,
-      chunkSeqs,
-      false,
-    )
-    throw error
-  }
-}
-
-/** Record one content-or-usage assistant message with replay-safe provenance. */
-function recordAssistantMessage(
-  session: Session,
-  turn: number,
-  step: number,
-  config: LlmCallConfig,
-  assembledContent: ContentBlock[],
-  message: Message,
-  assembler: BlockAssembler,
-  chunkSeqs: number[],
-  preserveReplayState = true,
-): void {
-  session.append(
-    'assistant/message',
-    {
-      turn,
-      step,
-      content: message.content,
-      provenance: assistantProvenance(
-        config,
-        assembler.replayState,
-        preserveReplayState && isDeepStrictEqual(message.content, assembledContent),
-      ),
-      ...assembler.usage === undefined ? {} : { usage: assembler.usage },
-    },
-    { surfaceOp: 'append', sourceEventSeqs: chunkSeqs },
-  )
-}
-
 /** Build durable assistant provenance, dropping replay state after any content rewrite. */
 function assistantProvenance(config: LlmCallConfig, replayState: unknown, contentUnchanged: boolean): NonNullable<Message['provenance']> {
   return {

packages/core/agent-loop/src/tool-calls.ts

@@ -0,0 +1,253 @@
+/**
+ * Schedules one assistant step's tool calls. Exclusive calls form barriers;
+ * parallel calls use a bounded rolling pool and are reclassified before start.
+ * Dispatch may overlap, while policy, results, and result context remain
+ * model-ordered. Abort stops replenishment and drains started calls.
+ *
+ * Each advertised call records a balanced `tool/call`/`tool/result` pair. Calls
+ * skipped after abort receive synthetic error results so replay stays valid.
+ * @module dsh-agent-loop/tool-calls
+ */
+
+import type { Context } from 'cordis'
+import { assertNever, type ToolCallBlock } from '@deepseek-ai/dsh-llm'
+import type { HookContext } from '@deepseek-ai/dsh-agent'
+import type { Session } from '@deepseek-ai/dsh-session'
+import { TOOL_REGISTRY_SCHEDULER, type ToolExecutionInput, type ToolExecutionMode, type ToolExecutionResult, type ToolRunContext } from '@deepseek-ai/dsh-tools'
+
+/** One tool call after argument parsing, ready to schedule. */
+interface PlannedCall {
+  block: ToolCallBlock
+  exec: ToolExecutionInput
+}
+
+/** Settled dispatch awaiting model-order finalization. */
+interface Slot {
+  exec: ToolRunContext
+  result: ToolExecutionResult
+  needsPost: boolean
+}
+
+/** One scheduler group outcome, including a drained cancellation. */
+interface GroupOutcome {
+  consumed: number
+  aborted: boolean
+}
+
+/**
+ * Schedule one assistant step's tool calls by their live concurrency mode.
+ * Started calls receive ordered results. Abort drains them, records synthetic
+ * results for unstarted calls, and returns with the signal still aborted after
+ * accepting started-call context into the batch FIFO owned by the caller.
+ * The committed step's AgentLoop driver boundary supplies the initiating Agent
+ * that becomes each explicit {@link ToolExecutionInput.agent}.
+ *
+ * @param ctx - loop context that owns the tool registry and carries the initiating Agent.
+ * @param turn - current turn number.
+ * @param step - current step number.
+ * @param toolCalls - assistant calls in model order.
+ * @param signal - abort signal shared by the step.
+ * @param maxParallel - validated in-flight cap.
+ * @param acceptContext - accepts committed result context into the active batch.
+ */
+export async function executeToolCalls(
+  ctx: Context,
+  turn: number,
+  step: number,
+  toolCalls: ToolCallBlock[],
+  signal: AbortSignal,
+  maxParallel: number,
+  acceptContext: (context: HookContext) => void,
+): Promise<void> {
+  const agent = ctx.agents.requireInitiator()
+  const { session } = agent
+
+  // Inputs are distinct because tools/execute wrappers may replace `exec.signal`.
+  const planned: PlannedCall[] = toolCalls.map(block => ({
+    block,
+    exec: {
+      callId: block.id,
+      name: block.name,
+      arguments: parseArguments(block.arguments),
+      agent,
+      signal,
+    },
+  }))
+
+  let next = 0
+  while (next < planned.length) {
+    // Commit before classifying again so registry changes affect unstarted calls.
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded by the loop condition
+    const first = planned[next]!
+    const mode = ctx.tools.executionMode(first.exec).kind
+    const group = mode === 'parallel' ? planned.slice(next) : [first]
+    const outcome = await runGroup(
+      ctx, turn, step, group, mode, signal, maxParallel, acceptContext,
+    )
+    next += outcome.consumed
+    if (outcome.aborted) {
+      for (const call of planned.slice(next)) appendSkippedToolCall(session, turn, step, call.block)
+      return
+    }
+  }
+}
+
+/** Parse model arguments, preserving invalid JSON as text and mapping empty input to `{}`. */
+function parseArguments(raw: string): unknown {
+  try {
+    return raw ? JSON.parse(raw) : {}
+  } catch {
+    return raw
+  }
+}
+
+/**
+ * Run one exclusive barrier or parallel pool. Later calls are reclassified
+ * before start; an exclusive reclassification waits for the current pool to
+ * drain and remains for the caller's next barrier. Results and contexts commit
+ * in model order. Abort stops starts, drains and commits started calls, accepts
+ * their contexts into the owning batch, records results for skipped calls, and
+ * returns an aborted outcome.
+ */
+async function runGroup(
+  ctx: Context,
+  turn: number,
+  step: number,
+  group: PlannedCall[],
+  mode: ToolExecutionMode['kind'],
+  signal: AbortSignal,
+  maxParallel: number,
+  acceptContext: (context: HookContext) => void,
+): Promise<GroupOutcome> {
+  const { session } = ctx.agents.requireInitiator()
+  const slots: (Slot | undefined)[] = group.map(() => undefined)
+  // Started slots retain their tool/call seq for result provenance.
+  const callSeqs: number[] = group.map(() => -1)
+  let nextToStart = 0
+  let committed = 0
+  let started = 0
+  let aborted: boolean = signal.aborted
+
+  // `committed` advances only across contiguous model-order slots.
+  const commitReady = async (): Promise<void> => {
+    while (committed < group.length) {
+      const slot = slots[committed]
+      if (slot === undefined) break
+      const call = group[committed]
+      const result = slot.needsPost
+        ? await ctx.tools[TOOL_REGISTRY_SCHEDULER].finalize(slot.exec, slot.result)
+        : ctx.tools[TOOL_REGISTRY_SCHEDULER].finish(slot.exec, slot.result)
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded index
+      appendToolResult(session, turn, step, call!.block, result, callSeqs[committed]!)
+      for (const context of result.additionalContexts ?? []) acceptContext(context)
+      committed++
+    }
+  }
+
+  const inFlight = new Map<number, Promise<number>>()
+
+  const startCall = async (index: number): Promise<void> => {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded index
+    const call = group[index]!
+    callSeqs[index] = appendToolCall(session, turn, step, call.block)
+    started++
+    const prepared = await ctx.tools[TOOL_REGISTRY_SCHEDULER].prepare(call.exec)
+    switch (prepared.kind) {
+      case 'dispatch': {
+        const promise = ctx.tools[TOOL_REGISTRY_SCHEDULER].dispatch(prepared.exec).then((outcome) => {
+          slots[index] = { exec: prepared.exec, result: outcome.result, needsPost: outcome.kind === 'post-result' }
+          return index
+        })
+        inFlight.set(index, promise)
+        break
+      }
+      case 'post-result':
+        slots[index] = { exec: prepared.exec, result: prepared.result, needsPost: true }
+        break
+      case 'final-result':
+        slots[index] = { exec: prepared.exec, result: prepared.result, needsPost: false }
+        break
+      /* v8 ignore next -- closed-union exhaustiveness guard */
+      default:
+        assertNever(prepared, 'tool-call scheduler prepare result')
+    }
+  }
+
+  const fillPool = async (): Promise<void> => {
+    while (!aborted && nextToStart < group.length && inFlight.size < maxParallel) {
+      // Re-read later modes after ordered commits so registry changes can create a barrier.
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded by the loop condition
+      const nextCall = group[nextToStart]!
+      if (nextToStart > 0 && mode === 'parallel'
+        && ctx.tools.executionMode(nextCall.exec).kind !== 'parallel') break
+      await startCall(nextToStart)
+      nextToStart++
+      await commitReady()
+      // Abort may arrive while pre-execute awaits.
+      if (signal.aborted) aborted = true
+    }
+  }
+
+  // Ordered pre-execute may await; only dispatch/body overlaps.
+  // TODO: Drain every started call before rethrowing a scheduler error; tool
+  // bodies must not outlive the failed turn.
+  await fillPool()
+  while (inFlight.size > 0) {
+    const settledIndex = await Promise.race(inFlight.values())
+    inFlight.delete(settledIndex)
+    await commitReady()
+    // Abort may arrive while a tool or ordered commit awaits.
+
+    if (signal.aborted) aborted = true
+    await fillPool()
+  }
+
+  if (aborted) {
+    // Started calls and accepted context settle first; every remaining model
+    // call then receives an ordered synthetic result before the turn aborts.
+    for (const call of group.slice(started)) appendSkippedToolCall(session, turn, step, call.block)
+    return { consumed: group.length, aborted: true }
+  }
+  /* v8 ignore next -- unreachable: a non-aborted group commits every started call */
+  if (committed !== started) throw new Error('tool-call scheduler: uncommitted settled calls')
+  return { consumed: started, aborted: false }
+}
+
+/** Append the durable call/result pair for a model call skipped after cancellation. */
+function appendSkippedToolCall(session: Session, turn: number, step: number, block: ToolCallBlock): void {
+  const callSeq = appendToolCall(session, turn, step, block)
+  appendToolResult(session, turn, step, block, {
+    content: [{ type: 'text', text: 'Error: tool call skipped because the step was aborted before execution' }],
+    isError: true,
+    error: { name: 'AbortError', code: 'ABORTED' },
+  }, callSeq)
+}
+
+/** Append a started call and return its provenance sequence. */
+function appendToolCall(session: Session, turn: number, step: number, block: ToolCallBlock): number {
+  const event = session.append('tool/call', { turn, step, callId: block.id, name: block.name, arguments: block.arguments })
+  return event.seq
+}
+
+/** Append a model-ordered result linked to its call event. */
+function appendToolResult(
+  session: Session,
+  turn: number,
+  step: number,
+  block: ToolCallBlock,
+  result: ToolExecutionResult,
+  callSeq: number,
+): void {
+  session.append('tool/result', {
+    turn, step,
+    // Correlation stays with the loop's authoritative model-transcript call id;
+    // registry results deliberately do not duplicate it.
+    callId: block.id,
+    content: result.content,
+    isError: result.isError,
+    ...result.error ? { error: result.error } : {},
+    // The tool's private presentation payload (e.g. a result-time diff),
+    // persisted so a UI bridge reproduces the card on replay.
+    ...result.meta !== undefined ? { meta: result.meta } : {},
+  }, { surfaceOp: 'append', sourceEventSeqs: [callSeq] })
+}

packages/core/agent-loop/tests/agent-initiator.spec.ts

@@ -0,0 +1,335 @@
+import { describe, expect, it } from 'vitest'
+import { Context, type Fiber } from 'cordis'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import LlmService, { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
+
+interface Harness {
+  ctx: Context
+  agentsFiber: Fiber
+  loopFiber: Fiber
+}
+
+async function harness(adapter: LlmAdapter): Promise<Harness> {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  const agentsFiber = await ctx.plugin(AgentRegistry)
+  const loopFiber = await ctx.plugin(AgentLoop, { agents: [] })
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return { ctx, agentsFiber, loopFiber }
+}
+
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'idle') {
+        dispose()
+        resolve()
+      }
+    })
+  })
+}
+
+function send(agent: Agent, text: string): void {
+  agent.send([{ type: 'text', text }])
+}
+
+/** Adapter that holds both drivers at the same awaited continuation. */
+class OverlapAdapter extends LlmAdapter {
+  private readonly bothStarted = Promise.withResolvers<boolean>()
+  private starts = 0
+  readonly observations: { sessionId: SessionId | undefined; before: Agent; after: Agent }[] = []
+
+  constructor(private readonly ctx: Context) {
+    super()
+  }
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const before = this.ctx.agents.requireInitiator()
+    this.starts += 1
+    if (this.starts === 2) this.bothStarted.resolve(true)
+    await this.bothStarted.promise
+    await Promise.resolve()
+    const after = this.ctx.agents.requireInitiator()
+    this.observations.push({ sessionId: options.sessionId, before, after })
+    yield* textResponse('done')
+  }
+}
+
+/** Test-only transport that materializes ambient identity at its request boundary. */
+class TestCapabilityTransport {
+  readonly requests: { path: string; headers: Record<string, string> }[] = []
+
+  constructor(private readonly agents: AgentRegistry) {}
+
+  async request(path: string): Promise<Record<string, string>> {
+    await Promise.resolve()
+    const headers = {
+      'X-Harness-Session-Id': this.agents.requireInitiator().session.id,
+    }
+    this.requests.push({ path, headers })
+    return headers
+  }
+}
+
+/** Adapter whose first call waits for cancellation and whose later calls complete. */
+class ReloadAdapter extends LlmAdapter {
+  readonly firstStarted = Promise.withResolvers<boolean>()
+  firstAgentDuringAbort: Agent | undefined
+  laterAgent: Agent | undefined
+  calls = 0
+  agents: AgentRegistry | undefined
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const agents = this.agents
+    if (agents === undefined) throw new Error('agent service missing')
+    this.calls += 1
+    if (this.calls === 1) {
+      this.firstStarted.resolve(true)
+      try {
+        await new Promise<void>((_resolve, reject) => {
+          const abort = (): void => { reject(new Error('aborted')) }
+          if (options.signal?.aborted === true) abort()
+          else options.signal?.addEventListener('abort', abort, { once: true })
+        })
+      } catch (error: unknown) {
+        await Promise.resolve()
+        this.firstAgentDuringAbort = agents.requireInitiator()
+        throw error
+      }
+      return
+    }
+    await Promise.resolve()
+    this.laterAgent = agents.requireInitiator()
+    yield* textResponse('reloaded')
+  }
+}
+
+describe('AgentLoop initiator scope', () => {
+  it('keeps overlapping driver continuations bound to their exact Agents', async () => {
+    const ctx = new Context()
+    const adapter = new OverlapAdapter(ctx)
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(AgentLoop, { agents: [] })
+    ctx.llm.registerAdapter(['mock'], adapter)
+
+    const a = ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
+    const b = ctx.agentLoop.create(SessionId('b'), { provider: 'mock', model: 'mock' })
+    const idleA = waitForIdle(ctx, a)
+    const idleB = waitForIdle(ctx, b)
+    send(a, 'a')
+    send(b, 'b')
+    await Promise.all([idleA, idleB])
+
+    expect(adapter.observations).toHaveLength(2)
+    expect(adapter.observations).toEqual(expect.arrayContaining([
+      { sessionId: a.session.id, before: a, after: a },
+      { sessionId: b.session.id, before: b, after: b },
+    ]))
+    expect(ctx.agents.currentInitiator()).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('keeps child setup under the parent boundary and restores the parent while the child driver remains active', async () => {
+    const adapter = new MockAdapter([
+      toolCallResponse('spawn', 'spawn-child', {}),
+      toolCallResponse('observe', 'observe-child', {}),
+      textResponse('child done'),
+      textResponse('parent done'),
+    ])
+    const { ctx } = await harness(adapter)
+    let parentDuringSetup: Agent | undefined
+    let explicitChild: Agent | undefined
+    let childDuringDriver: Agent | undefined
+    let parentWhileChildDriverActive: Agent | undefined
+    let child: Agent | undefined
+
+    ctx.tools.register(defineTool({
+      name: 'spawn-child',
+      description: 'create one child agent',
+      parameters: {},
+      execute: async (_args, exec) => {
+        if (exec.agent === undefined) throw new Error('parent agent missing')
+        const handle = await exec.agent.ctx.agents.create({
+          sessionId: SessionId('child-session'),
+          agentOptions: { provider: 'mock', model: 'mock' },
+          setup: (agentCtx) => {
+            parentDuringSetup = ctx.agents.requireInitiator()
+            explicitChild = agentCtx.agent
+            agentCtx.tools.register(defineTool({
+              name: 'observe-child',
+              description: 'observe child execution identity',
+              parameters: {},
+              execute: async () => {
+                await Promise.resolve()
+                childDuringDriver = ctx.agents.requireInitiator()
+                return [{ type: 'text', text: 'observed' }]
+              },
+            }))
+          },
+        })
+        child = handle.agent
+        parentWhileChildDriverActive = ctx.agents.requireInitiator()
+        send(handle.agent, 'run child')
+        await handle.agent.whenIdle()
+        await handle.dispose()
+        return [{ type: 'text', text: 'child completed' }]
+      },
+    }))
+
+    const parentHandle = await ctx.agents.create({
+      sessionId: SessionId('parent-session'),
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    const idle = waitForIdle(ctx, parentHandle.agent)
+    send(parentHandle.agent, 'spawn')
+    await idle
+
+    expect(parentDuringSetup).toBe(parentHandle.agent)
+    expect(explicitChild).toBe(child)
+    expect(childDuringDriver).toBe(child)
+    expect(parentWhileChildDriverActive).toBe(parentHandle.agent)
+    expect(ctx.agents.currentInitiator()).toBeUndefined()
+    await parentHandle.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('keeps agentless direct tools ambient-free and builds trusted transport headers internally', async () => {
+    const adapter = new MockAdapter([
+      toolCallResponse('capability', 'capability-request', { path: '/v1/capability' }),
+      textResponse('done'),
+    ])
+    const { ctx } = await harness(adapter)
+    const transport = new TestCapabilityTransport(ctx.agents)
+    let directAmbient: Agent | undefined
+    let captured: Agent | undefined
+
+    ctx.tools.register(defineTool({
+      name: 'agentless-probe',
+      description: 'observe an agentless call',
+      parameters: {},
+      execute: async () => {
+        await Promise.resolve()
+        directAmbient = ctx.agents.currentInitiator()
+        return [{ type: 'text', text: 'ok' }]
+      },
+    }))
+    ctx.tools.register(defineTool({
+      name: 'capability-request',
+      description: 'call the test capability transport',
+      parameters: { path: { type: 'string' } },
+      execute: async (args) => {
+        captured = ctx.agents.requireInitiator()
+        const path = (args as { path: string }).path
+        const headers = await transport.request(path)
+        return [{ type: 'text', text: JSON.stringify(headers) }]
+      },
+    }))
+
+    const direct = await ctx.tools.execute({
+      callId: CallId('direct'),
+      name: 'agentless-probe',
+      arguments: {},
+    })
+    expect(direct.isError).toBe(false)
+    expect(directAmbient).toBeUndefined()
+
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('transport-session'),
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    const idle = waitForIdle(ctx, handle.agent)
+    send(handle.agent, 'call transport')
+    await idle
+
+    expect(transport.requests).toEqual([{
+      path: '/v1/capability',
+      headers: { 'X-Harness-Session-Id': 'transport-session' },
+    }])
+    const schema = adapter.requests[0]?.tools?.find(tool => tool.name === 'capability-request')
+    expect(JSON.stringify(schema?.parameters)).not.toMatch(/session|harness/i)
+    const call = handle.agent.session.events.find(event => event.type === 'tool/call')
+    expect(call?.type === 'tool/call' ? call.data.arguments : undefined)
+      .toBe(JSON.stringify({ path: '/v1/capability' }))
+    expect(captured).toBe(handle.agent)
+
+    await handle.dispose()
+    expect(captured?.status).toBe('disposed')
+    expect(ctx.agents.currentInitiator()).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('drains the old driver before disabling ALS during agent-service restart', async () => {
+    const adapter = new ReloadAdapter()
+    const { ctx, agentsFiber, loopFiber } = await harness(adapter)
+    const oldService = ctx.agents
+    adapter.agents = oldService
+    const oldHandle = await ctx.agents.create({
+      sessionId: SessionId('before-restart-session'),
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    const oldAgent = oldHandle.agent
+    send(oldAgent, 'block')
+    await adapter.firstStarted.promise
+
+    await agentsFiber.restart()
+    await loopFiber.await()
+    expect(adapter.firstAgentDuringAbort?.id).toBe(oldAgent.id)
+    expect(adapter.firstAgentDuringAbort?.session).toBe(oldAgent.session)
+    expect(oldAgent.status).toBe('disposed')
+    expect(() => oldService.currentInitiator()).toThrow('agent initiator scope is disposed')
+    expect(ctx.agents).not.toBe(oldService)
+    adapter.agents = ctx.agents
+
+    const newHandle = await ctx.agents.create({
+      sessionId: SessionId('after-restart-session'),
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    const newAgent = newHandle.agent
+    const idle = waitForIdle(ctx, newAgent)
+    send(newAgent, 'continue')
+    await idle
+    expect(adapter.laterAgent?.id).toBe(newAgent.id)
+    expect(adapter.laterAgent?.session).toBe(newAgent.session)
+    await ctx.fiber.dispose()
+  })
+
+  it('keeps ALS readable while root disposal drains sibling AgentLoop fibers', async () => {
+    const ctx = new Context()
+    const adapter = new ReloadAdapter()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(AgentLoop, { agents: [] })
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const service = ctx.agents
+    adapter.agents = service
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('root-dispose-session'),
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    const agent = handle.agent
+    send(agent, 'block')
+    await adapter.firstStarted.promise
+
+    await ctx.fiber.dispose()
+    expect(adapter.firstAgentDuringAbort?.id).toBe(agent.id)
+    expect(adapter.firstAgentDuringAbort?.session).toBe(agent.session)
+    expect(agent.status).toBe('disposed')
+    expect(() => service.currentInitiator()).toThrow('agent initiator scope is disposed')
+  })
+})

packages/core/agent-loop/tests/agent.spec.ts

@@ -1,15 +1,18 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
-import { bindReactLoopAgentContext, prepareReactLoopAgent } from '../src/agent.ts'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from '@deepseek-ai/dsh-agent-loop'
+import { bindReactLoopAgentContext, prepareReactLoopAgent, type ReactLoopAgent } from '../src/agent.ts'
 import { MockAdapter, textResponse } from './mock-adapter.ts'
 
+function driverDone(agent: Agent): Promise<void> {
+  return (agent as Agent & { done: Promise<void> }).done
+}
+
 async function harness(adapter: MockAdapter) {
   const ctx = new Context()
   await ctx.plugin(LlmService)
@@ -22,7 +25,7 @@ async function harness(adapter: MockAdapter) {
   return ctx
 }
 
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') {
@@ -33,7 +36,7 @@ function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
   })
 }
 
-function waitForStatus(ctx: Context, agent: ReactLoopAgent, expected: ReactLoopAgent['status']): Promise<void> {
+function waitForStatus(ctx: Context, agent: Agent, expected: Agent['status']): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === expected) {
@@ -44,19 +47,23 @@ function waitForStatus(ctx: Context, agent: ReactLoopAgent, expected: ReactLoopA
   })
 }
 
-function send(agent: ReactLoopAgent, text: string) {
+function send(agent: Agent, text: string) {
   agent.send([{ type: 'text', text }])
 }
 
-describe('ReactLoopAgent', () => {
+describe('Agent', () => {
   it('rejects access before context binding and a second driver for one session', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create(SessionId('exclusive-driver'))
-    const prepared = prepareReactLoopAgent(ctx, AgentId('first-driver'), { provider: 'mock', model: 'mock' }, session)
+    const prepared = prepareReactLoopAgent(
+      ctx, SessionId('first-driver'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS,
+    )
 
     expect(() => prepared.agent.ctx).toThrow('context is not bound')
-    expect(() => prepareReactLoopAgent(ctx, AgentId('second-driver'), { provider: 'mock', model: 'mock' }, session))
+    expect(() => prepareReactLoopAgent(
+      ctx, SessionId('second-driver'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS,
+    ))
       .toThrow('already has a concrete agent driver')
 
     await prepared.dispose()
@@ -66,12 +73,12 @@ describe('ReactLoopAgent', () => {
   it('borrows caller options and binds its scoped context exactly once', async () => {
     const ctx = await harness(new MockAdapter([textResponse('unused')]))
     const options = { provider: 'mock', model: 'mock' }
-    const agent = ctx.agentLoop.create(AgentId('owned-bindings'), options)
+    const agent = ctx.agentLoop.create(SessionId('owned-bindings'), options)
 
     expect(agent.options).toBe(options)
     expect(agent.id).toBe('owned-bindings')
-    expect(agent.session.id).toMatch(/^owned-bindings-session-/)
-    expect(() => { bindReactLoopAgentContext(agent, new Context()) }).toThrow(/context is already bound/)
+    expect(agent.session.id).toBe(agent.id)
+    expect(() => { bindReactLoopAgentContext(agent as ReactLoopAgent, new Context()) }).toThrow(/context is already bound/)
 
     await ctx.fiber.dispose()
   })
@@ -79,14 +86,14 @@ describe('ReactLoopAgent', () => {
   it('send() throws after disposal', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
     await fiber.dispose()
-    await agent.done
+    await driverDone(agent)
 
     expect(() => { agent.send([{ type: 'text', text: 'too late' }]) }).toThrow('disposed')
   })
@@ -94,14 +101,14 @@ describe('ReactLoopAgent', () => {
   it('steer() throws after disposal', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
     await fiber.dispose()
-    await agent.done
+    await driverDone(agent)
 
     expect(() => { agent.steer([{ type: 'text', text: 'too late' }]) }).toThrow('disposed')
   })
@@ -109,14 +116,14 @@ describe('ReactLoopAgent', () => {
   it('inject() throws after disposal', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
     await fiber.dispose()
-    await agent.done
+    await driverDone(agent)
 
     expect(() => { agent.inject([{ type: 'text', text: 'too late' }]) }).toThrow('disposed')
   })
@@ -124,7 +131,7 @@ describe('ReactLoopAgent', () => {
   it('inject() decides enclosure from the LOG (open turn), not agent status', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // Simulate an OPEN turn in the log while the agent is idle (status is not a
     // reliable open-turn signal). inject must append into that open turn, NOT
@@ -150,7 +157,7 @@ describe('ReactLoopAgent', () => {
     // A persistence-like listener whose flush rejects.
     ctx.on('session/flush', () => { throw new Error('disk gone') })
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // inject() is synchronous and fires a fire-and-forget flush; a rejecting
     // flush must be contained (logged), never thrown into the caller.
@@ -163,12 +170,14 @@ describe('ReactLoopAgent', () => {
   it('idle inject() closes its one-shot turn AND still checkpoints even if the append throws', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     let flushes = 0
     ctx.on('session/flush', () => { flushes += 1 })
 
-    // Invalid injected content throws after turn/start. `finally` must still append turn/end and
-    // flush the balanced in-memory turn so a crash cannot lose it before the next checkpoint.
+    // Non-serializable injected content makes Session.append throw AFTER
+    // turn/start was recorded. The turn/end must still be appended (finally),
+    // AND the durability checkpoint must still fire — the balanced turn is in
+    // memory and a crash before the next turn/dispose would otherwise lose it.
     expect(() => {
       agent.inject([{ type: 'text', text: 'x', bad: 1n } as never], { source: { kind: 'plugin', plugin: 'p' } })
     }).toThrow(/non-JSON-serializable/)
@@ -181,7 +190,7 @@ describe('ReactLoopAgent', () => {
   it('idle inject() still checkpoints when a listener throws on the synthetic turn/end', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     let flushes = 0
     ctx.on('session/flush', () => { flushes += 1 })
     // Session contains a throwing post-commit turn/end observer. The accepted
@@ -204,7 +213,7 @@ describe('ReactLoopAgent', () => {
     // A non-Error rejection exercises the String() normalization branch.
     ctx.on('session/flush', () => { throw 'disk gone' })
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     const errors: { turn: number; step: number; message: string }[] = []
     ctx.on('agent/error', (_a, turn, step, error) => void errors.push({ turn, step, message: error.message }))
 
@@ -223,7 +232,7 @@ describe('ReactLoopAgent', () => {
   it('idle inject() with a non-serializable source opens no turn (nothing to close)', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // A non-serializable source makes the turn/start append throw BEFORE the
     // event is pushed (Session.append validates before push), so NO turn opens.
@@ -238,7 +247,7 @@ describe('ReactLoopAgent', () => {
   it('steer() when idle falls through to send() and starts a turn', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // steer while idle delegates to send
     agent.steer([{ type: 'text', text: 'steer idle' }], { source: { kind: 'plugin', plugin: 'test' } })
@@ -250,20 +259,29 @@ describe('ReactLoopAgent', () => {
   })
 
   it('disposer is idempotent (double-stop)', async () => {
-    // The internal start seam exposes one idle driver's disposer for repeated invocation.
+    // Create a bare Agent and start it through the package-internal
+    // test seam. Then call its disposer twice — the second call hits the
+    // early-return branch.
     const ctx = new Context()
     await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
     const session = ctx.sessions.create(SessionId('test'))
-    const prepared = prepareReactLoopAgent(ctx, AgentId('bare'), { provider: 'mock', model: 'mock' }, session)
+    const prepared = prepareReactLoopAgent(
+      ctx, SessionId('bare'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS,
+    )
     const { agent } = prepared
 
+    // Start the loop to get the disposer; the agent waits for messages
+    // (idle, never-resolving cancel), so it will stay idle.
     prepared.markPublished()
     const dispose = prepared.startDriver()
 
+    // First dispose
     const firstDisposal = dispose()
     expect(agent.status).toBe('disposed')
     await firstDisposal
 
+    // Second dispose — idempotent, no throw
     await expect(dispose()).resolves.toBeUndefined()
     expect(agent.status).toBe('disposed')
   })
@@ -272,7 +290,9 @@ describe('ReactLoopAgent', () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const session = ctx.sessions.create(SessionId('pre-start-dispose'))
-    const prepared = prepareReactLoopAgent(ctx, AgentId('pre-start-dispose'), { provider: 'mock', model: 'mock' }, session)
+    const prepared = prepareReactLoopAgent(
+      ctx, SessionId('pre-start-dispose'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS,
+    )
 
     await prepared.dispose()
     expect(prepared.agent.status).toBe('disposed')
@@ -286,7 +306,7 @@ describe('ReactLoopAgent', () => {
   it('setting the same status does not emit agent/status again', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const statuses: string[] = []
     ctx.on('agent/status', (subject, status) => {
@@ -305,7 +325,7 @@ describe('ReactLoopAgent', () => {
   it('whenIdle() resolves immediately when the agent is not running', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // Fresh agent is idle — whenIdle() takes the not-running fast path and
     // resolves without subscribing. await must not hang.
@@ -316,7 +336,7 @@ describe('ReactLoopAgent', () => {
   it('whenIdle() waits for queued work that has not flipped status yet', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'queued')
     let settled = false
@@ -334,8 +354,8 @@ describe('ReactLoopAgent', () => {
   it('whenIdle() awaits the running→idle transition, ignoring other subjects/running events', async () => {
     const adapter = new MockAdapter([textResponse('ok'), textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
-    const other = ctx.agentLoop.create(AgentId('a2'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const other = ctx.agentLoop.create(SessionId('a2'), { provider: 'mock', model: 'mock' })
 
     // Drive `agent` into `running`, then await whenIdle() — it subscribes to
     // agent/status and resolves on the first transition out of running.
@@ -358,8 +378,10 @@ describe('ReactLoopAgent', () => {
   })
 
   it('whenIdle() subscribed while running resolves via done when the agent is then disposed', async () => {
-    // Queue the internal waiter while running, then dispose the bare driver. Its disposed branch
-    // must chain the loop's `done` promise rather than resolve before exit.
+    // Covers the waiter's disposed arm: whenIdle() queues an internal waiter
+    // while running (not the fast path), then the disposer settles it and chains
+    // `done` (loop exit), not an eager resolve. A bare Agent + direct
+    // internal driver disposer keeps the emit synchronous.
     const ctx = new Context()
     await ctx.plugin(LlmService)
     await ctx.plugin(SessionStore)
@@ -369,7 +391,9 @@ describe('ReactLoopAgent', () => {
     const adapter = new MockAdapter(['hang'])
     ctx.llm.registerAdapter(['mock'], adapter)
     const session = ctx.sessions.create(SessionId('bare'))
-    const prepared = prepareReactLoopAgent(ctx, AgentId('bare'), { provider: 'mock', model: 'mock' }, session)
+    const prepared = prepareReactLoopAgent(
+      ctx, SessionId('bare'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS,
+    )
     const { agent } = prepared
     prepared.markPublished()
     const dispose = prepared.startDriver()
@@ -385,13 +409,15 @@ describe('ReactLoopAgent', () => {
   })
 
   it('whenIdle() subscribed while running survives a FIBER dispose (no hung promise)', async () => {
-    // The waiter is agent-owned state, not an effect-scoped listener that owner disposal would
-    // remove before the disposed transition. Fiber teardown must still settle it.
+    // The waiter is internal agent state, NOT an effect-scoped ctx.on listener:
+    // disposing the OWNING fiber runs the agent's listener disposers, which would
+    // have dropped a ctx.on-based waiter before the 'disposed' transition and
+    // hung the promise. With internal waiters, the fiber disposer still settles it.
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
@@ -404,19 +430,21 @@ describe('ReactLoopAgent', () => {
   })
 
   it('whenIdle() on a disposed agent awaits the loop exit (done), not just the status flip', async () => {
-    // Disposed status is emitted before the driver unwinds. `whenIdle()` must chain `done` so it
-    // resolves only after true loop exit.
+    // The disposer emits agent/status('disposed') BEFORE the driver loop
+    // unwinds, so whenIdle() must chain `done` (true quiescence) on the
+    // disposed path. Dispose a running agent, then assert whenIdle() resolves
+    // only after `done` — i.e. the loop has actually exited.
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
 
     let doneResolved = false
-    void agent.done.then(() => { doneResolved = true })
+    void driverDone(agent).then(() => { doneResolved = true })
     await fiber.dispose() // sets status disposed, aborts, drains the loop
     expect(agent.status).toBe('disposed')
 
@@ -431,7 +459,7 @@ describe('ReactLoopAgent', () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/status', (_subject, status) => {
       if (status === 'running') throw new Error('bad running listener')
     })
@@ -449,7 +477,7 @@ describe('ReactLoopAgent', () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.on('agent/status', (_subject, status) => {
       if (status === 'idle') throw new Error('bad idle listener')
     })

packages/core/agent-loop/tests/cancel.spec.ts

@@ -12,10 +12,14 @@ import { Context } from 'cordis'
 import LlmService, { type Message } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
-import { MockAdapter, textResponse } from './mock-adapter.ts'
+import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
+
+function driverDone(agent: Agent): Promise<void> {
+  return (agent as Agent & { done: Promise<void> }).done
+}
 
 async function harness(adapter: MockAdapter) {
   const ctx = new Context()
@@ -29,12 +33,12 @@ async function harness(adapter: MockAdapter) {
   return ctx
 }
 
-function send(agent: ReactLoopAgent, text: string) {
+function send(agent: Agent, text: string) {
   agent.send([{ type: 'text', text }])
 }
 
 /** Resolve on the agent's next idle transition (event-based, not status poll). */
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') { dispose(); resolve() }
@@ -43,7 +47,7 @@ function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
 }
 
 /** All user-message texts recorded in the log (to assert what actually ran). */
-function userTexts(agent: ReactLoopAgent): string[] {
+function userTexts(agent: Agent): string[] {
   return agent.session.events
     .filter(e => e.type === 'user/message')
     .flatMap(e => e.type === 'user/message' ? e.data.content : [])
@@ -54,7 +58,7 @@ describe('Agent.cancel()', () => {
   it('cancel() on an idle agent with nothing queued is a no-op; the next prompt runs (F2 leak guard)', async () => {
     const adapter = new MockAdapter([textResponse('reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // The loop is parked at the idle wait with nothing queued. A cancel here must
     // NOT arm the marker — otherwise the next legitimate prompt would be dropped.
@@ -71,7 +75,7 @@ describe('Agent.cancel()', () => {
   it('pre-step cancel drops the about-to-start turn (no turn is opened)', async () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // send() queues synchronously (status still idle, loop microtask not yet
     // resumed). Cancel in that pre-step window: the queued turn must not run.
@@ -90,7 +94,7 @@ describe('Agent.cancel()', () => {
   it('a whenIdle() waiter registered BEFORE a pre-step cancel resolves (F1 hang guard)', async () => {
     const adapter = new MockAdapter([textResponse('x')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // This waiter cannot rely on a running→idle transition because cancellation
     // drops the turn before it runs; the skip path must settle it directly.
@@ -109,7 +113,7 @@ describe('Agent.cancel()', () => {
   it('cancel() mid-step aborts the in-flight model call; the turn ends aborted', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -126,7 +130,7 @@ describe('Agent.cancel()', () => {
   it('cancel() with no reason defaults to "cancelled" when aborting an in-flight step', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -139,10 +143,63 @@ describe('Agent.cancel()', () => {
     expect(reasons).toEqual([{ kind: 'aborted', reason: 'cancelled' }])
   })
 
+  it('cancel from an assistant/message observer skips execution but balances replay', async () => {
+    const adapter = new MockAdapter([
+      toolCallResponse('c1', 'danger', {}),
+      textResponse('recovered after cancellation'),
+    ])
+    const ctx = await harness(adapter)
+    let executions = 0
+    ctx.tools.register(defineTool({
+      name: 'danger',
+      description: 'must not run after cancellation',
+      parameters: {},
+      async execute() {
+        executions += 1
+        return [{ type: 'text', text: 'ran' }]
+      },
+    }))
+    const agent = ctx.agentLoop.create(SessionId('cancel-after-assistant-message'), { provider: 'mock', model: 'mock' })
+    const dispose = ctx.on('session/event', (session, event) => {
+      if (session === agent.session && event.type === 'assistant/message') {
+        agent.cancel('cancelled after assistant message')
+      }
+    })
+
+    const reasons: TurnEndReason[] = []
+    ctx.on('session/event', (_session, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+    dispose()
+
+    expect(executions).toBe(0)
+    expect(reasons).toEqual([{ kind: 'aborted', reason: 'cancelled after assistant message' }])
+    const call = agent.session.events.find(event => event.type === 'tool/call')
+    const result = agent.session.events.find(event => event.type === 'tool/result')
+    expect(call?.type === 'tool/call' ? call.data.callId : undefined).toBe('c1')
+    expect(result?.type === 'tool/result' ? result.data : undefined).toMatchObject({
+      callId: 'c1',
+      isError: true,
+      error: { name: 'AbortError', code: 'ABORTED' },
+    })
+
+    send(agent, 'continue safely')
+    await waitForIdle(ctx, agent)
+    const replayedResult = adapter.requests[1]!.messages
+      .flatMap(message => message.content)
+      .find(block => block.type === 'tool-result')
+    expect(replayedResult).toMatchObject({ toolCallId: 'c1', isError: true })
+    expect(reasons).toEqual([
+      { kind: 'aborted', reason: 'cancelled after assistant message' },
+      { kind: 'completed' },
+    ])
+  })
+
   it('a prompt sent AFTER a cancelled turn settles runs normally (marker reset)', async () => {
     const adapter = new MockAdapter(['hang', textResponse('second reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // First turn hangs; cancel it mid-step.
     send(agent, 'first')
@@ -164,7 +221,7 @@ describe('Agent.cancel()', () => {
   it('cancel from inside the agent/session-prefix waterfall drops the step (prefix-composition window)', async () => {
     const adapter = new MockAdapter([textResponse('should not stream')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // Prefix composition runs before the pre-step seam on the instance's first
     // step; a cancel landing inside it must drop the about-to-start step
@@ -198,11 +255,10 @@ describe('Agent.cancel()', () => {
     ctx.llm.registerAdapter(['mock'], adapter)
 
     const handle = await ctx.agents.create({
-      agentId: AgentId('a-dispose-prefix'),
       sessionId: SessionId('dispose-prefix-session'),
       agentOptions: { provider: 'mock', model: 'mock' },
     })
-    const agent = handle.agent as ReactLoopAgent
+    const agent = handle.agent
 
     let disposalDone: Promise<void> | undefined
     let streamed = false
@@ -215,7 +271,7 @@ describe('Agent.cancel()', () => {
     send(agent, 'go')
     await new Promise(resolve => setTimeout(resolve, 0))
     await disposalDone
-    await agent.done
+    await driverDone(agent)
 
     // No step opened, no model call ran, and the turn closed disposed.
     expect(streamed).toBe(false)
@@ -227,7 +283,7 @@ describe('Agent.cancel()', () => {
   it('a cancel-interrupted prefix composition is discarded: the next send recomposes and ships the fresh prefix (stale-cache guard)', async () => {
     const adapter = new MockAdapter([textResponse('reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // The interrupted first composition must not cache its degraded empty value;
     // the next prompt recomposes and logs/sends the fresh prefix.
@@ -257,7 +313,7 @@ describe('Agent.cancel()', () => {
   it('cancel from a synchronous turn/start session-event listener drops the step (step-start window)', async () => {
     const adapter = new MockAdapter([textResponse('should not stream')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // A turn/start listener fires before a step controller exists, so the
     // turn-scoped marker—not step abort—must drop the pending step.
@@ -284,7 +340,7 @@ describe('Agent.cancel()', () => {
   it('cancel from a synchronous step/start session-event listener drops the step (post-step-start window)', async () => {
     const adapter = new MockAdapter([textResponse('should not stream')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // A step/start session-event listener fires AFTER step/start is appended
     // (and after the pre-step seam), so cancelling there lands in the SECOND
@@ -323,11 +379,10 @@ describe('Agent.cancel()', () => {
     ctx.llm.registerAdapter(['mock'], adapter)
 
     const handle = await ctx.agents.create({
-      agentId: AgentId('a-dispose-step-start'),
       sessionId: SessionId('dispose-step-start-session'),
       agentOptions: { provider: 'mock', model: 'mock' },
     })
-    const agent = handle.agent as ReactLoopAgent
+    const agent = handle.agent
 
     let disposalDone: Promise<void> | undefined
     let streamed = false
@@ -338,7 +393,7 @@ describe('Agent.cancel()', () => {
 
     send(agent, 'go')
     await disposalDone
-    await agent.done
+    await driverDone(agent)
 
     expect(streamed).toBe(false)
     expect(adapter.requests).toHaveLength(0)
@@ -355,7 +410,7 @@ describe('Agent.cancel()', () => {
     // `aborted` and run NO second step.
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let steps = 0
     const reasons: TurnEndReason[] = []
@@ -387,7 +442,7 @@ describe('Agent.cancel()', () => {
   it('cancel from a synchronous agent/status(running) listener drops the turn (window 2)', async () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // `agent/status` is synchronous, so cancellation can land after the first
     // pre-step check; the second check must drop the now-empty turn.
@@ -411,7 +466,7 @@ describe('Agent.cancel()', () => {
     // Cancellation must not settle idle while replacement work remains queued.
     const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let replaced = false
     const dispose = ctx.on('agent/status', (subject, status) => {
@@ -438,7 +493,7 @@ describe('Agent.cancel()', () => {
     // prompt B is queued before the loop resumes from the idle wait.
     const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'A')           // queues A (status still idle, loop microtask pending)
     const idle = agent.whenIdle() // registers a waiter (idle + hasQueued → no fast path)
@@ -457,7 +512,7 @@ describe('Agent.cancel()', () => {
   it("cancel clears the turn's steering — it is not re-enqueued as a fresh turn", async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))

packages/core/agent-loop/tests/config-session-id.spec.ts

@@ -7,15 +7,16 @@ import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, textResponse } from './mock-adapter.ts'
 
 const dirs: string[] = []
 afterEach(async () => { for (const d of dirs.splice(0)) await rm(d, { recursive: true, force: true }) })
 
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') { dispose(); resolve() }
@@ -23,7 +24,281 @@ function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
   })
 }
 
+async function makeCoreContext(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  return ctx
+}
+
 describe('config-driven session id', () => {
+  it('rejects an empty exact id before publishing an agent', async () => {
+    const ctx = await makeCoreContext()
+    await expect(ctx.plugin(AgentLoop, {
+      agents: [{ id: 'main', sessionId: SessionId(''), model: 'mock' }],
+    })).rejects.toThrow('expected string length >= 1')
+    expect(ctx.agents.get(SessionId(''))).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('accepts one exact fresh id and rejects it alongside a resume id', async () => {
+    const exact = await makeCoreContext()
+    await exact.plugin(AgentLoop, {
+      agents: [{ id: 'main', sessionId: SessionId('stdio-exact'), model: 'mock' }],
+    })
+    expect(exact.agents.get(SessionId('stdio-exact'))?.session.id).toBe('stdio-exact')
+    await exact.fiber.dispose()
+
+    const conflicting = await makeCoreContext()
+    await expect(conflicting.plugin(AgentLoop, {
+      agents: [{
+        id: 'main',
+        sessionId: SessionId('fresh'),
+        resumeSessionId: SessionId('persisted'),
+        model: 'mock',
+      }],
+    })).rejects.toThrow('sessionId and resumeSessionId are mutually exclusive')
+    await conflicting.fiber.dispose()
+  })
+
+  it('rejects duplicate exact ids before asynchronous configured startup', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-cfg-exact-duplicate-'))
+    dirs.push(root)
+    const ctx = await makeCoreContext()
+    await ctx.plugin(SessionPersistenceJsonl, { root })
+
+    const outcome = await ctx.plugin(AgentLoop, {
+      agents: [
+        { id: 'first', sessionId: SessionId('shared'), model: 'mock' },
+        { id: 'second', sessionId: SessionId('shared'), model: 'mock' },
+      ],
+    }).then(() => undefined, (error: unknown) => error)
+    const published = ctx.agents.get(SessionId('shared'))
+    await ctx.fiber.dispose()
+
+    expect(outcome).toEqual(new Error('agents "first" and "second" use duplicate exact session identity "shared"'))
+    expect(published).toBeUndefined()
+  })
+
+  it('restores a materialized exact id across an AgentLoop-only reload', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-cfg-exact-reload-'))
+    dirs.push(root)
+    const ctx = await makeCoreContext()
+    await ctx.plugin(SessionPersistenceJsonl, { root })
+    ctx.llm.registerAdapter(['mock'], new MockAdapter([textResponse('first'), textResponse('second')]))
+    const config = { agents: [{ id: 'main', sessionId: SessionId('stdio-exact-reload'), model: 'mock' }] }
+
+    const firstLoop = await ctx.plugin(AgentLoop, config)
+    let first: Agent | undefined
+    for (let i = 0; i < 50 && first === undefined; i++) {
+      await new Promise(resolve => setTimeout(resolve, 5))
+      first = ctx.agents.get(SessionId('stdio-exact-reload'))
+    }
+    expect(first).toBeDefined()
+    first!.send([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
+    await waitForIdle(ctx, first!)
+    await firstLoop.dispose()
+
+    const secondLoop = await ctx.plugin(AgentLoop, config)
+    let second: Agent | undefined
+    for (let i = 0; i < 50 && second === undefined; i++) {
+      await new Promise(resolve => setTimeout(resolve, 5))
+      second = ctx.agents.get(SessionId('stdio-exact-reload'))
+    }
+    expect(second).toBeDefined()
+    expect(JSON.stringify(second!.session.deriveMessages())).toContain('remember me')
+    second!.send([{ type: 'text', text: 'continue' }], { source: { kind: 'user' } })
+    await waitForIdle(ctx, second!)
+    await ctx.sessions.flush(second!.session)
+    const loaded = await ctx.sessionPersistence.load(SessionId('stdio-exact-reload'))
+    expect(loaded.events.filter(event => event.type === 'turn/start')).toHaveLength(2)
+
+    await secondLoop.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('waits for a draining exact-id lifecycle during an overlapping reload', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-cfg-exact-overlap-'))
+    dirs.push(root)
+    const ctx = await makeCoreContext()
+    await ctx.plugin(SessionPersistenceJsonl, { root })
+    const sessionId = SessionId('stdio-exact-overlap')
+    const config = { agents: [{ id: 'main', sessionId, model: 'mock' }] }
+    const firstLoop = await ctx.plugin(AgentLoop, config)
+    await expect.poll(() => ctx.agents.get(sessionId)).toBeDefined()
+    const first = ctx.agents.get(sessionId) as Agent
+
+    const flushGate = Promise.withResolvers<undefined>()
+    let flushStarted = false
+    ctx.on('session/flush', (session) => {
+      if (session !== first.session) return
+      flushStarted = true
+      return flushGate.promise
+    })
+    first.inject([{ type: 'text', text: 'persist before replacement' }], {
+      source: { kind: 'plugin', plugin: 'test' },
+    })
+    expect(flushStarted).toBe(true)
+
+    const firstDisposal = firstLoop.dispose()
+    await expect.poll(() => first.status).toBe('disposed')
+    const failures: unknown[] = []
+    ctx.on('agent-loop/config-start-failed', (_id, error) => { failures.push(error) })
+    const secondLoop = await ctx.plugin(AgentLoop, config)
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(ctx.agents.get(sessionId)).toBe(first)
+    expect(failures).toEqual([])
+
+    flushGate.resolve(undefined)
+    await firstDisposal
+    await expect.poll(() => ctx.agents.get(sessionId)).toBeDefined()
+    const second = ctx.agents.get(sessionId) as Agent
+    expect(second).not.toBe(first)
+    expect(JSON.stringify(second.session.deriveMessages())).toContain('persist before replacement')
+    expect(failures).toEqual([])
+
+    await secondLoop.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('cancels an exact-id reload while the prior lifecycle is still draining', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-cfg-exact-cancel-'))
+    dirs.push(root)
+    const ctx = await makeCoreContext()
+    await ctx.plugin(SessionPersistenceJsonl, { root })
+    const sessionId = SessionId('stdio-exact-cancel')
+    const config = { agents: [{ id: 'main', sessionId, model: 'mock' }] }
+    const firstLoop = await ctx.plugin(AgentLoop, config)
+    await expect.poll(() => ctx.agents.get(sessionId)).toBeDefined()
+    const first = ctx.agents.get(sessionId) as Agent
+
+    const flushGate = Promise.withResolvers<undefined>()
+    ctx.on('session/flush', (session) => {
+      if (session === first.session) return flushGate.promise
+    })
+    first.inject([{ type: 'text', text: 'persist before cancellation' }], {
+      source: { kind: 'plugin', plugin: 'test' },
+    })
+
+    const firstDisposal = firstLoop.dispose()
+    await expect.poll(() => first.status).toBe('disposed')
+    const secondLoop = await ctx.plugin(AgentLoop, config)
+    await secondLoop.dispose()
+    expect(ctx.agents.get(sessionId)).toBe(first)
+
+    flushGate.resolve(undefined)
+    await firstDisposal
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('contains an exact-id persistence lookup failure', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-cfg-exact-failure-'))
+    dirs.push(root)
+    const ctx = await makeCoreContext()
+    await ctx.plugin(SessionPersistenceJsonl, { root })
+    const failure = new Error('persistence index failed')
+    const listenerFailure = new Error('failure observer failed')
+    const asyncListenerFailure = new Error('async failure observer failed')
+    const failures: { sessionId: SessionId; error: unknown }[] = []
+    ctx.on('agent-loop/config-start-failed', () => { throw listenerFailure })
+    ctx.on('agent-loop/config-start-failed', () => Promise.reject(asyncListenerFailure) as never)
+    ctx.on('agent-loop/config-start-failed', (sessionId, error) => {
+      failures.push({ sessionId, error })
+    })
+    vi.spyOn(ctx.sessionPersistence, 'list').mockRejectedValue(failure)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+
+    await ctx.plugin(AgentLoop, {
+      agents: [{ id: 'main', sessionId: SessionId('stdio-exact-failure'), model: 'mock' }],
+    })
+
+    await expect.poll(() => warn).toHaveBeenCalledWith(expect.stringContaining(
+      'config-driven restore of "stdio-exact-failure" failed: Error: persistence index failed',
+    ))
+    expect(failures).toEqual([{ sessionId: SessionId('stdio-exact-failure'), error: failure }])
+    expect(warn).toHaveBeenCalledWith(
+      'agent "main": config-start-failed listener threw: Error: failure observer failed',
+    )
+    await expect.poll(() => warn).toHaveBeenCalledWith(
+      'agent "main": config-start-failed listener rejected: Error: async failure observer failed',
+    )
+    expect(ctx.agents.get(SessionId('stdio-exact-failure'))).toBeUndefined()
+    warn.mockRestore()
+    await ctx.fiber.dispose()
+  })
+
+  it('contains startup and observer failures whose string coercion throws', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-cfg-exact-unrenderable-'))
+    dirs.push(root)
+    const ctx = await makeCoreContext()
+    await ctx.plugin(SessionPersistenceJsonl, { root })
+    const unrenderable = {
+      [Symbol.toPrimitive](): never {
+        throw new Error('coercion escaped')
+      },
+    }
+    const failures: unknown[] = []
+    ctx.on('agent-loop/config-start-failed', () => { throw unrenderable })
+    // Deliberately violate the normal Error-only rejection rule to exercise the unknown boundary.
+    // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+    ctx.on('agent-loop/config-start-failed', () => Promise.reject(unrenderable) as never)
+    ctx.on('agent-loop/config-start-failed', (_sessionId, error) => { failures.push(error) })
+    vi.spyOn(ctx.sessionPersistence, 'list').mockRejectedValue(unrenderable)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+
+    await ctx.plugin(AgentLoop, {
+      agents: [{ id: 'main', sessionId: SessionId('stdio-exact-unrenderable'), model: 'mock' }],
+    })
+
+    await expect.poll(() => failures).toEqual([unrenderable])
+    expect(warn).toHaveBeenCalledWith(
+      'agent "main": config-driven restore of "stdio-exact-unrenderable" failed: <unrenderable thrown value>',
+    )
+    expect(warn).toHaveBeenCalledWith(
+      'agent "main": config-start-failed listener threw: <unrenderable thrown value>',
+    )
+    await expect.poll(() => warn).toHaveBeenCalledWith(
+      'agent "main": config-start-failed listener rejected: <unrenderable thrown value>',
+    )
+    await ctx.fiber.dispose()
+  })
+
+  it.each(['resolve', 'reject'] as const)(
+    'joins an exact-id persistence lookup that will %s before AgentLoop disposal completes',
+    async (outcome) => {
+      const root = await mkdtemp(join(tmpdir(), 'dsh-cfg-exact-dispose-'))
+      dirs.push(root)
+      const ctx = await makeCoreContext()
+      await ctx.plugin(SessionPersistenceJsonl, { root })
+      const listing = Promise.withResolvers<Awaited<ReturnType<typeof ctx.sessionPersistence.list>>>()
+      vi.spyOn(ctx.sessionPersistence, 'list').mockReturnValue(listing.promise)
+      const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+      const failures: unknown[] = []
+      ctx.on('agent-loop/config-start-failed', (_sessionId, error) => { failures.push(error) })
+
+      const loop = await ctx.plugin(AgentLoop, {
+        agents: [{ id: 'main', sessionId: SessionId('stdio-exact-dispose'), model: 'mock' }],
+      })
+      let disposed = false
+      const disposal = loop.dispose().then(() => { disposed = true })
+      await Promise.resolve()
+      expect(disposed).toBe(false)
+
+      if (outcome === 'resolve') listing.resolve([])
+      else listing.reject(new Error('startup cancelled by teardown'))
+      await disposal
+      expect(ctx.agents.get(SessionId('stdio-exact-dispose'))).toBeUndefined()
+      expect(failures).toEqual([])
+      expect(warn).not.toHaveBeenCalled()
+      warn.mockRestore()
+      await ctx.fiber.dispose()
+    },
+  )
+
   it('identity-nests the deferred resume fiber under its labeled owner effect', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
@@ -32,7 +307,7 @@ describe('config-driven session id', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
     const loopFiber = await ctx.plugin(AgentLoop, {
-      agents: [{ id: AgentId('main'), provider: 'mock', model: 'mock', resumeSessionId: SessionId('deferred') }],
+      agents: [{ id: SessionId('main'), provider: 'mock', model: 'mock', resumeSessionId: SessionId('deferred') }],
     })
 
     const resumeEffect = loopFiber.getEffects().find(effect => effect.label === 'agentLoop.resume(main)')
@@ -53,11 +328,13 @@ describe('config-driven session id', () => {
     await ctx1.plugin(SystemPrompt)
     await ctx1.plugin(ToolRegistry)
     await ctx1.plugin(AgentRegistry)
-    await ctx1.plugin(AgentLoop, { agents: [{ id: AgentId('cfg'), provider: 'mock', model: 'mock' }] })
+    await ctx1.plugin(AgentLoop, { agents: [{ id: SessionId('cfg'), provider: 'mock', model: 'mock' }] })
     await ctx1.plugin(SessionPersistenceJsonl, { root })
     ctx1.llm.registerAdapter(['mock'], new MockAdapter([textResponse('cfg')]))
-    const a1 = ctx1.agents.get(AgentId('cfg')) as ReactLoopAgent
+    const a1 = ctx1.agents.list()[0] as Agent
+    expect(a1.id).toBe(a1.session.id)
     expect(a1.session.id).toMatch(idPattern)
+    expect(ctx1.agents.get(SessionId('cfg'))).toBeUndefined()
     a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
@@ -70,10 +347,11 @@ describe('config-driven session id', () => {
     await ctx2.plugin(SystemPrompt)
     await ctx2.plugin(ToolRegistry)
     await ctx2.plugin(AgentRegistry)
-    await ctx2.plugin(AgentLoop, { agents: [{ id: AgentId('cfg'), provider: 'mock', model: 'mock' }] })
+    await ctx2.plugin(AgentLoop, { agents: [{ id: SessionId('cfg'), provider: 'mock', model: 'mock' }] })
     await ctx2.plugin(SessionPersistenceJsonl, { root })
     ctx2.llm.registerAdapter(['mock'], new MockAdapter([textResponse('cfg2')]))
-    const a2 = ctx2.agents.get(AgentId('cfg')) as ReactLoopAgent
+    const a2 = ctx2.agents.list()[0] as Agent
+    expect(a2.id).toBe(a2.session.id)
     expect(a2.session.id).toMatch(idPattern)
     expect(a2.session.id).not.toBe(a1.session.id)
     a2.send([{ type: 'text', text: 'q2' }], { source: { kind: 'user' } })
@@ -96,7 +374,7 @@ describe('config-driven session id', () => {
     await ctx1.plugin(AgentLoop, { agents: [] })
     await ctx1.plugin(SessionPersistenceJsonl, { root })
     ctx1.llm.registerAdapter(['mock'], new MockAdapter([textResponse('first')]))
-    const a1 = (await ctx1.agents.create({ agentId: AgentId('main'), sessionId: SessionId('sticky-1') })).agent as ReactLoopAgent
+    const a1 = (await ctx1.agents.create({ sessionId: SessionId('sticky-1') })).agent
     a1.send([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
@@ -109,19 +387,20 @@ describe('config-driven session id', () => {
     await ctx2.plugin(SystemPrompt)
     await ctx2.plugin(ToolRegistry)
     await ctx2.plugin(AgentRegistry)
-    await ctx2.plugin(AgentLoop, { agents: [{ id: AgentId('main'), provider: 'mock', model: 'mock', resumeSessionId: SessionId('sticky-1') }] })
+    await ctx2.plugin(AgentLoop, { agents: [{ id: SessionId('main'), provider: 'mock', model: 'mock', resumeSessionId: SessionId('sticky-1') }] })
     await ctx2.plugin(SessionPersistenceJsonl, { root })
     ctx2.llm.registerAdapter(['mock'], new MockAdapter([textResponse('second')]))
 
     // The deferred resume runs on a microtask after the backend is available.
-    let resumed: ReactLoopAgent | undefined
+    let resumed: Agent | undefined
     for (let i = 0; i < 50 && !resumed; i++) {
       await new Promise(r => setTimeout(r, 5))
-      resumed = ctx2.agents.get(AgentId('main')) as ReactLoopAgent | undefined
+      resumed = ctx2.agents.get(SessionId('sticky-1'))
     }
     expect(resumed).toBeDefined()
     // The live session id IS the resumed id (NOT a fresh ${id}-session-<uuid>),
     // and the prior turn's user message is in the derived history.
+    expect(resumed!.id).toBe(SessionId('sticky-1'))
     expect(resumed!.session.id).toBe('sticky-1')
     const derived = resumed!.session.deriveMessages()
     expect(JSON.stringify(derived)).toContain('remember me')
@@ -137,16 +416,16 @@ describe('config-driven session id', () => {
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
-    await ctx.plugin(AgentLoop, { agents: [{ id: AgentId('main'), provider: 'mock', model: 'mock', resumeSessionId: SessionId('does-not-exist') }] })
+    await ctx.plugin(AgentLoop, { agents: [{ id: SessionId('main'), provider: 'mock', model: 'mock', resumeSessionId: SessionId('does-not-exist') }] })
     const warn = vi.spyOn((ctx.agentLoop as unknown as { ctx: { logger: { warn: (...a: unknown[]) => void } } }).ctx.logger, 'warn')
       .mockImplementation(() => undefined)
     await ctx.plugin(SessionPersistenceJsonl, { root })
     ctx.llm.registerAdapter(['mock'], new MockAdapter([textResponse('x')]))
 
     // The deferred resume fails (no such session on disk). It must be contained:
-    // a warning is logged, no 'main' agent is registered, and the app stays up.
+    // a warning is logged, no agent is registered, and the app stays up.
     await new Promise(r => setTimeout(r, 200))
-    expect(ctx.agents.get(AgentId('main'))).toBeUndefined()
+    expect(ctx.agents.list()).toEqual([])
     expect(warn).toHaveBeenCalledWith(expect.stringContaining('config-driven resume of "does-not-exist" failed'))
     warn.mockRestore()
     await ctx.fiber.dispose()

packages/core/agent-loop/tests/contract-regressions.spec.ts

@@ -4,12 +4,16 @@ import LlmService, { CallId, ContentBlock, MessageSource, StreamChunk } from '@d
 import SessionStore, { Session, SessionEvent, SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineTool, type PostToolDecision } from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId, type ContinuationDecision } from '@deepseek-ai/dsh-agent'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import AgentRegistry, { type Agent, type ContinuationDecision } from '@deepseek-ai/dsh-agent'
+import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from '@deepseek-ai/dsh-agent-loop'
 import { prepareReactLoopAgent } from '../src/agent.ts'
 import * as Invariants from '@deepseek-ai/dsh-invariants'
 import { maxTokensResponse, MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
 
+function driverDone(agent: Agent): Promise<void> {
+  return (agent as Agent & { done: Promise<void> }).done
+}
+
 /** Regression tests for agent-loop boundary, identity, and lifecycle contracts. */
 
 async function harness(adapter: MockAdapter) {
@@ -24,7 +28,7 @@ async function harness(adapter: MockAdapter) {
   return ctx
 }
 
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') {
@@ -35,7 +39,7 @@ function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
   })
 }
 
-function send(agent: ReactLoopAgent, text: string) {
+function send(agent: Agent, text: string) {
   agent.send([{ type: 'text', text }])
 }
 
@@ -55,7 +59,7 @@ describe('session log records what agent/step-result actually produced', () => {
         return [{ type: 'text', text: 'ran' }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // Plugin rewrites the message: replaces the text AND adds a tool call.
     let rewritten = false
@@ -97,7 +101,7 @@ describe('session log records what agent/step-result actually produced', () => {
     response[response.length - 1] = { type: 'finish', reason: { kind: 'stop' }, replayState }
     const adapter = new MockAdapter([response])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('replay-state'), { provider: 'mock', model: 'next-model' })
+    const agent = ctx.agentLoop.create(SessionId('replay-state'), { provider: 'mock', model: 'next-model' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -121,7 +125,7 @@ describe('session log records what agent/step-result actually produced', () => {
       if (block?.type === 'text') block.text = 'mutated'
       return message
     })
-    const agent = ctx.agentLoop.create(AgentId('mutated-replay-state'), { provider: 'mock', model: 'next-model' })
+    const agent = ctx.agentLoop.create(SessionId('mutated-replay-state'), { provider: 'mock', model: 'next-model' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -141,7 +145,7 @@ describe('successful provider completion survives agent/step-result failure', ()
     const adapter = new MockAdapter([response])
     const ctx = await harness(adapter)
     await ctx.plugin(Invariants)
-    const agent = ctx.agentLoop.create(AgentId(id), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId(id), { provider: 'mock', model: 'mock' })
     const failure = new Error(`${id} result processing failed`)
     const reported: Error[] = []
 
@@ -200,7 +204,7 @@ describe('successful provider completion survives agent/step-result failure', ()
 })
 
 describe('abort during tool execution ends the turn', () => {
-  it('aborting the in-flight step inside a tool prevents both remaining tools and the next model step', async () => {
+  it('balances an aborted tool batch through context, steering, and post-step before closing', async () => {
     const adapter = new MockAdapter([
       // model asks for two tool calls in one step
       [
@@ -214,21 +218,29 @@ describe('abort during tool execution ends the turn', () => {
     ])
     const ctx = await harness(adapter)
     const executed: string[] = []
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineTool({
       name: 'aborter',
       description: '',
       parameters: {},
-      async execute() {
+      async execute(_args, exec) {
         executed.push('aborter')
-        // Fire the in-flight step's AbortController directly (the loop registers
-        // it on the agent). This is the bare step-abort path — distinct from
-        // cancel(), which would also clear the inbox; here the subject is the
-        // loop's response to its running step being aborted mid-tool.
+        exec.agent?.steer(
+          [{ type: 'text', text: 'steering before abort' }],
+          { source: { kind: 'plugin', plugin: 'abort-test' } },
+        )
+        // Exercise bare step abort without `cancel()` clearing queued work.
         ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('user interrupt')
         return [{ type: 'text', text: 'done' }]
       },
     }))
+    ctx.on('tools/post-execute', async exec => ({
+      kind: 'accept',
+      additionalContexts: [{
+        content: [{ type: 'text', text: `context for ${exec.callId}` }],
+        source: { kind: 'plugin', plugin: 'abort-test' },
+      }],
+    }))
     ctx.tools.register(defineTool({
       name: 'second',
       description: '',
@@ -240,20 +252,70 @@ describe('abort during tool execution ends the turn', () => {
     }))
 
     const reasons: TurnEndReason[] = []
-    ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
+    const order: string[] = []
+    ctx.on('session/event', (session, event) => {
+      if (session !== agent.session) return
+      switch (event.type) {
+        case 'assistant/message': order.push('assistant/message'); break
+        case 'tool/call': order.push(`tool/call:${event.data.callId}`); break
+        case 'tool/result': {
+          const outcome = event.data.error?.code === 'ABORTED' ? 'synthetic-aborted' : 'real'
+          order.push(`tool/result:${event.data.callId}:${outcome}`)
+          break
+        }
+        case 'context/message': order.push('context/message'); break
+        case 'steering/message': order.push('steering/message'); break
+        case 'step/end': order.push('step/end'); break
+        case 'turn/end': {
+          reasons.push(event.data.reason)
+          order.push(`turn/end:${event.data.reason.kind}`)
+          break
+        }
+      }
+    })
+    let postSteps = 0
+    ctx.on('agent/post-step', (subject, turn, step, signal) => {
+      if (subject !== agent) return
+      postSteps += 1
+      expect({ turn, step, aborted: signal.aborted }).toEqual({ turn: 1, step: 1, aborted: true })
+      order.push('agent/post-step')
+    })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
 
-    expect(executed).toEqual(['aborter'])           // second tool never ran
-    expect(adapter.requests).toHaveLength(1)        // no follow-up model call
+    expect(executed).toEqual(['aborter'])
+    expect(adapter.requests).toHaveLength(1)
+    expect(postSteps).toBe(1)
+    expect(order).toEqual([
+      'assistant/message',
+      'tool/call:c1',
+      'tool/result:c1:real',
+      'tool/call:c2',
+      'tool/result:c2:synthetic-aborted',
+      'context/message',
+      'steering/message',
+      'agent/post-step',
+      'step/end',
+      'turn/end:aborted',
+    ])
     expect(reasons).toEqual([{ kind: 'aborted', reason: 'user interrupt' }])
+    const calls = agent.session.events.filter(event => event.type === 'tool/call')
+    const results = agent.session.events.filter(event => event.type === 'tool/result')
+    expect(calls.map(event => event.data.callId)).toEqual([CallId('c1'), CallId('c2')])
+    expect(results).toHaveLength(2)
+    expect(results[0]!.data).toMatchObject({ callId: CallId('c1'), isError: false })
+    expect(results[1]!.data).toMatchObject({
+      callId: CallId('c2'),
+      isError: true,
+      error: { name: 'AbortError', code: 'ABORTED' },
+    })
   })
 
   it('records context accepted before a tool-step abort in the same turn', async () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'aborter', {})])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-abort-injection'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-abort-injection'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineTool({
       name: 'aborter',
       description: '',
@@ -299,7 +361,7 @@ describe('abort during tool execution ends the turn', () => {
       { type: 'finish', reason: { kind: 'tool-calls' } },
     ] satisfies StreamChunk[]])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-later-abort-context'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-later-abort-context'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineTool({
       name: 'first',
       description: '',
@@ -345,9 +407,9 @@ describe('abort during tool execution ends the turn', () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'waiter', {})])
     const ctx = await harness(adapter)
     const started = Promise.withResolvers<undefined>()
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-dispose-injection'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('a-dispose-injection'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
     ctx.tools.register(defineTool({
       name: 'waiter',
@@ -400,7 +462,7 @@ describe('abort during tool execution ends the turn', () => {
       textResponse('later turn'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-historical-tool-pair'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-historical-tool-pair'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineTool({
       name: 'aborter',
       description: '',
@@ -442,7 +504,7 @@ describe('steering from late extension points is never stranded', () => {
       textResponse('continued because of steering'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let steeredOnce = false
     ctx.on('agent/turn-continuation', async (_agent, _turn, _decision, next) => {
@@ -468,7 +530,7 @@ describe('steering from late extension points is never stranded', () => {
       textResponse('after goal reminder'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let steeredOnce = false
     ctx.on('session/event', (subject, event) => {
@@ -496,7 +558,7 @@ describe('steering from late extension points is never stranded', () => {
   it('steer() from a turn/end session-event listener becomes a queued message for the next turn', async () => {
     const adapter = new MockAdapter([textResponse('turn 1'), textResponse('turn 2')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const turns: number[] = []
     let steeredOnce = false
@@ -522,7 +584,7 @@ describe('steering from late extension points is never stranded', () => {
   it('steering queued during an aborted step is re-delivered, not silently consumed', async () => {
     const adapter = new MockAdapter(['hang', textResponse('recovered')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
@@ -545,7 +607,7 @@ describe('plugin exceptions are contained', () => {
   it('a throwing agent/turn-continuation listener ends the turn with an error, loop survives', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let threwOnce = false
     ctx.on('agent/turn-continuation', async (): Promise<ContinuationDecision> => {
@@ -573,7 +635,7 @@ describe('plugin exceptions are contained', () => {
   it('a rejecting session/flush listener is reported but does not kill the agent', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let rejectedOnce = false
     ctx.on('session/flush', async () => {
@@ -601,9 +663,9 @@ describe('disposed status is part of the agent/status contract', () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
 
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const statuses: string[] = []
@@ -614,7 +676,7 @@ describe('disposed status is part of the agent/status contract', () => {
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
     await fiber.dispose()
-    await agent.done
+    await driverDone(agent)
 
     expect(statuses).toEqual(['running', 'disposed'])
     expect(reasons).toEqual([{ kind: 'disposed' }])
@@ -624,9 +686,9 @@ describe('disposed status is part of the agent/status contract', () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
 
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     ctx.on('agent/status', (_agent, status) => {
@@ -636,10 +698,10 @@ describe('disposed status is part of the agent/status contract', () => {
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
     await fiber.dispose()
-    await agent.done // must not hang
+    await driverDone(agent) // must not hang
 
     expect(agent.status).toBe('disposed')
-    expect(ctx.agents.get(AgentId('scoped'))).toBeUndefined() // unregistered despite the throw
+    expect(ctx.agents.get(SessionId('scoped'))).toBeUndefined() // unregistered despite the throw
   })
 })
 
@@ -658,7 +720,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
   it('an agent without a model fails the step with a clear error (not NO_ADAPTER for "default")', async () => {
     const adapter = new MockAdapter([textResponse('never')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), {}) // no model
+    const agent = ctx.agentLoop.create(SessionId('a1'), {}) // no model
 
     const errors: Error[] = []
     ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error))
@@ -673,7 +735,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
   it('the agent/request waterfall can supply the model for a model-less agent', async () => {
     const adapter = new MockAdapter([textResponse('routed')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), {}) // no model — router plugin decides
+    const agent = ctx.agentLoop.create(SessionId('a1'), {}) // no model — router plugin decides
 
     ctx.on('agent/request', async (_agent, _turn, _step, config, _next) => {
       return { ...config, provider: 'mock', model: 'mock' }
@@ -688,7 +750,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
   it('agent/queued carries the resolved source; steering/message records its source', async () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'noop', {}), textResponse('done')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineTool({
       name: 'noop',
       description: '',
@@ -716,7 +778,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
   it('send() owns content and source before notification and delivery', async () => {
     const adapter = new MockAdapter([textResponse('done')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('owned-send'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('owned-send'), { provider: 'mock', model: 'mock' })
     const content = [{ type: 'text' as const, text: 'accepted-send' }]
     const source = { kind: 'plugin' as const, plugin: 'accepted-source' }
     let notifiedContent: ContentBlock[] | undefined
@@ -752,7 +814,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
   it('running steer() owns content and source before notification and delivery', async () => {
     const adapter = new MockAdapter([toolCallResponse('c1', 'gate', {}), textResponse('done')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('owned-steer'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('owned-steer'), { provider: 'mock', model: 'mock' })
     const entered = Promise.withResolvers<undefined>()
     const release = Promise.withResolvers<undefined>()
     ctx.tools.register(defineTool({
@@ -806,7 +868,7 @@ describe('turn numbering continues across seeded sessions', () => {
   it('a forked agent continues turn numbers after the seed log', async () => {
     const first = new MockAdapter([textResponse('turn one')])
     const ctx = await harness(first)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     send(agent, 'first')
     await waitForIdle(ctx, agent)
 
@@ -822,7 +884,9 @@ describe('turn numbering continues across seeded sessions', () => {
     ctx2.llm.registerAdapter(['mock'], second)
 
     const seeded = ctx2.sessions.create(SessionId('forked'), { seed: [...agent.session.events] })
-    const prepared = prepareReactLoopAgent(ctx2, AgentId('forked-agent'), { provider: 'mock', model: 'mock' }, seeded)
+    const prepared = prepareReactLoopAgent(
+      ctx2, SessionId('forked-agent'), { provider: 'mock', model: 'mock' }, seeded, DEFAULT_MAX_PARALLEL_TOOL_CALLS,
+    )
     const forked = prepared.agent
     prepared.markPublished()
     ctx2.effect(() => prepared.startDriver())
@@ -866,7 +930,7 @@ describe('a finish-error stream chunk ends the turn as error, not completed', ()
     ]
     const adapter = new MockAdapter([errorStream])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-finish-error'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-finish-error'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -891,7 +955,7 @@ describe('a finish-error stream chunk ends the turn as error, not completed', ()
     ]
     const adapter = new MockAdapter([abortedStream])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-finish-aborted'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-finish-aborted'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -909,7 +973,7 @@ describe('a finish-error stream chunk ends the turn as error, not completed', ()
     ]
     const adapter = new MockAdapter([errorStream])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-finish-error-nocode'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-finish-error-nocode'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -925,7 +989,7 @@ describe('step boundary publication order', () => {
   it('the step/start event is in session.events when its session/event listener fires', async () => {
     const adapter = new MockAdapter([textResponse('done')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-step-order'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-step-order'), { provider: 'mock', model: 'mock' })
 
     // Append commits before observers run.
     const observed: { turn: number; step: number; lastEventType: string | undefined; sawStepStart: boolean }[] = []
@@ -965,7 +1029,7 @@ describe('turn and step boundary recovery', () => {
   }
 
   /** Count turn/step boundary events for balance assertions. */
-  function boundaryCounts(agent: ReactLoopAgent) {
+  function boundaryCounts(agent: Agent) {
     const e = [...agent.session.events]
     return {
       turnStart: e.filter(x => x.type === 'turn/start').length,
@@ -980,7 +1044,7 @@ describe('turn and step boundary recovery', () => {
   it('a throwing step/start observer cannot change a successful turn', async () => {
     const adapter = new MockAdapter([textResponse('request completed')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-stepstart'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-stepstart'), { provider: 'mock', model: 'mock' })
 
     // Session owns post-commit containment. The loop sees a successful append,
     // runs the request, and balances the ordinary step and turn boundaries.
@@ -1009,7 +1073,7 @@ describe('turn and step boundary recovery', () => {
   it('a pre-commit step/start validation failure does not invent a step boundary', async () => {
     const adapter = new MockAdapter([textResponse('never reached')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-stepstart-veto'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-stepstart-veto'), { provider: 'mock', model: 'mock' })
     let rejected = false
     ctx.on('internal/dispatch', (_mode, name, args) => {
       if (name !== 'session/event') return
@@ -1040,7 +1104,7 @@ describe('turn and step boundary recovery', () => {
     const errorStream: StreamChunk[] = [{ type: 'finish', reason: { kind: 'error', message: 'provider failed' } }]
     const adapter = new MockAdapter([errorStream])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-turnend-veto'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-turnend-veto'), { provider: 'mock', model: 'mock' })
     let rejected = false
     ctx.on('internal/dispatch', (_mode, name, args) => {
       if (name !== 'session/event') return
@@ -1074,7 +1138,7 @@ describe('turn and step boundary recovery', () => {
   it('a one-shot step/end validation failure keeps the step open until retry succeeds', async () => {
     const adapter = new MockAdapter([textResponse('completed before close validation')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-stepend-veto'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-stepend-veto'), { provider: 'mock', model: 'mock' })
     let rejected = false
     ctx.on('internal/dispatch', (_mode, name, args) => {
       if (name !== 'session/event') return
@@ -1106,7 +1170,7 @@ describe('turn and step boundary recovery', () => {
     const errorStream: StreamChunk[] = [{ type: 'finish', reason: { kind: 'error', message: 'provider 500' } }]
     const adapter = new MockAdapter([errorStream, textResponse('turn 2 ok')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-errorlistener'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-errorlistener'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('agent/error', () => { if (!threw) { threw = true; throw new Error('boom error-listener') } })
@@ -1137,9 +1201,9 @@ describe('turn and step boundary recovery', () => {
     // balanced with reason disposed (no error event for a disposal).
     const adapter = new MockAdapter(['hang'])
     const ctx = await balancedHarness(adapter)
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-dispose'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('a-dispose'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -1148,7 +1212,7 @@ describe('turn and step boundary recovery', () => {
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
     await fiber.dispose() // dispose during the hanging step
-    await agent.done
+    await driverDone(agent)
 
     const e = [...agent.session.events]
     const turnStarts = e.filter(x => x.type === 'turn/start').length
@@ -1164,9 +1228,9 @@ describe('turn and step boundary recovery', () => {
     // Disposal remains authoritative when the listener also throws.
     const adapter = new MockAdapter([textResponse('never reached')])
     const ctx = await balancedHarness(adapter)
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-prestep-dispose-throw'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('a-prestep-dispose-throw'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     let threw = false
@@ -1180,7 +1244,7 @@ describe('turn and step boundary recovery', () => {
     ctx.on('agent/error', (_a, _t, _s, error) => void errorEmits.push(error))
 
     send(agent, 'go')
-    await agent.done
+    await driverDone(agent)
 
     const e = [...agent.session.events]
     // Balanced: one turn/start, one turn/end carrying disposed (NOT error).
@@ -1197,7 +1261,7 @@ describe('turn and step boundary recovery', () => {
   it('a throwing turn/start observer cannot starve the loop or later turns', async () => {
     const adapter = new MockAdapter([textResponse('turn 1'), textResponse('turn 2')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-preturn'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-preturn'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('session/event', (_session, event) => {
@@ -1228,7 +1292,7 @@ describe('turn and step boundary recovery', () => {
   it('a throwing step/end observer cannot rewrite the turn outcome', async () => {
     const adapter = new MockAdapter([textResponse('all good'), textResponse('turn 2 ok')])
     const ctx = await balancedHarness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-stepend-throw'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-stepend-throw'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('session/event', (_s, event) => {
@@ -1267,7 +1331,7 @@ describe('turn and step boundary recovery', () => {
     const errorStream: StreamChunk[] = [{ type: 'finish', reason: { kind: 'error', message: 'provider 500' } }]
     const adapter = new MockAdapter([errorStream, textResponse('turn 2 ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-stependthrow'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-stependthrow'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('session/event', (_s, event) => {
@@ -1297,7 +1361,7 @@ describe('turn and step boundary recovery', () => {
     // boundary stays authoritative and the loop continues normally.
     const adapter = new MockAdapter([textResponse('turn 1'), textResponse('turn 2')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a-turnendappend'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-turnendappend'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('session/event', (_s, event) => {
@@ -1343,7 +1407,7 @@ describe('tool result call identity', () => {
       return Promise.resolve({ kind: 'accept', content: [{ type: 'text', text: 'ok' }] })
     }, { prepend: true })
 
-    const agent = ctx.agentLoop.create(AgentId('a-callid'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-callid'), { provider: 'mock', model: 'mock' })
     send(agent, 'use tool')
     await waitForIdle(ctx, agent)
 
@@ -1374,7 +1438,7 @@ describe('surface: assistant/message records exact empty provenance when no chun
     const adapter = new MockAdapter([[]])
     const ctx = await harness(adapter)
     await ctx.plugin(Invariants)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/step-result', async (_agent, _turn, _step, _message, _next) => ({
       role: 'assistant' as const,
@@ -1419,9 +1483,9 @@ describe('disposal and cancellation during pre-step assembly', () => {
       return next()
     })
 
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-dispose-assemble'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('a-dispose-assemble'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -1436,7 +1500,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
 
     releaseAssemble()
     await disposalDone
-    await agent.done
+    await driverDone(agent)
     unlisten()
 
     // Turn boundaries are durable rows; there is no `agent/*` mirror to assert.
@@ -1469,9 +1533,9 @@ describe('disposal and cancellation during pre-step assembly', () => {
       return next()
     })
 
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-cancel-assemble'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('a-cancel-assemble'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -1484,7 +1548,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
     releaseAssemble()
     await waitForIdle(ctx, agent)
     await fiber.dispose()
-    await agent.done
+    await driverDone(agent)
     unlisten()
 
     const e = [...agent.session.events]
@@ -1523,9 +1587,9 @@ describe('disposal and cancellation during pre-step assembly', () => {
       await blocker
     })
 
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-dispose-prestep'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('a-dispose-prestep'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -1538,7 +1602,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
     const disposalDone = fiber.dispose()
     releasePreStep()
     await disposalDone
-    await agent.done
+    await driverDone(agent)
 
     // After the pre-step seam finishes, the post-seam cancel/dispose check
     // catches disposal. The step was never opened, no LLM call was made.
@@ -1574,9 +1638,9 @@ describe('disposal and cancellation during pre-step assembly', () => {
       await blocker
     })
 
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-cancel-prestep'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('a-cancel-prestep'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -1589,7 +1653,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
     releasePreStep()
     await waitForIdle(ctx, agent)
     await fiber.dispose()
-    await agent.done
+    await driverDone(agent)
 
     const e = [...agent.session.events]
     expect(e.filter(x => x.type === 'turn/start')).toHaveLength(1)
@@ -1624,9 +1688,9 @@ describe('disposal and cancellation during pre-step assembly', () => {
       return next()
     })
 
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('a-dispose-no-leak'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('a-dispose-no-leak'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     send(agent, 'go')
@@ -1635,7 +1699,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
     const disposalDone = fiber.dispose()
     releaseAssemble()
     await disposalDone
-    await agent.done
+    await driverDone(agent)
 
     const e = [...agent.session.events]
     expect(e.filter(x => x.type === 'turn/start')).toHaveLength(1)

packages/core/agent-loop/tests/coverage-edges.spec.ts

@@ -1,14 +1,19 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import LlmService, { CallId, LlmError, StreamChunk } from '@deepseek-ai/dsh-llm'
-import SessionStore, { TurnEndReason } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
 
+function driverDone(agent: Agent): Promise<void> {
+  return (agent as Agent & { done: Promise<void> }).done
+}
+
 async function harness(adapter: MockAdapter) {
   const ctx = new Context()
   await ctx.plugin(LlmService)
@@ -21,7 +26,7 @@ async function harness(adapter: MockAdapter) {
   return ctx
 }
 
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') {
@@ -32,7 +37,7 @@ function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
   })
 }
 
-function send(agent: ReactLoopAgent, text: string) {
+function send(agent: Agent, text: string) {
   agent.send([{ type: 'text', text }])
 }
 
@@ -40,7 +45,7 @@ describe('inbox acceptance', () => {
   it('rejects non-serializable content or source synchronously before notification or enqueue', async () => {
     const adapter = new MockAdapter([textResponse('turn 1')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     let queued = 0
     ctx.on('agent/queued', () => { queued += 1 })
 
@@ -80,7 +85,7 @@ describe('tool JSON parse', () => {
         return [{ type: 'text', text: typeof args === 'string' ? `raw: ${args}` : JSON.stringify(args) }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'use tool')
     await waitForIdle(ctx, agent)
@@ -113,7 +118,7 @@ describe('tool JSON parse', () => {
         return [{ type: 'text', text: 'ran with empty args' }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'use tool')
     await waitForIdle(ctx, agent)
@@ -126,7 +131,7 @@ describe('toError normalization', () => {
   it('normalizes non-Error throws from pre-commit dispatch validation via the runLoop backstop', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let threwOnce = false
     ctx.on('internal/dispatch', (_mode, name, args) => {
@@ -152,7 +157,7 @@ describe('toError normalization', () => {
   it('normalizes non-Error throws from agent/request waterfall via inline toError in runStep catch', async () => {
     const adapter = new MockAdapter([textResponse('irrelevant')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let threwOnce = false
     ctx.on('agent/request', async (_agent, _turn, _step, _options, _next) => {
@@ -180,7 +185,7 @@ describe('coded error data emission', () => {
   it('errorData includes code when a coded error (LlmError) is thrown from a plugin', async () => {
     const adapter = new MockAdapter([textResponse('turn 1')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let threwOnce = false
     ctx.on('agent/request', async (_agent, _turn, _step, _options, next) => {
@@ -212,9 +217,9 @@ describe('disposed vs aborted branching', () => {
   it('handles dispose during model streaming producing reason "disposed"', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
     const reasons: TurnEndReason[] = []
@@ -223,7 +228,7 @@ describe('disposed vs aborted branching', () => {
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
     await fiber.dispose() // dispose during hang
-    await agent.done
+    await driverDone(agent)
 
     // Disposal wins abort classification because the error path checks it first.
     expect(reasons).toContainEqual({ kind: 'disposed' })
@@ -240,7 +245,7 @@ describe('structured tool error propagation (the runtime-validation RFC, part 2)
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineTool({
       name: 'boom',
       description: 'always fails',

packages/core/agent-loop/tests/interception.spec.ts

@@ -1,16 +1,12 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import LlmService, { CallId, type Message } from '@deepseek-ai/dsh-llm'
-import SessionStore, { type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineTool, type PostToolDecision, type PreToolDecision } from '@deepseek-ai/dsh-tools'
-import AgentRegistry, {
-  AgentId,
-  type ContinuationDecision,
-  type PromptDecision,
-  type SessionStartSource,
-} from '@deepseek-ai/dsh-agent'
-import AgentLoop, { type ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import AgentRegistry, { type Agent, type ContinuationDecision, type PromptDecision, type SessionStartSource } from '@deepseek-ai/dsh-agent'
+
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
 
 /**
@@ -34,7 +30,7 @@ async function harness(adapter: MockAdapter) {
   return ctx
 }
 
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') {
@@ -45,11 +41,11 @@ function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
   })
 }
 
-function send(agent: ReactLoopAgent, text: string) {
+function send(agent: Agent, text: string) {
   agent.send([{ type: 'text', text }])
 }
 
-function events(agent: ReactLoopAgent): SessionEvent[] {
+function events(agent: Agent): SessionEvent[] {
   return [...agent.session.events]
 }
 
@@ -57,7 +53,7 @@ describe('agent/prompt-submit', () => {
   it('allow (default via next) records the user/message unchanged', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const seen: string[] = []
     ctx.on('agent/prompt-submit', async (_agent, content, _source, next) => {
@@ -76,7 +72,7 @@ describe('agent/prompt-submit', () => {
   it('allow with content REWRITES the prompt before it is recorded', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/prompt-submit', async (): Promise<PromptDecision> =>
       ({ kind: 'allow', content: [{ type: 'text', text: 'REWRITTEN' }] }))
@@ -94,7 +90,7 @@ describe('agent/prompt-submit', () => {
   it('allow with additionalContexts injects separate context/message events into the turn', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const meta = { kind: 'prompt-context', version: 1 }
     ctx.on('agent/prompt-submit', async (): Promise<PromptDecision> =>
@@ -119,17 +115,14 @@ describe('agent/prompt-submit', () => {
     expect(ctxMsg?.type === 'context/message' && ctxMsg.data.source).toEqual({ kind: 'plugin', plugin: 'test' })
     expect(ctxMsg?.type === 'context/message' && ctxMsg.data.envelope).toBe('raw')
     expect(ctxMsg?.type === 'context/message' && ctxMsg.data.meta).toEqual(meta)
-    // both the prompt and the injected context reach the model
     const sent = JSON.stringify(adapter.requests[0]!.messages)
     expect(sent).toContain('extra ctx')
   })
 
-  it('a prompt-submit rewrite + additionalContexts is VISIBLE to the agent/pre-step seam (merged ordering)', async () => {
-    // Prompt rewrites and injected context land before `agent/pre-step`, so a
-    // compaction listener measures the current surface before the single derive.
+  it('runs pre-step after prompt rewrites and injected context become durable', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/prompt-submit', async (): Promise<PromptDecision> =>
       ({
@@ -138,8 +131,6 @@ describe('agent/prompt-submit', () => {
         additionalContexts: [{ content: [{ type: 'text', text: 'injected ctx' }], source: { kind: 'plugin', plugin: 'test' } }],
       }))
 
-    // The pre-step seam (where compaction lives) derives the surface it would act
-    // on. Capture what it sees on the first step.
     let preStepDerived: string | undefined
     ctx.on('agent/pre-step', (subject, _turn, step) => {
       if (subject === agent && step === 1) preStepDerived = JSON.stringify(subject.session.deriveMessages())
@@ -148,8 +139,6 @@ describe('agent/prompt-submit', () => {
     send(agent, 'ORIGINAL prompt')
     await waitForIdle(ctx, agent)
 
-    // The pre-step seam ran and saw BOTH the rewrite (not the original) and the
-    // injected context — i.e. the prompt-submit effects landed before it.
     expect(preStepDerived).toBeDefined()
     expect(preStepDerived).toContain('REWRITTEN prompt')
     expect(preStepDerived).toContain('injected ctx')
@@ -159,7 +148,7 @@ describe('agent/prompt-submit', () => {
   it('block drops the (only) prompt → zero-step turn ends rejected, model never called', async () => {
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/prompt-submit', async (): Promise<PromptDecision> =>
       ({ kind: 'block', reason: 'blocked by policy' }))
@@ -195,7 +184,7 @@ describe('agent/prompt-submit', () => {
     // the allowed prompt keeps the turn from ending rejected.
     const adapter = new MockAdapter([textResponse('ran once')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/prompt-submit', async (_agent, content, _source, next): Promise<PromptDecision> => {
       const text = content.map(b => (b.type === 'text' ? b.text : '')).join('')
@@ -231,7 +220,7 @@ describe('agent/prompt-submit', () => {
   it('a throwing prompt-submit listener ends the turn balanced (error), loop survives', async () => {
     const adapter = new MockAdapter([textResponse('after')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let threw = false
     ctx.on('agent/prompt-submit', async () => {
@@ -264,7 +253,7 @@ describe('agent/session-start', () => {
     const sources: SessionStartSource[] = []
     ctx.on('agent/session-start', (_agent, source) => void sources.push(source))
 
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     // fires synchronously at create, before any turn
     expect(sources).toEqual(['startup'])
     expect(events(agent).some(e => e.type === 'turn/start')).toBe(false)
@@ -283,7 +272,7 @@ describe('agent/session-start', () => {
       agent.inject([{ type: 'text', text: 'session preamble' }], { source: { kind: 'plugin', plugin: 'test' } })
     })
 
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     send(agent, 'go')
     await waitForIdle(ctx, agent)
 
@@ -301,8 +290,8 @@ describe('agent/session-start', () => {
     ctx.on('agent/session-start', () => { throw new Error('session-start hook broke') })
 
     // create must not throw — the listener error is contained/logged
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
-    expect(agent.id).toBe(AgentId('a1'))
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    expect(agent.id).toBe(SessionId('a1'))
 
     // and the agent still runs
     send(agent, 'go')
@@ -315,8 +304,8 @@ describe('agent/session-prefix', () => {
   it('dispatches to global and matching agent-scope listeners only', async () => {
     const adapter = new MockAdapter([textResponse('a done'), textResponse('b done')])
     const ctx = await harness(adapter)
-    const agentA = ctx.agentLoop.create(AgentId('prefix-a'), { provider: 'mock', model: 'mock' })
-    const agentB = ctx.agentLoop.create(AgentId('prefix-b'), { provider: 'mock', model: 'mock' })
+    const agentA = ctx.agentLoop.create(SessionId('prefix-a'), { provider: 'mock', model: 'mock' })
+    const agentB = ctx.agentLoop.create(SessionId('prefix-b'), { provider: 'mock', model: 'mock' })
     const seen: string[] = []
     ctx.on('agent/session-prefix', async (agent, _prefix, _signal, next) => {
       seen.push(`global:${agent.id}`)
@@ -353,7 +342,7 @@ describe('agent/session-prefix', () => {
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reminder: Message = { role: 'user', content: [{ type: 'text', text: '<system-reminder>catalog</system-reminder>' }] }
     let composed = 0
@@ -383,10 +372,10 @@ describe('agent/session-prefix', () => {
     expect(agent.session.deriveMessages()[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'go' }] })
   })
 
-  it('composes before the first pre-step and hands the prefix to the seam (pressure gates see the real value)', async () => {
+  it('composes before the first pre-step and records the prefix on the request header', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reminder: Message = { role: 'user', content: [{ type: 'text', text: 'opener' }] }
     const order: string[] = []
@@ -394,26 +383,21 @@ describe('agent/session-prefix', () => {
       order.push('compose')
       return [reminder, ...await next()]
     })
-    const seen: (readonly Message[])[] = []
-    ctx.on('agent/pre-step', (_agent, _turn, _step, _system, sessionPrefix) => {
+    ctx.on('agent/pre-step', () => {
       order.push('pre-step')
-      seen.push(sessionPrefix)
     })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
 
-    // Composition precedes the pre-step seam, and the seam receives THIS
-    // instance's composed prefix — a token-pressure gate (compaction) counts
-    // what the request will actually carry, never a stale logged prefix.
     expect(order).toEqual(['compose', 'pre-step'])
-    expect(seen[0]).toEqual([reminder])
+    expect(agent.session.requestHeader()?.messagePrefix).toEqual([reminder])
   })
 
   it('the canonical prepend pattern composes contributions in registration order', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // Both listeners use the canonical `[mine, ...await next()]` prepend: the
     // waterfall unwinds innermost-first (the second listener's array is built
@@ -435,7 +419,7 @@ describe('agent/session-prefix', () => {
   it('with no contributions the header omits messagePrefix and the request is the bare derivation', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // A listener that delegates without contributing — the canonical no-op.
     ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next) => next())
@@ -451,7 +435,7 @@ describe('agent/session-prefix', () => {
   it('the frozen seed rejects in-place mutation — a contribution is a returned extension', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let mutationError: unknown
     ctx.on('agent/session-prefix', async (_agent, prefix, _signal, next): Promise<Message[]> => {
@@ -480,7 +464,7 @@ describe('agent/session-prefix', () => {
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const held: Message = { role: 'user', content: [{ type: 'text', text: 'v1' }] }
     ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise<Message[]> => [...await next(), held])
@@ -501,7 +485,7 @@ describe('agent/turn-continuation (ContinuationDecision)', () => {
   it('a continue decision with a reason records next-step steering in the same turn', async () => {
     const adapter = new MockAdapter([textResponse('step 1 no tools'), textResponse('step 2')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let forced = false
     ctx.on('agent/turn-continuation', async (_agent, _turn, _default, next): Promise<ContinuationDecision> => {
@@ -533,7 +517,7 @@ describe('agent/turn-continuation (ContinuationDecision)', () => {
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/turn-continuation', async (): Promise<ContinuationDecision> => ({ action: 'stop' }))
 
@@ -563,7 +547,7 @@ describe('tool additionalContexts buffering across a step', () => {
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // Each call attaches one context naming itself.
     ctx.on('tools/post-execute', async (exec, _result): Promise<PostToolDecision> =>
@@ -611,7 +595,7 @@ describe('tool additionalContexts buffering across a step', () => {
         return [{ type: 'text', text: 'outer result' }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -638,7 +622,7 @@ describe('tools/pre-execute gate (native-plugin permission pattern, end-to-end t
       name: 'danger', description: 'danger', parameters: {},
       async execute() { ran = true; return [{ type: 'text', text: 'should not run' }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
       if (exec.name === 'danger') return { kind: 'deny', reason: 'blocked dangerous tool' }
@@ -700,7 +684,7 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
       name: 'echo', description: 'echo', parameters: { text: { type: 'string' } },
       async execute(args) { return [{ type: 'text', text: String(args.text) }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'please echo hi')
     await waitForIdle(ctx, agent)
@@ -723,7 +707,7 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
     const adapter = new MockAdapter([textResponse('should not run')])
     const ctx = await harness(adapter)
     await ctx.plugin(NativeGuard)
-    const agent = ctx.agentLoop.create(AgentId('a2'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a2'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event: SessionEvent) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -742,7 +726,7 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
     await fiber.dispose()
 
     // After disposal, a destructive prompt is NOT blocked (the listener is gone).
-    const agent = ctx.agentLoop.create(AgentId('a3'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a3'), { provider: 'mock', model: 'mock' })
     send(agent, 'run rm -rf /')
     await waitForIdle(ctx, agent)
     // the prompt ran (not rejected) — proving the prompt-submit listener was disposed

packages/core/agent-loop/tests/loop.spec.ts

@@ -4,10 +4,15 @@ import LlmService, { CallId, StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, maxTokensResponse, textResponse, toolCallResponse } from './mock-adapter.ts'
 
+function driverDone(agent: Agent): Promise<void> {
+  return (agent as Agent & { done: Promise<void> }).done
+}
+
 async function harness(adapter: MockAdapter, persona = '') {
   const ctx = new Context()
   await ctx.plugin(LlmService)
@@ -25,7 +30,7 @@ async function harness(adapter: MockAdapter, persona = '') {
  * invoke this right after send(), when the loop hasn't woken yet (status is
  * still 'idle' synchronously), so polling the current status would lie.
  */
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') {
@@ -36,7 +41,7 @@ function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
   })
 }
 
-function send(agent: ReactLoopAgent, text: string) {
+function send(agent: Agent, text: string) {
   agent.send([{ type: 'text', text }])
 }
 
@@ -44,7 +49,7 @@ describe('agent loop', () => {
   it('runs a simple turn: queued message → model → idle, with ordered events', async () => {
     const adapter = new MockAdapter([textResponse('hello there')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     // All boundaries — turn and step — are durable session events on the
     // session/event feed (no agent/* mirror). Record them in fire order to
@@ -92,7 +97,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: `echo: ${args.text}` }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'use the tool')
     await waitForIdle(ctx, agent)
@@ -131,7 +136,7 @@ describe('agent loop', () => {
         return { content: [{ type: 'text', text: 'ok' }], meta: { diffs: [{ path: 'a.txt', oldText: null, newText: 'x' }] } }
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'use the tool')
     await waitForIdle(ctx, agent)
@@ -155,7 +160,7 @@ describe('agent loop', () => {
         return []
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
@@ -169,13 +174,12 @@ describe('agent loop', () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter, 'Working in {{cwd}}.')
     const handle = await ctx.agents.create({
-      agentId: AgentId('a-cwd'),
       sessionId: SessionId('s-cwd'),
       meta: { cwd: '/work/space' },
       agentOptions: { provider: 'mock', model: 'mock' },
     })
 
-    const agent = handle.agent as ReactLoopAgent
+    const agent = handle.agent
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
 
@@ -188,7 +192,7 @@ describe('agent loop', () => {
     const ctx = await harness(adapter, 'In {{cwd}}.')
     const errors: Error[] = []
     ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
@@ -230,7 +234,7 @@ describe('agent loop', () => {
     ctx.on('agent/request', async (_agent, _turn, _step, config, _next) => {
       return { ...config, provider: 'mock', model: 'mock' }
     })
-    const agent = ctx.agentLoop.create(AgentId('a-late-model'), {})
+    const agent = ctx.agentLoop.create(SessionId('a-late-model'), {})
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
@@ -256,7 +260,7 @@ describe('agent loop', () => {
       parameters: {},
       execute: () => Promise.resolve({ content: [{ type: 'text' as const, text: 'apparent success' }], meta }),
     }))
-    const agent = ctx.agentLoop.create(AgentId('bad-meta-agent'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('bad-meta-agent'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'use the tool')
     await waitForIdle(ctx, agent)
@@ -285,7 +289,7 @@ describe('agent loop', () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
     ctx.on('system-prompt/assemble', async () => ({ sections: [], tools: [], variables: {} }))
-    const agent = ctx.agentLoop.create(AgentId('a-no-system'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a-no-system'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
@@ -297,7 +301,7 @@ describe('agent loop', () => {
   it('records raw chunks for replay as assistant/chunk session events', async () => {
     const adapter = new MockAdapter([textResponse('abc')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'hi')
     await waitForIdle(ctx, agent)
@@ -321,7 +325,7 @@ describe('agent loop', () => {
     ])
     const ctx = await harness(adapter)
 
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineTool({
       name: 'slow',
       description: '',
@@ -353,7 +357,7 @@ describe('agent loop', () => {
   it('steering while idle behaves like send (starts a turn)', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.steer([{ type: 'text', text: 'hello' }])
     await waitForIdle(ctx, agent)
@@ -363,7 +367,7 @@ describe('agent loop', () => {
   it('inject() while idle wraps context in a one-shot turn, visible to the next request', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     agent.inject([{ type: 'text', text: 'file changed: a.ts' }], { source: { kind: 'plugin', plugin: 'watcher' } })
     // The idle inject records a self-contained turn (turn/start → context/message
@@ -387,7 +391,7 @@ describe('agent loop', () => {
   it('inject() can persist raw structured context without the generic context envelope', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('raw-context'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('raw-context'), { provider: 'mock', model: 'mock' })
     const text = '<system-reminder>Additional instructions from: pkg/AGENTS.md</system-reminder>'
     const meta = {
       kind: 'workspace-instructions',
@@ -416,7 +420,7 @@ describe('agent loop', () => {
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     let visibleDuringTool = false
     const meta = { kind: 'deferred-test', version: 1 }
     ctx.tools.register(defineTool({
@@ -482,7 +486,7 @@ describe('agent loop', () => {
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('invalid-context'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('invalid-context'), { provider: 'mock', model: 'mock' })
     ctx.tools.register(defineTool({
       name: 'invalid-injector',
       description: 'attempts an invalid context injection',
@@ -512,7 +516,7 @@ describe('agent loop', () => {
       textResponse('step 3'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let steps = 0
     ctx.on('session/event', (_session, event) => { if (event.type === 'step/end') steps++ })
@@ -538,7 +542,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: String(args.text) }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/turn-continuation', async () => ({ action: 'stop' }) as const)
 
@@ -553,7 +557,7 @@ describe('agent loop', () => {
   it('agent/request waterfall switches models by returning a replacement config; the switch is logged', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/request', async (_agent, _turn, _step, config, _next) => {
       // The seed is frozen — config is not a mutable per-call knob; a switch
@@ -573,10 +577,6 @@ describe('agent loop', () => {
   })
 
   it('agent/pre-step fires once per step before the step is opened', async () => {
-    // Two steps (a tool call, then a final text turn) → two model calls → two
-    // pre-step fires, each carrying the assembled full system prompt, BEFORE
-    // the step is opened and its request is derived (the request the adapter
-    // sees reflects any surface state at fire time).
     const adapter = new MockAdapter([
       toolCallResponse('c1', 'echo', {}, 'calling echo'),
       textResponse('done'),
@@ -586,23 +586,21 @@ describe('agent loop', () => {
       name: 'echo', description: 'echo', parameters: {},
       async execute() { return [{ type: 'text', text: 'echoed' }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    const fires: { turn: number; step: number; fullSystemPrompt: string }[] = []
-    ctx.on('agent/pre-step', (subject, turn, step, fullSystemPrompt) => {
-      if (subject === agent) fires.push({ turn, step, fullSystemPrompt })
+    const fires: { turn: number; step: number; signal: AbortSignal }[] = []
+    ctx.on('agent/pre-step', (subject, turn, step, signal) => {
+      if (subject === agent) fires.push({ turn, step, signal })
     })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
 
-    // One fire per step, in order, each with the assembled system prompt
-    // (here just the loop's own harness-identity section — no persona set).
-    const HARNESS = 'You are an AI agent powered by the DeepSeek Harness SDK.'
-    expect(fires).toEqual([
-      { turn: 1, step: 1, fullSystemPrompt: HARNESS },
-      { turn: 1, step: 2, fullSystemPrompt: HARNESS },
+    expect(fires.map(({ turn, step }) => ({ turn, step }))).toEqual([
+      { turn: 1, step: 1 },
+      { turn: 1, step: 2 },
     ])
+    expect(fires.every(({ signal }) => signal instanceof AbortSignal)).toBe(true)
   })
 
   it('agent/pre-step fires BEFORE the step it precedes opens (events land outside the step)', async () => {
@@ -610,7 +608,7 @@ describe('agent loop', () => {
     // same step's request must include it.
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let injected = false
     ctx.on('agent/pre-step', (subject) => {
@@ -644,7 +642,7 @@ describe('agent loop', () => {
     // closing, the turn records error, and the loop remains available.
     const adapter = new MockAdapter([textResponse('second turn ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let throwOnce = true
     ctx.on('agent/pre-step', () => {
@@ -678,7 +676,7 @@ describe('agent loop', () => {
   it('cancel() mid-stream ends the turn with reason aborted', async () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -698,7 +696,7 @@ describe('agent loop', () => {
     // turn stops by default and ends max-tokens, not completed.
     const adapter = new MockAdapter([maxTokensResponse('truncat')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -721,7 +719,7 @@ describe('agent loop', () => {
       textResponse('second half'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let steps = 0
     ctx.on('session/event', (_session, event) => { if (event.type === 'step/end') steps++ })
@@ -752,7 +750,7 @@ describe('agent loop', () => {
     // stop. The per-turn reason must be independent — turn 2 ends completed.
     const adapter = new MockAdapter([maxTokensResponse('cut'), textResponse('clean')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -785,7 +783,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: 'should not run' }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -822,7 +820,7 @@ describe('agent loop', () => {
       parameters: { text: { type: 'string' } },
       async execute() { return [{ type: 'text', text: 'should not run' }] },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -847,7 +845,7 @@ describe('agent loop', () => {
     // a durable successful-call boundary for replay consumers.
     const adapter = new MockAdapter([[{ type: 'finish', reason: { kind: 'stop' } }]])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const reasons: TurnEndReason[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
@@ -884,7 +882,7 @@ describe('agent loop', () => {
       expect(message.content).toEqual([{ type: 'text', text: 'partial text' }])
       return next()
     })
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -911,7 +909,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: String(args.text) }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     let threw = false
     // Post-commit session observers cannot control the loop. The tool call still
     // drives the second model request, and the turn completes normally.
@@ -930,7 +928,7 @@ describe('agent loop', () => {
   it('chains queued messages into consecutive turns', async () => {
     const adapter = new MockAdapter([textResponse('first'), textResponse('second')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const turns: number[] = []
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/start') turns.push(event.data.turn) })
@@ -955,7 +953,7 @@ describe('agent loop', () => {
   it('awaits session/flush at turn end (persistence checkpoint)', async () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let flushed = 0
     let flushedBeforeIdle = false
@@ -975,7 +973,7 @@ describe('agent loop', () => {
   it('errors from the model surface as agent/error and end the turn', async () => {
     const adapter = new MockAdapter([]) // script exhausted → throws
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const errors: Error[] = []
     const reasons: TurnEndReason[] = []
@@ -998,21 +996,21 @@ describe('agent loop', () => {
     const adapter = new MockAdapter(['hang'])
     const ctx = await harness(adapter)
 
-    let agent!: ReactLoopAgent
+    let agent!: Agent
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      agent = inner.agentLoop.create(AgentId('scoped'), { provider: 'mock', model: 'mock' })
+      agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
-    expect(ctx.agents.get(AgentId('scoped'))).toBe(agent)
+    expect(ctx.agents.get(SessionId('scoped'))).toBe(agent)
     send(agent, 'go')
     await new Promise(r => setTimeout(r, 30))
     expect(agent.status).toBe('running')
 
     await fiber.dispose()
-    await agent.done
+    await driverDone(agent)
 
     expect(agent.status).toBe('disposed')
-    expect(ctx.agents.get(AgentId('scoped'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('scoped'))).toBeUndefined()
     expect(() => { send(agent, 'too late') }).toThrow('disposed')
   })
 
@@ -1025,13 +1023,14 @@ describe('agent loop', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(AgentLoop, {
-      agents: [{ id: AgentId('config-agent'), provider: 'mock', model: 'mock' }],
+      agents: [{ id: SessionId('config-agent'), provider: 'mock', model: 'mock' }],
     })
     ctx.llm.registerAdapter(['mock'], adapter)
 
-    const agent = ctx.agents.get(AgentId('config-agent'))! as ReactLoopAgent
+    const agent = ctx.agents.list()[0]!
     expect(agent).toBeDefined()
-    expect(agent.id).toBe('config-agent')
+    expect(agent.id).toBe(agent.session.id)
+    expect(agent.id).toMatch(/^config-agent-session-/)
     expect(agent.options.model).toBe('mock')
 
     // the agent is alive: send triggers a turn
@@ -1048,10 +1047,10 @@ describe('agent loop', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(AgentLoop, {
-      agents: [{ id: AgentId('config-agent'), provider: 'mock', model: 'mock', cwd: '/work/project' }],
+      agents: [{ id: SessionId('config-agent'), provider: 'mock', model: 'mock', cwd: '/work/project' }],
     })
 
-    const agent = ctx.agents.get(AgentId('config-agent'))! as ReactLoopAgent
+    const agent = ctx.agents.list()[0]!
     expect(agent.session.header.cwd).toBe('/work/project')
   })
 
@@ -1069,7 +1068,7 @@ describe('agent loop', () => {
         return [{ type: 'text', text: String(args.text) }]
       },
     }))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     send(agent, 'run')
     await waitForIdle(ctx, agent)
 

packages/core/agent-loop/tests/properties.spec.ts

@@ -1,7 +1,12 @@
 /**
- * Deterministic property tests for inbox scheduling: every sent message logs
- * once, turn numbers increase, and status follows idle→running→idle/disposed.
- * Schedules advance on status events rather than wall-clock sleeps.
+ * Property-based tests for the agent loop's inbox/turn scheduling (the
+ * property-testing RFC). Deterministic by construction: schedules are driven
+ * through the `agent/status` settle signal (no wall-clock sleeps), so a flake
+ * is a finding, not timing noise.
+ *
+ * Invariants: every sent message appears exactly once in the log (none lost);
+ * turn numbers strictly increase; status transitions follow the legal machine
+ * idle→running→idle (and →disposed at teardown).
  */
 
 import { describe, expect, it } from 'vitest'
@@ -9,11 +14,12 @@ import { Context } from 'cordis'
 import LlmService from '@deepseek-ai/dsh-llm'
 import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { LlmAdapter } from '@deepseek-ai/dsh-llm'
-import SessionStore from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
-import AgentLoop, { type ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import fc from 'fast-check'
 
 /** A never-exhausting adapter: every model call returns the same short reply. */
@@ -42,7 +48,7 @@ async function harness() {
 }
 
 /** Resolve on the agent's next transition to idle (event-based, not polled). */
-function nextIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function nextIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') {
@@ -55,7 +61,7 @@ function nextIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
 
 /** Record every status transition for the legal-machine assertion. Returns
  * the seen list plus a disposer for the listener (per the registry convention). */
-function recordStatus(ctx: Context, agent: ReactLoopAgent): { seen: string[]; dispose: () => void } {
+function recordStatus(ctx: Context, agent: Agent): { seen: string[]; dispose: () => void } {
   const seen: string[] = []
   const dispose = ctx.on('agent/status', (subject, status) => {
     if (subject === agent) seen.push(status)
@@ -63,13 +69,13 @@ function recordStatus(ctx: Context, agent: ReactLoopAgent): { seen: string[]; di
   return { seen, dispose }
 }
 
-function userMessageTexts(agent: ReactLoopAgent): string[] {
+function userMessageTexts(agent: Agent): string[] {
   return agent.session.events
     .filter(e => e.type === 'user/message')
     .map(e => (e.data as { content: { type: string; text?: string }[] }).content.map(b => b.text ?? '').join(''))
 }
 
-function turnNumbers(agent: ReactLoopAgent): number[] {
+function turnNumbers(agent: Agent): number[] {
   return agent.session.events
     .filter(e => e.type === 'turn/start')
     .map(e => (e.data as { turn: number }).turn)
@@ -90,7 +96,7 @@ describe('agent loop scheduling properties', () => {
       async (texts) => {
         const ctx = await harness()
         try {
-          const agent = ctx.agentLoop.create(AgentId('a'), { provider: 'mock', model: 'mock' })
+          const agent = ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
           const { seen: trace } = recordStatus(ctx, agent)
           const idle = nextIdle(ctx, agent)
           // Send all in one synchronous tick: they queue before the loop wakes.
@@ -115,7 +121,7 @@ describe('agent loop scheduling properties', () => {
       async (texts) => {
         const ctx = await harness()
         try {
-          const agent = ctx.agentLoop.create(AgentId('a'), { provider: 'mock', model: 'mock' })
+          const agent = ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
           for (const text of texts) {
             const idle = nextIdle(ctx, agent)
             agent.send([{ type: 'text', text }])
@@ -140,7 +146,7 @@ describe('agent loop scheduling properties', () => {
       async (steps) => {
         const ctx = await harness()
         try {
-          const agent = ctx.agentLoop.create(AgentId('a'), { provider: 'mock', model: 'mock' })
+          const agent = ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
           // Capture before each send; the last waiter covers the final turn, and
           // awaiting an already-settled earlier waiter is harmless.
           let lastIdle: Promise<void> | undefined

packages/core/agent-loop/tests/request-cache.e2e.ts

@@ -1,10 +1,11 @@
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import LlmService from '@deepseek-ai/dsh-llm'
-import SessionStore from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId, type Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 
@@ -69,7 +70,7 @@ function waitForIdle(context: Context, agent: Agent): Promise<void> {
 describe.skipIf(!process.env.DEEPSEEK_API_KEY)('log-derived request cache hits (real API)', () => {
   it('every request after the first hits the provider prefix cache', async () => {
     ctx = await loopHarness()
-    const agent = ctx.agentLoop.create(AgentId('cache-e2e'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
+    const agent = ctx.agentLoop.create(SessionId('cache-e2e'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
     // Turn 1: forces a tool call → at least two steps (two model requests).
     agent.send([{ type: 'text', text: 'Look up the key "deploy-color" with the lookup tool and tell me the value.' }])

packages/core/agent-loop/tests/request-reconstruction.spec.ts

@@ -12,8 +12,9 @@ import type { GenerateOptions } from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionId, foldRequestHeader } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
 
 async function harness(adapter: MockAdapter, persona = 'stable base') {
@@ -28,7 +29,7 @@ async function harness(adapter: MockAdapter, persona = 'stable base') {
   return ctx
 }
 
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') {
@@ -39,7 +40,7 @@ function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
   })
 }
 
-function send(agent: ReactLoopAgent, text: string) {
+function send(agent: Agent, text: string) {
   agent.send([{ type: 'text', text }])
 }
 
@@ -71,7 +72,7 @@ describe('request stability across the loop', () => {
     ])
     const ctx = await harness(adapter)
     registerEcho(ctx)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)
@@ -92,7 +93,7 @@ describe('request stability across the loop', () => {
   it('a later turn append-extends the previous turn (one conversation, one log)', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'first')
     await waitForIdle(ctx, agent)
@@ -106,7 +107,7 @@ describe('request stability across the loop', () => {
   it('a compaction replace rewrites the resend, and the log explains it', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'first')
     await waitForIdle(ctx, agent)
@@ -139,7 +140,7 @@ describe('request stability across the loop', () => {
   it('a real system-prompt change is a full changed-header snapshot; a stable prompt logs nothing', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two'), textResponse('three')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'first')
     await waitForIdle(ctx, agent)
@@ -163,7 +164,7 @@ describe('request stability across the loop', () => {
   it('an inject() during the agent/request waterfall joins the NEXT request (the step/start boundary)', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let injected = false
     ctx.on('agent/request', async (_agent, _turn, _step, _config, next) => {
@@ -191,7 +192,7 @@ describe('request stability across the loop', () => {
   it('a mutation attempt on the frozen request content throws into the step (loud, not silent)', async () => {
     const adapter = new MockAdapter([textResponse('one')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const errors: Error[] = []
     ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error))
@@ -212,7 +213,7 @@ describe('request stability across the loop', () => {
   it('a fresh loop instance over a seeded log anchors with a resume snapshot and stays cache-aligned', async () => {
     const adapter = new MockAdapter([textResponse('one')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('gen1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('gen1'), { provider: 'mock', model: 'mock' })
     send(agent, 'first')
     await waitForIdle(ctx, agent)
 
@@ -221,12 +222,11 @@ describe('request stability across the loop', () => {
     const adapter2 = new MockAdapter([textResponse('two')])
     const ctx2 = await harness(adapter2)
     const handle = await ctx2.agents.create({
-      agentId: AgentId('gen2'),
       sessionId: SessionId('gen2-session'),
       seed: [...agent.session.events],
       agentOptions: { provider: 'mock', model: 'mock' },
     })
-    const agent2 = handle.agent as ReactLoopAgent
+    const agent2 = handle.agent
     send(agent2, 'second')
     await waitForIdle(ctx2, agent2)
 
@@ -241,7 +241,7 @@ describe('request stability across the loop', () => {
   it('a delegating listener cannot mutate the seed through next() — the fold stays log-true', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     ctx.on('agent/request', async (_agent, _turn, _step, _config, next) => {
       const config = await next()
@@ -275,7 +275,7 @@ describe('request stability across the loop', () => {
     ])
     const ctx = await harness(adapter)
     registerEcho(ctx)
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     send(agent, 'go')
     await waitForIdle(ctx, agent)

packages/core/agent-loop/tests/request-recovery.spec.ts

@@ -0,0 +1,516 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import LlmService, {
+  CallId,
+  CONTEXT_WINDOW_EXCEEDED_CODE,
+  LlmAdapter,
+  LlmError,
+} from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import type { PostToolDecision } from '@deepseek-ai/dsh-tools'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { maxTokensResponse, textResponse, toolCallResponse } from './mock-adapter.ts'
+
+class FailureScriptAdapter extends LlmAdapter {
+  requests: GenerateOptions[] = []
+
+  constructor(private readonly entries: (Error | StreamChunk[])[]) {
+    super()
+  }
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    this.requests.push(options)
+    const entry = this.entries.shift()
+    if (entry === undefined) throw new Error('failure script exhausted')
+    if (entry instanceof Error) throw entry
+    yield* entry
+  }
+}
+
+class IteratorConstructionFailureAdapter extends LlmAdapter {
+  stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
+    return {
+      [Symbol.asyncIterator](): AsyncIterator<StreamChunk> {
+        throw new LlmError('iterator construction failed', 'ITERATOR_CONSTRUCTION')
+      },
+    }
+  }
+}
+
+class SynchronousDispatchFailureAdapter extends LlmAdapter {
+  constructor(private readonly error: Error) {
+    super()
+  }
+
+  stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
+    throw this.error
+  }
+}
+
+class IteratorResultGetterFailureAdapter extends LlmAdapter {
+  constructor(
+    private readonly field: 'done' | 'value',
+    private readonly error: Error,
+  ) {
+    super()
+  }
+
+  stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const result = this.field === 'done' ? {} : { done: false }
+    Object.defineProperty(result, this.field, { get: () => { throw this.error } })
+    return {
+      [Symbol.asyncIterator](): AsyncIterator<StreamChunk> {
+        return { next: () => Promise.resolve(result as unknown as IteratorResult<StreamChunk>) }
+      },
+    }
+  }
+}
+
+const streamListenerFailureCases: readonly [string, (ctx: Context) => void][] = [
+  ['synchronous listener throw', (ctx) => {
+    ctx.on('llm/stream', () => { throw new Error('synchronous stream listener failed') })
+  }],
+  ['invalid listener iterable', (ctx) => {
+    ctx.on('llm/stream', () => ({}) as AsyncIterable<StreamChunk>)
+  }],
+  ['listener wrapper iteration failure', (ctx) => {
+    ctx.on('llm/stream', (_options, next) => (async function * () {
+      for await (const chunk of next()) {
+        yield chunk
+        throw new Error('stream listener wrapper failed')
+      }
+    })())
+  }],
+]
+
+async function harness(adapter?: LlmAdapter): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  if (adapter) ctx.llm.registerAdapter(['mock'], adapter)
+  return ctx
+}
+
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'idle') {
+        dispose()
+        resolve()
+      }
+    })
+  })
+}
+
+function send(agent: Agent): void {
+  agent.send([{ type: 'text', text: 'go' }])
+}
+
+function contextError(message = 'context too large'): LlmError {
+  return new LlmError(message, CONTEXT_WINDOW_EXCEEDED_CODE)
+}
+
+describe('agent post-step and request-error lifecycle', () => {
+  it('fires post-step after results, buffered context, and steering but before step/end', async () => {
+    const twoCalls: StreamChunk[] = [
+      { type: 'block-start', index: 0, blockType: 'tool-call' },
+      { type: 'block-end', index: 0, block: { type: 'tool-call', id: CallId('call-1'), name: 'work', arguments: '{}' } },
+      { type: 'block-start', index: 1, blockType: 'tool-call' },
+      { type: 'block-end', index: 1, block: { type: 'tool-call', id: CallId('call-2'), name: 'work', arguments: '{}' } },
+      { type: 'usage', usage: { inputTokens: 10, outputTokens: 5 } },
+      { type: 'finish', reason: { kind: 'tool-calls' } },
+    ]
+    const adapter = new FailureScriptAdapter([twoCalls, textResponse('done')])
+    const ctx = await harness(adapter)
+    ctx.tools.register(defineTool({
+      name: 'work',
+      description: 'do work',
+      parameters: {},
+      async execute(_args, exec) {
+        if (exec.callId === CallId('call-2')) {
+          exec.agent?.steer([{ type: 'text', text: 'steered' }], { source: { kind: 'plugin', plugin: 'test' } })
+        }
+        return [{ type: 'text', text: 'worked' }]
+      },
+    }))
+    ctx.on('tools/post-execute', async (exec, _result): Promise<PostToolDecision> => ({
+      kind: 'accept',
+      additionalContexts: [{
+        content: [{ type: 'text', text: `context for ${exec.callId}` }],
+        source: { kind: 'plugin', plugin: 'test' },
+      }],
+    }))
+    const agent = ctx.agentLoop.create(SessionId('post-step-order'), { provider: 'mock', model: 'mock' })
+    const order: string[] = []
+    ctx.on('session/event', (_session, event) => {
+      if (
+        event.type === 'assistant/message' || event.type === 'tool/call'
+        || event.type === 'tool/result' || event.type === 'context/message'
+        || event.type === 'steering/message' || event.type === 'step/end'
+      ) {
+        if (!('step' in event.data) || event.data.step === 1) order.push(event.type)
+      }
+    })
+    ctx.on('agent/post-step', (subject, turn, step, signal) => {
+      if (subject !== agent || step !== 1) return
+      expect({ turn, step, aborted: signal.aborted }).toEqual({ turn: 1, step: 1, aborted: false })
+      subject.inject([{ type: 'text', text: 'listener mutation' }], { source: { kind: 'plugin', plugin: 'post-step' } })
+      order.push('agent/post-step')
+    })
+
+    send(agent)
+    await waitForIdle(ctx, agent)
+
+    expect(order).toEqual([
+      'assistant/message',
+      'tool/call',
+      'tool/result',
+      'tool/call',
+      'tool/result',
+      'context/message',
+      'context/message',
+      'steering/message',
+      'context/message',
+      'agent/post-step',
+      'step/end',
+    ])
+  })
+
+  it('fires post-step for max-tokens and lets cancellation override that success', async () => {
+    const adapter = new FailureScriptAdapter([maxTokensResponse('partial')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('cancel-post-step-max-tokens'), { provider: 'mock', model: 'mock' })
+    let entered!: () => void
+    const postStepEntered = new Promise<void>((resolve) => { entered = resolve })
+    ctx.on('agent/post-step', async (_agent, turn, step, signal) => {
+      expect({ turn, step }).toEqual({ turn: 1, step: 1 })
+      entered()
+      await new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => { resolve() }, { once: true })
+      })
+    })
+
+    send(agent)
+    const idle = waitForIdle(ctx, agent)
+    await postStepEntered
+    agent.cancel('cancelled during max-tokens post-step')
+    await idle
+
+    expect(agent.session.events.find(event => event.type === 'assistant/message')).toMatchObject({
+      data: { usage: { inputTokens: 10, outputTokens: 7 } },
+    })
+    expect(agent.session.events.at(-1)).toMatchObject({
+      type: 'turn/end',
+      data: { reason: { kind: 'aborted', reason: 'cancelled during max-tokens post-step' } },
+    })
+  })
+
+  it('closes the successful step as disposed when disposal lands during post-step', async () => {
+    const adapter = new FailureScriptAdapter([
+      toolCallResponse('dispose-call', 'work', {}),
+      textResponse('must not continue'),
+    ])
+    const ctx = await harness(adapter)
+    ctx.tools.register(defineTool({
+      name: 'work',
+      description: 'do work',
+      parameters: {},
+      async execute() { return [{ type: 'text', text: 'worked' }] },
+    }))
+    const agent = ctx.agentLoop.create(SessionId('dispose-post-step'), { provider: 'mock', model: 'mock' })
+    let entered!: () => void
+    const postStepEntered = new Promise<void>((resolve) => { entered = resolve })
+    ctx.on('agent/post-step', async (_agent, turn, step, signal) => {
+      expect({ turn, step }).toEqual({ turn: 1, step: 1 })
+      entered()
+      await new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => { resolve() }, { once: true })
+      })
+    })
+
+    send(agent)
+    await postStepEntered
+    await ctx.fiber.dispose()
+
+    expect(adapter.requests).toHaveLength(1)
+    const boundaries = agent.session.events.filter(event =>
+      event.type === 'step/start' || event.type === 'step/end',
+    )
+    expect(boundaries.map(event => event.type)).toEqual(['step/start', 'step/end'])
+    expect(boundaries.map(event => event.data)).toEqual([
+      { turn: 1, step: 1 },
+      { turn: 1, step: 1 },
+    ])
+    expect(agent.session.events.at(-1)).toMatchObject({
+      type: 'turn/end',
+      data: { reason: { kind: 'disposed' } },
+    })
+  })
+
+  it.each([
+    ['thrown', contextError()],
+    ['in-band', [{ type: 'finish', reason: { kind: 'error', message: 'too large', code: CONTEXT_WINDOW_EXCEEDED_CODE } }] satisfies StreamChunk[]],
+  ] as const)('recovers a %s request failure in a new reconstructable step', async (_style, failure) => {
+    const adapter = new FailureScriptAdapter([failure, textResponse('recovered')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId(`recover-${_style}`), { provider: 'mock', model: 'mock' })
+    const attempts: number[] = []
+    ctx.on('agent/request-error', async (subject, turn, step, error, attempt) => {
+      expect(subject).toBe(agent)
+      expect({ turn, step, code: error.code }).toEqual({ turn: 1, step: 1, code: CONTEXT_WINDOW_EXCEEDED_CODE })
+      attempts.push(attempt)
+      subject.session.append('context/message', {
+        content: [{ type: 'text', text: 'RECOVERY SURFACE MUTATION' }],
+        source: { kind: 'plugin', plugin: 'test-recovery' },
+      }, { surfaceOp: 'append' })
+      return { action: 'retry' }
+    })
+
+    send(agent)
+    await waitForIdle(ctx, agent)
+
+    expect(attempts).toEqual([0])
+    expect(adapter.requests).toHaveLength(2)
+    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('RECOVERY SURFACE MUTATION')
+    const starts = agent.session.events.filter(event => event.type === 'step/start')
+    const ends = agent.session.events.filter(event => event.type === 'step/end')
+    expect(starts.map(event => event.data.step)).toEqual([1, 2])
+    expect(ends.map(event => event.data.step)).toEqual([1, 2])
+    const recovery = agent.session.events.find(event => event.type === 'context/message')!
+    expect(ends[0]!.seq).toBeLessThan(recovery.seq)
+    expect(recovery.seq).toBeLessThan(starts[1]!.seq)
+  })
+
+  it.each(streamListenerFailureCases)('does not offer %s to request recovery', async (_name, install) => {
+    const ctx = await harness(new FailureScriptAdapter([textResponse('unused')]))
+    const agent = ctx.agentLoop.create(SessionId(`stream-plugin-${_name.replaceAll(' ', '-')}`), { provider: 'mock', model: 'mock' })
+    let recoveries = 0
+    install(ctx)
+    ctx.on('agent/request-error', async (_agent, _turn, _step, _error, _attempt, _signal, next) => {
+      recoveries += 1
+      return next()
+    })
+
+    send(agent)
+    await waitForIdle(ctx, agent)
+
+    expect(recoveries).toBe(0)
+    expect(agent.session.events.at(-1)).toMatchObject({ type: 'turn/end', data: { reason: { kind: 'error' } } })
+  })
+
+  it('does not offer a nested model-call failure as the outer request failure', async () => {
+    const outer = new FailureScriptAdapter([textResponse('outer adapter must not run')])
+    const nested = new FailureScriptAdapter([contextError('nested overflow')])
+    const ctx = await harness(outer)
+    ctx.llm.registerAdapter(['nested'], nested)
+    ctx.on('llm/stream', (options, next) => {
+      if (options.provider !== 'mock') return next()
+      return (async function* () {
+        yield* ctx.llm.stream({
+          provider: 'nested',
+          model: 'nested',
+          messages: [],
+          ...options.signal === undefined ? {} : { signal: options.signal },
+        })
+        yield* next()
+      })()
+    })
+    const agent = ctx.agentLoop.create(SessionId('nested-stream-not-recoverable'), { provider: 'mock', model: 'mock' })
+    let recoveries = 0
+    ctx.on('agent/request-error', async (_agent, _turn, _step, _error, _attempt, _signal, next) => {
+      recoveries += 1
+      return next()
+    })
+
+    send(agent)
+    await waitForIdle(ctx, agent)
+
+    expect(nested.requests).toHaveLength(1)
+    expect(outer.requests).toHaveLength(0)
+    expect(recoveries).toBe(0)
+    expect(agent.session.events.at(-1)).toMatchObject({
+      type: 'turn/end',
+      data: { reason: { kind: 'error', message: 'nested overflow', code: CONTEXT_WINDOW_EXCEEDED_CODE } },
+    })
+  })
+
+  it.each(['prompt-submit', 'prompt-assembly', 'pre-step', 'request'] as const)(
+    'does not offer %s middleware failures to request recovery',
+    async (boundary) => {
+      const adapter = new FailureScriptAdapter([textResponse('unused')])
+      const ctx = await harness(adapter)
+      if (boundary === 'prompt-submit') {
+        ctx.on('agent/prompt-submit', () => { throw new Error('prompt submit failed') })
+      } else if (boundary === 'prompt-assembly') {
+        ctx.on('system-prompt/assemble', () => { throw new Error('prompt assembly failed') })
+      } else if (boundary === 'pre-step') {
+        ctx.on('agent/pre-step', () => { throw new Error('pre-step failed') })
+      } else {
+        ctx.on('agent/request', () => { throw new Error('request middleware failed') })
+      }
+      const agent = ctx.agentLoop.create(SessionId(`${boundary}-not-recoverable`), { provider: 'mock', model: 'mock' })
+      let recoveries = 0
+      ctx.on('agent/request-error', async (_agent, _turn, _step, _error, _attempt, _signal, next) => {
+        recoveries += 1
+        return next()
+      })
+
+      send(agent)
+      await waitForIdle(ctx, agent)
+
+      expect(recoveries).toBe(0)
+      expect(adapter.requests).toHaveLength(0)
+      expect(agent.session.events.at(-1)).toMatchObject({ type: 'turn/end', data: { reason: { kind: 'error' } } })
+    },
+  )
+
+  it('does not offer result, tool, or post-step plugin failures to request recovery', async () => {
+    for (const failure of ['result', 'tool', 'post-step'] as const) {
+      const adapter = new FailureScriptAdapter([
+        failure === 'tool' ? toolCallResponse(`call-${failure}`, 'work', {}) : textResponse('done'),
+        ...(failure === 'tool' ? [textResponse('done')] : []),
+      ])
+      const ctx = await harness(adapter)
+      if (failure === 'result') ctx.on('agent/step-result', () => { throw new Error('result failed') })
+      if (failure === 'post-step') ctx.on('agent/post-step', () => { throw new Error('post-step failed') })
+      if (failure === 'tool') {
+        vi.spyOn(ctx.tools, 'execute').mockRejectedValue(new Error('tool service failed'))
+      }
+      const agent = ctx.agentLoop.create(SessionId(`${failure}-not-recoverable`), { provider: 'mock', model: 'mock' })
+      let recoveries = 0
+      ctx.on('agent/request-error', async (_agent, _turn, _step, _error, _attempt, _signal, next) => {
+        recoveries += 1
+        return next()
+      })
+      send(agent)
+      await waitForIdle(ctx, agent)
+      expect(recoveries, failure).toBe(0)
+    }
+  })
+
+  it.each([
+    ['synchronous dispatch', (error: Error) => new SynchronousDispatchFailureAdapter(error)],
+    ['done getter', (error: Error) => new IteratorResultGetterFailureAdapter('done', error)],
+    ['value getter', (error: Error) => new IteratorResultGetterFailureAdapter('value', error)],
+  ] as const)('preserves original Error identity for adapter %s', async (_name, makeAdapter) => {
+    const original = contextError(`${_name} overflow`)
+    const ctx = await harness(makeAdapter(original))
+    const agent = ctx.agentLoop.create(SessionId(`identity-${_name.replaceAll(' ', '-')}`), { provider: 'mock', model: 'mock' })
+    let seen: Error | undefined
+    ctx.on('agent/request-error', async (_agent, _turn, _step, error, _attempt, _signal, next) => {
+      seen = error
+      return next()
+    })
+
+    send(agent)
+    await waitForIdle(ctx, agent)
+
+    expect(seen).toBe(original)
+  })
+
+  it('classifies iterator construction and explicit NO_ADAPTER as model-request failures', async () => {
+    for (const scenario of ['iterator', 'no-adapter'] as const) {
+      const ctx = scenario === 'iterator' ? await harness(new IteratorConstructionFailureAdapter()) : await harness()
+      const agent = ctx.agentLoop.create(SessionId(`request-boundary-${scenario}`), { provider: 'mock', model: 'mock' })
+      let seen = ''
+      ctx.on('agent/request-error', async (_agent, _turn, _step, error, _attempt, _signal, next) => {
+        seen = error.code ?? ''
+        return next()
+      })
+      send(agent)
+      await waitForIdle(ctx, agent)
+      expect(seen).toBe(scenario === 'iterator' ? 'ITERATOR_CONSTRUCTION' : 'NO_ADAPTER')
+    }
+  })
+
+  it('tracks consecutive retry attempts and resets after a successful request', async () => {
+    const capped = new FailureScriptAdapter([contextError('first overflow'), contextError('second overflow')])
+    const cappedCtx = await harness(capped)
+    const cappedAgent = cappedCtx.agentLoop.create(SessionId('retry-cap'), { provider: 'mock', model: 'mock' })
+    const cappedAttempts: number[] = []
+    cappedCtx.on('agent/request-error', async (_agent, _turn, _step, _error, attempt, _signal, next) => {
+      cappedAttempts.push(attempt)
+      return attempt < 1 ? { action: 'retry' } : next()
+    })
+    send(cappedAgent)
+    await waitForIdle(cappedCtx, cappedAgent)
+    expect(cappedAttempts).toEqual([0, 1])
+
+    const reset = new FailureScriptAdapter([
+      contextError('first overflow'),
+      toolCallResponse('retry-reset-call', 'work', {}),
+      contextError('later overflow'),
+    ])
+    const resetCtx = await harness(reset)
+    resetCtx.tools.register(defineTool({
+      name: 'work',
+      description: 'continue',
+      parameters: {},
+      async execute() { return [{ type: 'text', text: 'worked' }] },
+    }))
+    const resetAgent = resetCtx.agentLoop.create(SessionId('retry-reset'), { provider: 'mock', model: 'mock' })
+    const resetAttempts: { step: number; attempt: number }[] = []
+    resetCtx.on('agent/request-error', async (_agent, _turn, step, _error, attempt, _signal, next) => {
+      resetAttempts.push({ step, attempt })
+      return resetAttempts.length === 1 ? { action: 'retry' } : next()
+    })
+    send(resetAgent)
+    await waitForIdle(resetCtx, resetAgent)
+    expect(resetAttempts).toEqual([{ step: 1, attempt: 0 }, { step: 3, attempt: 0 }])
+  })
+
+  it('preserves the original provider error when recovery throws', async () => {
+    const adapter = new FailureScriptAdapter([contextError('original overflow')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId('recovery-throws'), { provider: 'mock', model: 'mock' })
+    ctx.on('agent/request-error', () => { throw new Error('recovery exploded') })
+
+    send(agent)
+    await waitForIdle(ctx, agent)
+
+    expect(agent.session.events.at(-1)).toMatchObject({
+      type: 'turn/end',
+      data: { reason: { kind: 'error', message: 'original overflow', code: CONTEXT_WINDOW_EXCEEDED_CODE } },
+    })
+  })
+
+  it.each(['cancel', 'dispose'] as const)('keeps %s live through request recovery', async (action) => {
+    const adapter = new FailureScriptAdapter([contextError()])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(SessionId(`${action}-recovery`), { provider: 'mock', model: 'mock' })
+    let entered!: () => void
+    const recoveryEntered = new Promise<void>((resolve) => { entered = resolve })
+    ctx.on('agent/request-error', async (_agent, _turn, _step, _error, _attempt, signal) => {
+      entered()
+      await new Promise<void>((resolve) => {
+        signal.addEventListener('abort', () => { resolve() }, { once: true })
+      })
+      return { action: 'retry' }
+    })
+
+    send(agent)
+    const idle = waitForIdle(ctx, agent)
+    await recoveryEntered
+    if (action === 'cancel') {
+      agent.cancel('cancelled during recovery')
+      await idle
+    } else {
+      await ctx.fiber.dispose()
+    }
+
+    expect(adapter.requests).toHaveLength(1)
+    expect(agent.session.events.at(-1)).toMatchObject({
+      type: 'turn/end',
+      data: { reason: action === 'cancel' ? { kind: 'aborted', reason: 'cancelled during recovery' } : { kind: 'disposed' } },
+    })
+  })
+})

packages/core/agent-loop/tests/resume.spec.ts

@@ -8,9 +8,10 @@ import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, textResponse } from './mock-adapter.ts'
 
 const dirs: string[] = []
@@ -50,7 +51,7 @@ async function persistSession(sessionId: SessionId): Promise<string> {
   return root
 }
 
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') { dispose(); resolve() }
@@ -83,11 +84,10 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     ctx.on('session/created', () => throwUnknown(failure))
 
     await expect(ctx.agents.resume({
-      agentId: AgentId('unknown-resume-failure'),
       resumeSessionId: sessionId,
     })).rejects.toBe(failure)
 
-    expect(ctx.agents.get(AgentId('unknown-resume-failure'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('unknown-resume-failure'))).toBeUndefined()
     expect(ctx.sessions.get(sessionId)).toBeUndefined()
     await ctx.fiber.dispose()
   })
@@ -95,27 +95,26 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
   it('createAgent uses the caller-supplied sessionId (not ${id}-session)', async () => {
     const adapter = new MockAdapter([textResponse('hi')])
     const { ctx } = await persistentHarness(adapter)
-    const { agent } = await ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('custom-session'), meta: { cwd: '/w' } })
+    const { agent } = await ctx.agents.create({ sessionId: SessionId('custom-session'), meta: { cwd: '/w' } })
     expect(agent.session.id).toBe('custom-session')
     expect(agent.session.header.cwd).toBe('/w')
     await ctx.fiber.dispose()
   })
 
-  it('createAgent rejects a duplicate agent id BEFORE creating the session (no orphan)', async () => {
+  it('createAgent rejects a duplicate identity without orphaning a session', async () => {
     const adapter = new MockAdapter([textResponse('hi')])
     const { ctx } = await persistentHarness(adapter)
-    await ctx.agents.create({ agentId: AgentId('dup'), sessionId: SessionId('sess-a') })
-    // A second create with the SAME agent id but a fresh session id must reject
-    // up front — and must NOT leave an orphaned 'sess-b' session behind.
-    await expect(ctx.agents.create({ agentId: AgentId('dup'), sessionId: SessionId('sess-b') })).rejects.toThrow(/already registered/)
-    expect(ctx.sessions.get(SessionId('sess-b'))).toBeUndefined()
+    const sessionId = SessionId('sess-a')
+    await ctx.agents.create({ sessionId })
+    await expect(ctx.agents.create({ sessionId })).rejects.toThrow(/already exists/)
+    expect(ctx.sessions.list()).toHaveLength(1)
     await ctx.fiber.dispose()
   })
 
   it('createAgent works without meta (no cwd)', async () => {
     const adapter = new MockAdapter([textResponse('hi')])
     const { ctx } = await persistentHarness(adapter)
-    const { agent } = await ctx.agents.create({ agentId: AgentId('a-nometa'), sessionId: SessionId('nometa-session') })
+    const { agent } = await ctx.agents.create({ sessionId: SessionId('nometa-session') })
     expect(agent.session.id).toBe('nometa-session')
     expect(agent.session.header.cwd).toBeUndefined()
     await ctx.fiber.dispose()
@@ -125,7 +124,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     // Lifecycle 1: create a no-cwd session and run a turn.
     const adapter1 = new MockAdapter([textResponse('a')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
-    const a1 = (await ctx1.agents.create({ agentId: AgentId('m'), sessionId: SessionId('nocwd-sess') })).agent as ReactLoopAgent
+    const a1 = (await ctx1.agents.create({ sessionId: SessionId('nocwd-sess') })).agent
     a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     await ctx1.fiber.dispose()
@@ -141,7 +140,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     await ctx2.plugin(AgentLoop, { agents: [] })
     await ctx2.plugin(SessionPersistenceJsonl, { root })
     ctx2.llm.registerAdapter(['mock'], adapter2)
-    const a2 = (await ctx2.agents.resume({ agentId: AgentId('m'), resumeSessionId: SessionId('nocwd-sess') })).agent as ReactLoopAgent
+    const a2 = (await ctx2.agents.resume({ resumeSessionId: SessionId('nocwd-sess') })).agent
     expect(a2.session.header.cwd).toBeUndefined()
     await ctx2.fiber.dispose()
   })
@@ -152,7 +151,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const sources1: string[] = []
     ctx1.on('agent/session-start', (_agent, source) => void sources1.push(source))
-    const a1 = (await ctx1.agents.create({ agentId: AgentId('s'), sessionId: SessionId('start-sess') })).agent as ReactLoopAgent
+    const a1 = (await ctx1.agents.create({ sessionId: SessionId('start-sess') })).agent
     expect(sources1).toEqual(['startup'])
     a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
@@ -171,7 +170,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     ctx2.llm.registerAdapter(['mock'], adapter2)
     const sources2: string[] = []
     ctx2.on('agent/session-start', (_agent, source) => void sources2.push(source))
-    await ctx2.agents.resume({ agentId: AgentId('s'), resumeSessionId: SessionId('start-sess') })
+    await ctx2.agents.resume({ resumeSessionId: SessionId('start-sess') })
     expect(sources2).toEqual(['resume'])
     await ctx2.fiber.dispose()
   })
@@ -186,7 +185,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
 
     ctx.on('session/created', (session) => {
       expect(ctx.sessions.get(session.id)).toBe(session)
-      expect(ctx.agents.get(AgentId('resumed-atomic'))?.session).toBe(session)
+      expect(ctx.agents.get(sessionId)?.session).toBe(session)
       order.push('session/created')
     })
     ctx.on('agent/created', (agent) => {
@@ -199,11 +198,10 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     })
 
     const resuming = ctx.agents.resume({
-      agentId: AgentId('resumed-atomic'),
       resumeSessionId: sessionId,
       agentOptions: { provider: 'mock', model: 'mock' },
       setup: async (agentCtx) => {
-        expect(agentCtx.agent?.id).toBe(AgentId('resumed-atomic'))
+        expect(agentCtx.agent?.id).toBe(sessionId)
         expect(agentCtx.agent?.session.events).toHaveLength(2)
         agentCtx.on('session/created', () => void order.push('setup-listener:session/created'))
         agentCtx.on('agent/created', () => void order.push('setup-listener:agent/created'))
@@ -215,7 +213,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     })
 
     await setupStarted.promise
-    expect(ctx.agents.get(AgentId('resumed-atomic'))).toBeUndefined()
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
     expect(ctx.sessions.get(sessionId)).toBeUndefined()
     expect(order).toEqual(['setup:start'])
 
@@ -236,17 +234,15 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
 
   it('successful resume disposal retires its caller-owned transaction effects', async () => {
     const sessionId = SessionId('resume-retired-effects-s')
-    const agentId = AgentId('resume-retired-effects')
     const root = await persistSession(sessionId)
     const ctx = await mountPersistentHarness(root, new MockAdapter([textResponse('next')]))
     const handle = await ctx.agents.resume({
-      agentId,
       resumeSessionId: sessionId,
       agentOptions: { provider: 'mock', model: 'mock' },
     })
     const transactionLabels = [
-      `agentLoop.owner(${agentId})`,
-      `agentLoop.lifecycle(${agentId})`,
+      `agentLoop.owner(${sessionId})`,
+      `agentLoop.lifecycle(${sessionId})`,
     ]
 
     expect(ctx.fiber.getEffects().map(effect => effect.label)).toEqual(expect.arrayContaining(transactionLabels))
@@ -255,7 +251,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     await ctx.fiber.dispose()
   })
 
-  it('resume setup rejection publishes nothing, unwinds, and releases both identities', async () => {
+  it('resume setup rejection publishes nothing, unwinds, and releases the identity', async () => {
     const sessionId = SessionId('resume-setup-reject')
     const root = await persistSession(sessionId)
     const ctx = await mountPersistentHarness(root, new MockAdapter([textResponse('next')]))
@@ -265,7 +261,6 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     ctx.on('agent/session-start', () => void published.push('agent/session-start'))
 
     await expect(ctx.agents.resume({
-      agentId: AgentId('resume-reject'),
       resumeSessionId: sessionId,
       agentOptions: { provider: 'mock', model: 'mock' },
       setup: async () => {
@@ -275,10 +270,9 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     })).rejects.toThrow('resume setup failed')
 
     expect(published).toEqual([])
-    expect(ctx.agents.get(AgentId('resume-reject'))).toBeUndefined()
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
     expect(ctx.sessions.get(sessionId)).toBeUndefined()
     const retry = await ctx.agents.resume({
-      agentId: AgentId('resume-reject'),
       resumeSessionId: sessionId,
       agentOptions: { provider: 'mock', model: 'mock' },
     })
@@ -299,7 +293,6 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     let resuming!: ReturnType<typeof ctx.agents.resume>
     const owner = await ctx.plugin(Object.assign((inner: Context) => {
       resuming = inner.agents.resume({
-        agentId: AgentId('resume-owner-race'),
         resumeSessionId: sessionId,
         agentOptions: { provider: 'mock', model: 'mock' },
         setup: async () => {
@@ -313,7 +306,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     await owner.dispose()
     await expect(resuming).rejects.toThrow(/owner disposed during setup/)
     expect(published).toEqual([])
-    expect(ctx.agents.get(AgentId('resume-owner-race'))).toBeUndefined()
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
     expect(ctx.sessions.get(sessionId)).toBeUndefined()
 
     gate.resolve(undefined)
@@ -322,9 +315,8 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     await ctx.fiber.dispose()
   })
 
-  it('owner unload aborts a never-settling persistence load, releases identities, and blocks late publication', async () => {
+  it('owner unload aborts a never-settling persistence load, releases the identity, and blocks late publication', async () => {
     const sessionId = SessionId('resume-load-owner-unload')
-    const agentId = AgentId('resume-load-race')
     const root = await persistSession(sessionId)
     const ctx = await mountPersistentHarness(root, new MockAdapter([textResponse('next')]))
     const snapshot = await ctx.sessionPersistence.load(sessionId)
@@ -348,19 +340,19 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
 
     let resuming!: ReturnType<typeof ctx.agents.resume>
     const owner = await ctx.plugin(Object.assign((inner: Context) => {
-      resuming = inner.agents.resume({ agentId, resumeSessionId: sessionId, agentOptions: { provider: 'mock', model: 'mock' } })
+      resuming = inner.agents.resume({ resumeSessionId: sessionId, agentOptions: { provider: 'mock', model: 'mock' } })
     }, { inject: ['agents'] }))
     await loadStarted.promise
 
     const rejection = expect(promptly(resuming)).rejects.toThrow(/owner disposed during setup/)
     await promptly(owner.dispose())
     expect(published).toEqual([])
-    expect(ctx.agents.get(agentId)).toBeUndefined()
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
     expect(ctx.sessions.get(sessionId)).toBeUndefined()
 
     // owner.dispose() awaited transaction settlement, so the same identities
     // can be reused before awaiting the public rejection.
-    const retry = await promptly(ctx.agents.resume({ agentId, resumeSessionId: sessionId, agentOptions: { provider: 'mock', model: 'mock' } }))
+    const retry = await promptly(ctx.agents.resume({ resumeSessionId: sessionId, agentOptions: { provider: 'mock', model: 'mock' } }))
     await rejection
     expect(loads).toBe(2)
     expect(published).toEqual(['session/created', 'agent/created', 'agent/session-start'])
@@ -370,7 +362,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     lateLoad.resolve(structuredClone(snapshot))
     await Promise.resolve()
     await Promise.resolve()
-    expect(ctx.agents.get(agentId)).toBe(retry.agent)
+    expect(ctx.agents.get(sessionId)).toBe(retry.agent)
     expect(ctx.sessions.get(sessionId)).toBe(retry.agent.session)
     expect(published).toEqual(['session/created', 'agent/created', 'agent/session-start'])
 
@@ -380,7 +372,6 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
 
   it('AgentLoop unload aborts persistence load and awaits wrapper settlement', async () => {
     const sessionId = SessionId('resume-load-factory-unload')
-    const agentId = AgentId('resume-load-factory-race')
     const root = await persistSession(sessionId)
     const ctx = new Context()
     await ctx.plugin(LlmService)
@@ -404,14 +395,14 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     ctx.on('session/created', () => void published.push('session/created'))
     ctx.on('agent/created', () => void published.push('agent/created'))
 
-    const resuming = ctx.agents.resume({ agentId, resumeSessionId: sessionId, agentOptions: { provider: 'mock', model: 'mock' } })
+    const resuming = ctx.agents.resume({ resumeSessionId: sessionId, agentOptions: { provider: 'mock', model: 'mock' } })
     await loadStarted.promise
     const rejection = expect(promptly(resuming)).rejects.toThrow(/agent loop is not active/)
     await promptly(loopFiber.dispose())
     await rejection
 
     expect(published).toEqual([])
-    expect(ctx.agents.get(agentId)).toBeUndefined()
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
     expect(ctx.sessions.get(sessionId)).toBeUndefined()
     lateLoad.resolve(structuredClone(snapshot))
     await Promise.resolve()
@@ -452,7 +443,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     await ctx2.plugin(AgentLoop, { agents: [] })
     await ctx2.plugin(SessionPersistenceJsonl, { root })
     ctx2.llm.registerAdapter(['mock'], adapter2)
-    const a2 = (await ctx2.agents.resume({ agentId: AgentId('m'), resumeSessionId: SessionId('forked-sess') })).agent as ReactLoopAgent
+    const a2 = (await ctx2.agents.resume({ resumeSessionId: SessionId('forked-sess') })).agent
     expect(a2.session.header.parentSession).toBe('parent-sess')
     expect(a2.session.header.cwd).toBe('/w')
     expect(a2.session.header.seedLength).toBe(seed.length)
@@ -464,7 +455,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     // clean disposal follows, so disk presence proves its own checkpoint ran.
     const adapter1 = new MockAdapter([textResponse('answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
-    const a1 = (await ctx1.agents.create({ agentId: AgentId('m'), sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent as ReactLoopAgent
+    const a1 = (await ctx1.agents.create({ sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent
     a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     a1.inject([{ type: 'text', text: 'background task 42 finished' }], { source: { kind: 'plugin', plugin: 'tool-bash' } })
@@ -487,7 +478,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     // survive persistence and resume.
     const adapter1 = new MockAdapter([textResponse('answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
-    const a1 = (await ctx1.agents.create({ agentId: AgentId('m'), sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent as ReactLoopAgent
+    const a1 = (await ctx1.agents.create({ sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent
     a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     a1.inject([{ type: 'text', text: 'background task 42 finished' }], { source: { kind: 'plugin', plugin: 'tool-bash' } })
@@ -505,7 +496,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     await ctx2.plugin(AgentLoop, { agents: [] })
     await ctx2.plugin(SessionPersistenceJsonl, { root })
     ctx2.llm.registerAdapter(['mock'], adapter2)
-    const a2 = (await ctx2.agents.resume({ agentId: AgentId('m'), resumeSessionId: SessionId('inject-sess') })).agent as ReactLoopAgent
+    const a2 = (await ctx2.agents.resume({ resumeSessionId: SessionId('inject-sess') })).agent
     const flat = JSON.stringify(a2.session.deriveMessages())
     expect(flat).toContain('background task 42 finished')
     await ctx2.fiber.dispose()
@@ -515,7 +506,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     // Lifecycle 1: run one full turn, persisting it.
     const adapter1 = new MockAdapter([textResponse('first answer')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
-    const a1 = (await ctx1.agents.create({ agentId: AgentId('main'), sessionId: SessionId('sess-resume'), meta: { cwd: '/w' } })).agent as ReactLoopAgent
+    const a1 = (await ctx1.agents.create({ sessionId: SessionId('sess-resume'), meta: { cwd: '/w' } })).agent
     a1.send([{ type: 'text', text: 'first question' }], { source: { kind: 'user' } })
     await waitForIdle(ctx1, a1)
     const events1 = [...a1.session.events]
@@ -535,7 +526,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     await ctx2.plugin(SessionPersistenceJsonl, { root })
     ctx2.llm.registerAdapter(['mock'], adapter2)
 
-    const a2 = (await ctx2.agents.resume({ agentId: AgentId('main'), resumeSessionId: SessionId('sess-resume') })).agent as ReactLoopAgent
+    const a2 = (await ctx2.agents.resume({ resumeSessionId: SessionId('sess-resume') })).agent
     // The resumed session carries the prior history…
     expect(a2.session.id).toBe('sess-resume')
     expect(a2.session.events.length).toBe(events1.length)
@@ -563,7 +554,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(AgentLoop, { agents: [] })
     ctx.llm.registerAdapter(['mock'], adapter)
-    await expect(ctx.agents.resume({ agentId: AgentId('m'), resumeSessionId: SessionId('nope') }))
+    await expect(ctx.agents.resume({ resumeSessionId: SessionId('nope') }))
       .rejects.toThrow(/session persistence is not configured/)
     await ctx.fiber.dispose()
   })

packages/core/agent-loop/tests/scope-lifecycle.spec.ts

@@ -4,10 +4,11 @@ import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId, agentEvents, assembleContextFor } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { agentEvents, assembleContextFor } from '@deepseek-ai/dsh-agent'
+
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { scopeOf } from '@deepseek-ai/dsh-scope'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { MockAdapter, textResponse } from './mock-adapter.ts'
 
@@ -27,7 +28,7 @@ async function harness(adapter: MockAdapter = new MockAdapter([textResponse('ok'
   return (await harnessWithLoop(adapter)).ctx
 }
 
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') {
@@ -57,33 +58,31 @@ function disposeCurrentLifecycle(ownerCtx: Context): void {
 }
 
 describe('agent scope lifecycle', () => {
-  it('rejects an already-aborted creation signal before publishing either identity', async () => {
+  it('rejects an already-aborted creation signal before publishing either object', async () => {
     const ctx = await harness()
     const reason = new Error('cancelled before creation')
     const controller = new AbortController()
     controller.abort(reason)
 
     await expect(ctx.agents.create({
-      agentId: AgentId('pre-aborted'),
       sessionId: SessionId('pre-aborted-s'),
       signal: controller.signal,
     })).rejects.toBe(reason)
 
-    expect(ctx.agents.get(AgentId('pre-aborted'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('pre-aborted-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('pre-aborted-s'))).toBeUndefined()
 
     const valueController = new AbortController()
     valueController.abort('plain cancellation reason')
     await expect(ctx.agents.create({
-      agentId: AgentId('pre-aborted-value'),
       sessionId: SessionId('pre-aborted-value-s'),
       signal: valueController.signal,
     })).rejects.toMatchObject({
-      message: 'agent "pre-aborted-value" creation aborted',
+      message: 'agent "pre-aborted-value-s" creation aborted',
       cause: 'plain cancellation reason',
     })
 
-    expect(ctx.agents.get(AgentId('pre-aborted-value'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('pre-aborted-value-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('pre-aborted-value-s'))).toBeUndefined()
     await ctx.fiber.dispose()
   })
@@ -100,12 +99,11 @@ describe('agent scope lifecycle', () => {
     })
 
     await expect(ctx.agents.create({
-      agentId: AgentId('prepare-abort'),
       sessionId: SessionId('prepare-abort-s'),
       signal: controller.signal,
     })).rejects.toBe(reason)
 
-    expect(ctx.agents.get(AgentId('prepare-abort'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('prepare-abort-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('prepare-abort-s'))).toBeUndefined()
     await ctx.fiber.dispose()
   })
@@ -124,7 +122,7 @@ describe('agent scope lifecycle', () => {
     thrown = createFailure
     let createCaught: unknown
     try {
-      ctx.agentLoop.create(AgentId('unknown-create'))
+      ctx.agentLoop.create(SessionId('unknown-create'))
     } catch (error: unknown) {
       createCaught = error
     }
@@ -133,28 +131,45 @@ describe('agent scope lifecycle', () => {
     const ownedFailure = { source: 'createAgent' }
     thrown = ownedFailure
     await expect(ctx.agents.create({
-      agentId: AgentId('unknown-owned-create'),
       sessionId: SessionId('unknown-owned-create-s'),
     })).rejects.toBe(ownedFailure)
 
-    expect(ctx.agents.get(AgentId('unknown-create'))).toBeUndefined()
-    expect(ctx.agents.get(AgentId('unknown-owned-create'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('unknown-create'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('unknown-owned-create-s'))).toBeUndefined()
     await ctx.fiber.dispose()
   })
 
   it('wires agent.ctx: tagged with the agent, DX field set, ctx.agent safe elsewhere', async () => {
     const ctx = await harness()
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     expect(scopeOf(agent.ctx)).toBe(agent)
     expect(agent.ctx.agent).toBe(agent)
     // The root accessor default: a plain context answers undefined, not a throw.
     expect(ctx.agent).toBeUndefined()
-    await ctx.agents.get(AgentId('a1'))?.whenIdle()
+    await ctx.agents.get(SessionId('a1'))?.whenIdle()
+  })
+
+  it('records agents created through an agent context as non-root runtime children', async () => {
+    const ctx = await harness()
+    const root = await ctx.agents.create({
+      sessionId: SessionId('runtime-root'),
+      agentOptions: { model: 'mock' },
+    })
+    const child = await root.agent.ctx.agents.create({
+      sessionId: SessionId('runtime-child'),
+      agentOptions: { model: 'mock' },
+    })
+
+    expect(ctx.agents.list()).toEqual([root.agent, child.agent])
+    expect(ctx.agents.roots()).toEqual([root.agent])
+
+    await child.dispose()
+    await root.dispose()
   })
 
   it('scoped registrations live in the agent world and die with the agent', async () => {
     const ctx = await harness()
-    const handle = await ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('s1'), agentOptions: { provider: 'mock', model: 'mock' } })
+    const handle = await ctx.agents.create({ sessionId: SessionId('s1'), agentOptions: { provider: 'mock', model: 'mock' } })
     const { agent } = handle
     agent.ctx.systemPrompt.section({ name: 'deployment:persona', order: 0, text: 'You run tests.' })
     agent.ctx.tools.register({
@@ -179,8 +194,8 @@ describe('agent scope lifecycle', () => {
 
   it('agent.ctx listeners hear only their own agent (scoped dispatch end to end)', async () => {
     const ctx = await harness(new MockAdapter([textResponse('one'), textResponse('two')]))
-    const a = ctx.agentLoop.create(AgentId('a'), { provider: 'mock', model: 'mock' })
-    const b = ctx.agentLoop.create(AgentId('b'), { provider: 'mock', model: 'mock' })
+    const a = ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
+    const b = ctx.agentLoop.create(SessionId('b'), { provider: 'mock', model: 'mock' })
 
     const heard: string[] = []
     a.ctx.on('agent/status', (subject, status) => void heard.push(`a-sees:${subject.id}:${status}`))
@@ -210,7 +225,6 @@ describe('agent scope lifecycle', () => {
     })
 
     const handle = await ctx.agents.create({
-      agentId: AgentId('child'),
       sessionId: SessionId('child-s'),
       agentOptions: { provider: 'mock', model: 'mock' },
       setup: async (agentCtx) => {
@@ -224,14 +238,14 @@ describe('agent scope lifecycle', () => {
     await handle.dispose()
   })
 
-  it('keeps both identities unpublished until async setup completes, then announces in order', async () => {
+  it('keeps both objects unpublished until async setup completes, then announces in order', async () => {
     const ctx = await harness()
     const gate = Promise.withResolvers<undefined>()
     const setupStarted = Promise.withResolvers<undefined>()
     const order: string[] = []
     ctx.on('session/created', (session) => {
       expect(ctx.sessions.get(session.id)).toBe(session)
-      expect(ctx.agents.get(AgentId('atomic'))?.session).toBe(session)
+      expect(ctx.agents.get(session.id)?.session).toBe(session)
       order.push('session/created')
     })
     ctx.on('agent/created', () => void order.push('agent/created'))
@@ -239,11 +253,10 @@ describe('agent scope lifecycle', () => {
     const acceptedOptions = { provider: 'mock', model: 'mock' }
 
     const creating = ctx.agents.create({
-      agentId: AgentId('atomic'),
-      sessionId: SessionId('atomic-s'),
+      sessionId: SessionId('atomic'),
       agentOptions: acceptedOptions,
       setup: async (agentCtx) => {
-        expect(agentCtx.agent?.id).toBe(AgentId('atomic'))
+        expect(agentCtx.agent?.id).toBe(SessionId('atomic'))
         agentCtx.on('session/created', () => void order.push('setup-listener:session/created'))
         agentCtx.on('agent/created', () => void order.push('setup-listener:agent/created'))
         order.push('setup:start')
@@ -253,8 +266,8 @@ describe('agent scope lifecycle', () => {
       },
     })
     await setupStarted.promise
-    expect(ctx.agents.get(AgentId('atomic'))).toBeUndefined()
-    expect(ctx.sessions.get(SessionId('atomic-s'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('atomic'))).toBeUndefined()
+    expect(ctx.sessions.get(SessionId('atomic'))).toBeUndefined()
     expect(order).toEqual(['setup:start'])
     gate.resolve(undefined)
     const handle = await creating
@@ -281,16 +294,14 @@ describe('agent scope lifecycle', () => {
       if (started === 2) bothStarted.resolve(undefined)
       await gate.promise
     }
-    const agentId = AgentId('concurrent-final-enter')
+    const sessionId = SessionId('concurrent-final-enter')
     const first = ctx.agents.create({
-      agentId,
-      sessionId: SessionId('concurrent-final-enter-a'),
+      sessionId,
       agentOptions: { provider: 'mock', model: 'mock' },
       setup,
     })
     const second = ctx.agents.create({
-      agentId,
-      sessionId: SessionId('concurrent-final-enter-b'),
+      sessionId,
       agentOptions: { provider: 'mock', model: 'mock' },
       setup,
     })
@@ -304,7 +315,7 @@ describe('agent scope lifecycle', () => {
     const rejected = outcomes.filter((outcome): outcome is PromiseRejectedResult => outcome.status === 'rejected')
     expect(fulfilled).toHaveLength(1)
     expect(rejected).toHaveLength(1)
-    expect(String(rejected[0]!.reason)).toMatch(/already registered/)
+    expect(String(rejected[0]!.reason)).toMatch(/already exists/)
     expect(ctx.agents.list()).toEqual([fulfilled[0]!.value.agent])
     expect(ctx.sessions.list()).toEqual([fulfilled[0]!.value.agent.session])
 
@@ -318,7 +329,6 @@ describe('agent scope lifecycle', () => {
     const pendingController = new AbortController()
     const setupStarted = Promise.withResolvers<undefined>()
     const pending = ctx.agents.create({
-      agentId: AgentId('signal-pending'),
       sessionId: SessionId('signal-pending-s'),
       agentOptions: { provider: 'mock', model: 'mock' },
       signal: pendingController.signal,
@@ -330,12 +340,11 @@ describe('agent scope lifecycle', () => {
     await setupStarted.promise
     pendingController.abort(new Error('cancel pending creation'))
     await expect(pending).rejects.toThrow('cancel pending creation')
-    expect(ctx.agents.get(AgentId('signal-pending'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('signal-pending-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('signal-pending-s'))).toBeUndefined()
 
     const liveController = new AbortController()
     const live = await ctx.agents.create({
-      agentId: AgentId('signal-live'),
       sessionId: SessionId('signal-live-s'),
       agentOptions: { provider: 'mock', model: 'mock' },
       signal: liveController.signal,
@@ -358,7 +367,6 @@ describe('agent scope lifecycle', () => {
     let creating!: ReturnType<typeof ctx.agents.create>
     const owner = await ctx.plugin(Object.assign((inner: Context) => {
       creating = inner.agents.create({
-        agentId: AgentId('owner-race'),
         sessionId: SessionId('owner-race-s'),
         agentOptions: { provider: 'mock', model: 'mock' },
         setup: async () => {
@@ -372,7 +380,7 @@ describe('agent scope lifecycle', () => {
     await owner.dispose()
     await expect(creating).rejects.toThrow(/owner disposed during setup/)
     expect(published).toEqual([])
-    expect(ctx.agents.get(AgentId('owner-race'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('owner-race-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('owner-race-s'))).toBeUndefined()
     // Let the losing callback settle; Promise.race already observes it.
     gate.resolve(undefined)
@@ -386,7 +394,6 @@ describe('agent scope lifecycle', () => {
     let creating2!: ReturnType<typeof ctx.agents.create>
     const owner2 = await ctx.plugin(Object.assign((inner: Context) => {
       creating2 = inner.agents.create({
-        agentId: AgentId('owner-race-2'),
         sessionId: SessionId('owner-race-s-2'),
         agentOptions: { provider: 'mock', model: 'mock' },
         setup: async () => {
@@ -400,7 +407,7 @@ describe('agent scope lifecycle', () => {
     const unload2 = owner2.dispose()
     await expect(creating2).rejects.toThrow(/owner disposed during setup/)
     await unload2
-    expect(ctx.agents.get(AgentId('owner-race-2'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('owner-race-s-2'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('owner-race-s-2'))).toBeUndefined()
   })
 
@@ -413,7 +420,6 @@ describe('agent scope lifecycle', () => {
     ctx.on('agent/created', () => void published.push('agent/created'))
 
     const creating = ctx.agents.create({
-      agentId: AgentId('factory-setup-race'),
       sessionId: SessionId('factory-setup-race-s'),
       agentOptions: { provider: 'mock', model: 'mock' },
       setup: async () => {
@@ -426,7 +432,7 @@ describe('agent scope lifecycle', () => {
     await loopFiber.dispose()
     await expect(creating).rejects.toThrow(/agent loop is not active/)
     expect(published).toEqual([])
-    expect(ctx.agents.get(AgentId('factory-setup-race'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('factory-setup-race-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('factory-setup-race-s'))).toBeUndefined()
 
     gate.resolve(undefined)
@@ -444,7 +450,6 @@ describe('agent scope lifecycle', () => {
     })
 
     const creating = ctx.agents.create({
-      agentId: AgentId('factory-scope-race'),
       sessionId: SessionId('factory-scope-race-s'),
       agentOptions: { provider: 'mock', model: 'mock' },
       setup: () => { setupCalls += 1 },
@@ -452,7 +457,7 @@ describe('agent scope lifecycle', () => {
     await expect(creating).rejects.toThrow(/agent loop is not active/)
     await loopFiber.dispose()
     expect(setupCalls).toBe(0)
-    expect(ctx.agents.get(AgentId('factory-scope-race'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('factory-scope-race-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('factory-scope-race-s'))).toBeUndefined()
 
     await ctx.fiber.dispose()
@@ -479,7 +484,6 @@ describe('agent scope lifecycle', () => {
     const owner = ctx.plugin(Object.assign((inner: Context) => {
       ownerFiber = inner.fiber
       creating = inner.agents.create({
-        agentId: AgentId('caller-scope-race'),
         sessionId: SessionId('caller-scope-race-s'),
         agentOptions: { provider: 'mock', model: 'mock' },
       })
@@ -495,7 +499,7 @@ describe('agent scope lifecycle', () => {
     await ownerDisposal
     await owner
     expect(scopeFiber?.uid).toBeNull()
-    expect(ctx.agents.get(AgentId('caller-scope-race'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('caller-scope-race-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('caller-scope-race-s'))).toBeUndefined()
     await owner.dispose()
     await ctx.fiber.dispose()
@@ -511,17 +515,17 @@ describe('agent scope lifecycle', () => {
       void loopFiber.dispose()
     })
 
-    expect(() => ctx.agentLoop.create(AgentId('config-scope-race'), { provider: 'mock', model: 'mock' }))
+    expect(() => ctx.agentLoop.create(SessionId('config-scope-race'), { provider: 'mock', model: 'mock' }))
       .toThrow(/agent loop is not active/)
     await loopFiber.dispose()
-    expect(ctx.agents.get(AgentId('config-scope-race'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('config-scope-race'))).toBeUndefined()
     expect(ctx.sessions.list()).toHaveLength(sessionsBefore)
     await ctx.fiber.dispose()
   })
 
   it('synchronous create leaves no lifecycle state when session preparation fails', async () => {
     const ctx = await harness()
-    const id = AgentId('config-prepare-failure')
+    const id = SessionId('config-prepare-failure')
 
     expect(() => ctx.agentLoop.create(id, { provider: 'mock', model: 'mock' }, { cwd: 'relative' }))
       .toThrow(/absolute path/)
@@ -542,12 +546,11 @@ describe('agent scope lifecycle', () => {
     })
 
     await expect(ctx.agents.create({
-      agentId: AgentId('factory-scope-throw'),
       sessionId: SessionId('factory-scope-throw-s'),
       agentOptions: { provider: 'mock', model: 'mock' },
     })).rejects.toThrow('scope preparation failed')
     await loopFiber.dispose()
-    expect(ctx.agents.get(AgentId('factory-scope-throw'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('factory-scope-throw-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('factory-scope-throw-s'))).toBeUndefined()
 
     await ctx.fiber.dispose()
@@ -556,23 +559,21 @@ describe('agent scope lifecycle', () => {
   it('AgentLoop unload is a structural co-owner of every live programmatic agent', async () => {
     const { ctx, loopFiber } = await harnessWithLoop()
     const loop = ctx.agentLoop
-    const agentId = AgentId('factory-live')
+    const sessionId = SessionId('factory-live')
     const handle = await ctx.agents.create({
-      agentId,
       sessionId: SessionId('factory-live-s'),
       agentOptions: { provider: 'mock', model: 'mock' },
     })
 
     await loopFiber.dispose()
     expect(handle.agent.status).toBe('disposed')
-    expect(ctx.agents.get(agentId)).toBeUndefined()
-    expect(ctx.sessions.get(SessionId('factory-live-s'))).toBeUndefined()
-    expect(ctx.fiber.getEffects().filter(effect => effect.label === `agentLoop.owner(${agentId})`)).toEqual([])
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
+    expect(ctx.sessions.get(sessionId)).toBeUndefined()
+    expect(ctx.fiber.getEffects().filter(effect => effect.label === `agentLoop.owner(${sessionId})`)).toEqual([])
     // The consumer handle shares the provider's completed quiescence boundary.
     await handle.dispose()
 
     await expect(loop.createAgent(ctx, {
-      agentId: AgentId('factory-inactive'),
       sessionId: SessionId('factory-inactive-s'),
     })).rejects.toThrow('agent loop is not active')
     await ctx.fiber.dispose()
@@ -583,7 +584,6 @@ describe('agent scope lifecycle', () => {
     let creating!: ReturnType<typeof ctx.agents.create>
     const owner = await ctx.plugin(Object.assign((inner: Context) => {
       creating = inner.agents.create({
-        agentId: AgentId('dependency-origin'),
         sessionId: SessionId('dependency-origin-s'),
         agentOptions: { provider: 'mock', model: 'mock' },
         setup: (agentCtx) => {
@@ -623,7 +623,7 @@ describe('agent scope lifecycle', () => {
     })
     ctx.on('session/created', (session) => {
       if (session.id !== SessionId('session-created-barrier-s')) return
-      const agent = ctx.agents.get(AgentId('session-created-barrier'))!
+      const agent = ctx.agents.get(SessionId('session-created-barrier-s'))!
       expect(ctx.sessions.get(session.id)).toBe(session)
       expect(agent.session).toBe(session)
       agent.ctx.effect(() => () => { lifecycle.push('scope-disposed') })
@@ -638,7 +638,6 @@ describe('agent scope lifecycle', () => {
     const owner = await ctx.plugin(Object.assign((inner: Context) => {
       ownerCtx = inner
       creating = inner.agents.create({
-        agentId: AgentId('session-created-barrier'),
         sessionId: SessionId('session-created-barrier-s'),
         agentOptions: { provider: 'mock', model: 'mock' },
       })
@@ -652,7 +651,7 @@ describe('agent scope lifecycle', () => {
       'session-disposed',
       'scope-disposed',
     ])
-    expect(ctx.agents.get(AgentId('session-created-barrier'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('session-created-barrier-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('session-created-barrier-s'))).toBeUndefined()
     await ctx.fiber.dispose()
   })
@@ -666,19 +665,19 @@ describe('agent scope lifecycle', () => {
       if (session.id === SessionId('agent-created-barrier-s')) lifecycle.push('session-created')
     })
     ctx.on('agent/created', (agent) => {
-      if (agent.id !== AgentId('agent-created-barrier')) return
+      if (agent.id !== SessionId('agent-created-barrier-s')) return
       lifecycle.push('agent-created:dispose')
       disposeCurrentLifecycle(ownerCtx)
     })
     ctx.on('agent/created', (agent) => {
-      if (agent.id !== AgentId('agent-created-barrier')) return
+      if (agent.id !== SessionId('agent-created-barrier-s')) return
       expect(ctx.agents.get(agent.id)).toBe(agent)
       expect(ctx.sessions.get(agent.session.id)).toBe(agent.session)
       agent.ctx.effect(() => () => { lifecycle.push('scope-disposed') })
       lifecycle.push('agent-created:observer')
     })
     ctx.on('agent/disposed', (agent) => {
-      if (agent.id === AgentId('agent-created-barrier')) lifecycle.push('agent-disposed')
+      if (agent.id === SessionId('agent-created-barrier-s')) lifecycle.push('agent-disposed')
     })
     ctx.on('session/disposed', (session) => {
       if (session.id === SessionId('agent-created-barrier-s')) lifecycle.push('session-disposed')
@@ -687,7 +686,6 @@ describe('agent scope lifecycle', () => {
     const owner = await ctx.plugin(Object.assign((inner: Context) => {
       ownerCtx = inner
       creating = inner.agents.create({
-        agentId: AgentId('agent-created-barrier'),
         sessionId: SessionId('agent-created-barrier-s'),
         agentOptions: { provider: 'mock', model: 'mock' },
       })
@@ -703,7 +701,7 @@ describe('agent scope lifecycle', () => {
       'session-disposed',
       'scope-disposed',
     ])
-    expect(ctx.agents.get(AgentId('agent-created-barrier'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('agent-created-barrier-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('agent-created-barrier-s'))).toBeUndefined()
     await ctx.fiber.dispose()
   })
@@ -715,13 +713,12 @@ describe('agent scope lifecycle', () => {
     let creating!: ReturnType<typeof ctx.agents.create>
     ctx.on('agent/session-start', agent => void starts.push(agent.id))
     ctx.on('agent/created', (agent) => {
-      if (agent.id === AgentId('listener-dispose')) void ownerCtx.fiber.dispose()
+      if (agent.id === SessionId('listener-dispose-s')) void ownerCtx.fiber.dispose()
     })
 
     const owner = await ctx.plugin(Object.assign((inner: Context) => {
       ownerCtx = inner
       creating = inner.agents.create({
-        agentId: AgentId('listener-dispose'),
         sessionId: SessionId('listener-dispose-s'),
         agentOptions: { provider: 'mock', model: 'mock' },
       })
@@ -730,7 +727,7 @@ describe('agent scope lifecycle', () => {
     await expect(creating).rejects.toThrow(/owner disposed during setup/)
     await owner.dispose()
     expect(starts).toEqual([])
-    expect(ctx.agents.get(AgentId('listener-dispose'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('listener-dispose-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('listener-dispose-s'))).toBeUndefined()
     await ctx.fiber.dispose()
   })
@@ -739,20 +736,20 @@ describe('agent scope lifecycle', () => {
     const ctx = await harness()
     let ownerCtx!: Context
     let creating!: ReturnType<typeof ctx.agents.create>
-    let announced!: ReactLoopAgent
+    let announced!: Agent
     const statuses: string[] = []
     let scopeDisposed = false
     let observerSawLive = false
     ctx.on('agent/status', (agent, status) => {
-      if (agent.id === AgentId('session-start-dispose')) statuses.push(status)
+      if (agent.id === SessionId('session-start-dispose-s')) statuses.push(status)
     })
     ctx.on('agent/session-start', (agent) => {
-      if (agent.id !== AgentId('session-start-dispose')) return
-      announced = agent as ReactLoopAgent
+      if (agent.id !== SessionId('session-start-dispose-s')) return
+      announced = agent
       disposeCurrentLifecycle(ownerCtx)
     })
     ctx.on('agent/session-start', (agent) => {
-      if (agent.id !== AgentId('session-start-dispose')) return
+      if (agent.id !== SessionId('session-start-dispose-s')) return
       expect(ctx.agents.get(agent.id)).toBe(agent)
       expect(ctx.sessions.get(agent.session.id)).toBe(agent.session)
       agent.ctx.effect(() => () => { scopeDisposed = true })
@@ -762,7 +759,6 @@ describe('agent scope lifecycle', () => {
     const owner = await ctx.plugin(Object.assign((inner: Context) => {
       ownerCtx = inner
       creating = inner.agents.create({
-        agentId: AgentId('session-start-dispose'),
         sessionId: SessionId('session-start-dispose-s'),
         agentOptions: { provider: 'mock', model: 'mock' },
       })
@@ -775,7 +771,7 @@ describe('agent scope lifecycle', () => {
     expect(observerSawLive).toBe(true)
     expect(scopeDisposed).toBe(true)
     expect(announced.session.events).toEqual([])
-    expect(ctx.agents.get(AgentId('session-start-dispose'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('session-start-dispose-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('session-start-dispose-s'))).toBeUndefined()
     await ctx.fiber.dispose()
   })
@@ -787,7 +783,6 @@ describe('agent scope lifecycle', () => {
     ctx.on('agent/created', () => void published.push('agent/created'))
     ctx.on('agent/session-start', () => void published.push('agent/session-start'))
     await expect(ctx.agents.create({
-      agentId: AgentId('bad'),
       sessionId: SessionId('bad-s'),
       agentOptions: { provider: 'mock', model: 'mock' },
       setup: async () => {
@@ -798,13 +793,13 @@ describe('agent scope lifecycle', () => {
 
     // Nothing leaked: no agent, no session, and the ids are reusable.
     expect(published).toEqual([])
-    expect(ctx.agents.get(AgentId('bad'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('bad-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('bad-s'))).toBeUndefined()
-    const retry = await ctx.agents.create({ agentId: AgentId('bad'), sessionId: SessionId('bad-s'), agentOptions: { provider: 'mock', model: 'mock' } })
+    const retry = await ctx.agents.create({ sessionId: SessionId('bad-s'), agentOptions: { provider: 'mock', model: 'mock' } })
     await retry.dispose()
   })
 
-  it('rejects an exotic durable seed before publishing either identity', async () => {
+  it('rejects an exotic durable seed before publishing either object', async () => {
     const ctx = await harness()
     const published: string[] = []
     ctx.on('session/created', () => { published.push('session') })
@@ -817,17 +812,15 @@ describe('agent scope lifecycle', () => {
     }] as unknown as SessionEvent[]
 
     await expect(ctx.agents.create({
-      agentId: AgentId('exotic-seed'),
       sessionId: SessionId('exotic-seed-session'),
       agentOptions: { provider: 'mock', model: 'mock' },
       seed,
     })).rejects.toThrow(/seed event at index 0 is not losslessly JSON-serializable/)
 
     expect(published).toEqual([])
-    expect(ctx.agents.get(AgentId('exotic-seed'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('exotic-seed-session'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('exotic-seed-session'))).toBeUndefined()
     const retry = await ctx.agents.create({
-      agentId: AgentId('exotic-seed'),
       sessionId: SessionId('exotic-seed-session'),
       agentOptions: { provider: 'mock', model: 'mock' },
     })
@@ -843,13 +836,13 @@ describe('agent scope lifecycle', () => {
       if (boom) { boom = false; throw new Error('boom created') }
     })
     await expect(ctx.agents.create({
-      agentId: AgentId('bad'), sessionId: SessionId('bad-s'), agentOptions: { provider: 'mock', model: 'mock' },
+      sessionId: SessionId('bad-s'), agentOptions: { provider: 'mock', model: 'mock' },
     })).rejects.toThrow('boom created')
-    expect(ctx.agents.get(AgentId('bad'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('bad-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('bad-s'))).toBeUndefined()
     expect(disposed).toEqual([]) // inserted but never announced: no impossible disposed edge
     // The rollback also disposed the scope fiber: re-creating works cleanly.
-    const retry = await ctx.agents.create({ agentId: AgentId('bad'), sessionId: SessionId('bad-s'), agentOptions: { provider: 'mock', model: 'mock' } })
+    const retry = await ctx.agents.create({ sessionId: SessionId('bad-s'), agentOptions: { provider: 'mock', model: 'mock' } })
     expect(scopeOf(retry.agent.ctx)).toBe(retry.agent)
     await retry.dispose()
   })
@@ -866,18 +859,17 @@ describe('agent scope lifecycle', () => {
     ctx.on('agent/disposed', (agent) => { lifecycle.push(`agent-disposed:${agent.id}`) })
 
     await expect(ctx.agents.create({
-      agentId: AgentId('partial-agent'),
       sessionId: SessionId('partial-session'),
       agentOptions: { provider: 'mock', model: 'mock' },
     })).rejects.toThrow('agent observer failed')
 
     expect(lifecycle).toEqual([
       'session-created:partial-session',
-      'agent-created:partial-agent',
-      'agent-disposed:partial-agent',
+      'agent-created:partial-session',
+      'agent-disposed:partial-session',
       'session-disposed:partial-session',
     ])
-    expect(ctx.agents.get(AgentId('partial-agent'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('partial-session'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('partial-session'))).toBeUndefined()
   })
 
@@ -892,23 +884,23 @@ describe('agent scope lifecycle', () => {
       }
     })
 
-    expect(() => ctx.agentLoop.create(AgentId('config-bad'), { provider: 'mock', model: 'mock' }))
+    expect(() => ctx.agentLoop.create(SessionId('config-bad'), { provider: 'mock', model: 'mock' }))
       .toThrow('config publish failed')
-    expect(ctx.agents.get(AgentId('config-bad'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('config-bad'))).toBeUndefined()
     expect(ctx.sessions.list()).toHaveLength(sessionsBefore)
   })
 
   it('registrations through a disposed agent ctx throw INACTIVE_EFFECT', async () => {
     const ctx = await harness()
-    const handle = await ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('s1'), agentOptions: { provider: 'mock', model: 'mock' } })
+    const handle = await ctx.agents.create({ sessionId: SessionId('s1'), agentOptions: { provider: 'mock', model: 'mock' } })
     await handle.dispose()
     expect(() => handle.agent.ctx.on('agent/status', () => {})).toThrow(/inactive context/)
   })
 
   it('agentEvents fuses carrier and subject for custom drivers', async () => {
     const ctx = await harness()
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
-    const other = ctx.agentLoop.create(AgentId('a2'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    const other = ctx.agentLoop.create(SessionId('a2'), { provider: 'mock', model: 'mock' })
     const heard: string[] = []
     agent.ctx.on('agent/error', (subject: Agent, turn: number) => void heard.push(`${subject.id}:${turn}`))
 
@@ -921,7 +913,7 @@ describe('agent scope lifecycle', () => {
     const ctx = await harness()
     let handle!: Awaited<ReturnType<typeof ctx.agents.create>>
     const owner = await ctx.plugin(Object.assign(async (inner: Context) => {
-      handle = await inner.agents.create({ agentId: AgentId('o1'), sessionId: SessionId('o1-s'), agentOptions: { provider: 'mock', model: 'mock' } })
+      handle = await inner.agents.create({ sessionId: SessionId('o1-s'), agentOptions: { provider: 'mock', model: 'mock' } })
     }, { inject: ['agents'] }))
     const { agent } = handle
 
@@ -930,7 +922,7 @@ describe('agent scope lifecycle', () => {
       if (event.type === 'turn/end') order.push('turn-end')
     })
     ctx.on('agent/disposed', () => {
-      order.push(`disposed(listed=${ctx.agents.get(AgentId('o1')) !== undefined})`)
+      order.push(`disposed(listed=${ctx.agents.get(SessionId('o1-s')) !== undefined})`)
       order.push(`session-still-stored=${ctx.sessions.get(SessionId('o1-s')) !== undefined}`)
     })
 
@@ -953,7 +945,7 @@ describe('agent scope lifecycle', () => {
     const ctx = await harness()
     let handle!: Awaited<ReturnType<typeof ctx.agents.create>>
     const owner = await ctx.plugin(Object.assign(async (inner: Context) => {
-      handle = await inner.agents.create({ agentId: AgentId('h1'), sessionId: SessionId('h1-s'), agentOptions: { provider: 'mock', model: 'mock' } })
+      handle = await inner.agents.create({ sessionId: SessionId('h1-s'), agentOptions: { provider: 'mock', model: 'mock' } })
     }, { inject: ['agents'] }))
 
     const teardownDone: string[] = []
@@ -965,23 +957,22 @@ describe('agent scope lifecycle', () => {
     // actually finished (the raw wrapper returns undefined on a repeat call).
     await handle.dispose()
     expect(teardownDone).toContain('unregistered')
-    expect(ctx.agents.get(AgentId('h1'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('h1-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('h1-s'))).toBeUndefined()
     await unload
   })
 
   it('successful handle disposal retires its caller ownership effect', async () => {
     const ctx = await harness()
-    const agentId = AgentId('retired-owner-effect')
+    const sessionId = SessionId('retired-owner-effect')
     const handle = await ctx.agents.create({
-      agentId,
-      sessionId: SessionId('retired-owner-effect-s'),
+      sessionId,
       agentOptions: { provider: 'mock', model: 'mock' },
     })
 
-    expect(ctx.fiber.getEffects().map(effect => effect.label)).toContain(`agentLoop.owner(${agentId})`)
+    expect(ctx.fiber.getEffects().map(effect => effect.label)).toContain(`agentLoop.owner(${sessionId})`)
     await handle.dispose()
-    expect(ctx.fiber.getEffects().filter(effect => effect.label === `agentLoop.owner(${agentId})`)).toEqual([])
+    expect(ctx.fiber.getEffects().filter(effect => effect.label === `agentLoop.owner(${sessionId})`)).toEqual([])
     await ctx.fiber.dispose()
   })
 
@@ -992,7 +983,6 @@ describe('agent scope lifecycle', () => {
     let handle!: Awaited<ReturnType<typeof ctx.agents.create>>
     const owner = await ctx.plugin(Object.assign(async (inner: Context) => {
       handle = await inner.agents.create({
-        agentId: AgentId('manual-first'),
         sessionId: SessionId('manual-first-s'),
         agentOptions: { provider: 'mock', model: 'mock' },
         setup(agentCtx) {
@@ -1012,7 +1002,7 @@ describe('agent scope lifecycle', () => {
     expect(ownerSettled).toBe(false)
     gate.resolve(undefined)
     await Promise.all([disposing, unloading])
-    expect(ctx.agents.get(AgentId('manual-first'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('manual-first-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('manual-first-s'))).toBeUndefined()
     await ctx.fiber.dispose()
   })
@@ -1022,13 +1012,11 @@ describe('agent scope lifecycle', () => {
     const gate = Promise.withResolvers<undefined>()
     const cleanupStarted = Promise.withResolvers<undefined>()
     const sessionDisposed = Promise.withResolvers<undefined>()
-    const agentId = AgentId('quiescent-reuse')
-    const sessionId = SessionId('quiescent-reuse-s')
+    const sessionId = SessionId('quiescent-reuse')
     ctx.on('session/disposed', (session) => {
       if (session.id === sessionId) sessionDisposed.resolve(undefined)
     })
     const first = await ctx.agents.create({
-      agentId,
       sessionId,
       agentOptions: { provider: 'mock', model: 'mock' },
       setup(agentCtx) {
@@ -1041,10 +1029,10 @@ describe('agent scope lifecycle', () => {
 
     const disposing = first.dispose()
     await Promise.all([sessionDisposed.promise, cleanupStarted.promise])
-    expect(ctx.agents.get(agentId)).toBeUndefined()
+    expect(ctx.agents.get(sessionId)).toBeUndefined()
     expect(ctx.sessions.get(sessionId)).toBeUndefined()
-    const replacement = await ctx.agents.create({ agentId, sessionId, agentOptions: { provider: 'mock', model: 'mock' } })
-    expect(ctx.agents.get(agentId)).toBe(replacement.agent)
+    const replacement = await ctx.agents.create({ sessionId, agentOptions: { provider: 'mock', model: 'mock' } })
+    expect(ctx.agents.get(sessionId)).toBe(replacement.agent)
     expect(ctx.sessions.get(sessionId)).toBe(replacement.agent.session)
 
     gate.resolve(undefined)
@@ -1056,7 +1044,6 @@ describe('agent scope lifecycle', () => {
   it('handle.dispose() awaits an idle-injection flush before unregistering or detaching', async () => {
     const ctx = await harness()
     const handle = await ctx.agents.create({
-      agentId: AgentId('idle-flush'),
       sessionId: SessionId('idle-flush-s'),
       agentOptions: { provider: 'mock', model: 'mock' },
     })
@@ -1075,12 +1062,12 @@ describe('agent scope lifecycle', () => {
     const disposal = handle.dispose().then(() => { disposed = true })
     await new Promise(resolve => setTimeout(resolve, 0))
     expect(disposed).toBe(false)
-    expect(ctx.agents.get(AgentId('idle-flush'))).toBe(handle.agent)
+    expect(ctx.agents.get(SessionId('idle-flush-s'))).toBe(handle.agent)
     expect(ctx.sessions.get(SessionId('idle-flush-s'))).toBe(handle.agent.session)
 
     gate.resolve(undefined)
     await disposal
-    expect(ctx.agents.get(AgentId('idle-flush'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('idle-flush-s'))).toBeUndefined()
     expect(ctx.sessions.get(SessionId('idle-flush-s'))).toBeUndefined()
   })
 })

packages/core/agent-loop/tests/tool-calls.spec.ts

@@ -0,0 +1,588 @@
+/**
+ * Exercises scheduler ordering and cancellation with deterministic gated tools.
+ * ACP goldens own transcript-facing coverage.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { CallId, StreamChunk } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import LlmService from '@deepseek-ai/dsh-llm'
+import ToolRegistry, { defineTool, type PostToolDecision, type PreToolDecision } from '@deepseek-ai/dsh-tools'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { MockAdapter, textResponse } from './mock-adapter.ts'
+
+async function harness(adapter: MockAdapter, maxParallelToolCalls?: number) {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: '' })
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(AgentLoop, {
+    agents: [],
+    ...maxParallelToolCalls === undefined ? {} : { maxParallelToolCalls },
+  })
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return ctx
+}
+
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'idle') { dispose(); resolve() }
+    })
+  })
+}
+
+function events(agent: Agent): SessionEvent[] {
+  return [...agent.session.events]
+}
+
+/** Build one assistant response containing the supplied tool calls. */
+function multiCall(calls: { id: string; name: string; args: object }[]): StreamChunk[] {
+  const chunks: StreamChunk[] = []
+  calls.forEach((call, index) => {
+    chunks.push(
+      { type: 'block-start', index, blockType: 'tool-call' },
+      { type: 'block-end', index, block: { type: 'tool-call', id: CallId(call.id), name: call.name, arguments: JSON.stringify(call.args) } },
+    )
+  })
+  chunks.push(
+    { type: 'usage', usage: { inputTokens: 5, outputTokens: 5 } },
+    { type: 'finish', reason: { kind: 'tool-calls' } },
+  )
+  return chunks
+}
+
+/** A tool whose calls block until the test releases them by callId. */
+function gatedTool(name: string, parallel: boolean) {
+  const gates = new Map<string, () => void>()
+  const started: string[] = []
+  const tool = defineTool({
+    name,
+    description: `gated ${name}`,
+    parameters: { id: { type: 'string', required: true } },
+    ...parallel ? { isConcurrencySafe: () => true } : {},
+    async execute(args) {
+      started.push(args.id)
+      await new Promise<void>((resolve) => { gates.set(args.id, resolve) })
+      return [{ type: 'text', text: `done-${args.id}` }]
+    },
+  })
+  return {
+    tool,
+    started,
+    release(id: string) { gates.get(id)?.(); gates.delete(id) },
+    pending() { return [...gates.keys()] },
+  }
+}
+
+function gatedParallelTool(name: string) {
+  return gatedTool(name, true)
+}
+
+function gatedExclusiveTool(name: string) {
+  return gatedTool(name, false)
+}
+
+/** Poll until `predicate` holds, letting microtasks/timers drain between checks. */
+async function until(predicate: () => boolean): Promise<void> {
+  for (let i = 0; i < 1000 && !predicate(); i++) await new Promise(r => setTimeout(r, 0))
+  if (!predicate()) throw new Error('until: condition never held')
+}
+
+describe('tool-call scheduler: grouping and barriers', () => {
+  it('runs parallel-safe siblings concurrently (all start before any completes)', async () => {
+    const adapter = new MockAdapter([
+      multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }, { id: 'c3', name: 'p', args: { id: '3' } }]),
+      textResponse('done'),
+    ])
+    const ctx = await harness(adapter)
+    const gated = gatedParallelTool('p')
+    ctx.tools.register(gated.tool)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    agent.send([{ type: 'text', text: 'go' }])
+    await until(() => gated.started.length === 3)
+    expect(gated.started).toEqual(['1', '2', '3'])
+    gated.release('1'); gated.release('2'); gated.release('3')
+    await waitForIdle(ctx, agent)
+  })
+
+  it('an exclusive call between two parallel-safe calls forms a barrier (3 groups)', async () => {
+    const order: string[] = []
+    const adapter = new MockAdapter([
+      multiCall([
+        { id: 'c1', name: 'r', args: { id: 'A1' } },
+        { id: 'c2', name: 'w', args: { id: 'A2' } },
+        { id: 'c3', name: 'r', args: { id: 'A3' } },
+      ]),
+      textResponse('done'),
+    ])
+    const ctx = await harness(adapter)
+    ctx.tools.register(defineTool({
+      name: 'r', description: 'read', parameters: { id: { type: 'string', required: true } },
+      isConcurrencySafe: () => true,
+      async execute(args) { order.push(`r-start-${args.id}`); order.push(`r-end-${args.id}`); return [{ type: 'text', text: 'r' }] },
+    }))
+    ctx.tools.register(defineTool({
+      name: 'w', description: 'write', parameters: { id: { type: 'string', required: true } },
+      async execute(args) { order.push(`w-${args.id}`); return [{ type: 'text', text: 'w' }] },
+    }))
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    expect(order).toEqual(['r-start-A1', 'r-end-A1', 'w-A2', 'r-start-A3', 'r-end-A3'])
+  })
+
+  it('reclassifies pending calls after an exclusive barrier replaces their tool', async () => {
+    const adapter = new MockAdapter([
+      multiCall([
+        { id: 'c1', name: 'replace', args: { id: '0' } },
+        { id: 'c2', name: 'x', args: { id: '1' } },
+        { id: 'c3', name: 'x', args: { id: '2' } },
+      ]),
+      textResponse('done'),
+    ])
+    const ctx = await harness(adapter)
+    const replacement = gatedExclusiveTool('x')
+    const disposeSafe = ctx.tools.register(defineTool({
+      name: 'x',
+      description: 'initially safe',
+      parameters: { id: { type: 'string', required: true } },
+      isConcurrencySafe: () => true,
+      async execute(args) { return [{ type: 'text', text: `old-${args.id}` }] },
+    }))
+    ctx.tools.register(defineTool({
+      name: 'replace',
+      description: 'replace x',
+      parameters: { id: { type: 'string', required: true } },
+      async execute() {
+        disposeSafe()
+        ctx.tools.register(replacement.tool)
+        return [{ type: 'text', text: 'replaced' }]
+      },
+    }))
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    agent.send([{ type: 'text', text: 'go' }])
+    await until(() => replacement.started.length === 1)
+    await new Promise(r => setTimeout(r, 5))
+    expect(replacement.started).toEqual(['1'])
+    replacement.release('1')
+    await until(() => replacement.started.length === 2)
+    expect(replacement.started).toEqual(['1', '2'])
+    replacement.release('2')
+    await waitForIdle(ctx, agent)
+  })
+
+  it('stops replenishing when a result observer makes the next call exclusive', async () => {
+    const adapter = new MockAdapter([
+      multiCall([
+        { id: 'c1', name: 'x', args: { id: '1' } },
+        { id: 'c2', name: 'x', args: { id: '2' } },
+        { id: 'c3', name: 'x', args: { id: '3' } },
+      ]),
+      textResponse('done'),
+    ])
+    const ctx = await harness(adapter, 2)
+    const initial = gatedParallelTool('x')
+    const replacement = gatedExclusiveTool('x')
+    const disposeInitial = ctx.tools.register(initial.tool)
+    ctx.on('tools/result', (exec) => {
+      if (exec.callId !== CallId('c1')) return
+      disposeInitial()
+      ctx.tools.register(replacement.tool)
+    })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    agent.send([{ type: 'text', text: 'go' }])
+    await until(() => initial.started.length === 2)
+    initial.release('1')
+    await until(() => events(agent).some(event =>
+      event.type === 'tool/result' && event.data.callId === CallId('c1')))
+    await new Promise(r => setTimeout(r, 5))
+    expect(replacement.started).toEqual([])
+    initial.release('2')
+    await until(() => replacement.started.length === 1)
+    expect(replacement.started).toEqual(['3'])
+    replacement.release('3')
+    await waitForIdle(ctx, agent)
+  })
+})
+
+describe('tool-call scheduler: model-order results despite out-of-order settlement', () => {
+  it('commits tool/result in model order even when a later call settles first', async () => {
+    const adapter = new MockAdapter([
+      multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]),
+      textResponse('done'),
+    ])
+    const ctx = await harness(adapter)
+    const gated = gatedParallelTool('p')
+    ctx.tools.register(gated.tool)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    agent.send([{ type: 'text', text: 'go' }])
+    await until(() => gated.started.length === 2)
+    gated.release('2')
+    await new Promise(r => setTimeout(r, 5))
+    const beforeFirst = events(agent).filter(e => e.type === 'tool/result')
+    expect(beforeFirst).toEqual([])
+    gated.release('1')
+    await waitForIdle(ctx, agent)
+
+    const results = events(agent).filter(e => e.type === 'tool/result')
+    expect(results.map(e => e.data.callId)).toEqual([CallId('c1'), CallId('c2')])
+  })
+
+  it('derived history pairs calls in model order regardless of tool/call log interleaving', async () => {
+    const adapter = new MockAdapter([
+      multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]),
+      textResponse('done'),
+    ])
+    const ctx = await harness(adapter)
+    const gated = gatedParallelTool('p')
+    ctx.tools.register(gated.tool)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await until(() => gated.started.length === 2)
+    gated.release('2'); gated.release('1')
+    await waitForIdle(ctx, agent)
+
+    const messages = agent.session.deriveMessages()
+    const toolResults = messages.flatMap(m => m.content.filter(b => b.type === 'tool-result'))
+    expect(toolResults.map(b => b.toolCallId)).toEqual([CallId('c1'), CallId('c2')])
+  })
+})
+
+describe('tool-call scheduler: rolling pool honors maxParallelToolCalls', () => {
+  it('rejects invalid global maxParallelToolCalls config at plugin load', async () => {
+    await expect(harness(new MockAdapter([]), 0)).rejects.toThrow()
+    await expect(harness(new MockAdapter([]), 1.5)).rejects.toThrow()
+  })
+
+  it('defensively rejects invalid caps when direct construction bypasses the config schema', () => {
+    expect(() => new AgentLoop(new Context(), { agents: [], maxParallelToolCalls: 0 }))
+      .toThrow('maxParallelToolCalls must be a positive integer')
+    expect(() => new AgentLoop(new Context(), { agents: [], maxParallelToolCalls: 1.5 }))
+      .toThrow('maxParallelToolCalls must be a positive integer')
+  })
+
+  it('defaults the cap when direct construction bypasses the config schema', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SystemPrompt, { persona: '' })
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+
+    expect(() => new AgentLoop(ctx, { agents: [] })).not.toThrow()
+    await ctx.fiber.dispose()
+  })
+
+  it('starts at most the cap, replenishing as calls settle', async () => {
+    const adapter = new MockAdapter([
+      multiCall([1, 2, 3, 4].map(n => ({ id: `c${n}`, name: 'p', args: { id: String(n) } }))),
+      textResponse('done'),
+    ])
+    const ctx = await harness(adapter, 2)
+    const gated = gatedParallelTool('p')
+    ctx.tools.register(gated.tool)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    agent.send([{ type: 'text', text: 'go' }])
+    await until(() => gated.started.length === 2)
+    await new Promise(r => setTimeout(r, 5))
+    expect(gated.started).toEqual(['1', '2'])
+    gated.release('1')
+    await until(() => gated.started.length === 3)
+    expect(gated.started).toEqual(['1', '2', '3'])
+    expect(events(agent)
+      .filter(e => e.type === 'tool/call' || e.type === 'tool/result')
+      .map(e => `${e.type}:${String(e.data.callId)}`)
+      .slice(0, 4))
+      .toEqual(['tool/call:c1', 'tool/call:c2', 'tool/result:c1', 'tool/call:c3'])
+    gated.release('2'); gated.release('3')
+    await until(() => gated.started.length === 4)
+    gated.release('4')
+    await waitForIdle(ctx, agent)
+    expect(events(agent).filter(e => e.type === 'tool/result').map(e => e.data.callId))
+      .toEqual([CallId('c1'), CallId('c2'), CallId('c3'), CallId('c4')])
+  })
+
+  it('maxParallelToolCalls: 1 is fully serial (no second start before the first settles)', async () => {
+    const adapter = new MockAdapter([
+      multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]),
+      textResponse('done'),
+    ])
+    const ctx = await harness(adapter, 1)
+    const gated = gatedParallelTool('p')
+    ctx.tools.register(gated.tool)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await until(() => gated.started.length === 1)
+    await new Promise(r => setTimeout(r, 5))
+    expect(gated.started).toEqual(['1'])
+    gated.release('1')
+    await until(() => gated.started.length === 2)
+    gated.release('2')
+    await waitForIdle(ctx, agent)
+  })
+
+  it('applies the configured cap to every factory-created agent', async () => {
+    const adapter = new MockAdapter([
+      multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]),
+      textResponse('done'),
+    ])
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SystemPrompt, { persona: '' })
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(AgentLoop, { agents: [], maxParallelToolCalls: 1 })
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const gated = gatedParallelTool('p')
+    ctx.tools.register(gated.tool)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await until(() => gated.started.length === 1)
+    await new Promise(r => setTimeout(r, 5))
+    expect(gated.started).toEqual(['1'])
+    gated.release('1')
+    await until(() => gated.started.length === 2)
+    gated.release('2')
+    await waitForIdle(ctx, agent)
+  })
+
+})
+
+describe('tool-call scheduler: ordered middleware and additional contexts', () => {
+  it('tools/pre-execute and tools/post-execute observe model call order', async () => {
+    const adapter = new MockAdapter([
+      multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }, { id: 'c3', name: 'p', args: { id: '3' } }]),
+      textResponse('done'),
+    ])
+    const ctx = await harness(adapter)
+    const gated = gatedParallelTool('p')
+    ctx.tools.register(gated.tool)
+    const pre: string[] = []
+    const post: string[] = []
+    ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => { pre.push(String(exec.callId)); return next() })
+    ctx.on('tools/post-execute', async (exec, _result, next): Promise<PostToolDecision> => { post.push(String(exec.callId)); return next() })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    agent.send([{ type: 'text', text: 'go' }])
+    await until(() => gated.started.length === 3)
+    gated.release('3'); gated.release('2'); gated.release('1')
+    await waitForIdle(ctx, agent)
+
+    expect(pre).toEqual([CallId('c1'), CallId('c2'), CallId('c3')].map(String))
+    expect(post).toEqual([CallId('c1'), CallId('c2'), CallId('c3')].map(String))
+  })
+
+  it('injects additional contexts in model call order, not settlement order', async () => {
+    const adapter = new MockAdapter([
+      multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]),
+      textResponse('done'),
+    ])
+    const ctx = await harness(adapter, 2)
+    const gated = gatedParallelTool('p')
+    ctx.tools.register(gated.tool)
+    ctx.on('tools/post-execute', async (exec, _result): Promise<PostToolDecision> =>
+      ({ kind: 'accept', additionalContexts: [{ content: [{ type: 'text', text: `ctx-${exec.callId}` }], source: { kind: 'plugin', plugin: 'p' } }] }))
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    agent.send([{ type: 'text', text: 'go' }])
+    await until(() => gated.started.length === 2)
+    gated.release('2'); gated.release('1')
+    await waitForIdle(ctx, agent)
+
+    const log = events(agent)
+    const contextTexts = log.filter(e => e.type === 'context/message')
+      .map(e => (e.data.content[0] as { text: string }).text)
+    expect(contextTexts).toEqual(['ctx-c1', 'ctx-c2'])
+    const lastResult = log.findLastIndex(e => e.type === 'tool/result')
+    const firstContext = log.findIndex(e => e.type === 'context/message')
+    expect(lastResult).toBeLessThan(firstContext)
+  })
+
+  it('orders pre-execute denials and errors without dispatching them', async () => {
+    const adapter = new MockAdapter([
+      multiCall([
+        { id: 'c1', name: 'p', args: { id: '1' } },
+        { id: 'c2', name: 'p', args: { id: '2' } },
+        { id: 'c3', name: 'p', args: { id: '3' } },
+      ]),
+      textResponse('done'),
+    ])
+    const ctx = await harness(adapter)
+    const gated = gatedParallelTool('p')
+    ctx.tools.register(gated.tool)
+    const post: string[] = []
+    ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
+      if (exec.callId === CallId('c2')) return { kind: 'deny', reason: 'blocked by policy' }
+      if (exec.callId === CallId('c3')) throw new Error('pre exploded')
+      return next()
+    })
+    ctx.on('tools/post-execute', async (exec, _result, next): Promise<PostToolDecision> => {
+      post.push(String(exec.callId))
+      return next()
+    })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    agent.send([{ type: 'text', text: 'go' }])
+    await until(() => gated.started.length === 1)
+    gated.release('1')
+    await waitForIdle(ctx, agent)
+
+    expect(gated.started).toEqual(['1'])
+    expect(post).toEqual(['c1', 'c2'])
+    const results = events(agent).filter(e => e.type === 'tool/result')
+    expect(results.map(e => e.data.callId)).toEqual([CallId('c1'), CallId('c2'), CallId('c3')])
+    expect((results[1]!.data.content[0] as { text: string }).text).toContain('blocked by policy')
+    expect((results[2]!.data.content[0] as { text: string }).text).toContain('pre exploded')
+  })
+})
+
+describe('tool-call scheduler: abort handling', () => {
+  it('starts no calls when the signal is already aborted before a parallel group', async () => {
+    const adapter = new MockAdapter([
+      multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]),
+      textResponse('should never be requested'),
+    ])
+    const ctx = await harness(adapter)
+    const gated = gatedParallelTool('p')
+    ctx.tools.register(gated.tool)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    ctx.on('session/event', (session, event) => {
+      if (session === agent.session && event.type === 'assistant/message') {
+        ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('already aborted')
+      }
+    })
+
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    expect(gated.started).toEqual([])
+    expect(events(agent).filter(e => e.type === 'tool/call').map(e => e.data.callId))
+      .toEqual([CallId('c1'), CallId('c2')])
+    expect(events(agent).filter(e => e.type === 'tool/result').map(e => ({
+      callId: e.data.callId,
+      isError: e.data.isError,
+      error: e.data.error,
+    }))).toEqual([
+      { callId: CallId('c1'), isError: true, error: { name: 'AbortError', code: 'ABORTED' } },
+      { callId: CallId('c2'), isError: true, error: { name: 'AbortError', code: 'ABORTED' } },
+    ])
+  })
+
+  it('stops starting siblings when abort fires during ordered pre-execute', async () => {
+    const adapter = new MockAdapter([
+      multiCall([{ id: 'c1', name: 'p', args: { id: '1' } }, { id: 'c2', name: 'p', args: { id: '2' } }]),
+      textResponse('should never be requested'),
+    ])
+    const ctx = await harness(adapter)
+    const gated = gatedParallelTool('p')
+    ctx.tools.register(gated.tool)
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+    ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
+      if (exec.callId === CallId('c1')) {
+        ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('pre cancelled')
+      }
+      return next()
+    })
+
+    agent.send([{ type: 'text', text: 'go' }])
+    await until(() => gated.started.length === 1)
+    await new Promise(r => setTimeout(r, 5))
+    expect(gated.started).toEqual(['1'])
+    gated.release('1')
+    await waitForIdle(ctx, agent)
+
+    expect(events(agent).filter(e => e.type === 'tool/call').map(e => e.data.callId))
+      .toEqual([CallId('c1'), CallId('c2')])
+    expect(events(agent).filter(e => e.type === 'tool/result').map(e => e.data.callId))
+      .toEqual([CallId('c1'), CallId('c2')])
+    expect(events(agent).filter(e => e.type === 'tool/result').at(-1)?.data)
+      .toMatchObject({ callId: CallId('c2'), isError: true, error: { name: 'AbortError', code: 'ABORTED' } })
+  })
+
+  it('stops replenishing after abort, commits started results, and drains accepted additional contexts', async () => {
+    const adapter = new MockAdapter([
+      multiCall([1, 2, 3, 4].map(n => ({ id: `c${n}`, name: 'p', args: { id: String(n) } }))),
+      textResponse('should never be requested'),
+    ])
+    const ctx = await harness(adapter, 2)
+    const gated = gatedParallelTool('p')
+    ctx.tools.register(gated.tool)
+    ctx.on('tools/post-execute', async (exec, _result, next): Promise<PostToolDecision> => ({
+      ...await next(),
+      additionalContexts: [{ content: [{ type: 'text', text: `ctx-${exec.callId}` }], source: { kind: 'plugin', plugin: 'p' } }],
+    }))
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    agent.send([{ type: 'text', text: 'go' }])
+    await until(() => gated.started.length === 2)
+    ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('stop now')
+    gated.release('1')
+    gated.release('2')
+    await waitForIdle(ctx, agent)
+
+    expect(gated.started).toEqual(['1', '2'])
+    expect(events(agent).filter(e => e.type === 'tool/call').map(e => e.data.callId))
+      .toEqual([CallId('c1'), CallId('c2'), CallId('c3'), CallId('c4')])
+    expect(events(agent).filter(e => e.type === 'tool/result').map(e => e.data.callId))
+      .toEqual([CallId('c1'), CallId('c2'), CallId('c3'), CallId('c4')])
+    expect(events(agent).filter(e => e.type === 'tool/result').slice(-2).map(e => e.data))
+      .toEqual([
+        expect.objectContaining({ callId: CallId('c3'), isError: true, error: { name: 'AbortError', code: 'ABORTED' } }),
+        expect.objectContaining({ callId: CallId('c4'), isError: true, error: { name: 'AbortError', code: 'ABORTED' } }),
+      ])
+    const settled = events(agent).filter(e => e.type === 'tool/result' || e.type === 'context/message')
+    expect(settled.map(e => e.type))
+      .toEqual(['tool/result', 'tool/result', 'tool/result', 'tool/result', 'context/message', 'context/message'])
+    expect(settled.filter(e => e.type === 'context/message')
+      .map(e => (e.data.content[0] as { text: string }).text))
+      .toEqual(['ctx-c1', 'ctx-c2'])
+  })
+
+  it('does not run an exclusive barrier after a parallel group aborts', async () => {
+    const adapter = new MockAdapter([
+      multiCall([
+        { id: 'c1', name: 'p', args: { id: '1' } },
+        { id: 'c2', name: 'p', args: { id: '2' } },
+        { id: 'c3', name: 'x', args: { id: '3' } },
+      ]),
+      textResponse('should never be requested'),
+    ])
+    const ctx = await harness(adapter, 2)
+    const gated = gatedParallelTool('p')
+    const exclusive: string[] = []
+    ctx.tools.register(gated.tool)
+    ctx.tools.register(defineTool({
+      name: 'x',
+      description: 'exclusive',
+      parameters: { id: { type: 'string', required: true } },
+      async execute(args) { exclusive.push(args.id); return [{ type: 'text', text: 'x' }] },
+    }))
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
+
+    agent.send([{ type: 'text', text: 'go' }])
+    await until(() => gated.started.length === 2)
+    ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('stop before barrier')
+    gated.release('1')
+    gated.release('2')
+    await waitForIdle(ctx, agent)
+
+    expect(exclusive).toEqual([])
+    expect(events(agent).filter(e => e.type === 'tool/call').map(e => e.data.callId))
+      .toEqual([CallId('c1'), CallId('c2'), CallId('c3')])
+    expect(events(agent).filter(e => e.type === 'tool/result').at(-1)?.data)
+      .toMatchObject({ callId: CallId('c3'), isError: true, error: { name: 'AbortError', code: 'ABORTED' } })
+  })
+})

packages/core/agent-loop/tests/tool-order.spec.ts

@@ -9,12 +9,13 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import LlmService from '@deepseek-ai/dsh-llm'
-import SessionStore, { foldRequestHeader } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, foldRequestHeader } from '@deepseek-ai/dsh-session'
 import SystemPrompt, { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import type { Config as SystemPromptConfig } from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
-import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, textResponse } from './mock-adapter.ts'
 
 async function harness(adapter: MockAdapter, toolOrder?: SystemPromptConfig['toolOrder']) {
@@ -29,7 +30,7 @@ async function harness(adapter: MockAdapter, toolOrder?: SystemPromptConfig['too
   return ctx
 }
 
-function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (subject, status) => {
       if (subject === agent && status === 'idle') {
@@ -56,7 +57,7 @@ async function runTurn(registrationOrder: string[], toolOrder?: SystemPromptConf
   const adapter = new MockAdapter([textResponse('done')])
   const ctx = await harness(adapter, toolOrder)
   for (const name of registrationOrder) registerNamed(ctx, name)
-  const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+  const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
   agent.send([{ type: 'text', text: 'go' }])
   await waitForIdle(ctx, agent)
   return { ctx, agent, adapter }
@@ -98,7 +99,7 @@ describe('loop-level canonical tool order', () => {
     registerNamed(ctx, 'alpha')
     const errors: Error[] = []
     ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error))
-    const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     agent.send([{ type: 'text', text: 'go' }])
     await waitForIdle(ctx, agent)
     expect(adapter.requests).toHaveLength(0)

packages/core/agent-loop/tests/turn-stop.spec.ts

@@ -1,11 +1,12 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import LlmService from '@deepseek-ai/dsh-llm'
-import SessionStore, { type TurnEndReason } from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId, type TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
-import AgentRegistry, { AgentId, type ContinuationStop } from '@deepseek-ai/dsh-agent'
-import AgentLoop, { type ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import AgentRegistry, { type Agent, type ContinuationStop } from '@deepseek-ai/dsh-agent'
+
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import * as Invariants from '@deepseek-ai/dsh-invariants'
 import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
 
@@ -22,7 +23,7 @@ async function harness(adapter: MockAdapter): Promise<Context> {
   return ctx
 }
 
-function send(agent: ReactLoopAgent, text = 'go'): Promise<void> {
+function send(agent: Agent, text = 'go'): Promise<void> {
   agent.send([{ type: 'text', text }])
   return agent.whenIdle()
 }
@@ -45,7 +46,7 @@ describe('agent/turn-stop', () => {
       textResponse('must not be requested'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('terminal-steering'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('terminal-steering'), { provider: 'mock', model: 'mock' })
     agent.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
 
     let steered = false
@@ -72,7 +73,7 @@ describe('agent/turn-stop', () => {
       textResponse('must not become a late-steering turn'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('terminal-flush-steering'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('terminal-flush-steering'), { provider: 'mock', model: 'mock' })
     agent.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
 
     let injected = false
@@ -98,7 +99,7 @@ describe('agent/turn-stop', () => {
       textResponse('queued follow-up answer'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('terminal-flush-send'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('terminal-flush-send'), { provider: 'mock', model: 'mock' })
     agent.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
 
     let queued = false
@@ -124,8 +125,8 @@ describe('agent/turn-stop', () => {
     ])
     const ctx = await harness(adapter)
     registerEcho(ctx)
-    const stopped = ctx.agentLoop.create(AgentId('stopped'), { provider: 'mock', model: 'mock' })
-    const ordinary = ctx.agentLoop.create(AgentId('ordinary'), { provider: 'mock', model: 'mock' })
+    const stopped = ctx.agentLoop.create(SessionId('stopped'), { provider: 'mock', model: 'mock' })
+    const ordinary = ctx.agentLoop.create(SessionId('ordinary'), { provider: 'mock', model: 'mock' })
     stopped.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
 
     await send(stopped)
@@ -145,7 +146,7 @@ describe('agent/turn-stop', () => {
     ])
     const ctx = await harness(adapter)
     registerEcho(ctx)
-    const agent = ctx.agentLoop.create(AgentId('owned-listener'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('owned-listener'), { provider: 'mock', model: 'mock' })
     const disposeStop = agent.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
 
     await send(agent, 'first turn')
@@ -162,7 +163,7 @@ describe('agent/turn-stop', () => {
       textResponse('healthy later turn'),
     ])
     const ctx = await harness(adapter)
-    const agent = ctx.agentLoop.create(AgentId('bad-policy'), { provider: 'mock', model: 'mock' })
+    const agent = ctx.agentLoop.create(SessionId('bad-policy'), { provider: 'mock', model: 'mock' })
     const reasons: TurnEndReason[] = []
     const errors: string[] = []
     ctx.on('session/event', (session, event) => {

packages/core/agent/README.md

@@ -1,37 +1,50 @@
 # dsh-agent
 
-Agent interface, registry, and `agent/*` event vocabulary. Every plugin (UI, hooks, orchestrators) programs against the `Agent` handle defined here — it has zero loop dependency, so the loop is swappable.
+Agent interface, registry, process-local initiator scope, and `agent/*` event vocabulary. Every plugin (UI, hooks, orchestrators) programs against the `Agent` handle defined here — it has zero loop dependency, so the loop is swappable.
 
 ## Service: `AgentRegistry` (ctx key: `agents`)
 
-Tracks live agents so UI, hook, and orchestrator plugins can find them without importing the concrete loop package.
+Tracks live agents and carries the initiating Agent through asynchronous driver work without importing the concrete loop package.
 
 ### Public API
 
-`Agent.ctx` owns registrations visible only to that agent. `agentEvents()` couples event subjects to their scope carrier, and `assembleContextFor()` couples the agent and prompt scope. Creation and resume may compose this context through `setup`; the agent remains unpublished and must not be driven until creation resolves.
+The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-scope`, key = the agent) — register tools/sections/variables/listeners through it for that agent alone, all unwound on disposal. `agentEvents(ctx, agent)` is the fused dispatcher for ordinary agent-subject operations (carrier + injected subject in one move); its notification mode invokes every listener and contains both synchronous throws and returned-promise rejections. The registry lifecycle pair reuses one stable routing carrier. `assembleContextFor(agent)` builds the per-agent assembly context (`agent` + `scope` together). `CreateAgentOptions.setup(agentCtx)` and `ResumeAgentOptions.setup(agentCtx)` compose a fresh or resumed agent's scoped world while both objects remain unpublished. Setup is trusted, composition-only same-process code: drive the agent only after creation resolves.
 
 - `ctx.agents.register(agent: Agent): () => void` — record an **already-constructed** agent. Disposed with the calling fiber.
-- Advanced factory lifecycle: `enter(agent)` publishes without announcing and returns an entry-bound detach; `announce(agent)` emits creation once. Detach during creation dispatch is deferred. Ordinary plugins use `register()`.
-- `ctx.agents.get(id: AgentId): Agent | undefined`
+- Advanced ordered lifecycle: `enter(agent, owner): () => void` enforces `agent.id === agent.session.id`, performs the authoritative ID collision check, and inserts without announcing; `owner` explicitly records the live creator-agent relation (or `undefined` for a root), independently of durable session lineage. `announce(agent)` emits `agent/created` exactly once. A detach requested synchronously by a creation listener is deferred until that dispatch unwinds, and every detach checks the captured entry object, so a stale capability cannot delete a later same-ID replacement. The async factory uses this split; ordinary plugins use `register()`.
+- `ctx.agents.get(id: SessionId): Agent | undefined`
+- `ctx.agents.isOwnedBy(id: SessionId, owner: Agent): boolean` — whether the exact live entry was created through that parent agent's scoped context; runtime ownership is independent of durable session lineage.
 - `ctx.agents.list(): Agent[]`
+- `ctx.agents.roots(): Agent[]` — live agents created without an owning agent context; a resumed lineage-bearing session can still be a runtime root.
+
+#### Initiating Agent scope
+
+`AgentLoop` runs each concrete driver's complete lifetime inside an initiator boundary. Concurrent drivers remain isolated: a child driver's continuations carry the child, while the parent continuation regains the parent as soon as `withInitiator()` returns; drain tracking continues until the child driver's Promise settles. Creation, persistence load, and unpublished setup remain outside the child's boundary, so setup initiated by a parent inherits the parent while `agentCtx.agent` identifies the child explicitly.
+
+- `ctx.agents.currentInitiator(): Agent | undefined` — read the inherited initiator without requiring one.
+- `ctx.agents.requireInitiator(): Agent` — read it or throw `no initiating agent is active`.
+- `ctx.agents.withInitiator(agent, operation)` — run with one exact Agent and preserve the operation's exact synchronous value or Promise.
+- `ctx.agents.withoutInitiator(operation)` — hide an inherited initiator for unrelated process-local work.
+
+The scope carries the `Agent` itself and is process-local. Ambient presence is neither liveness proof nor authorization; explicit Agent fields remain authoritative at service, worker, process, persistence, and wire boundaries. Teardown rejects new boundaries, lets injected dependents and returned-Promise boundaries drain, then disables the underlying `AsyncLocalStorage`; unreturned work remains owned by the subsystem that detached it. If a boundary's inherited async chain starts an owning Cordis fiber's unload, that nested boundary chain is released from the drain so the unload cannot wait on itself; its continuations observe the disposed service after teardown. The [initiator-scope decision](../../../docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.md) owns the detailed boundary and teardown contract.
 
 #### Factory seam (creation)
 
-The loop plugin registers `AgentFactory`, keeping consumers independent of its concrete package. Each call is traced through the caller's context so the caller owns the resulting transaction and handle.
+Agent *creation* is provided by the plugin implementing `AgentFactory` (`dsh-agent-loop`), registered via `setFactory`. This keeps creation on the `dsh-agent` interface so consumers (UI, the ACP bridge) program against `ctx.agents` without depending on the concrete loop package. The registry canonicalizes an already traced Service to its concrete target and re-traces each call through the caller's context; this avoids nested Cordis shadows while passing an explicit caller-bound `ownerCtx` to plain factories.
 
 - `ctx.agents.setFactory(factory: AgentFactory): () => void` — register the creation factory (the loop calls this on construction). Throws on a second factory; the slot clears on dispose.
-- `ctx.agents.create(options)` creates and composes an unpublished session and agent, then atomically enters the registries and starts the loop. A creation-only signal cancels before publication; same-ID contenders arbitrate at entry and losers roll back.
-- `ctx.agents.resume(options)` loads a persisted session and follows the same composition and publication boundary. It requires [session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md).
+- `ctx.agents.create(options: CreateAgentOptions): Promise<AgentHandle>` — create a session and agent, await optional setup while unpublished, then publish through final `SessionStore.enter()` and `AgentRegistry.enter()` checks. Concurrent same-ID creation is unsupported: more than one operation may prepare, but only one can enter; every loser rolls its private scope/session/driver back. An optional creation-only `signal` cancels unpublished setup and is detached before the handle is returned; later cancellation uses `handle.dispose()` or `agent.cancel()`. Publication is rollback-covered and every delivered creation edge is paired during rollback. Rejects if no factory is registered.
+- `ctx.agents.resume(options: ResumeAgentOptions): Promise<AgentHandle>` — load a persisted session ([session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md)), mint a fresh unpublished agent scope, await optional setup, and use the same final-entry publication sequence. Its optional `signal` is likewise creation-only. Rejects if no factory is registered or session persistence is unconfigured.
 
-`AgentHandle = { agent, dispose }` is the consumer teardown capability; registry observers receive only the bare agent. Disposal stops and drains the loop and idle-injection flushes before unregistering the agent, detaching its session, and unwinding its scope. Caller and factory unload share that memoized boundary.
+`AgentHandle = { agent: Agent; dispose(): Promise<void> }`. The disposer is a **consumer capability** — no observer holding the bare registry entry can tear the agent down. The caller fiber and the registered factory provider are structural co-owners: caller unload enforces structured ownership, while factory unload must stop old instances because their scoped dependency surface belongs to that provider. `dispose()` from any owner reaches one memoized quiescence boundary: it stops the loop, `await`s its exit plus every outstanding idle-injection flush (not just the `disposed` status flip), unregisters the agent, removes its session from the store, and finally unwinds its scoped world. This order captures every agent-started `session/flush` before the session is detached and keeps scoped listeners alive through those checkpoints. `ctx.agents.get(id)` still returns a bare `Agent`; the ACP bridge and in-process subagent backends hold consumer handles, while config-created agents are already owned by the loop fiber.
 
 ### Live events
 
 `dsh-agent` declares the live `agent/*` coordination vocabulary so plugins do not depend on the concrete loop. Exact signatures, dispatch modes, scope-filtering rules, and payload contracts live in the generated [Cordis event catalog](../../../docs/cordis-catalog/events.md); the [architecture turn flow](../../../docs/architecture.md#turn-flow) shows their order relative to durable session events.
 
-`agent/created` runs after setup and both registry entries; the following `agent/session-start` is the first supported startup injection point. `agent/disposed` means the exact entry left the registry. The loop quiesces its driver first; directly registered custom agents own any stronger ordering.
+The lifecycle edges have two important local caveats. `agent/created` runs after scoped setup and after both session and agent registry entries exist. Setup is trusted composition-only code; the immediately following non-vetoing `agent/session-start` notification is the first supported startup injection point. `agent/disposed` always means the exact agent has left the registry. AgentLoop emits it after its driver is quiescent, while ordered teardown may still be detaching the session and unwinding the scope; custom agents registered directly own any stronger driver-ordering contract themselves.
 
-Most interception points are cooperative waterfalls returning seam-specific decisions. `agent/pre-step` is a serial surface-mutation checkpoint, while `agent/turn-stop` is the terminal serial fold: it runs after ordinary continuation and steering folding, and a returned stop remains in force through turn close and flush so later steering cannot create an extra step or turn. Ordinary queued prompts remain intact. The full rationale is in the [agent-scope runtime-design RFC](../../../docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way).
+Most interception points are cooperative waterfalls returning seam-specific decisions. `agent/pre-step` and `agent/post-step` are serial checkpoints around a step's durable work, while `agent/request-error` is the failed-model-request recovery waterfall: a retry opens a new numbered step after the failed step closes. `agent/turn-stop` is the terminal serial fold: it runs after ordinary continuation and steering folding, and a returned stop remains in force through turn close and flush so later steering cannot create an extra step or turn. Ordinary queued prompts remain intact. The full rationale for scoped dispatch and terminal settlement is in the [agent-scope runtime-design RFC](../../../docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way).
 
 `PromptDecision.additionalContexts` is an array so every injected context keeps its own source, envelope, and metadata. A `ContinuationDecision` reason is narrower: it becomes a `steering/message`, not a `context/message`, and therefore carries only content and source.
 
@@ -58,18 +71,36 @@ The handle every plugin programs against:
 
 ### User, steering, and injected messages
 
-**What the model sees**: `send`, `steer`, and `inject` feed the owning session. `agent/prompt-submit`, `agent/session-prefix`, and other declared events let plugins block a prompt or add request material; this interface contributes no fixed prose itself.
+#### What the model sees
 
-**Token effect**: Accepted content becomes retained history or a repeated session prefix; blocked content contributes no request tokens. Size is caller- and plugin-dependent.
+`send`, `steer`, and `inject` feed the owning session. `agent/prompt-submit`, `agent/session-prefix`, and other declared events let plugins block a prompt or add request material; this interface contributes no fixed prose itself.
+
+#### Token effect
+
+Accepted content becomes retained history or a repeated session prefix; blocked content contributes no request tokens. Size is caller- and plugin-dependent.
+
+#### KV Cache effect
+
+Accepted history and steering are append-only; a blocked submission sends no request. A session prefix remains stable within its loop instance, while a new or resumed instance may establish a different prefix.
 
 ### Agent-scoped request composition
 
-**What the model sees**: Registrations through `agent.ctx` can shadow prompt sections or tools and can install agent-only interceptors during unpublished setup.
+#### What the model sees
 
-**Token effect**: The package adds zero tokens itself; scoped contributions affect only that agent and disappear on disposal.
+Registrations through `agent.ctx` can shadow prompt sections or tools and can install agent-only interceptors during unpublished setup.
+
+#### Token effect
+
+The package adds zero tokens itself; scoped contributions affect only that agent and disappear on disposal.
+
+#### KV Cache effect
+
+Prefix-stable while an agent's scoped registrations are unchanged. Setup or reload that changes prompt sections, tool definitions, or request listeners may invalidate reuse from the first affected request token.
 
 ## Known Limitations and Deferred Work
 
+- **Initiator scope is process-local** — workers, child processes, HTTP, durable queues, and restarts materialize any required identity explicitly.
+- **Ambient identity may outlive liveness** — consumers still check `agent.status`, cancellation, and the owning capability contract before lifecycle-sensitive work.
 - **Inter-agent channels beyond delegation** — shared state, streaming child output, and background/poll semantics remain outside the current synchronous `ctx.subagents` seam.
 - **`agent/session-start` cannot gate startup** — it remains a synchronous, veto-less notification; async composition that must finish before publication belongs in the factory's `setup(agentCtx)` transaction instead.
 - **No public step-only abort** — `cancel()` clears ALL pending work (queued + steering + in-flight); an abort that preserves queued prompts returns only with a named consumer ([stop-surface RFC](../../../docs/rfc/implemented/simplification/2026-06-20-public-agent-stop-surface.md)).

packages/core/agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-agent",
-  "description": "Agent interface, registry, and event vocabulary for the DeepSeek Harness",
+  "description": "Agent interface, registry, initiator scope, and event vocabulary for the DeepSeek Harness",
   "version": "0.0.1",
   "private": true,
   "type": "module",

packages/core/agent/src/index.ts

@@ -1,15 +1,18 @@
 /**
- * Agent registry service. Tracks live agents so plugins can find them without
- * depending on the concrete loop package. Agent creation belongs to the loop.
+ * Agent service: live registry, factory delegation, and process-local
+ * initiator scope. Concrete creation and driving belong to the loop.
  *
  * @module @deepseek-ai/dsh-agent
  */
 
-import { Context, getTraceable, Service, symbols } from 'cordis'
+import { Context, FiberState, getTraceable, Service, symbols } from 'cordis'
+import type { Fiber } from 'cordis'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { isPromise } from 'node:util/types'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
-import type { Agent, AgentId, AgentOptions } from './types.ts'
+import type { Agent, AgentOptions } from './types.ts'
 
 export * from './types.ts'
 export { agentEvents, assembleContextFor } from './dispatch.ts'
@@ -31,23 +34,57 @@ declare module 'cordis' {
   }
 }
 
-/** Options for creating an agent and its caller-named session. */
+/**
+ * Options for programmatically creating an agent through the registry factory
+ * ({@link AgentRegistry.create}). The caller supplies the single live
+ * `sessionId` shared by the agent registry and session log (e.g. an
+ * ACP-generated id), plus optional session metadata (the validated `cwd`, fork
+ * lineage); the factory creates the session and agent under that identity.
+ */
 export interface CreateAgentOptions {
-  /** The agent's id (the registry handle). */
-  readonly agentId: AgentId
-  /** The live session's id (NOT derived from agentId). */
+  /** The live agent/session identity. */
   readonly sessionId: SessionId
-  /** Durable session metadata, validated and detached before setup. */
+  /**
+   * Session creation metadata: validated absolute `cwd`, `parentSession`
+   * fork lineage, and the `seedLength` seed boundary. Mirrors the
+   * `cwd`/`parentSession`/`seedLength` fields of
+   * {@link CreateSessionOptions.meta} in dsh-session (the internal-only
+   * `createdAt`, used when reconstructing a persisted session, is deliberately
+   * excluded — a factory caller never sets it). This is durable session data,
+   * so the session boundary validates and snapshots it before asynchronous
+   * setup begins.
+   */
   readonly meta?: { readonly cwd?: string; readonly parentSession?: SessionId; readonly seedLength?: number }
-  /** Balanced contiguous event prefix for a forked session. */
+  /**
+   * Seed events to reconstruct the child session's log from (the fork lineage
+   * primitive). When present, the factory creates the session with this event
+   * prefix so `deriveMessages()`/`lastTurnNumber` continue from it — used by the
+   * in-process FORK subagent backend to seed a child with a balanced
+   * completed-turn prefix of the parent's log. The prefix MUST be contiguous
+   * from seq 0, carry only lossless-JSON data, and be balanced (no open
+   * turn/step, no dangling tool-call), or the session constructor (and the
+   * dev-mode invariants replay) reject it. The factory passes the raw seed to
+   * the session's durable validator/snapshot boundary. Absent for a fresh
+   * (spawn) child.
+   */
   readonly seed?: readonly SessionEvent[]
   /** Per-agent options (model, …). */
   readonly agentOptions?: AgentOptions
   /** Optional creation-only cancellation signal; detached before the returned handle becomes visible. */
   readonly signal?: AbortSignal
   /**
-   * Compose the unpublished scoped context before lifecycle announcements.
-   * Failure rolls back without publishing either id; setup must not drive the agent.
+   * Creation-time composition of the agent's scoped world. The factory awaits
+   * setup after minting `agentCtx` but BEFORE inserting or announcing either
+   * the session or agent, so observers can never see a partially configured
+   * world. Everything registered through `agentCtx` (scoped tools, prompt
+   * sections/variables, `restrict()`, listeners, awaited child plugins) exists
+   * before `session/created`, `agent/created`, `agent/session-start`, and the
+   * first prompt assembly. A throw/rejection or owner disposal rolls the scope
+   * back without publishing either id.
+   *
+   * **Setup composes, it never drives**: the callback is trusted same-process
+   * code and receives the full scoped context, so this is a contract rather
+   * than a runtime restriction. Drive the agent only after creation resolves.
    */
   readonly setup?: (agentCtx: Context) => Promise<void> | void
 }
@@ -57,23 +94,41 @@ export interface CreateAgentOptions {
  * ({@link AgentRegistry.resume}).
  */
 export interface ResumeAgentOptions {
-  /** The agent's id (the registry handle). */
-  readonly agentId: AgentId
-  /** The persisted session id to load and resume on. */
+  /** The persisted session id to load and use as the live agent/session identity. */
   readonly resumeSessionId: SessionId
   /** Per-agent options (model, …). */
   readonly agentOptions?: AgentOptions
   /** Optional creation-only cancellation signal for persistence load/setup; detached before return. */
   readonly signal?: AbortSignal
-  /** Compose after persistence load under the same unpublished rollback contract as create. */
+  /**
+   * Resume-time composition of the agent's fresh scoped world. Persistence is
+   * loaded first; the factory then mints `agentCtx` and awaits setup while the
+   * reconstructed session and agent remain unpublished. The callback has the
+   * same trusted composition-only contract as
+   * {@link CreateAgentOptions.setup}: all registrations exist before either
+   * creation announcement, and rejection or owner disposal rolls the
+   * transaction back without publishing either id.
+   */
   readonly setup?: (agentCtx: Context) => Promise<void> | void
 }
 
 /**
- * Holder-owned agent capability. Disposal stops and drains the loop and idle
- * flushes before unregistering the agent, detaching its session, and unwinding
- * its scoped context. Provider unload reaches the same quiescence boundary;
- * registry observers receive only the bare {@link Agent}.
+ * An owned agent plus its disposer, returned by {@link AgentRegistry.create} /
+ * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: among consumers,
+ * only the holder can tear this agent down. The registered factory provider is
+ * also a structural owner because the scoped agent depends on that provider's
+ * service surface; provider unload stops and drains every live handle it made.
+ * `dispose()` stops the loop, awaits its exit and every outstanding
+ * idle-injection flush (quiescence — NOT just the `disposed`
+ * status flip), unregisters the agent, removes its session from the store, and
+ * finally unwinds its scoped world. This order captures every agent-started
+ * `session/flush` before the session is detached and keeps scoped listeners
+ * alive through those checkpoints.
+ *
+ * `ctx.agents.get(id)` still returns a bare {@link Agent} — the handle is
+ * exposed only to the consumer owner that created it; the structural provider
+ * reaches the same teardown internally. Config-created agents (the loop's own
+ * startup) are owned by the loop fiber and never need a handle.
  */
 export interface AgentHandle {
   agent: Agent
@@ -88,16 +143,30 @@ export interface AgentHandle {
  */
 export interface AgentFactory {
   /**
-   * Create and compose under caller ownership, publish and announce session then
-   * agent, emit session-start, and start the driver. Rollback pairs any creation
-   * announcement that began.
+   * Create a new agent on a caller-supplied session id. Async because creation
+   * awaits unpublished setup, inserts both session and agent, emits their
+   * creation notifications in order, emits `agent/session-start`, and only
+   * then starts the loop. The sequence is
+   * rollback-covered, but notifications delivered before a later listener
+   * failure remain observable; every agent or session creation announcement
+   * that began is paired by `agent/disposed` or `session/disposed` during
+   * rollback. The owner disposes the resolved handle to stop/drain,
+   * unregister, remove the session, and unwind the scope.
+   * The registry passes a context carrying the `create()` caller's fiber and
+   * scope as `ownerCtx`. The implementation attaches the unpublished
+   * transaction and resulting lifecycle to that owner; it must not infer
+   * ownership from the factory object's registration context.
    * @param ownerCtx - caller-bound context that owns the transaction and live handle.
    * @param options - agent/session identity, configuration, and optional setup.
    * @returns the owned handle after setup, both announcements, and loop start complete.
    */
   createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>
   /**
-   * Load, compose, publish, announce, and resume an agent under caller ownership.
+   * Load a persisted session and resume an agent on it. Async because it awaits
+   * both `ctx.sessionPersistence.load` and the optional unpublished setup
+   * transaction; must be called after that service exists (consumers inject
+   * `sessionPersistence`). Publication follows the same ordered boundary as
+   * {@link createAgent}.
    * @param ownerCtx - caller-bound context that owns load, setup, and the live handle.
    * @param options - persisted identity, configuration, and optional setup.
    * @returns the owned handle after setup, both announcements, and loop start complete.
@@ -107,57 +176,160 @@ export interface AgentFactory {
 
 /** Thrown when create/resume is called before an agent factory is registered. */
 const NO_FACTORY_MESSAGE = 'no agent factory registered (load an agent-loop plugin)'
+const NO_INITIATOR_MESSAGE = 'no initiating agent is active'
+const DISPOSED_INITIATOR_MESSAGE = 'agent initiator scope is disposed'
 
 /** All mutable lifecycle state for one exact registry entry. */
 interface AgentEntry {
-  readonly id: AgentId
+  readonly id: SessionId
   readonly agent: Agent
+  /** Runtime creator-agent ownership; independent of durable session lineage. */
+  readonly owner: Agent | undefined
   readonly carrier: Scoped<Agent>
   announced: boolean
   announcing: boolean
   detachRequested: boolean
 }
 
+/** One tracked boundary plus its inherited nesting chain. */
+interface InitiatorRun {
+  active: boolean
+  readonly parent: InitiatorRun | undefined
+}
+
 /** Plain holder prevents Cordis from tracing the factory field before the caller context is known. */
 interface FactorySlot {
   readonly target: AgentFactory
 }
 
 /**
- * Agent registry (`ctx.agents`): tracks live agents so UI, hook, and
- * orchestrator plugins can find them without depending on the concrete loop
- * package. Agent *creation* is provided by whichever plugin implements the
- * {@link AgentFactory} (`@deepseek-ai/dsh-agent-loop`), registered via
- * {@link setFactory}.
+ * Agent service (`ctx.agents`): tracks live agents and carries the initiating
+ * Agent through one process-local asynchronous driver chain. Agent *creation*
+ * is provided by whichever plugin implements the {@link AgentFactory}
+ * (`@deepseek-ai/dsh-agent-loop`), registered via {@link setFactory}.
+ *
+ * Initiator methods provide same-process causal attribution only. Ambient
+ * presence is neither liveness proof nor authorization; subjects and owners
+ * remain explicit, as does identity at worker, process, persistence, and wire
+ * boundaries. Returned Promise boundaries drain during teardown, except a
+ * nested lineage that starts an owning-fiber unload is excluded from its own drain.
  */
 export class AgentRegistry extends Service {
-  private store = new Map<AgentId, AgentEntry>()
-  // TODO(agent-entry-mirror): derive exact-object checks from store.get(agent.id)
-  // plus entry.agent identity; this WeakMap mirrors the authoritative id map.
-  private entries = new WeakMap<Agent, AgentEntry>()
+  private store = new Map<SessionId, AgentEntry>()
   private factory: FactorySlot | undefined
+  private readonly initiators = new AsyncLocalStorage<Agent | undefined>()
+  private readonly initiatorRuns = new AsyncLocalStorage<InitiatorRun>()
+  private initiatorState: 'active' | 'closing' | 'disposed' = 'active'
+  private activeInitiatorRuns = 0
+  private initiatorDrain: PromiseWithResolvers<void> | undefined
+  private initiatorDisposal: Promise<void> | undefined
 
   constructor(ctx: Context) {
     super(ctx, 'agents')
-    // Agent contexts shadow this plain-context default with an own property.
+    // The `ctx.agent` DX accessor: default `undefined` on every context, so a
+    // plain plugin context reads cleanly instead of hitting the Cordis
+    // unknown-property throw. Each Agent.ctx shadows it with an own property
+    // (own properties resolve before the context proxy is consulted), so the
+    // accessor body never needs to resolve a scope itself. Effect-scoped:
+    // unwinds with this service's fiber.
     ctx.accessor('agent', { get: () => undefined })
+    ctx.on('internal/status', (fiber) => {
+      if (fiber.state === FiberState.UNLOADING && this.hasLifecycleAncestor(fiber)) {
+        this.closeInitiators()
+      }
+    })
+    ctx.effect(function* (this: AgentRegistry) {
+      yield () => this.disposeInitiators()
+      yield () => { this.closeInitiators() }
+    }.bind(this), 'agents.initiatorLifecycle()')
   }
 
   /**
-   * Register the effect-scoped creation factory, rejecting a duplicate. Service
-   * factories are retraced through each create/resume caller for ownership.
+   * Read the Agent that initiated the inherited asynchronous driver chain.
+   * Use this optional form for logging, tracing, metrics, or host attribution
+   * that also supports agentless calls. When a parent creates a child, setup
+   * reports the causal parent while `agentCtx.agent` identifies the child.
+   * @returns the inherited Agent, or `undefined` outside an initiator boundary
+   *   and inside an explicit clearing boundary.
+   * @throws when this service instance has been disposed.
+   */
+  currentInitiator(): Agent | undefined {
+    this.assertInitiatorsReadable()
+    return this.initiators.getStore()
+  }
+
+  /**
+   * Read the initiating Agent and fail when no initiator boundary is active.
+   * Use this for private helpers contractually below a driver, or for a
+   * deployment-owned outbound request whose contract forbids agentless calls.
+   * Generic or direct-call seams use optional lookup or explicit request fields.
+   * @returns the inherited Agent.
+   * @throws when no initiator is active or this service instance has been disposed.
+   */
+  requireInitiator(): Agent {
+    const agent = this.currentInitiator()
+    if (agent === undefined) throw new Error(NO_INITIATOR_MESSAGE)
+    return agent
+  }
+
+  /**
+   * Run an operation with one exact Agent as its process-local initiator. The
+   * exact synchronous value or Promise returned by the operation is preserved.
+   * Custom drivers and test harnesses wrap their complete returned foreground
+   * lifetime.
+   * A queue or wire receiver may establish this boundary only after validating
+   * explicit identity and resolving the exact live Agent; this method does neither.
+   * Detached work remains owned by the subsystem that starts it.
+   * @param agent - initiating Agent to inherit; presence is neither liveness proof nor authorization.
+   * @param operation - synchronous or asynchronous operation to invoke.
+   * @returns the exact value returned by `operation`.
+   * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+   */
+  withInitiator<T>(agent: Agent, operation: () => T): T {
+    return this.runWithInitiator(agent, operation)
+  }
+
+  /**
+   * Run an operation inside a boundary that hides any inherited initiating
+   * Agent. The exact synchronous value or Promise is preserved.
+   * Use this while creating lazy shared timers, queue pumps, pool maintenance,
+   * watchers, or exporters so they do not inherit the first Agent that happens
+   * to initialize them. It clears only initiator attribution, not explicit
+   * fields, and does not own or drain detached resources.
+   * @param operation - synchronous or asynchronous operation to invoke without an initiator.
+   * @returns the exact value returned by `operation`.
+   * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+   */
+  withoutInitiator<T>(operation: () => T): T {
+    return this.runWithInitiator(undefined, operation)
+  }
+
+  /**
+   * Register the agent-creation factory (the loop calls this on construction,
+   * effect-scoped). A traced Cordis service is canonicalized to its concrete
+   * target; each create/resume call is then traced through that caller's
+   * context so ownership follows the caller without stacking proxy layers.
+   * Throws if a factory is already registered. Returns the disposer; on
+   * dispose the factory slot is cleared.
    * @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
-   * @returns the exact Cordis effect disposer.
+   * @returns the disposer that clears the factory slot. The exact
+   *   Cordis effect disposer (single-shot): composite (generator) effects may
+   *   yield it directly — exact identity nests the teardown in order.
    */
   setFactory(factory: AgentFactory): () => void {
     const dispose = this.ctx.effect(() => {
       if (this.factory !== undefined) throw new Error('an agent factory is already registered')
-      // Store the concrete service; calls are retraced through their owner.
+      // Avoid stacking two Cordis shadow layers when a caller passes a Service
+      // already read through a context. Calls are re-traced through their
+      // actual owner context below.
       const target = (factory as AgentFactory & { [symbols.original]?: AgentFactory })[symbols.original] ?? factory
       this.factory = { target }
       return () => { this.factory = undefined }
     }, 'agents.setFactory()')
-    // Return the exact disposer so composite effects preserve teardown order.
+    // The exact cordis effect disposer (the agents.register() convention): a
+    // caller's composite effect can yield it for in-order teardown; the
+    // loop's constructor effect returns it directly, identity-nesting the
+    // registration under that effect.
     // eslint-disable-next-line @typescript-eslint/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
     return dispose
   }
@@ -169,14 +341,20 @@ export class AgentRegistry extends Service {
   }
 
   /**
-   * Create and publish an owned agent and session through the active factory.
-   * Rejects if no factory is registered or creation, setup, or publication fails.
-   * @param options - agent id, session id/seed/metadata, and agent options.
+   * Create and publish a new agent through the registered factory.
+   * Distinct from {@link register} (which records an already-constructed
+   * agent): this constructs the agent and its session. Rejects if no factory is
+   * registered or creation/setup fails. The resolved {@link AgentHandle} lets
+   * the owner tear down exactly this agent.
+   * @param options - shared identity, session seed/metadata, and agent options.
    * @returns the handle after setup, rollback-covered publication, and loop start complete.
    */
   async create(options: CreateAgentOptions): Promise<AgentHandle> {
     const ownerCtx = this.ctx
-    // Bind service effects to this caller while preserving factory dependencies.
+    // Re-trace a Service-backed factory through the accessing context
+    // explicitly. This preserves AgentLoop's dependency origin while binding
+    // its effects to ownerCtx; plain factories receive ownerCtx as an explicit
+    // capability and need no Cordis tracker magic.
     const { target } = this.requireFactory()
     const receiver = getTraceable(ownerCtx, target)
     // eslint-disable-next-line @typescript-eslint/unbound-method -- Reflect.apply intentionally supplies the caller-traced receiver
@@ -199,14 +377,26 @@ export class AgentRegistry extends Service {
   }
 
   /**
-   * Register a live agent in the calling effect scope, with scope-filtered
-   * creation and disposal events. Duplicate ids throw.
+   * Register a live agent. Throws if an agent with the same id is already
+   * registered. Emits `agent/created` on registration and `agent/disposed`
+   * when the calling fiber is disposed — both with the agent's scope carrier
+   * (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
+   * emits are scope-filtered regardless of which context invoked `register`
+   * (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
+   * requires passing the carrier). Returns the disposer.
    * @param agent - the already-constructed agent to record in the store.
-   * @returns the exact Cordis effect disposer for nested teardown ordering.
+   * @returns the EXACT Cordis effect disposer (single-shot; a repeat call
+   *   returns undefined without awaiting an in-flight teardown). Exact
+   *   identity is load-bearing: a composite (generator) effect that owns a
+   *   teardown ORDER — the agent factory's lifecycle chain — must yield THIS
+   *   function so Cordis nests the unregistration at that yield position;
+   *   yielding a wrapper would leave it disposing as a concurrent sibling on
+   *   owner unload, unregistering the agent (and emitting `agent/disposed`)
+   *   while its final turn is still draining.
    */
   register(agent: Agent): () => void {
     const dispose = this.ctx.effect(function* (this: AgentRegistry) {
-      yield this.enter(agent)
+      yield this.enter(agent, this.ctx.agent)
       this.announce(agent)
     }.bind(this), 'agents.register()')
     // eslint-disable-next-line @typescript-eslint/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
@@ -214,31 +404,48 @@ export class AgentRegistry extends Service {
   }
 
   /**
-   * Insert an unpublished agent for an ordered factory transaction.
+   * Insert an already-constructed agent without announcing it. This is the
+   * advanced ordered-lifecycle primitive used by the async agent factory: it
+   * first completes setup while the agent is unpublished, then assigns the
+   * returned detach closure into its pre-installed composite teardown before
+   * calling {@link announce}. Ordinary callers use {@link register}.
    * @param agent - the prepared, unpublished agent.
-   * @returns an idempotent closure that removes this exact entry and emits the
-   * paired disposal edge; detachment during creation dispatch is deferred.
+   * @param owner - live agent whose scoped context created this agent, or
+   *   undefined for a top-level runtime root. This is runtime ownership, not
+   *   the resumed session's durable parent lineage.
+   * @returns an idempotent closure that removes this exact entry and emits
+   *   `agent/disposed` with listener failures contained. When called from a
+   *   synchronous `agent/created` listener, removal and disposal wait until
+   *   that creation dispatch unwinds.
    */
-  enter(agent: Agent): () => void {
+  enter(agent: Agent, owner: Agent | undefined): () => void {
     const id = agent.id
+    if (id !== agent.session.id) {
+      throw new Error(`agent id "${id}" does not match session id "${agent.session.id}"`)
+    }
     const carrier = scopeTarget(agent, agent)
-    // Prepared transactions arbitrate identity at this publication boundary.
-    if (this.entries.has(agent) || this.store.has(id)) throw new Error(`agent "${id}" is already registered`)
+    // This is the authoritative collision boundary. Concurrent create/resume
+    // operations may both prepare, but only one exact entry can publish.
+    if (this.store.has(id)) throw new Error(`agent "${id}" is already registered`)
     const entry: AgentEntry = {
       id,
       agent,
+      owner,
       carrier,
       announced: false,
       announcing: false,
       detachRequested: false,
     }
     this.store.set(id, entry)
-    this.entries.set(agent, entry)
     let entered = true
     const detach = (): void => {
       if (!entered) return
       entered = false
-      // Creation listeners observe one stable entry before paired disposal.
+      // Every callback reached by this creation dispatch must observe the same
+      // live entry, and disposal must follow creation. A listener may own
+      // the advanced detach capability, so make that ordering structural:
+      // visibility and the paired disposal are deferred until announce()'s
+      // synchronous dispatch has unwound.
       if (entry.announcing) {
         entry.detachRequested = true
         return
@@ -256,7 +463,6 @@ export class AgentRegistry extends Service {
     /* v8 ignore next -- enter() rejects replacement while this single-shot detach capability is live. */
     if (this.store.get(entry.id) !== entry) return
     this.store.delete(entry.id)
-    this.entries.delete(entry.agent)
     // An insertion rolled back before announce was never externally created,
     // so emitting disposed would invent an impossible lifecycle edge. Marking
     // happens before the created emit: if a later created listener throws,
@@ -288,8 +494,8 @@ export class AgentRegistry extends Service {
    *   creation listener).
    */
   announce(agent: Agent): void {
-    const entry = this.entries.get(agent)
-    if (entry === undefined || this.store.get(entry.id) !== entry) {
+    const entry = this.store.get(agent.id)
+    if (entry === undefined || entry.agent !== agent) {
       throw new Error(`agent "${agent.id}" is not live in this registry`)
     }
     if (entry.announced || entry.announcing) {
@@ -318,13 +524,25 @@ export class AgentRegistry extends Service {
 
   /**
    * Look up a live agent.
-   * @param id - the agent id to look up.
+   * @param id - the shared agent/session id to look up.
    * @returns the agent, or undefined when no live agent has that id.
    */
-  get(id: AgentId): Agent | undefined {
+  get(id: SessionId): Agent | undefined {
     return this.store.get(id)?.agent
   }
 
+  /**
+   * Test whether a live agent was created through one exact parent agent's
+   * scoped context. Runtime ownership is independent of durable session
+   * lineage and remains unambiguous when unrelated providers reuse an id.
+   * @param id - the candidate child agent's shared agent/session id.
+   * @param owner - the expected runtime creator agent.
+   * @returns true only while the exact child entry is live under that owner.
+   */
+  isOwnedBy(id: SessionId, owner: Agent): boolean {
+    return this.store.get(id)?.owner === owner
+  }
+
   /**
    * All live agents, in registration order.
    * @returns a fresh array; mutating it does not affect the registry.
@@ -332,6 +550,104 @@ export class AgentRegistry extends Service {
   list(): Agent[] {
     return [...this.store.values()].map(entry => entry.agent)
   }
+
+  /**
+   * All live top-level agents in registration order. A top-level agent was
+   * created without an owning agent context; durable session lineage does not
+   * affect this runtime relation, so a resumed fork may still be a root.
+   * @returns a fresh array; mutating it does not affect the registry.
+   */
+  roots(): Agent[] {
+    return [...this.store.values()]
+      .filter(entry => entry.owner === undefined)
+      .map(entry => entry.agent)
+  }
+
+  /** Reject new initiator boundaries while inherited continuations drain. */
+  private closeInitiators(): void {
+    if (this.initiatorState === 'active') this.initiatorState = 'closing'
+  }
+
+  /** Wait for returned-Promise boundaries, then invalidate retained references. */
+  private disposeInitiators(): Promise<void> {
+    return (this.initiatorDisposal ??= (async () => {
+      this.closeInitiators()
+      this.releaseReentrantInitiatorRuns()
+      if (this.activeInitiatorRuns !== 0) {
+        this.initiatorDrain ??= Promise.withResolvers<void>()
+        await this.initiatorDrain.promise
+      }
+      this.initiatorState = 'disposed'
+      this.initiators.disable()
+      this.initiatorRuns.disable()
+    })())
+  }
+
+  /** Establish one tracked initiator or clearing boundary. */
+  private runWithInitiator<T>(agent: Agent | undefined, operation: () => T): T {
+    if (this.initiatorState !== 'active') throw new Error(DISPOSED_INITIATOR_MESSAGE)
+    const run: InitiatorRun = {
+      active: true,
+      parent: this.initiatorRuns.getStore(),
+    }
+    this.activeInitiatorRuns += 1
+    let result: T
+    try {
+      result = this.initiatorRuns.run(run, () => this.initiators.run(agent, operation))
+    } catch (error: unknown) {
+      this.releaseInitiatorRun(run)
+      throw error
+    }
+    if (isPromise(result)) {
+      try {
+        void Promise.prototype.then.call(
+          result,
+          () => { this.releaseInitiatorRun(run) },
+          () => { this.releaseInitiatorRun(run) },
+        )
+      } catch {
+        // A branded Promise may expose a failing @@species. Observer setup did
+        // not attach, so preserve the exact return without leaking the run.
+        this.releaseInitiatorRun(run)
+      }
+    } else {
+      this.releaseInitiatorRun(run)
+    }
+    return result
+  }
+
+  /** Whether one unloading fiber owns this service's lifecycle. */
+  private hasLifecycleAncestor(candidate: Fiber): boolean {
+    let fiber = this.ctx.fiber
+    while (true) {
+      if (fiber === candidate) return true
+      const parent = fiber.parent.fiber
+      if (parent === fiber) return false
+      fiber = parent
+    }
+  }
+
+  private assertInitiatorsReadable(): void {
+    if (this.initiatorState === 'disposed') throw new Error(DISPOSED_INITIATOR_MESSAGE)
+  }
+
+  /** Exclude the boundary chain that initiated this teardown from its own drain. */
+  private releaseReentrantInitiatorRuns(): void {
+    let run = this.initiatorRuns.getStore()
+    while (run !== undefined) {
+      this.releaseInitiatorRun(run)
+      run = run.parent
+    }
+  }
+
+  private releaseInitiatorRun(run: InitiatorRun): void {
+    if (!run.active) return
+    run.active = false
+    this.activeInitiatorRuns -= 1
+    if (this.activeInitiatorRuns !== 0) return
+    this.initiatorDrain?.resolve()
+    this.initiatorDrain = undefined
+  }
 }
 
 export default AgentRegistry

packages/core/agent/src/types.ts

@@ -5,25 +5,11 @@
  * @module @deepseek-ai/dsh-agent/types
  */
 
-import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { Context } from 'cordis'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { ContentBlock, LlmCallConfig, Message, MessageSource } from '@deepseek-ai/dsh-llm'
+import type { ContextEnvelope, JsonValue, Session, SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-system-prompt'
-
-/** Identifies one live agent in the registry. */
-export type AgentId = Branded<'AgentId'>
-
-/**
- * Brand a string as an {@link AgentId}.
- * @param id - the raw agent id string.
- * @returns the same string, branded (a compile-time cast — no runtime cost).
- */
-export function AgentId(id: string): AgentId {
-  return id as AgentId
-}
-import type { ContextEnvelope, JsonValue, Session } from '@deepseek-ai/dsh-session'
-
 declare module '@deepseek-ai/dsh-system-prompt' {
   interface AssembleContext {
     /** Agent for this assembly; absent on diagnostics. When present, `scope` must identify the same agent. */
@@ -84,6 +70,12 @@ export type ContinuationDecision =
   | { action: 'stop' }
   | { action: 'continue'; reason?: { content: ContentBlock[]; source: MessageSource } }
 
+/** Failed-request recovery decision; `retry` opens another numbered step while listeners delegate by calling `next()`. */
+export type RequestErrorDecision = { action: 'fail' } | { action: 'retry' }
+
+/** Model-request failure with an optional machine-routable provider code. */
+export type RequestError = Error & { code?: string }
+
 /**
  * The terminal subset of {@link ContinuationDecision}. A listener on
  * `agent/turn-stop` returns this to make the already-composed continuation
@@ -94,9 +86,10 @@ export type ContinuationStop = Extract<ContinuationDecision, { action: 'stop' }>
 /** Why a session lifecycle began; seeded creates are `startup`, while persisted loads are `resume`. */
 export type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
 
-/** Public agent handle; the concrete driver belongs to `@deepseek-ai/dsh-agent-loop`. */
+/** Public agent handle; its concrete implementation is internal to `@deepseek-ai/dsh-agent-loop`. */
 export interface Agent {
-  readonly id: AgentId
+  /** The single identity shared with {@link session}. */
+  readonly id: SessionId
   readonly options: AgentOptions
   readonly session: Session
   readonly status: AgentStatus
@@ -198,23 +191,17 @@ declare module 'cordis' {
 
     // ---- step/request extension seams (serial + waterfall) ----
     /**
-     * Awaited serial checkpoint for session-surface mutation after prompt
-     * assembly and before `step/start`; appends land outside the pending step.
-     * The loop derives history once afterward, so compaction records and
-     * replacements are included without rewriting an assembled request. The
-     * prompt and prefix are the exact pressure inputs for that request, and
+     * Awaited serial checkpoint before `step/start`; appends land outside the
+     * pending step and are included when the loop derives request history.
      * `signal` cancels listener work.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @param agent - the agent opening the step.
      * @param turn - the open turn number.
      * @param step - the pending step number.
-     * @param fullSystemPrompt - the assembled prompt.
-     * @param sessionPrefix - the frozen request prefix.
      * @param signal - the turn abort signal.
      * @mode serial
      */
-    // TODO: Move prompt-pressure inputs behind a compaction-specific seam if no second consumer appears.
-    'agent/pre-step'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise<void> | void
+    'agent/pre-step'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal): Promise<void> | void
     /**
      * Allow, rewrite, or block one drained prompt before it becomes a user
      * message. Call `next()` for the unchanged default.
@@ -242,9 +229,9 @@ declare module 'cordis' {
      * result is computed once per loop instance, logged on its anchoring request
      * header, and reused so the provider prefix remains stable. Interrupted
      * composition is discarded. Composition precedes the first `agent/pre-step`
-     * and request boundary, so listener appends join the current request and
-     * pressure accounting sees the composed prefix. Changing context belongs in
-     * history; contributors should prepend to `await next()` to preserve registration order.
+     * and request boundary, so listener appends join the current request.
+     * Changing context belongs in history; contributors should prepend to
+     * `await next()` to preserve registration order.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
      * @param agent - the agent whose session prefix is being composed.
      * @param prefix - the frozen seed; return an extended replacement.
@@ -263,6 +250,32 @@ declare module 'cordis' {
      * @mode waterfall
      */
     'agent/step-result'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, message: Message, next: () => Promise<Message>): Promise<Message>
+    /**
+     * Awaited serial checkpoint after the response, real or synthetic tool
+     * results, injected context, and steering are durable but before `step/end`.
+     * A cancelled tool batch reaches this checkpoint with an aborted signal.
+     * @param agent - the agent whose step is settling.
+     * @param turn - the open turn number.
+     * @param step - the open step number.
+     * @param signal - the turn abort signal.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+     * @mode serial
+     */
+    'agent/post-step'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal): Promise<void> | void
+    /**
+     * Recover a model-request failure after its failed step has closed. `retry`
+     * opens a new numbered step; `fail` preserves the original request error.
+     * Call `next()` to delegate to the next recovery listener or the default.
+     * @param agent - the agent whose request failed.
+     * @param turn - the open turn number.
+     * @param step - the failed step number.
+     * @param error - the original model-request failure.
+     * @param retryAttempt - zero-based number of prior recovery retries.
+     * @param signal - the turn abort signal.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+     * @mode waterfall
+     */
+    'agent/request-error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, retryAttempt: number, signal: AbortSignal, next: () => Promise<RequestErrorDecision>): Promise<RequestErrorDecision>
     /**
      * Override whether the turn continues. The default continues after tool
      * calls or steering and stops otherwise; a continue reason becomes steering.

packages/core/agent/tests/agent-initiator.spec.ts

@@ -0,0 +1,265 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { runInNewContext } from 'node:vm'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
+
+function agent(id: string): Agent {
+  return { id: SessionId(id) } as Agent
+}
+
+async function harness(): Promise<{
+  ctx: Context
+  service: AgentRegistry
+  dispose: () => Promise<void>
+}> {
+  const ctx = new Context()
+  const fiber = await ctx.plugin(AgentRegistry)
+  return {
+    ctx,
+    service: ctx.agents,
+    dispose: fiber.dispose,
+  }
+}
+
+/** Fail a lifecycle regression promptly instead of waiting for Vitest's suite timeout. */
+async function promptly<T>(task: Promise<T>): Promise<T> {
+  const timeout = Promise.withResolvers<never>()
+  const timer = setTimeout(() => { timeout.reject(new Error('initiator teardown did not settle promptly')) }, 1000)
+  try {
+    return await Promise.race([task, timeout.promise])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+describe('AgentRegistry initiator scope', () => {
+  it('reports an absent initiator and requires an active boundary', async () => {
+    const { service, dispose } = await harness()
+    expect(service.currentInitiator()).toBeUndefined()
+    expect(() => service.requireInitiator()).toThrow('no initiating agent is active')
+    await dispose()
+  })
+
+  it('preserves exact synchronous and Promise return identities across await', async () => {
+    const { service, dispose } = await harness()
+    const initiator = agent('identity')
+    const value = { result: true }
+    expect(service.withInitiator(initiator, () => {
+      expect(service.requireInitiator()).toBe(initiator)
+      return value
+    })).toBe(value)
+
+    const promise = service.withInitiator(initiator, async () => {
+      expect(service.requireInitiator()).toBe(initiator)
+      await Promise.resolve()
+      expect(service.requireInitiator()).toBe(initiator)
+      return value
+    })
+    expect(service.withInitiator(initiator, () => promise)).toBe(promise)
+    await expect(promise).resolves.toBe(value)
+    expect(service.currentInitiator()).toBeUndefined()
+    await dispose()
+  })
+
+  it('tracks a branded Promise without calling its overridable then property', async () => {
+    const { service, dispose } = await harness()
+    const initiator = agent('overridden-then')
+    const release = Promise.withResolvers<boolean>()
+    void Object.defineProperty(release.promise, 'then', {
+      value: () => { throw new Error('overridden then called') },
+    })
+
+    const pending = service.withInitiator(initiator, () => release.promise)
+    expect(pending).toBe(release.promise)
+
+    let disposed = false
+    const disposal = dispose().then(() => { disposed = true })
+    await Promise.resolve()
+    expect(disposed).toBe(false)
+
+    release.resolve(true)
+    await new Promise<void>((resolve, reject) => {
+      void Promise.prototype.then.call(pending, resolve, reject)
+    })
+    await disposal
+    expect(disposed).toBe(true)
+  })
+
+  it('preserves a settled branded Promise when its species blocks observer construction', async () => {
+    const { service, dispose } = await harness()
+    const initiator = agent('invalid-species')
+    const promise = Promise.resolve()
+    const constructor = {}
+    Object.defineProperty(constructor, Symbol.species, {
+      get: () => { throw new Error('invalid species') },
+    })
+    void Object.defineProperty(promise, 'constructor', { value: constructor })
+
+    expect(service.withInitiator(initiator, () => promise)).toBe(promise)
+    await dispose()
+  })
+
+  it('isolates overlapping initiators', async () => {
+    const { service, dispose } = await harness()
+    const a = agent('a')
+    const b = agent('b')
+    const bothStarted = Promise.withResolvers<boolean>()
+    const release = Promise.withResolvers<boolean>()
+    let starts = 0
+    const run = (initiator: Agent): Promise<void> => service.withInitiator(initiator, async () => {
+      expect(service.requireInitiator()).toBe(initiator)
+      starts += 1
+      if (starts === 2) bothStarted.resolve(true)
+      await release.promise
+      expect(service.requireInitiator()).toBe(initiator)
+    })
+
+    const pending = [run(a), run(b)]
+    await bothStarted.promise
+    expect(service.currentInitiator()).toBeUndefined()
+    release.resolve(true)
+    await Promise.all(pending)
+    await dispose()
+  })
+
+  it('restores nested and explicitly cleared boundaries', async () => {
+    const { service, dispose } = await harness()
+    const parent = agent('parent')
+    const child = agent('child')
+
+    service.withInitiator(parent, () => {
+      expect(service.requireInitiator()).toBe(parent)
+      service.withInitiator(child, () => { expect(service.requireInitiator()).toBe(child) })
+      expect(service.requireInitiator()).toBe(parent)
+      service.withoutInitiator(() => {
+        expect(service.currentInitiator()).toBeUndefined()
+        expect(() => service.requireInitiator()).toThrow('no initiating agent is active')
+      })
+      expect(service.requireInitiator()).toBe(parent)
+    })
+    expect(service.currentInitiator()).toBeUndefined()
+    await dispose()
+  })
+
+  it('restores the parent after synchronous throws and rejected operations', async () => {
+    const { service, dispose } = await harness()
+    const parent = agent('parent')
+    const child = agent('child')
+    const syncError = new Error('sync failure')
+    const asyncError = new Error('async failure')
+
+    service.withInitiator(parent, () => {
+      expect(() => service.withInitiator(child, () => { throw syncError })).toThrow(syncError)
+      expect(service.requireInitiator()).toBe(parent)
+    })
+    await expect(service.withInitiator(child, async () => {
+      await Promise.resolve()
+      throw asyncError
+    })).rejects.toBe(asyncError)
+    expect(service.currentInitiator()).toBeUndefined()
+    await dispose()
+  })
+
+  it('stops new boundaries, drains active Promises, and invalidates retained references', async () => {
+    const { ctx, service, dispose } = await harness()
+    const initiator = agent('draining')
+    const release = Promise.withResolvers<boolean>()
+    const pending = service.withInitiator(initiator, async () => {
+      await release.promise
+      expect(service.requireInitiator()).toBe(initiator)
+    })
+    let disposed = false
+    const disposal = dispose().then(() => { disposed = true })
+    await Promise.resolve()
+
+    expect(() => service.withInitiator(initiator, () => 1)).toThrow('agent initiator scope is disposed')
+    expect(() => service.withoutInitiator(() => 1)).toThrow('agent initiator scope is disposed')
+    expect(disposed).toBe(false)
+    expect(ctx.get('agents')).toBeUndefined()
+    release.resolve(true)
+    await pending
+    await disposal
+    expect(() => service.currentInitiator()).toThrow('agent initiator scope is disposed')
+    expect(() => service.requireInitiator()).toThrow('agent initiator scope is disposed')
+  })
+
+  it('drains cross-realm Promise boundaries before disposal', async () => {
+    const { service, dispose } = await harness()
+    const initiator = agent('cross-realm')
+    const release = Promise.withResolvers<boolean>()
+    const operation = runInNewContext(
+      '(async () => { await release; inspect() })',
+      {
+        release: release.promise,
+        inspect: () => { expect(service.requireInitiator()).toBe(initiator) },
+      },
+    ) as () => Promise<void>
+    const pending = service.withInitiator(initiator, operation)
+    expect(pending).not.toBeInstanceOf(Promise)
+
+    let disposed = false
+    const disposal = dispose().then(() => { disposed = true })
+    await Promise.resolve()
+    expect(disposed).toBe(false)
+
+    release.resolve(true)
+    await pending
+    await disposal
+    expect(disposed).toBe(true)
+  })
+
+  it('does not self-deadlock when a boundary returns service disposal', async () => {
+    const { service, dispose } = await harness()
+    const initiator = agent('service-disposer')
+
+    const returned = service.withInitiator(initiator, dispose)
+    await promptly(returned)
+
+    expect(() => service.currentInitiator()).toThrow('agent initiator scope is disposed')
+  })
+
+  it('does not self-deadlock when nested boundaries return ancestor disposal', async () => {
+    const { ctx, service } = await harness()
+    const parent = agent('parent-disposer')
+    const child = agent('child-disposer')
+    let disposal: Promise<void> | undefined
+
+    const returned = service.withInitiator(parent, () => service.withInitiator(child, () => {
+      disposal = ctx.fiber.dispose()
+      return disposal
+    }))
+    expect(returned).toBe(disposal)
+
+    await promptly(returned)
+    expect(() => service.currentInitiator()).toThrow('agent initiator scope is disposed')
+  })
+
+  it('excludes an asynchronous teardown initiator while draining unrelated boundaries', async () => {
+    const { ctx, service } = await harness()
+    const initiator = agent('async-disposer')
+    const unrelated = agent('unrelated')
+    const release = Promise.withResolvers<boolean>()
+    const pending = service.withInitiator(unrelated, async () => {
+      await release.promise
+      expect(service.requireInitiator()).toBe(unrelated)
+    })
+
+    const returned = service.withInitiator(initiator, async () => {
+      await Promise.resolve()
+      await ctx.fiber.dispose()
+    })
+    let disposed = false
+    void returned.then(() => { disposed = true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(disposed).toBe(false)
+
+    release.resolve(true)
+    await pending
+    await promptly(returned)
+
+    expect(() => service.currentInitiator()).toThrow('agent initiator scope is disposed')
+  })
+})

packages/core/agent/tests/agent.spec.ts

@@ -2,15 +2,16 @@ import { describe, expect, expectTypeOf, it } from 'vitest'
 import { Context, Service, symbols } from 'cordis'
 import type { Events } from 'cordis'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry, { AgentId, agentEvents } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { agentEvents } from '@deepseek-ai/dsh-agent'
+
 import type { Agent, AgentFactory, ContinuationStop, CreateAgentOptions, ResumeAgentOptions } from '@deepseek-ai/dsh-agent'
 
 function stubAgent(rawId: string): Agent {
-  const id = AgentId(rawId)
+  const id = SessionId(rawId)
   return {
     id,
     options: {},
-    session: new Session(SessionId(`${id}-session`)),
+    session: new Session(id),
     status: 'idle',
     ctx: new Context(),
     send() {},
@@ -41,6 +42,7 @@ describe('AgentRegistry', () => {
     const dispose = ctx.agents.register(agent)
     expect(ctx.agents.get(agent.id)).toBe(agent)
     expect(ctx.agents.list()).toEqual([agent])
+    expect(ctx.agents.roots()).toEqual([agent])
     expect(() => ctx.agents.register(stubAgent('a1'))).toThrow(/already registered/)
 
     dispose()
@@ -48,6 +50,37 @@ describe('AgentRegistry', () => {
     expect(lifecycle).toEqual(['created:a1', 'disposed:a1'])
   })
 
+  it('rejects an agent whose registry and session identities differ', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const agent = { ...stubAgent('agent-id'), session: new Session(SessionId('session-id')) }
+
+    expect(() => ctx.agents.enter(agent, undefined))
+      .toThrow('agent id "agent-id" does not match session id "session-id"')
+    expect(ctx.agents.list()).toEqual([])
+  })
+
+  it('tracks runtime creator ownership separately from registry order', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const root = stubAgent('root')
+    const child = stubAgent('child')
+    const detachRoot = ctx.agents.enter(root, undefined)
+    ctx.agents.announce(root)
+    const detachChild = ctx.agents.enter(child, root)
+    ctx.agents.announce(child)
+
+    expect(ctx.agents.list()).toEqual([root, child])
+    expect(ctx.agents.roots()).toEqual([root])
+    expect(ctx.agents.isOwnedBy(child.id, root)).toBe(true)
+    expect(ctx.agents.isOwnedBy(root.id, root)).toBe(false)
+    expect(ctx.agents.isOwnedBy(SessionId('missing'), root)).toBe(false)
+
+    detachChild()
+    expect(ctx.agents.isOwnedBy(child.id, root)).toBe(false)
+    detachRoot()
+  })
+
   it('rolls an entry back and pairs a partially delivered creation when a listener throws', async () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
@@ -57,7 +90,7 @@ describe('AgentRegistry', () => {
     ctx.on('agent/disposed', agent => void lifecycle.push(`disposed:${agent.id}`))
 
     expect(() => ctx.agents.register(stubAgent('vetoed'))).toThrow('creation veto')
-    expect(ctx.agents.get(AgentId('vetoed'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('vetoed'))).toBeUndefined()
     expect(lifecycle).toEqual(['created:vetoed', 'disposed:vetoed'])
   })
 
@@ -93,7 +126,7 @@ describe('AgentRegistry', () => {
     ctx.on('agent/disposed', agent => void lifecycle.push(`disposed:${agent.id}`))
 
     const first = stubAgent('split')
-    const detachFirst = ctx.agents.enter(first)
+    const detachFirst = ctx.agents.enter(first, undefined)
     expect(lifecycle).toEqual([])
     ctx.agents.announce(first)
     expect(() => { ctx.agents.announce(first) }).toThrow(/already announced/)
@@ -101,7 +134,7 @@ describe('AgentRegistry', () => {
     detachFirst()
 
     const replacement = stubAgent('split')
-    const detachReplacement = ctx.agents.enter(replacement)
+    const detachReplacement = ctx.agents.enter(replacement, undefined)
     detachFirst()
     expect(ctx.agents.get(replacement.id)).toBe(replacement)
     expect(() => { ctx.agents.announce(first) }).toThrow(/not live/)
@@ -121,7 +154,7 @@ describe('AgentRegistry', () => {
     })
     ctx.on('agent/created', () => void order.push(`second:${ctx.agents.get(agent.id) === agent}`))
     ctx.on('agent/disposed', () => void order.push('disposed'))
-    const detach = ctx.agents.enter(agent)
+    const detach = ctx.agents.enter(agent, undefined)
     ctx.agents.announce(agent)
     expect(order).toEqual(['first:true', 'after-detach:true', 'second:true', 'disposed'])
     expect(ctx.agents.get(agent.id)).toBeUndefined()
@@ -158,11 +191,11 @@ describe('AgentRegistry factory seam', () => {
     const factory: AgentFactory = {
       async createAgent(ownerCtx, options) {
         calls.create.push({ ownerCtx, options })
-        return { agent: stubAgent(options.agentId), dispose: () => Promise.resolve() }
+        return { agent: stubAgent(options.sessionId), dispose: () => Promise.resolve() }
       },
       async resume(ownerCtx, options) {
         calls.resume.push({ ownerCtx, options })
-        return { agent: stubAgent(options.agentId), dispose: () => Promise.resolve() }
+        return { agent: stubAgent(options.resumeSessionId), dispose: () => Promise.resolve() }
       },
     }
     return { factory, calls }
@@ -171,15 +204,15 @@ describe('AgentRegistry factory seam', () => {
   it('requires a factory and delegates through the calling context', async () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
-    await expect(ctx.agents.create({ agentId: AgentId('a'), sessionId: SessionId('s') })).rejects.toThrow(/no agent factory/)
+    await expect(ctx.agents.create({ sessionId: SessionId('s') })).rejects.toThrow(/no agent factory/)
     const { factory, calls } = stubFactory()
     ctx.agents.setFactory(factory)
 
     let callerFiber: Context['fiber'] | undefined
     await ctx.plugin(Object.assign(async (inner: Context) => {
       callerFiber = inner.fiber
-      await inner.agents.create({ agentId: AgentId('create'), sessionId: SessionId('create-s') })
-      await inner.agents.resume({ agentId: AgentId('resume'), resumeSessionId: SessionId('resume-s') })
+      await inner.agents.create({ sessionId: SessionId('create-s') })
+      await inner.agents.resume({ resumeSessionId: SessionId('resume-s') })
     }, { inject: ['agents'] }))
     expect(calls.create[0]?.ownerCtx.fiber).toBe(callerFiber)
     expect(calls.resume[0]?.ownerCtx.fiber).toBe(callerFiber)
@@ -192,9 +225,9 @@ describe('AgentRegistry factory seam', () => {
       inner.agents.setFactory(stubFactory().factory)
       expect(() => inner.agents.setFactory(stubFactory().factory)).toThrow(/already registered/)
     }, { inject: ['agents'] }))
-    await expect(ctx.agents.create({ agentId: AgentId('before'), sessionId: SessionId('before-s') })).resolves.toBeDefined()
+    await expect(ctx.agents.create({ sessionId: SessionId('before-s') })).resolves.toBeDefined()
     await owner.dispose()
-    await expect(ctx.agents.create({ agentId: AgentId('after'), sessionId: SessionId('after-s') })).rejects.toThrow(/no agent factory/)
+    await expect(ctx.agents.create({ sessionId: SessionId('after-s') })).rejects.toThrow(/no agent factory/)
   })
 
   it('canonicalizes an already traced Service before tracing it for the caller', async () => {
@@ -214,18 +247,18 @@ describe('AgentRegistry factory seam', () => {
       }
       async createAgent(_ownerCtx: Context, options: CreateAgentOptions) {
         this.calls().push('create')
-        return { agent: stubAgent(options.agentId), dispose: () => Promise.resolve() }
+        return { agent: stubAgent(options.sessionId), dispose: () => Promise.resolve() }
       }
       async resume(_ownerCtx: Context, options: ResumeAgentOptions) {
         this.calls().push('resume')
-        return { agent: stubAgent(options.agentId), dispose: () => Promise.resolve() }
+        return { agent: stubAgent(options.resumeSessionId), dispose: () => Promise.resolve() }
       }
     }
     await ctx.plugin(TracedFactory)
     const traced = (ctx as Context & { tracedFactory: TracedFactory }).tracedFactory
     ctx.agents.setFactory(traced)
-    await ctx.agents.create({ agentId: AgentId('create'), sessionId: SessionId('create-s') })
-    await ctx.agents.resume({ agentId: AgentId('resume'), resumeSessionId: SessionId('resume-s') })
+    await ctx.agents.create({ sessionId: SessionId('create-s') })
+    await ctx.agents.resume({ resumeSessionId: SessionId('resume-s') })
     const raw = (traced as unknown as { [symbols.original]?: TracedFactory })[symbols.original]
     expect(states.get(raw!)).toEqual(['create', 'resume'])
   })

packages/core/agent/tests/gen-cordis-catalog.spec.ts

@@ -1,12 +1,13 @@
 /**
- * Negative-path tests for the cordis catalog generator (`scripts/gen-cordis-catalog.ts`).
+ * Contract and negative-path tests for the cordis catalog generator
+ * (`scripts/gen-cordis-catalog.ts`).
  */
 
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
-import { collectEvents, collectServices } from '../../../../scripts/gen-cordis-catalog.ts'
+import { collectEvents, collectServices, renderEvents, renderServices } from '../../../../scripts/gen-cordis-catalog.ts'
 
 /** Write a fixture package exposing one `interface Events` block and return the
  * scan root to hand `collectEvents`. */
@@ -58,6 +59,8 @@ describe('gen-cordis-catalog collectEvents', () => {
     ))
     expect(events).toHaveLength(1)
     expect(events[0]).toMatchObject({ name: 'fix/happened', scope: 'fix', mode: 'emit', doc: 'A thing happened.' })
+    expect(events[0]?.jsDoc).toBe('/**\n * A thing happened.\n * @param id - which thing.\n * @mode emit\n */')
+    expect(renderEvents(events)).toContain("```ts cordis-catalog\n/**\n * A thing happened.\n * @param id - which thing.\n * @mode emit\n */\n'fix/happened'(id: string): void\n```")
   })
 
   it('classifies a trailing-next signature as a waterfall', () => {
@@ -74,6 +77,33 @@ describe('gen-cordis-catalog collectEvents', () => {
     expect(events[0]?.mode).toBe('parallel')
   })
 
+  it('accepts linked, foundation, generic-parameter, and explicitly exempt signature types', () => {
+    const events = collectEvents(make(
+      '    /**\n     * Carry linked and foundation types.\n     * @param value - the linked value.\n     * @param preset - deployment metadata outside the core catalog.\n     * @param signal - cancellation.\n     * @mode parallel\n     */\n    \'fix/typed\'<T extends SessionEvent>(value: Readonly<T>, preset: PresetSpec, signal: AbortSignal): Promise<T>',
+    ))
+    expect(events).toHaveLength(1)
+    expect(renderEvents(events)).toContain('Types: [SessionEvent](../core-data-structures/core.md)')
+    expect(renderEvents(events)).not.toContain('[PresetSpec]')
+  })
+
+  it('aggregates every unclassified signature type with its source and remediation', () => {
+    const expected = new RegExp([
+      '2 signature type-link coverage violation\\(s\\)',
+      'fix/one',
+      'packages/group/fix/src/index.ts',
+      'MissingOne',
+      'fix/two',
+      'packages/group/fix/src/index.ts',
+      'missingTwo',
+      'Add it to LINK_MAP',
+      'FOUNDATION_TYPE_NAMES',
+      'TYPE_LINK_EXEMPTIONS',
+    ].join('[\\s\\S]*'))
+    expect(() => collectEvents(make(
+      '    /**\n     * First.\n     * @param value - first value.\n     * @mode emit\n     */\n    \'fix/one\'(value: MissingOne): void\n    /**\n     * Second.\n     * @param value - second value.\n     * @mode emit\n     */\n    \'fix/two\'(value: missingTwo): void',
+    ))).toThrow(expected)
+  })
+
   it('hard-errors when an event is missing its @mode tag', () => {
     expect(() => collectEvents(make(
       '    /** No mode here. */\n    \'fix/untagged\'(): void',
@@ -158,6 +188,17 @@ export class FixService {
     expect(services).toHaveLength(1)
     expect(services[0]).toMatchObject({ key: 'fix', type: 'FixService', abstract: false, doc: 'Fixture service.' })
     expect(services[0]?.methods).toHaveLength(3)
+    expect(services[0]?.methods[0]).toEqual({
+      signature: 'run(id: string): string',
+      jsDoc: '/**\n * Do the thing.\n * @param id - which thing to do.\n * @returns the outcome of doing it.\n */',
+    })
+    expect(renderServices(services)).toContain('```ts cordis-catalog\n/**\n * Do the thing.\n * @param id - which thing to do.\n * @returns the outcome of doing it.\n */\nrun(id: string): string\n\n/** Fire and forget (void needs no @returns). */\npoke(): void')
+  })
+
+  it('hard-errors on an unclassified service-method signature type', () => {
+    expect(() => collectServices(makeService(
+      '/** Fixture service. */\nexport class FixService {\n  /**\n   * Use an unknown value.\n   * @param value - the value.\n   */\n  run(value: MissingServiceType): void {}\n}',
+    ))).toThrow(/service method ctx\.fix\.run .* references unclassified type 'MissingServiceType'/)
   })
 
   it('hard-errors on a public method with no JSDoc at all', () => {

packages/core/session/README.md

@@ -35,7 +35,7 @@ Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.
 - `session.append(type, data, opts?)` snapshots and freezes durable data and surface metadata, validates marker shape, provenance, and complete replacement coverage, commits synchronously, then notifies observers with independent failure containment. Reentrant attached-session appends reject, and runtime checks cover widened unions and loaded logs.
 - `session.deriveMessages()` incrementally projects each new surface entry once and returns a fresh array over shared frozen messages. Assistant projections preserve provider/model provenance and adapter-private replay state. A surface rewrite rebuilds the projection; there is no raw-log fallback.
 - `session.deriveEventMessage(event)` is the canonical per-event projection used by reconstruction and invariants.
-- `session.surface` lazily folds only new `surfaceOp` markers; `replaceGeneration` changes on every rewrite.
+- `session.surface` exposes the readonly `SessionSurface` view owned by the session's single incremental surface manager; `replaceGeneration` changes on every committed rewrite.
 - `session.events` is a cached frozen snapshot invalidated by append; accepted events remain deeply frozen.
 - `session.seq`, `session.id` — current sequence and readonly typed identity.
 - `session.header: SessionHeader` — detached, deep-frozen creation metadata (`version`, `id`, `createdAt`, optional `cwd`/`parentSession`/`seedLength`). Construction validates the durable record and requires its id to match `session.id`.
@@ -48,6 +48,7 @@ Durable values need one accepted representation, not a check followed by a secon
 
 - `SurfaceOp` — how an event entered the ordered surface: `'append'` (normal tail append) or `{ op: 'replace', start, end }` (replace entries from `start` through `end` inclusive — both must be valid surface seqs; `start === end` replaces one entry). Used by compaction to shadow old events without deleting them.
 - `SurfaceIntent` — `{ surfaceOp: SurfaceOp; sourceEventSeqs?: number[] }`, the required third parameter to `session.append()` for surface-eligible types.
+- `SessionSurface` — the readonly live `nodes` and `replaceGeneration` projection exposed by `session.surface`; candidate validation remains private to `Session`.
 - `foldSurface(events)` — replay the canonical surface contract into detached current event sequences and actual replacement ranges. The same pass rejects non-contiguous seqs, misplaced or malformed metadata, empty or duplicate provenance, non-earlier sources, invalid positional ranges, and replacements that fail to cite every shadowed surface entry; `SurfaceManager` shares the atomic transition while retaining only its incremental sequence cache.
 - `isSurfaceEvent(event)` / `isSurfaceEligibleType(type)` — the first narrows a `SessionEvent` to a fully formed surface event; the second detects a surface-eligible event missing its marker when validating a seed or loaded log.
 
@@ -84,21 +85,45 @@ Every `SessionEvent` carries two optional top-level fields (structural metadata)
 
 ### Derived message history
 
-**What the model sees**: The model receives projections of `user/message`, `assistant/message`, and `tool/result` surface entries verbatim. A `context/message` is a user-role message containing exactly `<context source="<source-kind>">`, its content blocks, and `</context>`; `steering/message` uses the identical `<steering source="<source-kind>">` / `</steering>` wrapper. Tool calls live inside assistant messages. Chunks, boundaries, usage, hook records, todo records, and other log-only events add no message.
+#### What the model sees
 
-**Token effect**: Appended surface entries are resent on later steps. A `replace` surface operation removes the shadowed entries from future inputs without deleting their raw log records.
+The model receives projections of `user/message`, `assistant/message`, and `tool/result` surface entries verbatim. A `context/message` is a user-role message containing exactly `<context source="<source-kind>">`, its content blocks, and `</context>`; `steering/message` uses the identical `<steering source="<source-kind>">` / `</steering>` wrapper. Tool calls live inside assistant messages. Chunks, boundaries, usage, hook records, todo records, and other log-only events add no message.
+
+#### Token effect
+
+Appended surface entries are resent on later steps. A `replace` surface operation removes the shadowed entries from future inputs without deleting their raw log records.
+
+#### KV Cache effect
+
+Appended surface entries preserve reusable prefixes. A `replace` operation invalidates reuse from the first shadowed message even though the underlying event log stays append-only.
 
 ### Crash-repair result
 
-**What the model sees**: If a persisted turn ended with unanswered tool calls, each synthetic error result contains exactly `Tool call interrupted by a crash; no result was recorded.`
+#### What the model sees
 
-**Token effect**: Zero tokens in an intact session. Each repaired call adds this retained error text on resume.
+If a persisted turn ended with unanswered tool calls, each synthetic error result contains exactly `Tool call interrupted by a crash; no result was recorded.`
+
+#### Token effect
+
+Zero tokens in an intact session. Each repaired call adds this retained error text on resume.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
 ### Logged request header
 
-**What the model sees**: The session reconstructs the system prompt, tool schemas, call config, and session prefix that the loop actually sent. Header events do not add a second copy to message history; the prefix is prepended outside `deriveMessages()`.
+#### What the model sees
 
-**Token effect**: Zero duplicate tokens from logging. The reconstructed prefix, system text, and schemas still incur their normal per-request cost.
+The session reconstructs the system prompt, tool schemas, call config, and session prefix that the loop actually sent. Header events do not add a second copy to message history; the prefix is prepended outside `deriveMessages()`.
+
+#### Token effect
+
+Zero duplicate tokens from logging. The reconstructed prefix, system text, and schemas still incur their normal per-request cost.
+
+#### KV Cache effect
+
+Logging causes no invalidation, and exact reconstruction preserves request-prefix identity. A later header with changed prefix, prompt, or schemas may invalidate reuse from its first difference.
 
 ## Known Limitations and Deferred Work
 

packages/core/session/src/index.ts

@@ -16,13 +16,14 @@ import { SESSION_FORMAT_VERSION, SessionId } from './types.ts'
 import type { ContextEnvelope, CreateSessionOptions, EpochHeader, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SurfaceIntent, SurfaceEventType } from './types.ts'
 import { snapshotJsonValue } from './json.ts'
 import { SurfaceManager } from './surface.ts'
+import type { SessionSurface } from './surface.ts'
 import { foldRequestHeader } from './request-header.ts'
 
 export * from './types.ts'
 export { isJsonValue, snapshotJsonValue } from './json.ts'
 export type { JsonValue } from './json.ts'
 export { interruptedTurnClosers } from './repair.ts'
-export type { SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts'
+export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts'
 export { foldSurface, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
 export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts'
 
@@ -251,22 +252,12 @@ export function renderContextContent(
  */
 export class Session {
   private log: SessionEvent[] = []
-  /** Incremental acceptance state, kept separate from the public lazy view. */
-  private readonly surfaceValidator = new SurfaceManager(this.log)
-
-  /**
-   * Derived surface — a cached order of message-producing event sequences.
-   * Lazily rebuilt from `surfaceOp` markers in the log; processes only new
-   * events (delta) on each access — the log is append-only, so prior events
-   * never change.
-   * Undefined until first accessed (including after fork/seed).
-   */
-  private _surface: SurfaceManager | undefined
+  /** Single incremental owner of surface acceptance and projection state. */
+  private readonly surfaceManager = new SurfaceManager(this.log)
 
   /** The ordered surface over this session's event log. */
-  get surface(): SurfaceManager {
-    if (!this._surface) this._surface = new SurfaceManager(this.log)
-    return this._surface
+  get surface(): SessionSurface {
+    return this.surfaceManager
   }
 
   /**
@@ -279,7 +270,12 @@ export class Session {
    */
   readonly header: SessionHeader
 
-  constructor(public readonly id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader) {
+  /** The session identity, derived from its durable header's single copy. */
+  get id(): SessionId {
+    return this.header.id
+  }
+
+  constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader) {
     if (seed) {
       // Validate the seed to the SAME invariants `append` enforces, so a
       // replay/fork (`ctx.sessions.create(id, { seed })`) cannot construct a
@@ -304,7 +300,7 @@ export class Session {
         // live append and a full-log fold. The candidate is planned before it
         // enters `log`, so a failure cannot partially mutate the surface.
         try {
-          this.surfaceValidator.validateNext(snapshot)
+          this.surfaceManager.validateNext(snapshot)
         } catch (error: unknown) {
           throw new Error(`invalid seed event at index ${index}: ${error instanceof Error ? error.message : 'invalid surface metadata'}`)
         }
@@ -397,7 +393,7 @@ export class Session {
       data: dataSnapshot,
       ...(surfaceMetadataSnapshot as { surfaceOp?: unknown; sourceEventSeqs?: unknown }),
     } as unknown as SessionEvent<T>)
-    this.surfaceValidator.validateNext(event as SessionEvent)
+    this.surfaceManager.validateNext(event as SessionEvent)
 
     if (entry !== undefined) entry.appending = true
     try {
@@ -463,7 +459,7 @@ export class Session {
    *
    * CACHED: each surface node is projected exactly once, when first seen — a
    * call costs O(new nodes), and a surface rewrite (a `replace`;
-   * {@link SurfaceManager.replaceGeneration}) rebuilds. The returned array is
+   * {@link SessionSurface.replaceGeneration}) rebuilds. The returned array is
    * a fresh snapshot per call (later appends never grow an array a caller
    * already holds); the `Message` objects in it are SHARED and **deep-frozen**.
    * Their content reuses the already frozen durable event data, so the cache
@@ -471,8 +467,9 @@ export class Session {
    * @returns a fresh array of the shared, frozen derived history.
    */
   deriveMessages(): Message[] {
-    const nodes = this.surface.nodes
-    const generation = this.surface.replaceGeneration
+    const surface = this.surface
+    const nodes = surface.nodes
+    const generation = surface.replaceGeneration
     if (generation !== this.derivedGeneration) {
       this.derived = []
       this.derivedNodes = 0

packages/core/session/src/surface.ts

@@ -55,6 +55,14 @@ export interface SurfaceFoldResult {
   replacements: SurfaceFoldReplacement[]
 }
 
+/** Readonly live projection of the message-producing session events. */
+export interface SessionSurface {
+  /** Current surface event sequences in model-visible order. */
+  readonly nodes: readonly number[]
+  /** Monotonic count of committed positional replacements. */
+  readonly replaceGeneration: number
+}
+
 /** Mutable state shared by complete and incremental folds. */
 interface SurfaceFoldState {
   nodes: number[]
@@ -244,7 +252,7 @@ export function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult
 }
 
 /** Incremental ordered surface view and append-boundary validator. */
-export class SurfaceManager {
+export class SurfaceManager implements SessionSurface {
   /** Shared transition state; replacement history is not retained. */
   private _state = createFoldState()
   /** Last processed seq; -1 folds a seeded log on first access. */

packages/core/session/tests/gen-persistence-catalog.spec.ts

@@ -9,6 +9,7 @@ import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import {
   annotateSurface,
+  collectEventEnvelopeTypes,
   collectLogEvents,
   collectSurfaceEventTypes,
   render,
@@ -56,6 +57,7 @@ describe('gen-persistence-catalog collectLogEvents', () => {
       scope: 'fix',
       doc: 'A thing was recorded.',
       payload: '{ turn: number }',
+      declaration: '/** A thing was recorded. */\n\'fix/happened\': { turn: number }',
       source: 'packages/core/fix/src/types.ts:3',
     })
   })
@@ -102,10 +104,13 @@ describe('gen-persistence-catalog collectLogEvents', () => {
   it('collapses a newline-separated multi-line payload to a valid one-line fragment', () => {
     const events = collectLogEvents(make({
       'packages/group/fix/src/types.ts': merge(
-        '    /** Wide payload. */\n    \'fix/wide\': {\n      alpha: string[]\n      range: { start: number; end: number }\n      count: number\n    }',
+        '    /** Wide payload. */\n    \'fix/wide\': {\n      /** Alpha values. */\n      alpha: string[]\n      range: { start: number; end: number }\n      count: number\n    }',
       ),
     }))
     expect(events[0]?.payload).toBe('{ alpha: string[]; range: { start: number; end: number }; count: number }')
+    expect(events[0]?.declaration).toBe(
+      '/** Wide payload. */\n\'fix/wide\': {\n  /** Alpha values. */\n  alpha: string[]\n  range: { start: number; end: number }\n  count: number\n}',
+    )
   })
 
   it('hard-errors on a member with no description prose', () => {
@@ -158,6 +163,59 @@ describe('gen-persistence-catalog collectLogEvents', () => {
   })
 })
 
+describe('gen-persistence-catalog collectEventEnvelopeTypes', () => {
+  const declarations = `/** Event keys. */
+export type SessionEventType = keyof SessionEventMap
+/** Surface-producing event keys. */
+export type SurfaceEventType = 'fix/message'
+/** Surface placement. */
+export type SurfaceOp = 'append'
+/** One persisted event. */
+export type SessionEvent<T extends SessionEventType = SessionEventType> = { type: T }
+`
+
+  it('extracts the envelope declarations with their complete JSDoc in canonical order', () => {
+    const entries = collectEventEnvelopeTypes(make({
+      'packages/core/fix/package.json': OWNER_MANIFEST,
+      'packages/core/fix/src/types.ts': declarations,
+    }))
+    expect(entries.map(entry => entry.name)).toEqual([
+      'SessionEventType',
+      'SurfaceEventType',
+      'SurfaceOp',
+      'SessionEvent',
+    ])
+    expect(entries[3]).toMatchObject({
+      declaration: '/** One persisted event. */\nexport type SessionEvent<T extends SessionEventType = SessionEventType> = { type: T }',
+      source: 'packages/core/fix/src/types.ts:8',
+    })
+  })
+
+  it('hard-errors when an envelope declaration is missing', () => {
+    expect(() => collectEventEnvelopeTypes(make({
+      'packages/core/fix/package.json': OWNER_MANIFEST,
+      'packages/core/fix/src/types.ts': declarations.replace('/** Surface placement. */\nexport type SurfaceOp = \'append\'\n', ''),
+    }))).toThrow(/missing event-envelope declaration\(s\): SurfaceOp/)
+  })
+
+  it('hard-errors on duplicate, unexported, undocumented, or mistagged envelope declarations', () => {
+    const violations = new RegExp([
+      '4 JSDoc completeness violation\\(s\\)',
+      '[\\s\\S]*not exported',
+      '[\\s\\S]*@mode tag',
+      '[\\s\\S]*SurfaceOp.*no description prose',
+      '[\\s\\S]*SessionEvent.*already declared',
+    ].join(''))
+    expect(() => collectEventEnvelopeTypes(make({
+      'packages/core/fix/package.json': OWNER_MANIFEST,
+      'packages/core/fix/src/types.ts': declarations
+        .replace('/** Event keys. */\nexport type SessionEventType', '/** Event keys.\n * @mode emit\n */\ntype SessionEventType')
+        .replace('/** Surface placement. */\n', '')
+        + '/** Duplicate event. */\nexport type SessionEvent = { type: never }\n',
+    }))).toThrow(violations)
+  })
+})
+
 describe('gen-persistence-catalog collectSurfaceEventTypes', () => {
   it('parses the literal union', () => {
     const types = collectSurfaceEventTypes(make({
@@ -192,9 +250,21 @@ describe('gen-persistence-catalog annotateSurface + render', () => {
     scope: name.split('/')[0] ?? name,
     payload: '{ turn: number }',
     doc: `Records ${name}.`,
+    declaration: `/** Records ${name}. */\n'${name}': { turn: number }`,
     source: 'packages/core/fix/src/types.ts:3',
   })
 
+  const envelopeTypes = [
+    'SessionEventType',
+    'SurfaceEventType',
+    'SurfaceOp',
+    'SessionEvent',
+  ].map(name => ({
+    name: name as 'SessionEventType' | 'SurfaceEventType' | 'SurfaceOp' | 'SessionEvent',
+    declaration: `/** ${name}. */\nexport type ${name} = never`,
+    source: 'packages/core/fix/src/types.ts:1',
+  }))
+
   it('badges union members surface and everything else log-only', () => {
     const annotated = annotateSurface([entry('fix/message'), entry('fix/marker')], ['fix/message'])
     expect(annotated.map(e => [e.name, e.surface])).toEqual([['fix/message', true], ['fix/marker', false]])
@@ -205,11 +275,13 @@ describe('gen-persistence-catalog annotateSurface + render', () => {
       .toThrow(/'fix\/ghost' name no declared log event/)
   })
 
-  it('renders badges, payload fences, and the generated-file header', () => {
-    const out = render(annotateSurface([entry('fix/message'), entry('fix/marker')], ['fix/message']))
+  it('renders badges, declaration fences, and the generated-file header', () => {
+    const out = render(annotateSurface([entry('fix/message'), entry('fix/marker')], ['fix/message']), envelopeTypes)
     expect(out).toContain('Generated by scripts/gen-persistence-catalog.ts')
+    expect(out).toContain('# Session Persistence Event Catalog')
+    expect(out).toContain('```ts persistence-catalog\n/** SessionEventType. */\nexport type SessionEventType = never')
     expect(out).toContain('#### `fix/message` — surface')
     expect(out).toContain('#### `fix/marker` — log-only')
-    expect(out).toContain('```ts persistence-catalog\n\'fix/marker\': { turn: number }\n```')
+    expect(out).toContain('```ts persistence-catalog\n/** Records fix/marker. */\n\'fix/marker\': { turn: number }\n```')
   })
 })

packages/core/session/tests/session.spec.ts

@@ -1,10 +1,18 @@
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, expectTypeOf, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SESSION_FORMAT_VERSION, Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
-import type { CreateSessionOptions, SessionEventType, SessionHeader, TodoItem } from '@deepseek-ai/dsh-session'
+import type { CreateSessionOptions, SessionEventType, SessionHeader, SessionSurface, TodoItem } from '@deepseek-ai/dsh-session'
 
 describe('Session', () => {
+  it('exposes one stable readonly surface view', () => {
+    const session = new Session(SessionId('surface-view'))
+    const surface = session.surface
+
+    expectTypeOf(surface).toEqualTypeOf<SessionSurface>()
+    expect(surface).toBe(session.surface)
+  })
+
   it('derives message history from the event log', () => {
     const session = new Session(SessionId('s1'))
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
@@ -1031,6 +1039,45 @@ describe('SessionStore', () => {
     expect(observed).toEqual([appended])
   })
 
+  it('does not publish a surface transition rejected by internal dispatch', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const session = ctx.sessions.create(SessionId('surface-dispatch-veto'))
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'source' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    const surface = session.surface
+    let reject = true
+    ctx.on('internal/dispatch', (_mode, name) => {
+      if (name === 'session/event' && reject) {
+        reject = false
+        throw new Error('reject surface candidate')
+      }
+    })
+
+    expect(() => session.append('assistant/message', {
+      provenance: { provider: 'mock', model: 'mock' },
+      turn: 1,
+      step: 1,
+      content: [{ type: 'text', text: 'replacement' }],
+    }, {
+      surfaceOp: { op: 'replace', start: 0, end: 0 },
+      sourceEventSeqs: [0],
+    })).toThrow('reject surface candidate')
+
+    expect(session.events).toHaveLength(1)
+    expect(surface.nodes).toEqual([0])
+    expect(surface.replaceGeneration).toBe(0)
+
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'next' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    expect(surface.nodes).toEqual([0, 1])
+    expect(surface.replaceGeneration).toBe(0)
+  })
+
   it('resolves session/event dispatch before commit so instrumentation failure cannot hide a logged event', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)

packages/core/session/tests/surface.spec.ts

@@ -142,6 +142,11 @@ describe('SurfaceManager', () => {
   it('leaves incremental state unchanged when candidate validation fails', () => {
     const s = new Session(SessionId('atomic-validation'))
     s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    const surface = s.surface
+    const nodes = surface.nodes
+
+    expect(nodes).toEqual(foldSurface(s.events).nodes)
+    expect(surface.replaceGeneration).toBe(0)
 
     expect(() => s.append(
       'assistant/message',
@@ -150,8 +155,16 @@ describe('SurfaceManager', () => {
     )).toThrow(/missing 0/)
 
     expect(s.events).toHaveLength(1)
+    expect(s.surface).toBe(surface)
+    expect(surface.nodes).toEqual([0])
+    expect(surface.replaceGeneration).toBe(0)
+    expect(surface.nodes).toEqual(foldSurface(s.events).nodes)
+
     s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    expect(s.surface.nodes).toEqual([0, 1])
+    expect(surface.nodes).toBe(nodes)
+    expect(surface.nodes).toEqual([0, 1])
+    expect(surface.replaceGeneration).toBe(0)
+    expect(surface.nodes).toEqual(foldSurface(s.events).nodes)
   })
 
   it('foldSurface rejects a surface-eligible event without its mandatory marker', () => {

packages/core/system-prompt/README.md

@@ -44,21 +44,37 @@ Design rationale: [the prompt-variables RFC](../../../docs/rfc/implemented/archi
 
 ### System prompt
 
-**What the model sees**: Every assembly starts with the harness identity below, then the configured persona and ordered plugin sections after strict variable interpolation. Empty sections disappear; scoped sections and variables can shadow globals for one agent. The final `system-prompt/assemble` waterfall result is authoritative, so an expert listener's changes determine the delivered prompt and tool schemas.
+#### What the model sees
 
-**Token effect**: Identity is a fixed per-request cost. Persona and plugin text are repeated per request and scale with their rendered content.
+Every assembly starts with the harness identity below, then the configured persona and ordered plugin sections after strict variable interpolation. Empty sections disappear; scoped sections and variables can shadow globals for one agent. The final `system-prompt/assemble` waterfall result is authoritative, so an expert listener's changes determine the delivered prompt and tool schemas.
 
-#### Harness identity
+##### Harness identity
 
 ```markdown
 You are an AI agent powered by the DeepSeek Harness SDK.
 ```
 
+#### Token effect
+
+Identity is a fixed per-request cost. Persona and plugin text are repeated per request and scale with their rendered content.
+
+#### KV Cache effect
+
+Prefix-stable while identity, persona, variables, section text, and order render identically. Any change may invalidate reuse from the first changed system-prompt token.
+
 ### Tool schemas
 
-**What the model sees**: For shipped tools, the model receives the per-agent-visible subset of the [generated tool schemas](../../../docs/tool-catalog.md#tool-package-map), ordered by configuration or lexicographically after restrictions and assembly interception. Extensions can contribute additional definitions through the same registry. Sections and schema providers are separate assembly inputs, so a tool restriction does not remove independently registered guidance.
+#### What the model sees
 
-**Token effect**: Schema tokens repeat on every request. Restricting a tool removes its entire schema cost for that agent but not a separate prompt section; reordering changes cache shape but not semantic content.
+For shipped tools, the model receives the per-agent-visible subset of the [generated tool schemas](../../../docs/tool-catalog.md#tool-package-map), ordered by configuration or lexicographically after restrictions and assembly interception. Extensions can contribute additional definitions through the same registry. Sections and schema providers are separate assembly inputs, so a tool restriction does not remove independently registered guidance.
+
+#### Token effect
+
+Schema tokens repeat on every request. Restricting a tool removes its entire schema cost for that agent but not a separate prompt section; reordering changes cache shape but not semantic content.
+
+#### KV Cache effect
+
+Prefix-stable while the visible schema set, rendering, and order are unchanged. Registration, restriction, or reordering may invalidate reuse from the first changed schema token.
 
 ## Known Limitations and Deferred Work
 

packages/core/tools/README.md

@@ -21,6 +21,7 @@ tools:
 - `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]` Schemas of everything the scope can see (without the `execute` functions). The shipped tools' schemas are catalogued in [docs/tool-catalog.md](../../../docs/tool-catalog.md), generated by booting each tool plugin and harvesting this method (see [the tool-schema-catalog RFC](../../../docs/rfc/implemented/process/2026-07-02-tool-schema-catalog.md)).
 - `ctx.tools.guard(guard: ToolGuard): () => void` Register a monotonic synchronous execution guard after `tools/pre-execute`: returning a reason denies the call, while `undefined` leaves it unchanged. A plain-context guard applies globally; an `agent.ctx` guard applies only to that agent. Later waterfall listeners cannot turn a guard denial back into permission. Disposed with the calling fiber.
 - `ctx.tools.execute(exec)` losslessly snapshots and freezes arguments, assigns an opaque token, runs the complete policy/dispatch/result pipeline, then independently snapshots the authoritative outcome before final observation. Invalid arguments use the same result path without reaching policy or the body; around wrappers may replace only `signal`.
+- `ctx.tools.executionMode(exec)` returns `parallel` only when the visible definition's `isConcurrencySafe(exec.arguments)` classifier returns exactly `true`; unknown, hidden, undeclared, invalid, or throwing classifications are exclusive.
 
 ### Injected services
 
@@ -32,7 +33,7 @@ The live registry pipeline has three transformable waterfalls followed by the ob
 
 ### Key types
 
-- `ToolDefinition` — `ToolSchema` + `execute(args, exec)`, optional presentation callbacks, and cooperative `timeoutMs`.
+- `ToolDefinition` — `ToolSchema` + `execute(args, exec)`, optional presentation callbacks, cooperative `timeoutMs`, and optional per-call `isConcurrencySafe(args)` classification.
 - `ToolExecutionInput` — the caller-supplied call description: `{ callId, name, arguments, agent?, parent?, signal? }`; callers may pass an enclosing execution's opaque token as `parent` but never choose the new execution's own token.
 - `ToolExecutionToken` — a fresh branded `Symbol` assigned by the registry. It supports equality correlation only and never crosses a model, log, or worker boundary.
 - `ToolExecution` — the pipeline-owned call: immutable `{ token, callId, name, arguments, agent?, parent? }` identity plus optional operational `signal`, which an around wrapper may add, replace, remove, and restore. A nested call's `parent` is a `ToolExecutionToken`, not an execution object.
@@ -87,6 +88,8 @@ See `defineTool`, `validateArgs`, `ToolArgsError`, `SchemaSpec`, `InferArgs`, an
 
 Optional `timeoutMs` must be positive and finite; it is policy metadata, not model-visible schema.
 
+Optional `isConcurrencySafe(args)` receives typed, softly validated arguments. Exact `true` permits concurrent dispatch/body execution; invalid input and all other outcomes remain exclusive. Opted-in bodies do not mutate parent-owned state, and shared-state races must commute or fail closed. The [parallel tool-call RFC](../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md) owns the full safety contract.
+
 ### Structured-output schema subset
 
 `StructuredOutputSchema` is the object-rooted raw JSON Schema subset used by subagents and workflows for machine-readable results. It accepts one scalar `type`, object `properties`/`required`/boolean `additionalProperties`, array `items`, and scalar `enum`/`const`. The annotations `description`, `title`, `default`, and `examples` are ignored but must remain JSON data. Type arrays, undeclared required keys, and unsupported keywords fail through `OutputSchemaError` rather than being ignored; `validateStructuredValue()` returns path-qualified violations without throwing.
@@ -108,21 +111,33 @@ Under `code` or `both`, the registry exposes the reserved `run_code` transport a
 - **The dispatch bridge** (`run_code`'s execute): every binding call is JSON-normalized before dispatch (a value that does not survive — `BigInt`, circulars — rejects that one call, so the dispatched form and logged form are the same JSON value by construction), serialized through a per-run queue (even `Promise.all` executes underlying calls one at a time in submission order), given the outer execution's opaque token as `parent`, and run through the complete pre-execute → guards → execute → post-execute → result pipeline. A denial reaches the program as a binding rejection, and each sub-call is logged as a `tool/code-dispatch` session event with deterministic id `<parent>:code:<n>`; `deriveMessages()` does not surface that event. Token correlation lets commit-style observers defer an inner success until the final `run_code` result without exposing the live outer execution; ordinary tool side effects are not rolled back. Every sub-call `additionalContexts` entry is deferred through the outer `ToolRunContext` in dispatch order; the loop appends those contexts only after the parent `run_code` result, preserving adjacency and retaining each source/envelope/meta even when the program later fails.
 - **Settlement discipline**: the bridge owns a run-scoped abort that follows the outer signal in and fires when the run settles for any reason, so a budget expiry aborts an in-flight sub-tool instead of orphaning it; the bridge then drains its queue BEFORE returning, so every `tool/code-dispatch` lands inside the open turn. A failed run throws `CodeRunFailedError` (`code: 'CODE_RUN_FAILED'`, message = the failure kind + captured logs), which the pipeline converts to a structured `isError` the model self-corrects from.
 
+### Parallel execution
+
+The agent loop groups consecutive `parallel` calls into a bounded rolling pool and treats each `exclusive` call as an ordering barrier. Only dispatch/body overlaps; policy, durable results, and context retain model order. Code Mode bindings remain serial. The [parallel tool-call RFC](../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md) owns the shipped declarations and rationale.
+
 ## Model Experience
 
 ### Normal tool schemas
 
-**What the model sees**: In normal mode the model sees each visible definition's exact name, description, and JSON schema; the shipped definitions are recorded in the generated [tool package map and schema sections](../../../docs/tool-catalog.md#tool-package-map). Agent-scoped restrictions, shadows, and extension registrations change that agent's end-tool set.
+#### What the model sees
 
-**Token effect**: Fixed per-request cost proportional to the visible definitions. Restrictions that hide tools remove their entire schema cost for that agent.
+In normal mode the model sees each visible definition's exact name, description, and JSON schema; the shipped definitions are recorded in the generated [tool package map and schema sections](../../../docs/tool-catalog.md#tool-package-map). Agent-scoped restrictions, shadows, and extension registrations change that agent's end-tool set.
+
+#### Token effect
+
+Fixed per-request cost proportional to the visible definitions. Restrictions that hide tools remove their entire schema cost for that agent.
+
+#### KV Cache effect
+
+Prefix-stable while visible definitions and their order are unchanged. Registration, disposal, or scoped restriction may invalidate reuse from the first changed schema token.
 
 ### Code Mode schema and system prompt
 
-**What the model sees**: Code Mode exposes the generated [`run_code` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tools), the SDK instructions below, and the generated exact `declare const tools` block. `both` exposes normal schemas and this Code Mode surface.
+#### What the model sees
 
-**Token effect**: Fixed per-request cost proportional to the visible definitions. Code Mode trades end-tool schemas for generated SDK text plus one transport schema rather than promising a universal reduction.
+Code Mode exposes the generated [`run_code` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tools), the SDK instructions below, and the generated exact `declare const tools` block. `both` exposes normal schemas and this Code Mode surface.
 
-#### Code Mode SDK instructions
+##### Code Mode SDK instructions
 
 ```markdown
 ## Writing code for run_code
@@ -137,17 +152,33 @@ Pass `run_code` the body of an async TypeScript function (erasable syntax only
 The available tools:
 ```
 
+#### Token effect
+
+Fixed per-request cost proportional to the visible definitions. Code Mode trades end-tool schemas for generated SDK text plus one transport schema rather than promising a universal reduction.
+
+#### KV Cache effect
+
+Prefix-stable while the Code Mode selection, generated SDK, transport schema, and visible tool set are unchanged. Mode or filter changes may invalidate reuse from the first changed prompt or schema token.
+
 ### Tool-call history and results
 
-**What the model sees**: The loop retains model-emitted arguments and the registry's final content. Any thrown or denied call becomes exactly `Error: <message>`. Code Mode returns only the outer program's printed lines and rendered return value, `(run_code completed with no output)` when both are empty, or `Error: code run failed (<kind>): <message>` followed conditionally by `Captured output:` and the captured lines. Inner dispatch events stay log-only; post-execute listeners may append source-attributed context after the result.
+#### What the model sees
 
-**Token effect**: Arguments, results, and additional context are data-dependent and resent until compaction. Restrictions that hide tools also remove their schemas before the model can call them.
+The loop retains model-emitted arguments and the registry's final content. Any thrown or denied call becomes exactly `Error: <message>`. Code Mode returns only the outer program's printed lines and rendered return value, `(run_code completed with no output)` when both are empty, or `Error: code run failed (<kind>): <message>` followed conditionally by `Captured output:` and the captured lines. Inner dispatch events stay log-only; post-execute listeners may append source-attributed context after the result.
+
+#### Token effect
+
+Arguments, results, and additional context are data-dependent and resent until compaction. Restrictions that hide tools also remove their schemas before the model can call them.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
 ## Known Limitations and Deferred Work
 
-- **Native tool calls execute sequentially** — `ToolDefinition` carries no concurrency-safety metadata; adding it (and parallel execution in the loop) waits on the deferred tool-shapes review (`TODO(review)`).
+- **Concurrency policy is not an event seam** — `executionMode()` reads the resolved tool definition directly; plugins can only declare a classifier on definitions they own.
 - **`tools/pre-execute` deliberately cannot rewrite `exec.arguments`** — logged and rendered args would desync from what ran; the rewrite design is [a proposed RFC](../../../docs/rfc/proposed/feature/2026-06-30-pre-tool-input-rewrite.md).
-- **`defineTool`'s schema DSL is a deliberate subset** — string/number/boolean/object/array with string-only `enum`; `validateArgs` tolerates extra keys and never applies `default` (`XXX(unused-default)` flags removing that field); raw-registered JSON-Schema tools validate their own input.
+- **`defineTool`'s schema DSL is a deliberate subset** — string/number/boolean/object/array with string-only `enum`; `validateArgs` tolerates extra keys and preserves `default` as a model-visible JSON Schema annotation without applying it during validation; dynamic Cordis mounts may supply defaults even though first-party definitions do not, while raw-registered JSON-Schema tools validate their own input.
 - **`timeoutMs` on a definition is declarative only** — the registry never enforces deadlines; enforcement requires the `@deepseek-ai/dsh-timeout-policy` wrapper.
 - **Code Mode is TypeScript-only and the presentation mode is service-wide** — `mode: code`/`both` rejects prompt assembly unless `ctx.codeRuntime.language === 'typescript'`; scoped restrictions/shadows still choose each agent's visible bindings, but one tool cannot be native-only while another is code-only.
 - **Code Mode bindings return text only** — non-text content blocks in a sub-call result collapse to `[<type> content]` placeholders.

packages/core/tools/src/index.ts

@@ -117,9 +117,6 @@ declare module 'cordis' {
   }
 }
 
-// TODO(concurrency): revisit these shapes when concurrency metadata becomes useful
-// (for example, a read-only hint that would permit safe parallel execution).
-
 /** Tool output, optionally with lossless-JSON presentation metadata persisted for replay. */
 export type ToolExecuteReturn = ContentBlock[] | { content: ContentBlock[]; meta?: unknown }
 
@@ -134,6 +131,20 @@ export interface ToolDefinition extends ToolSchema {
    * cooperative implementation that can reach quiescence when the signal aborts.
    */
   timeoutMs?: number
+  /**
+   * Pure synchronous classifier for overlap with sibling tool calls. Only
+   * `true` opts in; omission, exceptions, non-`true` returns, and invalid
+   * `defineTool` arguments are exclusive. This metadata is never model-visible.
+   *
+   * Opted-in executions must not mutate parent-owned state. Shared state must
+   * tolerate concurrent dispatch; recorder races are permitted only when they
+   * commute or fail closed. See the
+   * [parallel-tool-call RFC](../../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md)
+   * for the full contract.
+   * @param args - parsed arguments; `defineTool` validates before calling.
+   * @returns Whether this call may join a parallel group.
+   */
+  isConcurrencySafe?(args: unknown): boolean
   /**
    * Optional: how to present the PENDING state of one call in a UI, derived from
    * the call's `args` (parsed arguments, `unknown` — the tool validates/narrows
@@ -195,6 +206,14 @@ export interface ToolExecutionInput {
   signal?: AbortSignal
 }
 
+/**
+ * Scheduling mode for one pending call. `parallel` may overlap with siblings;
+ * `exclusive` runs alone and forms an ordering barrier.
+ */
+export type ToolExecutionMode =
+  | { kind: 'parallel' }
+  | { kind: 'exclusive' }
+
 /**
  * One pending tool call inside the registry pipeline. Parsed arguments cross
  * one lossless-JSON materialization boundary before policy and are deep-frozen;
@@ -222,6 +241,47 @@ export interface ToolRunContext extends ToolExecution {
   deferContext(context: HookContext): void
 }
 
+/**
+ * Scheduler-only result after ordered pre-execute and guards. A `post-result`
+ * still receives post-execute; a `final-result` bypasses it.
+ * @internal
+ */
+export type ScheduledToolPreparation =
+  | { kind: 'dispatch'; exec: ToolRunContext }
+  | { kind: 'post-result'; exec: ToolRunContext; result: ToolExecutionResult }
+  | { kind: 'final-result'; exec: ToolRunContext; result: ToolExecutionResult }
+
+/**
+ * Scheduler-only dispatch result. A `post-result` still receives post-execute;
+ * a `final-result` already matches {@link ToolRegistry.execute} failure semantics.
+ * @internal
+ */
+export type ScheduledToolDispatch =
+  | { kind: 'post-result'; result: ToolExecutionResult }
+  | { kind: 'final-result'; result: ToolExecutionResult }
+
+/**
+ * Symbol-keyed scheduler view that keeps pre/post policy ordered while
+ * overlapping dispatch. Ordinary callers use {@link ToolRegistry.execute};
+ * this is not a plugin seam.
+ * @internal
+ */
+export interface ToolRegistryScheduler {
+  /** Materialize input, run the ordered pre-execute/guard gate, and decide what stage follows. */
+  prepare(exec: ToolExecutionInput): Promise<ScheduledToolPreparation>
+  /** Run only the around-dispatch/body stage. */
+  dispatch(exec: ToolRunContext): Promise<ScheduledToolDispatch>
+  /** Run ordered post-execute finalization, then materialize and notify the final outcome. */
+  finalize(exec: ToolRunContext, result: ToolExecutionResult): Promise<ToolExecutionResult>
+  /** Materialize and notify a final outcome that must bypass post-execute. */
+  finish(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult
+}
+
+/**
+ * Scheduler entry point omitted from the generated named service API.
+ * @internal
+ */
+export const TOOL_REGISTRY_SCHEDULER: unique symbol = Symbol('@deepseek-ai/dsh-tools.scheduler')
 /** Structured error metadata for a failed tool call (alongside the model-facing text). */
 export interface ToolErrorInfo {
   name: string
@@ -382,6 +442,16 @@ export class ToolRegistry extends Service {
     mode: z.union(['native', 'code', 'both'] as const).default('native'),
   })
 
+  /** Internal staged view consumed by `dsh-agent-loop`'s parallel scheduler. */
+  readonly [TOOL_REGISTRY_SCHEDULER]: ToolRegistryScheduler = {
+    prepare: exec => this.prepareScheduledExecution(exec),
+    dispatch: exec => this.dispatchScheduledExecution(exec),
+    finalize: (exec, result) => this.finalizeScheduledExecution(exec, result),
+    finish: (exec, result) => this.finishScheduledExecution(exec, result),
+  }
+
+  /** Context deferred by a running tool body, keyed by its scheduler-owned execution. */
+  private deferredContexts = new WeakMap<ToolRunContext, HookContext[]>()
   private global = new Map<string, ToolDefinition>()
   private scoped = new Map<ScopeKey, Map<string, ToolDefinition>>()
   /** Compiled restriction filters, per scope (see {@link restrict}). */
@@ -682,6 +752,24 @@ export class ToolRegistry extends Service {
     }
   }
 
+  /**
+   * Classify a pending call through the caller's visible tool definition. Only
+   * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or
+   * throwing classifiers are exclusive.
+   * @param exec - call name, parsed arguments, and optional agent scope.
+   * @returns the fail-closed scheduling mode.
+   */
+  executionMode(exec: ToolExecutionInput): ToolExecutionMode {
+    const tool = this.get(exec.name, exec.agent)
+    if (!tool?.isConcurrencySafe) return { kind: 'exclusive' }
+    try {
+      const concurrencySafe: unknown = tool.isConcurrencySafe(exec.arguments)
+      return concurrencySafe === true ? { kind: 'parallel' } : { kind: 'exclusive' }
+    } catch {
+      return { kind: 'exclusive' }
+    }
+  }
+
   /**
    * Execute through pre-policy, guards, around-dispatch, post-policy, and final
    * notification. Tool and listener failures resolve as materialized error
@@ -692,6 +780,28 @@ export class ToolRegistry extends Service {
    * @returns the materialized final result.
    */
   async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult> {
+    return this.prepareExecution(exec, prepared => this.completeScheduledExecution(prepared))
+  }
+
+  private async completeScheduledExecution(prepared: ScheduledToolPreparation): Promise<ToolExecutionResult> {
+    switch (prepared.kind) {
+      case 'dispatch': {
+        const dispatched = await this.dispatchScheduledExecution(prepared.exec)
+        return dispatched.kind === 'post-result'
+          ? await this.finalizeScheduledExecution(prepared.exec, dispatched.result)
+          : this.finishScheduledExecution(prepared.exec, dispatched.result)
+      }
+      case 'post-result':
+        return await this.finalizeScheduledExecution(prepared.exec, prepared.result)
+      case 'final-result':
+        return this.finishScheduledExecution(prepared.exec, prepared.result)
+      /* v8 ignore next -- closed-union exhaustiveness guard */
+      default:
+        return assertNever(prepared, 'scheduled tool preparation')
+    }
+  }
+
+  private createExecution(exec: ToolExecutionInput): ScheduledToolPreparation | { kind: 'ready'; exec: ToolRunContext } {
     const deferredContexts: HookContext[] = []
     const token = createExecutionToken()
     const callId = exec.callId
@@ -710,105 +820,143 @@ export class ToolRegistry extends Service {
         deferredContexts.push(context)
       },
     }
-    let execution: ToolRunContext
     try {
       const detached = snapshotJsonValue(exec.arguments)
       if (detached === undefined) {
         throw new TypeError('tool execution arguments must be losslessly JSON-serializable')
       }
-      execution = {
-        ...base,
-        arguments: deepFreeze(detached),
-      }
+      const execution: ToolRunContext = { ...base, arguments: deepFreeze(detached) }
+      this.deferredContexts.set(execution, deferredContexts)
+      return { kind: 'ready', exec: execution }
     } catch (error: unknown) {
-      execution = { ...base, arguments: undefined }
-      const result = this.materializeFinalResult(toolErrorResult(error))
-      this.notifyResult(execution, result)
-      return result
+      const execution: ToolRunContext = { ...base, arguments: undefined }
+      return { kind: 'final-result', exec: execution, result: toolErrorResult(error) }
     }
-    let result: ToolExecutionResult
+  }
+
+  /**
+   * Run the ordered pre-execute and monotonic guard stages for the scheduler.
+   * @param input - the caller-supplied execution input.
+   * @returns the prepared execution plus the next scheduler stage.
+   * @internal
+   */
+  private async prepareScheduledExecution(input: ToolExecutionInput): Promise<ScheduledToolPreparation> {
+    return this.prepareExecution(input, prepared => prepared)
+  }
+
+  private async prepareExecution<T>(
+    input: ToolExecutionInput,
+    next: (prepared: ScheduledToolPreparation) => T | PromiseLike<T>,
+  ): Promise<T> {
+    const created = this.createExecution(input)
+    if (created.kind !== 'ready') return next(created)
+    const exec = created.exec
     try {
-      result = this.materializeFinalResult(await this.executePipeline(execution, deferredContexts))
+      const carrier = scopeTarget(this, exec.agent)
+      const gate = await this.ctx.waterfall(
+        carrier, 'tools/pre-execute', exec,
+        () => Promise.resolve<PreToolDecision>({ kind: 'allow' }),
+      )
+      const decision = gate.kind === 'ask' ? await this.serviceAsk(exec, gate) : gate
+      const denialReason = decision.kind === 'allow'
+        ? this.guardReason(exec)
+        : decision.reason
+      if (denialReason !== undefined) {
+        return await next({
+          kind: 'post-result',
+          exec,
+          result: {
+            content: [{ type: 'text', text: `Error: ${denialReason}` }],
+            isError: true,
+          },
+        })
+      }
+      return await next({ kind: 'dispatch', exec })
     } catch (error: unknown) {
-      // Outer backstop: a throwing pre/post-execute listener, guard, or the
-      // waterfall machinery becomes an isError result, never a turn failure.
-      result = this.materializeFinalResult(toolErrorResult(error))
+      return next({ kind: 'final-result', exec, result: toolErrorResult(error) })
     }
-    this.notifyResult(execution, result)
-    return result
   }
 
-  /** Run the transformable pipeline; {@link execute} owns final normalization and notification. */
-  private async executePipeline(exec: ToolRunContext, deferredContexts: HookContext[]): Promise<ToolExecutionResult> {
-    // --- Gate: tools/pre-execute. An `ask` resolves through the optional
-    // approval seam (or degrades to deny) before the monotonic guards run. The
-    // carrier keys dispatch by exec.agent, so an `agent.ctx` listener gates only
-    // its own agent's calls (agent-less calls are subject-less).
-    const carrier = scopeTarget(this, exec.agent)
-    const gate = await this.ctx.waterfall(
-      carrier, 'tools/pre-execute', exec,
-      () => Promise.resolve<PreToolDecision>({ kind: 'allow' }),
-    )
-    const decision = gate.kind === 'ask' ? await this.serviceAsk(exec, gate) : gate
-    const denialReason = decision.kind === 'allow'
-      ? this.guardReason(exec)
-      : decision.reason
-    if (denialReason !== undefined) {
-      // Every non-grant, including a failed/unavailable approval request, takes
-      // the same deny path and still reaches post-policy plus result observers.
-      const denied: ToolExecutionResult = {
-        content: [{ type: 'text', text: `Error: ${denialReason}` }],
-        isError: true,
-      }
-      return await this.postExecute(exec, denied)
-    }
-
-    // --- Around-dispatch: tools/execute. The base `next` is the dispatch-
-    // with-normalization thunk — the tool body's own try/catch turns a throw
-    // into an isError result so a wrapper (and post-execute) can inspect it;
-    // an unknown tool routes through the same catch. A `tools/execute` listener
-    // (e.g. a timeout plugin) wraps this thunk: it may replace `exec.signal`
-    // before delegating and inspect the normalized result after. Dispatched with the
-    // same carrier as the gate, so an `agent.ctx` wrapper wraps only its own
-    // agent's calls. ---
-    const result = await this.ctx.waterfall(
-      carrier, 'tools/execute', exec,
-      async (): Promise<ToolExecutionResult> => {
-        try {
-          // Resolve through the CALLER's visible view ({@link get}): a scoped
-          // tool shadows its global name-twin for that agent, and a
-          // restricted-away global tool is exactly as absent as a nonexistent
-          // one — same UNKNOWN_TOOL result, no capability leak in the error.
-          const tool = this.get(exec.name, exec.agent)
-          if (!tool) throw new ToolNotFoundError(exec.name)
-          // Normalize the two `execute` return shapes: a bare ContentBlock[] (no
-          // meta) or a { content, meta } object (a tool attaching a private
-          // presentation payload). An array IS the content; the object carries it.
-          const returned = await tool.execute(exec.arguments, exec)
-          const content = Array.isArray(returned) ? returned : returned.content
-          const meta = Array.isArray(returned) ? undefined : returned.meta
-          return { content, isError: false, ...meta !== undefined ? { meta } : {} }
-        } catch (error: unknown) {
-          return toolErrorResult(error)
+  /**
+   * Run around-dispatch and the tool body. Tool and unknown-tool failures still
+   * receive post-execute; pipeline failures are already final.
+   * @param exec - the prepared execution.
+   * @returns whether the result still needs post-execute.
+   * @internal
+   */
+  private async dispatchScheduledExecution(exec: ToolRunContext): Promise<ScheduledToolDispatch> {
+    try {
+      const carrier = scopeTarget(this, exec.agent)
+      const result = await this.ctx.waterfall(
+        carrier, 'tools/execute', exec,
+        async (): Promise<ToolExecutionResult> => {
+          try {
+            const tool = this.get(exec.name, exec.agent)
+            if (!tool) throw new ToolNotFoundError(exec.name)
+            const returned = await tool.execute(exec.arguments, exec)
+            const content = Array.isArray(returned) ? returned : returned.content
+            const meta = Array.isArray(returned) ? undefined : returned.meta
+            return { content, isError: false, ...meta !== undefined ? { meta } : {} }
+          } catch (error: unknown) {
+            return toolErrorResult(error)
+          }
+        },
+      )
+      const deferredContexts = this.deferredContexts.get(exec)
+      /* v8 ignore next -- dispatch only receives executions minted by this registry's prepare stage */
+      if (deferredContexts === undefined) throw new Error('tool registry scheduler invariant violated: unprepared execution')
+      const resultWithDeferredContexts: ToolExecutionResult = deferredContexts.length === 0
+        ? result
+        : {
+          ...result,
+          additionalContexts: [
+            ...deferredContexts,
+            ...result.additionalContexts ?? [],
+          ],
         }
-      },
-    )
-    const resultWithDeferredContexts: ToolExecutionResult = deferredContexts.length === 0
-      ? result
-      : {
-        ...result,
-        additionalContexts: [
-          ...deferredContexts,
-          ...result.additionalContexts ?? [],
-        ],
-      }
-    return await this.postExecute(exec, resultWithDeferredContexts)
+      return { kind: 'post-result', result: resultWithDeferredContexts }
+    } catch (error: unknown) {
+      return { kind: 'final-result', result: toolErrorResult(error) }
+    }
   }
 
-  /** Notify final-result observers without giving them a mutation/error channel into the outcome. */
+  /**
+   * Run ordered post-execute, then materialize and notify the final outcome.
+   * @param exec - the prepared execution.
+   * @param result - dispatch/pre result that still needs post-execute.
+   * @returns the materialized final result.
+   * @internal
+   */
+  private async finalizeScheduledExecution(exec: ToolRunContext, result: ToolExecutionResult): Promise<ToolExecutionResult> {
+    try {
+      return this.finishScheduledExecution(exec, await this.postExecute(exec, result))
+    } catch (error: unknown) {
+      return this.finishScheduledExecution(exec, toolErrorResult(error))
+    }
+  }
+
+  /**
+   * Materialize and notify a final result that must bypass post-execute.
+   * @param exec - the prepared execution.
+   * @param result - final result.
+   * @returns the materialized final result.
+   * @internal
+   */
+  private finishScheduledExecution(exec: ToolRunContext, result: ToolExecutionResult): ToolExecutionResult {
+    let finalResult: ToolExecutionResult
+    try {
+      finalResult = this.materializeFinalResult(result)
+    } catch (error: unknown) {
+      finalResult = this.materializeFinalResult(toolErrorResult(error))
+    }
+    this.notifyResult(exec, finalResult)
+    return finalResult
+  }
+
+  /** Notify observers without exposing a mutation or error channel into the outcome. */
   private notifyResult(exec: ToolExecution, result: ToolExecutionResult): void {
-    // The pipeline is over: freeze the remaining mutable signal slot so every
-    // observer sees the SAME WeakMap-keyable execution without a mutation race.
+    // Freeze the remaining mutable signal slot before observers receive the
+    // shared WeakMap-keyable execution object.
     Object.freeze(exec)
     const callbacks = this.ctx.events.dispatch('emit', [
       scopeTarget(this, exec.agent), 'tools/result', exec, result,

packages/core/tools/src/schema.ts

@@ -21,12 +21,8 @@ export interface SchemaProp {
   /** Enum of allowed values (strings only). */
   enum?: string[]
   /**
-   * Default value, emitted into the JSON Schema only (validation never applies
-   * it — see the validator note below).
-   *
-   * XXX(unused-default): no tool definition in the repo sets `default`; it rides
-   * into the wire schema for a model that no tool surfaces it to. Drop the field
-   * and its converter line unless a real tool needs a model-visible default.
+   * Model-visible JSON Schema default annotation. Validation does not apply it;
+   * dynamic tool mounts may supply it even though first-party definitions do not.
    */
   default?: unknown
   /** Nested properties for type: 'object'. */
@@ -283,6 +279,14 @@ export interface DefineToolOptions<S extends SchemaSpec> {
    * is never sent to the model.
    */
   readonly timeoutMs?: number
+  /**
+   * Optional pure synchronous classifier for sibling overlap. It receives typed
+   * arguments after soft validation; invalid input returns `false` without
+   * invoking it. See {@link ToolDefinition.isConcurrencySafe}.
+   * @param args - typed validated arguments.
+   * @returns whether this call may join a parallel group.
+   */
+  isConcurrencySafe?(args: InferArgs<S>): boolean
   /**
    * Tool execution function. `args` is typed as {@link InferArgs<S>} — zero
    * casts needed. Returns either a bare {@link ContentBlock}`[]` (model-facing
@@ -315,7 +319,7 @@ export interface DefineToolOptions<S extends SchemaSpec> {
  * @param options - the tool's name, description, typed parameter schema,
  *   execute body, and optional presenters.
  * @returns a registry-ready definition with strict execution validation and
- *   soft presenter validation for replay compatibility.
+ *   soft presenter and classifier validation for replay compatibility.
  */
 export function defineTool<S extends SchemaSpec>(options: DefineToolOptions<S>): ToolDefinition {
   // Object-literal execute methods don't use `this`; the reference is safe.
@@ -325,6 +329,8 @@ export function defineTool<S extends SchemaSpec>(options: DefineToolOptions<S>):
   const userPresentCall = options.presentCall
   // eslint-disable-next-line @typescript-eslint/unbound-method
   const userPresentResult = options.presentResult
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const userIsConcurrencySafe = options.isConcurrencySafe
   if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
     throw new Error(`defineTool(${options.name}): timeoutMs must be a positive finite number`)
   }
@@ -359,5 +365,12 @@ export function defineTool<S extends SchemaSpec>(options: DefineToolOptions<S>):
       return userPresentResult(args as InferArgs<S>, result)
     }
   }
+  // Invalid arguments fail closed without invoking the typed classifier.
+  if (userIsConcurrencySafe) {
+    tool.isConcurrencySafe = (args: unknown): boolean => {
+      if (validateArgs(options.parameters, args).length > 0) return false
+      return userIsConcurrencySafe(args as InferArgs<S>)
+    }
+  }
   return tool
 }

packages/core/tools/tests/code-mode.spec.ts

@@ -8,7 +8,6 @@ import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
 import type { CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtime'
 import ToolRegistry, { CodeRunFailedError, RUN_CODE_NAME, defineTool } from '@deepseek-ai/dsh-tools'
 import type { Config, PostToolDecision, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEventMap } from '@deepseek-ai/dsh-session'
@@ -59,7 +58,7 @@ async function setup(options: SetupOptions = {}) {
 
 /** Mint one production-shaped agent scope that can register scoped tool policy. */
 async function mintAgentScope(ctx: Context, name = 'scoped'): Promise<{ scope: Scope; agent: Agent }> {
-  const agent = { id: AgentId(name) } as Agent
+  const agent = { id: SessionId(name) } as Agent
   let scope!: Scope
   await ctx.plugin(Object.assign((inner: Context) => { scope = createScope(inner, agent) },
     { inject: ['tools', 'systemPrompt'] }))

packages/core/tools/tests/execution-mode.spec.ts

@@ -0,0 +1,136 @@
+/** Covers fail-closed per-call classification and model-schema isolation. */
+
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, {
+  defineTool,
+  type ToolDefinition,
+  type ToolExecutionInput,
+  type ToolExecutionMode,
+} from '@deepseek-ai/dsh-tools'
+
+async function setup() {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  return ctx
+}
+
+function exec(name: string, args: unknown): ToolExecutionInput {
+  return { callId: CallId('c1'), name, arguments: args }
+}
+
+describe('ToolRegistry.executionMode', () => {
+  it('returns parallel only for an explicit true classifier', async () => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: 'safe',
+      description: 'parallel-safe',
+      parameters: {},
+      isConcurrencySafe: () => true,
+      async execute() { return [] },
+    }))
+    expect(ctx.tools.executionMode(exec('safe', {}))).toEqual({ kind: 'parallel' })
+  })
+
+  it('defaults to exclusive for a tool with no isConcurrencySafe declaration', async () => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: 'plain',
+      description: 'no declaration',
+      parameters: {},
+      async execute() { return [] },
+    }))
+    expect(ctx.tools.executionMode(exec('plain', {}))).toEqual({ kind: 'exclusive' })
+  })
+
+  it('returns exclusive for an unknown tool', async () => {
+    const ctx = await setup()
+    expect(ctx.tools.executionMode(exec('nonexistent', {}))).toEqual({ kind: 'exclusive' })
+  })
+
+  it('returns exclusive when the classifier returns false for these args', async () => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: 'rw',
+      description: 'read or write',
+      parameters: { mode: { type: 'string', required: true } },
+      isConcurrencySafe: args => args.mode === 'read',
+      async execute() { return [] },
+    }))
+    expect(ctx.tools.executionMode(exec('rw', { mode: 'read' }))).toEqual({ kind: 'parallel' })
+    expect(ctx.tools.executionMode(exec('rw', { mode: 'write' }))).toEqual({ kind: 'exclusive' })
+  })
+
+  it('classifies invalid defineTool arguments as exclusive without throwing', async () => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: 'needs-mode',
+      description: 'requires mode',
+      parameters: { mode: { type: 'string', required: true } },
+      isConcurrencySafe: () => true,
+      async execute() { return [] },
+    }))
+    expect(ctx.tools.executionMode(exec('needs-mode', {}))).toEqual({ kind: 'exclusive' })
+  })
+
+  it('treats a throwing raw classifier as exclusive', async () => {
+    const ctx = await setup()
+    const raw: ToolDefinition = {
+      name: 'thrower',
+      description: 'classifier throws',
+      parameters: { type: 'object', properties: {} },
+      isConcurrencySafe() { throw new Error('boom') },
+      async execute() { return [] },
+    }
+    ctx.tools.register(raw)
+    expect(ctx.tools.executionMode(exec('thrower', {}))).toEqual({ kind: 'exclusive' })
+  })
+
+  it('treats a truthy non-boolean raw result as exclusive', async () => {
+    const ctx = await setup()
+    const raw = {
+      name: 'truthy',
+      description: 'classifier returns a truthy string',
+      parameters: { type: 'object', properties: {} },
+      isConcurrencySafe() { return 'yes' },
+      async execute() { return [] },
+    } as unknown as ToolDefinition
+    ctx.tools.register(raw)
+    expect(ctx.tools.executionMode(exec('truthy', {}))).toEqual({ kind: 'exclusive' })
+  })
+
+  it('passes parsed arguments directly to a raw definition', async () => {
+    const ctx = await setup()
+    let seen: unknown
+    ctx.tools.register({
+      name: 'raw-safe',
+      description: 'raw',
+      parameters: { type: 'object', properties: {} },
+      isConcurrencySafe(args) { seen = args; return true },
+      async execute() { return [] },
+    })
+    expect(ctx.tools.executionMode(exec('raw-safe', { anything: 1 }))).toEqual({ kind: 'parallel' })
+    expect(seen).toEqual({ anything: 1 })
+  })
+
+  it('isConcurrencySafe never reaches the model-facing schemas() projection', async () => {
+    const ctx = await setup()
+    ctx.tools.register(defineTool({
+      name: 'safe',
+      description: 'parallel-safe',
+      parameters: { x: { type: 'string', required: true } },
+      isConcurrencySafe: () => true,
+      async execute() { return [] },
+    }))
+    const schema = ctx.tools.schemas()[0] as unknown as Record<string, unknown>
+    expect(Object.keys(schema).sort()).toEqual(['description', 'name', 'parameters'])
+    expect(schema.isConcurrencySafe).toBeUndefined()
+  })
+
+  it('ToolExecutionMode is the object-tagged union', () => {
+    expectTypeOf<ToolExecutionMode>().toEqualTypeOf<{ kind: 'parallel' } | { kind: 'exclusive' }>()
+  })
+})

packages/core/tools/tests/scoped.spec.ts

@@ -6,9 +6,11 @@ import type { Scope } from '@deepseek-ai/dsh-scope'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import type { PreToolDecision, ToolDefinition, ToolExecution, ToolExecutionInput, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
-import type { Agent, AgentId } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+
 import { CallId } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SessionId } from '@deepseek-ai/dsh-session'
 
 /** Mount the registry (with its systemPrompt dependency) on a fresh context. */
 async function mount(): Promise<Context> {
@@ -20,7 +22,7 @@ async function mount(): Promise<Context> {
 
 /** Mint a scope whose key doubles as a minimal Agent-like object. */
 async function mintAgentScope(ctx: Context, name: string): Promise<{ scope: Scope; key: Agent }> {
-  const key = { id: name as AgentId } as Agent
+  const key = { id: name as SessionId } as Agent
   let scope!: Scope
   // The scoped context resolves services through the MINTING plugin's
   // dependency chain — the minter must inject what scope holders will reach
@@ -62,7 +64,7 @@ describe('scoped tool registration', () => {
   it('files a scoped tool in its layer: visible/executable for that scope only', async () => {
     const ctx = await mount()
     const { scope, key } = await mintAgentScope(ctx, 'a')
-    const other = { id: 'other' as AgentId } as Agent
+    const other = { id: 'other' as SessionId } as Agent
     ctx.tools.register(tool('shared'))
     scope.ctx.tools.register(tool('mine'))
 
@@ -195,7 +197,7 @@ describe('scoped execution dispatch', () => {
   it('an agent.ctx pre-execute listener gates only its own agent (and never subject-less calls)', async () => {
     const ctx = await mount()
     const { scope, key } = await mintAgentScope(ctx, 'a')
-    const other = { id: 'other' as AgentId } as Agent
+    const other = { id: 'other' as SessionId } as Agent
     ctx.tools.register(tool('t'))
 
     const seen: (string | undefined)[] = []
@@ -213,7 +215,7 @@ describe('scoped execution dispatch', () => {
   it('applies scoped guards after pre-execute and unwinds duplicate registrations independently', async () => {
     const ctx = await mount()
     const { scope, key } = await mintAgentScope(ctx, 'a')
-    const other = { id: 'other' as AgentId } as Agent
+    const other = { id: 'other' as SessionId } as Agent
     let bodyCalls = 0
     ctx.tools.register({
       ...tool('t'),
@@ -428,7 +430,7 @@ describe('scoped execution dispatch', () => {
   it('uses one input snapshot for the normalized error shell', async () => {
     const ctx = await mount()
     const { scope, key } = await mintAgentScope(ctx, 'accepted')
-    const driftAgent = { id: 'drift' as AgentId } as Agent
+    const driftAgent = { id: 'drift' as SessionId } as Agent
     ctx.tools.register(tool('parent'))
     ctx.tools.register(tool('t'))
     let parent!: ToolExecutionToken

packages/examples/README.md

@@ -5,11 +5,12 @@ Pre-composed plugin bundles a thin leaf `cordis.yml` loads instead of assembling
 | Package | npm name | Role |
 |---|---|---|
 | `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | The executor-less/UI-less agent spine as one bundle plugin (`timer` + `llm` + sessions + system-prompt + tools + skills + agents + invariants + `tool-bash` + workspace-context + `tool-skill` + `agent-loop`) |
-| `stdio-demo/` | `@deepseek-ai/dsh-stdio-demo` | Terminal stdio chat app: the spine + console logger + readline UI + a pre-created `main` agent, with a boot `bin` |
+| `stdio-demo/` | `@deepseek-ai/dsh-stdio-demo` | Terminal chat app: the spine + JSONL persistence + TTY-selected `dsh-tui`/`dsh-stdio` front door + a pre-created `main` agent, with a boot `bin` |
+| `cli-demo/` | `@deepseek-ai/dsh-cli-demo` | Headless one-shot app: the spine + JSONL persistence + a pre-created `main` agent, with text and DSH-native JSON output |
 | `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP server app: the spine + JSONL persistence + the [`acp`](../ui/acp/README.md) bridge (no stdout logger), with a boot `bin` |
 | `jsonrpc-demo/` | `@deepseek-ai/dsh-jsonrpc-demo` | Bin-only runtime that boots an external `cordis.yml` for the stdio JSON-RPC SDK client |
 
-`agent-spine-demo` is the shared bundle; `stdio-demo` and `acp-demo` compose it with opposite front-door clusters (console logger + readline UI vs the stdout-owning ACP bridge) and own their boot bins. `jsonrpc-demo` mounts no composition of its own — it boots whatever tree the deployment's `cordis.yml` names, and is what the Python SDK runtime launches.
+`agent-spine-demo` is the shared bundle; `stdio-demo`, `cli-demo`, and `acp-demo` compose it with terminal, headless one-shot, and ACP front doors and own their boot bins. `jsonrpc-demo` mounts no composition of its own — it boots whatever tree the deployment's `cordis.yml` names, and is what the Python SDK runtime launches.
 
 These are **not** product API. The spine pieces they bundle live in [`core/`](../core/README.md), the bridges/channels/boot-glue in [`ui/`](../ui/README.md), and the swappable backends (LLM adapter, bash executor) in their capability groups; a demo bundle just picks one concrete composition of them. Swap or fork one freely.
 

packages/examples/acp-demo/README.md

@@ -27,6 +27,7 @@ Because the package wires no logger entry, an ACP leaf has **nothing to get wron
 |---|---|---|
 | `provider` | (required) | the initial provider route for each per-session agent the bridge creates; ACP model selection may replace it per session |
 | `model` | (required) | the initial model for each per-session agent; ACP clients may switch among adapter-advertised models |
+| `maxParallelToolCalls` | agent-loop default | positive-integer concurrent tool-call cap shared by the bundled loop's agents; `1` is serial |
 | `persona` | — | the deployment persona template (may reference `{{provider}}`/`{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
 | `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
 | `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home exposed to model bash and used by local skill discovery |
@@ -54,6 +55,10 @@ All diagnostics go to **stderr** — stdout is the protocol.
 
 Indirectly, through `dsh-agent-spine-demo` and `dsh-acp`, which compose each ACP agent's prompt, tools, and message history; this app bundle adds no model-bound content itself.
 
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
 ## Known Limitations and Deferred Work
 
 - **JSONL persistence is baked in** — config chooses its root but cannot select a different backend; that requires a sibling entry or differently composed app package.

packages/examples/acp-demo/src/index.ts

@@ -19,6 +19,7 @@ import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 
 export const name = 'acp-demo'
+const DEFAULT_PERSISTENCE_ROOT = './.sessions'
 
 /**
  * App config: the swappable per-deployment values. `provider` and `model` configure the
@@ -34,6 +35,8 @@ export interface Config {
   provider: string
   /** Model name for ACP-created agents (must have a registered adapter). */
   model: string
+  /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */
+  maxParallelToolCalls?: number
   /** Deployment persona (the system-prompt plugin's `persona` config). */
   persona?: string
   /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */
@@ -60,6 +63,7 @@ export interface Config {
 export const Config: z<Config> = z.object({
   provider: z.string().required(),
   model: z.string().required(),
+  maxParallelToolCalls: z.number().step(1).min(1),
   persona: z.string(),
   // The array default is forced to undefined: ABSENT means "lexicographic
   // order" (the owning dsh-system-prompt schema does the same), while
@@ -67,9 +71,7 @@ export const Config: z<Config> = z.object({
   toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
   tools: ToolRegistry.Config,
   dshHome: z.string(),
-  // TODO(single-default-literal): share this schema default and the defensive
-  // apply() fallback through one named constant while retaining both boundaries.
-  persistenceRoot: z.string().default('./.sessions'),
+  persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT),
   workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
   skills: agentCore.SkillConfigSchema,
   toolBash: agentCore.ToolBashConfigSchema,
@@ -87,6 +89,6 @@ export const Config: z<Config> = z.object({
 export function apply(ctx: Context, config: Config): void {
   ctx.plugin(agentCore, agentCore.pickSpineConfig(config))
   ctx.plugin(UserInteractionService)
-  ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
+  ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT })
   ctx.plugin(acp, { provider: config.provider, model: config.model })
 }

packages/examples/acp-demo/tests/acp-agent.spec.ts

@@ -83,7 +83,7 @@ describe('dsh-acp-demo composition', () => {
   })
 
   it('defaults the persistence root when omitted', async () => {
-    // Exercises the `?? './.sessions'` fallback for a direct-apply caller that
+    // Exercises the `DEFAULT_PERSISTENCE_ROOT` fallback for a direct-apply caller that
     // bypasses the schema's `.default(...)`: call `apply` directly (not via
     // `ctx.plugin`, which validates+defaults the config first) with no
     // persistenceRoot, so the runtime fallback is the one that fires.
@@ -127,6 +127,19 @@ describe('dsh-acp-demo composition', () => {
     await ctx.fiber.dispose()
   })
 
+  it('forwards maxParallelToolCalls to the bundled agent loop', async () => {
+    const ctx = await mount({
+      provider: 'mock',
+      model: 'mock',
+      maxParallelToolCalls: 3,
+      persistenceRoot: '/tmp/dsh-acp-demo-test-parallel',
+      skills: await isolatedSkillsConfig(),
+      workspaceContext: false,
+    })
+    expect(ctx.get('agentLoop')?.config.maxParallelToolCalls).toBe(3)
+    await ctx.fiber.dispose()
+  })
+
   it('forwards bundled tool config into agent-core', async () => {
     const ctx = await mount({
       provider: 'mock',

packages/examples/agent-spine-demo/README.md

@@ -16,7 +16,7 @@ Read this package for the whole plugin tree and its composition order.
 @deepseek-ai/dsh-tools            registry + guarded pre/around/post/final-result pipeline
 @deepseek-ai/dsh-skill            skill provider registry
 @deepseek-ai/dsh-skill-local      local filesystem skill provider
-@deepseek-ai/dsh-agent            agent registry + agent/* event vocabulary
+@deepseek-ai/dsh-agent            agent registry + initiator scope + agent/* events
 @deepseek-ai/dsh-tasks            generic background-task registry
 @deepseek-ai/dsh-invariants       dev-mode event-contract assertions
 @deepseek-ai/dsh-tool-bash        the model-facing bash schema
@@ -34,7 +34,7 @@ The spine is everything COMMON to every front door. The swappable and front-door
 - **the LLM adapter** — the bundle ships the abstract `llm` service; the leaf registers a concrete adapter on `ctx.llm` (`llm-deepseek`, `llm-pi-ai`, `llm-replay`).
 - **the bash executor** — the bundle ships `tool-bash` (the consumer schema); the leaf provides `ctx.bash` (`bash-local` or a sandboxed impl).
 - **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings.
-- **presentation + per-app infra** — the stdio UI / ACP bridge, a console logger, `hmr`. These form the coupled "front-door cluster" that the app packages ([`dsh-stdio-demo`](../../examples/stdio-demo/README.md), [`dsh-acp-demo`](../../examples/acp-demo/README.md)) bake in. `timer` is in the spine (common to both, stdout-silent); a console logger is NOT (it writes to stdout, which the ACP bridge reserves for JSON-RPC).
+- **presentation + per-app infra** — the terminal (`dsh-tui` / `dsh-stdio`) or ACP front door and `hmr`. These form the coupled front-door cluster that the app packages ([`dsh-stdio-demo`](../../examples/stdio-demo/README.md), [`dsh-acp-demo`](../../examples/acp-demo/README.md)) bake in. `timer` is in the spine because it is common and stdout-silent; front doors own stdout and remain outside.
 
 This is the [interface/implementation/consumer seam](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md) raised to the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door.
 
@@ -42,11 +42,11 @@ This is the [interface/implementation/consumer seam](../../../docs/rfc/implement
 
 ```ts
 import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
-// { agents?, persona?, toolOrder?, tools?, dshHome?, skills?, workspaceContext, toolBash?, toolTasks? }
+// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, skills?, workspaceContext, toolBash?, toolTasks? }
 // workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults.
 ```
 
-The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. It resolves `dshHome` once through [`@deepseek-ai/dsh-home`](../../util/home/README.md) and forwards that absolute value to tool-bash's managed environment and local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer, while `toolTasks` controls generic `task_output` wait bounds; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields.
+The bundle FORWARDS each field to the child that owns it: `agents` and `maxParallelToolCalls` to `agent-loop` (`agents` defaults to `[]`; the cap defaults there), so each app supplies its own pre-created agents — a stdio app pre-creates `main`, while the ACP app creates agents on demand at `session/new`; `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. It resolves `dshHome` once through [`@deepseek-ai/dsh-home`](../../util/home/README.md) and forwards that absolute value to tool-bash's managed environment and local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer, while `toolTasks` controls generic `task_output` wait bounds; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields.
 
 ## Why a code bundle, not a shared YAML include
 
@@ -56,6 +56,10 @@ A YAML include can deduplicate config but cannot own a bin or provide front-door
 
 Indirectly, through `dsh-system-prompt`, `dsh-tool-skill`, `dsh-tool-bash`, and `dsh-tools`, which this bundle mounts without adding model-bound wrapper content.
 
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
 ## Known Limitations and Deferred Work
 
 - **The spine set is fixed in code** — `apply()` mounts every child unconditionally (including `tool-bash`); no config excludes or replaces one, so swapping the loop or dropping a spine member means composing a different bundle.

packages/examples/agent-spine-demo/src/index.ts

@@ -57,6 +57,8 @@ export interface SkillConfig {
 export interface Config {
   /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
   agents?: AgentLoopConfig['agents']
+  /** Agent-loop concurrency cap; `1` is serial. */
+  maxParallelToolCalls?: AgentLoopConfig['maxParallelToolCalls']
   /** The deployment persona (see dsh-system-prompt's `Config`). */
   persona?: SystemPromptConfig['persona']
   /** The explicit model-facing tool order (see dsh-system-prompt's `Config`). */
@@ -109,6 +111,7 @@ export const Config = z.intersect([
  */
 export function pickSpineConfig(config: Omit<Config, 'agents'>): Omit<Config, 'agents'> {
   return {
+    ...config.maxParallelToolCalls !== undefined ? { maxParallelToolCalls: config.maxParallelToolCalls } : {},
     ...config.persona !== undefined ? { persona: config.persona } : {},
     ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
     ...config.tools !== undefined ? { tools: config.tools } : {},
@@ -160,5 +163,8 @@ export function apply(ctx: Context, config: Config): void {
   // rendered order, so workspace instructions must precede the skill catalog.
   ctx.plugin(toolSkill, config.skills?.tool ?? {})
   ctx.plugin(toolTasks, config.toolTasks ?? {})
-  ctx.plugin(AgentLoop, { agents: config.agents ?? [] })
+  ctx.plugin(AgentLoop, {
+    agents: config.agents ?? [],
+    ...config.maxParallelToolCalls !== undefined ? { maxParallelToolCalls: config.maxParallelToolCalls } : {},
+  })
 }

packages/examples/agent-spine-demo/tests/agent-core.spec.ts

@@ -6,7 +6,7 @@ import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import * as agentCore from '../src/index.ts'
-import { AgentId, agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
+import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
@@ -86,10 +86,10 @@ async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
   }
 }
 
-function waitForMainIdle(ctx: Context): Promise<void> {
+function waitForIdle(ctx: Context, target: Agent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = ctx.on('agent/status', (agent, status) => {
-      if (agent.id === 'main' && status === 'idle') {
+      if (agent === target && status === 'idle') {
         dispose()
         resolve()
       }
@@ -129,22 +129,34 @@ describe('dsh-agent-spine-demo bundle', () => {
 
   it('defaults the agents list to empty (no pre-created agents)', async () => {
     const ctx = await mount({ workspaceContext: false })
-    expect(ctx.get('agents')?.get(AgentId('main'))).toBeUndefined()
+    expect(ctx.get('agents')?.get(SessionId('main'))).toBeUndefined()
     await ctx.fiber.dispose()
   })
 
   it('forwards a pre-created agent to the loop and the persona to system-prompt', async () => {
     const ctx = await mount({
-      agents: [{ id: AgentId('main'), provider: 'mock', model: 'mock' }],
+      agents: [{ id: SessionId('main'), provider: 'mock', model: 'mock' }],
       persona: 'You are main.',
       workspaceContext: false,
     })
-    expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
+    const agent = ctx.get('agents')?.list()[0]
+    expect(agent?.id).toBe(agent?.session.id)
+    expect(agent?.id).toMatch(/^main-session-/)
     const assembly = await ctx.get('systemPrompt')!.assemble()
     expect(assembly.sections.find(s => s.name === 'deployment:persona')?.text).toBe('You are main.')
     await ctx.fiber.dispose()
   })
 
+  it('forwards the global maxParallelToolCalls config to agent-loop', async () => {
+    const ctx = await mount({
+      agents: [{ id: SessionId('main'), provider: 'mock', model: 'mock' }],
+      maxParallelToolCalls: 3,
+      workspaceContext: false,
+    })
+    expect(ctx.get('agentLoop')?.config.maxParallelToolCalls).toBe(3)
+    await ctx.fiber.dispose()
+  })
+
   it('tolerates a schema-bypassing direct apply (the ?? fallbacks fire)', async () => {
     // ctx.plugin validates + defaults the bundle config first; a direct apply
     // skips the schema, so the forwarding `?? []` / `?? ''` are what fire.
@@ -168,7 +180,6 @@ describe('dsh-agent-spine-demo bundle', () => {
       await ctx.plugin(LocalFileSystem, { cwd: '/' })
       ctx.llm.registerAdapter(['mock'], adapter)
       const handle = await ctx.agents.create({
-        agentId: AgentId('main'),
         sessionId: SessionId('main-session'),
         meta: { cwd: root },
         agentOptions: { provider: 'mock', model: 'mock' },
@@ -176,7 +187,7 @@ describe('dsh-agent-spine-demo bundle', () => {
       const agent = handle.agent
 
       agent.send([{ type: 'text', text: 'hi' }])
-      await waitForMainIdle(ctx)
+      await waitForIdle(ctx, agent)
 
       const sentText = adapter.requests[0]?.messages.map(messageText).join('\n')
       expect(sentText).toContain('hi')
@@ -199,14 +210,13 @@ describe('dsh-agent-spine-demo bundle', () => {
       const ctx = await mount({ workspaceContext: { maxBytes: 0 } })
       ctx.llm.registerAdapter(['mock'], adapter)
       const handle = await ctx.agents.create({
-        agentId: AgentId('main'),
         sessionId: SessionId('main-disabled-session'),
         meta: { cwd: root },
         agentOptions: { provider: 'mock', model: 'mock' },
       })
 
       handle.agent.send([{ type: 'text', text: 'hi' }])
-      await waitForMainIdle(ctx)
+      await waitForIdle(ctx, handle.agent)
 
       expect(adapter.requests[0]?.messages).toEqual([{ role: 'user', content: [{ type: 'text', text: 'hi' }] }])
       await handle.dispose()
@@ -289,14 +299,13 @@ describe('dsh-agent-spine-demo bundle', () => {
         content: 'body',
       })
       const handle = await ctx.agents.create({
-        agentId: AgentId('main'),
         sessionId: SessionId('prefix-order-session'),
         meta: { cwd: root },
         agentOptions: { provider: 'mock', model: 'mock' },
       })
 
       handle.agent.send([{ type: 'text', text: 'hi' }])
-      await waitForMainIdle(ctx)
+      await waitForIdle(ctx, handle.agent)
 
       expect(messageText(adapter.requests[0]?.messages[0])).toContain('workspace rule before skills')
       expect(messageText(adapter.requests[0]?.messages[1])).toContain('prefix-order-skill')

packages/examples/cli-demo/README.md

@@ -0,0 +1,74 @@
+# @deepseek-ai/dsh-cli-demo
+
+Headless one-shot app and bin for running one agent task without a readline or editor client. It composes [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md), JSONL persistence, and exactly one fresh top-level agent. The bin submits the task, waits for its durable turn ending, renders the selected output, disposes to quiescence, and exits.
+
+The package mounts no console logger, readline UI, user-interaction service, or `ask_user_question` tool. Stdout is reserved for the selected output format; diagnostics use stderr.
+
+## Config
+
+| Key | Default | Routed to |
+|---|---|---|
+| `provider` | required | the configured agent's provider route |
+| `model` | required | the configured agent's model |
+| `maxParallelToolCalls` | agent-loop default | positive-integer concurrent tool-call cap; `1` is serial |
+| `persona` | — | the deployment persona in `dsh-system-prompt` |
+| `toolOrder` | lexicographic | explicit model-facing tool order in `dsh-system-prompt` |
+| `tools` | `{ mode: 'native' }` | tool-registry presentation config through `dsh-agent-spine-demo` |
+| `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home exposed to model bash and used by local skill discovery |
+| `skills` | owner defaults | skill registry, local provider, and model-facing skill tool |
+| `toolBash` | owner defaults | model-facing bash config, including this producer's background opt-in |
+| `toolTasks` | owner defaults | generic `task_output` wait bounds |
+| `persistenceRoot` | `./.sessions` | JSONL session root |
+| `workspaceContext` | required | workspace-instruction byte budget, or `false` to disable loading |
+
+## CLI contract
+
+```sh
+dsh-cli-demo [--config path] [--output-format text|json|stream-json] <task>
+```
+
+`--config` defaults to `./cordis.yml`; `--output-format` defaults to `text`. Exactly one nonblank positional task is required, so quote tasks containing spaces. `--help` prints usage without booting. There is no `-p` or `--print` flag.
+
+The root headless-agent example supplies its leaf:
+
+```sh
+pnpm run demo:headless -- "inspect the failing test and fix it"
+```
+
+Loader configs with bare package specifiers require `node --expose-internals` or the Loader's optional native fallback. The root command supplies the Node flag.
+
+### Output formats
+
+- `text` writes the last assistant message containing text, followed by one newline.
+- `json` writes one DSH-native result record: `{ type: "result", success, sessionId, turn, result, reason, usage? }`. `usage` sums every model step in the task turn.
+- `stream-json` writes each canonical event from the top-level session's task turn as `{ type: "session_event", sessionId, event }`, then the same result record. Child-agent activity appears only through the parent tool events and results.
+
+Only `reason.kind === "completed"` exits successfully. Other durable turn endings still emit partial text or a result record, add a stderr diagnostic, and exit nonzero. Argument and boot failures leave stdout empty. SIGINT and SIGTERM cancel active work, await disposal, and exit 130 and 143 respectively.
+
+The task turn is explicitly flushed before final output. Session logs remain under `persistenceRoot` after the process exits.
+
+## Operational safety
+
+The headless-agent leaf supplies local bash, filesystem, skill, subagent, workflow, and todo capabilities. A task can therefore mutate the launch workspace, run commands, spawn child agents, and consume provider tokens. Run the CLI from the intended project directory, review the leaf's capability and sandbox configuration, and do not treat non-interactive execution as an approval boundary.
+
+## Model Experience
+
+### One-shot task turn
+
+#### What the model sees
+
+The positional task becomes one user message. Through `dsh-agent-spine-demo`, the top-level agent also receives configured workspace instructions and persona, the skill catalog, visible tool schemas, and retained tool results needed for later steps in the same turn.
+
+#### Token effect
+
+The task, prompt sections, tool schemas, assistant output, and tool results consume tokens on each model step. JSON event streaming and final rendering add no model tokens; delegated child work has its own model usage and is not included in the parent result's `usage` total.
+
+#### KV Cache effect
+
+Tool-round history is append-only while the one-shot agent's prompt, schemas, model route, and session prefix remain fixed. Changing that composition establishes a different request prefix; JSON output mode has no cache effect.
+
+## Known Limitations and Deferred Work
+
+- **One fresh top-level session per process** — its workspace cwd is the launch directory; there is no resume, second prompt, stdin context, or concurrent top-level session in this app.
+- **No interactive question or approval provider** — tools that require a human answer cannot complete unless a different leaf composes a non-interactive provider with explicit policy.
+- **Streaming is top-level-session-only** — child sessions are not flattened into the stream, and aggregate usage covers only model steps recorded on the parent task turn.

packages/examples/cli-demo/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@deepseek-ai/dsh-cli-demo",
+  "description": "Headless one-shot agent app with text and DSH-native JSON output",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "bin": {
+    "dsh-cli-demo": "lib/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./bin": {
+      "types": "./lib/types/bin.d.ts",
+      "default": "./lib/bin.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/bin.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@cordisjs/plugin-include": "^1.0.4",
+    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
+    "@deepseek-ai/dsh-app-boot": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "@deepseek-ai/dsh-workspace-context": "^0.0.1",
+    "cordis": "^4.0.0-rc.7",
+    "schemastery": "^3.17.0"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-include": "workspace:^",
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-workspace-context": "workspace:^",
+    "cordis": "^4.0.0-rc.7",
+    "schemastery": "^3.17.0"
+  }
+}

packages/examples/cli-demo/src/bin.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Process wrapper for `dsh-cli-demo`; covered parsing and task execution live in
+ * `cli.ts` while this entry owns Unix signal-to-exit-code mapping.
+ * @module @deepseek-ai/dsh-cli-demo/bin
+ */
+
+import { installFailLoud } from '@deepseek-ai/dsh-app-boot'
+import { executeCli } from './cli.ts'
+
+const NAME = 'dsh-cli-demo'
+
+/* v8 ignore start -- thin self-executing process glue; built-bin tests exercise
+   real argv, signals, Loader boot, output, and exit codes */
+const abort = new AbortController()
+let signalExitCode: number | undefined
+const interrupt = (signal: 'SIGINT' | 'SIGTERM', code: number): void => {
+  signalExitCode ??= code
+  if (!abort.signal.aborted) abort.abort(`received ${signal}`)
+}
+const onSigint = (): void => { interrupt('SIGINT', 130) }
+const onSigterm = (): void => { interrupt('SIGTERM', 143) }
+const uninstallFailLoud = installFailLoud(NAME)
+process.on('SIGINT', onSigint)
+process.on('SIGTERM', onSigterm)
+try {
+  const code = await executeCli(process.argv.slice(2), { signal: abort.signal })
+  process.exitCode = signalExitCode ?? code
+} finally {
+  process.off('SIGINT', onSigint)
+  process.off('SIGTERM', onSigterm)
+  uninstallFailLoud()
+}
+/* v8 ignore stop */

packages/examples/cli-demo/src/cli.ts

@@ -0,0 +1,447 @@
+/**
+ * Command parser and one-turn driver for `dsh-cli-demo`. The executable wrapper
+ * owns process signals; this module owns output, durability, and cleanup.
+ * @module @deepseek-ai/dsh-cli-demo/cli
+ */
+
+import { parseArgs } from 'node:util'
+import type { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session'
+import { boot, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+
+const CLI_NAME = 'dsh-cli-demo'
+const DEFAULT_CONFIG_PATH = './cordis.yml'
+const OUTPUT_FORMATS = ['text', 'json', 'stream-json'] as const
+const USAGE = `Usage: ${CLI_NAME} [--config path] [--output-format text|json|stream-json] <task>\n`
+
+/** Supported CLI output encodings. */
+export type OutputFormat = typeof OUTPUT_FORMATS[number]
+
+/** Parsed command: help exits before boot; run carries one validated task. */
+export type CliCommand =
+  | { readonly kind: 'help' }
+  | {
+    readonly kind: 'run'
+    readonly configPath: string
+    readonly outputFormat: OutputFormat
+    readonly task: string
+  }
+
+/** DSH-native final record emitted by JSON modes. */
+export interface CliResult {
+  readonly type: 'result'
+  readonly success: boolean
+  readonly sessionId: string
+  readonly turn: number
+  readonly result: string
+  readonly reason: TurnEndReason
+  readonly usage?: TokenUsage
+}
+
+/** Options for one turn against the configured top-level agent. */
+export interface OneShotOptions {
+  /** Exactly one nonblank user task. */
+  readonly task: string
+  /** Optional signal that cancels the selected agent. */
+  readonly signal?: AbortSignal
+  /** Synchronous task-turn observer; a throw cancels the agent and fails the run after flush. */
+  readonly onEvent?: (sessionId: string, event: SessionEvent) => void
+}
+
+/** Injectable process boundaries used by {@link executeCli}. */
+export interface CliRuntime {
+  /** Process cwd for config resolution and `.env` loading. */
+  readonly cwd?: string
+  /** Cancellation signal, normally aborted by SIGINT or SIGTERM. */
+  readonly signal?: AbortSignal
+  /** Loader boot boundary. */
+  readonly boot?: (name: string, absoluteConfigPath: string) => Promise<Context>
+  /** Optional `.env` loader boundary. */
+  readonly loadEnv?: (name: string, dir: string, warn: (line: string) => void) => void
+  /** Stdout sink; throws are treated as output failures. */
+  readonly writeStdout?: (chunk: string) => unknown
+  /** Stderr diagnostic sink. */
+  readonly writeStderr?: (chunk: string) => unknown
+  /** Context disposal boundary. */
+  readonly dispose?: (ctx: Context) => Promise<void>
+}
+
+interface ParsedArguments {
+  readonly values: {
+    readonly config?: string
+    readonly 'output-format'?: string
+    readonly help?: boolean
+  }
+  readonly positionals: string[]
+}
+
+class CliArgumentError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'CliArgumentError'
+  }
+}
+
+class CliInterruptedError extends Error {
+  constructor(reason: string) {
+    super(reason)
+    this.name = 'CliInterruptedError'
+  }
+}
+
+/** Render an arbitrary value without trusting its type traps or string coercion. */
+function renderUnknown(value: unknown): string {
+  try {
+    return String(value)
+  } catch {
+    return '[unrenderable thrown value]'
+  }
+}
+
+/** Normalize an arbitrary thrown value without letting inspection escape containment. */
+function toError(error: unknown): Error {
+  try {
+    if (error instanceof Error) return error
+  } catch {
+    // A hostile proxy may throw during instanceof; use the total renderer below.
+  }
+  return new Error(renderUnknown(error))
+}
+
+function interruptionReason(signal: AbortSignal): string {
+  return signal.reason === undefined ? 'interrupted' : renderUnknown(signal.reason)
+}
+
+/**
+ * Parse the bin arguments and enforce the one-positional-task contract.
+ * @param args - arguments after the executable name.
+ * @returns a help or run command.
+ * @throws {@link CliArgumentError} for unknown flags, invalid formats, or task cardinality.
+ */
+export function parseCliArgs(args: readonly string[]): CliCommand {
+  let parsed: ParsedArguments
+  try {
+    parsed = parseArgs({
+      args: [...args],
+      options: {
+        config: { type: 'string' },
+        'output-format': { type: 'string' },
+        help: { type: 'boolean' },
+      },
+      allowPositionals: true,
+      strict: true,
+    })
+  } catch (error: unknown) {
+    throw new CliArgumentError(toError(error).message)
+  }
+
+  if (parsed.values.help === true) return { kind: 'help' }
+  if (parsed.positionals.length !== 1) {
+    throw new CliArgumentError(`expected exactly one positional task, received ${parsed.positionals.length}`)
+  }
+  // Cardinality was checked above, so index zero exists.
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const task = parsed.positionals[0]!
+  if (task.trim().length === 0) throw new CliArgumentError('task must not be blank')
+
+  const requestedFormat = parsed.values['output-format'] ?? 'text'
+  if (!OUTPUT_FORMATS.some(format => format === requestedFormat)) {
+    throw new CliArgumentError(`unsupported output format ${JSON.stringify(requestedFormat)}`)
+  }
+  return {
+    kind: 'run',
+    configPath: parsed.values.config ?? DEFAULT_CONFIG_PATH,
+    outputFormat: requestedFormat as OutputFormat,
+    task,
+  }
+}
+
+function addUsage(total: TokenUsage | undefined, step: TokenUsage): TokenUsage {
+  const next: TokenUsage = {
+    inputTokens: (total?.inputTokens ?? 0) + step.inputTokens,
+    outputTokens: (total?.outputTokens ?? 0) + step.outputTokens,
+  }
+  for (const key of ['cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens'] as const) {
+    if (total?.[key] !== undefined || step[key] !== undefined) next[key] = (total?.[key] ?? 0) + (step[key] ?? 0)
+  }
+  return next
+}
+
+function assistantText(event: Extract<SessionEvent, { type: 'assistant/message' }>): string | undefined {
+  const blocks = event.data.content.filter(block => block.type === 'text')
+  return blocks.length === 0 ? undefined : blocks.map(block => block.text).join('')
+}
+
+/** Wait for startup quiescence while making pre-run cancellation terminal. */
+async function waitForStartupIdle(agent: Agent, signal?: AbortSignal): Promise<void> {
+  if (signal === undefined) {
+    await agent.whenIdle()
+    return
+  }
+  if (signal.aborted) {
+    agent.cancel(interruptionReason(signal))
+    throw new CliInterruptedError(interruptionReason(signal))
+  }
+  await new Promise<void>((resolve, reject) => {
+    const onAbort = (): void => {
+      agent.cancel(interruptionReason(signal))
+      reject(new CliInterruptedError(interruptionReason(signal)))
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    void agent.whenIdle().then(resolve, reject).finally(() => {
+      signal.removeEventListener('abort', onAbort)
+    })
+  })
+}
+
+/**
+ * Run one message-triggered turn on the configured top-level agent, aggregate its
+ * final text and model usage, wait for idle plus an explicit persistence flush,
+ * and return its durable ending. Only the selected agent's task turn reaches
+ * `onEvent`; startup injections and unrelated sessions are ignored. The context
+ * must contain exactly one top-level agent. Signal abort cancels that agent; an
+ * abort before the correlated task turn rejects. An observer throw cancels the
+ * turn and is rethrown after the agent reaches idle and the session flushes.
+ * @param ctx - settled Loader root containing one agent plus `ctx.sessions`.
+ * @param options - task, optional cancellation, and optional stream observer.
+ * @returns the DSH-native result envelope after durable quiescence.
+ */
+export async function runOneShot(ctx: Context, options: OneShotOptions): Promise<CliResult> {
+  const agents = ctx.get('agents')?.roots() ?? []
+  const [agent] = agents
+  if (agent === undefined || agents.length !== 1) {
+    throw new Error(`config must create exactly one top-level agent, found ${agents.length}`)
+  }
+  await waitForStartupIdle(agent, options.signal)
+
+  let targetTurn: number | undefined
+  let reason: TurnEndReason | undefined
+  let result = ''
+  let usage: TokenUsage | undefined
+  let outputError: Error | undefined
+  let resolveTurn!: () => void
+  let rejectTurn!: (error: Error) => void
+  let settled = false
+  const turnEnded = new Promise<void>((resolve, reject) => {
+    resolveTurn = resolve
+    rejectTurn = reject
+  })
+
+  const settleResolved = (): void => {
+    settled = true
+    resolveTurn()
+  }
+  const settleRejected = (error: Error): void => {
+    settled = true
+    rejectTurn(error)
+  }
+  const observe = (sessionId: string, event: SessionEvent): void => {
+    if (outputError !== undefined || options.onEvent === undefined) return
+    try {
+      options.onEvent(sessionId, event)
+    } catch (error: unknown) {
+      outputError = toError(error)
+      agent.cancel('stream output failed')
+    }
+  }
+
+  const disposeListener = ctx.on('session/event', (session, event) => {
+    if (session !== agent.session || settled) return
+    if (targetTurn === undefined) {
+      if (event.type !== 'turn/start' || event.data.trigger.kind !== 'message') return
+      targetTurn = event.data.turn
+    }
+    observe(session.id, event)
+    if (event.type === 'assistant/message' && event.data.turn === targetTurn) {
+      result = assistantText(event) ?? result
+      if (event.data.usage !== undefined) usage = addUsage(usage, event.data.usage)
+    }
+    if (event.type === 'turn/end' && event.data.turn === targetTurn) {
+      reason = event.data.reason
+      settleResolved()
+    }
+  })
+
+  const signal = options.signal
+  let onAbort: (() => void) | undefined
+  if (signal !== undefined) {
+    onAbort = (): void => {
+      agent.cancel(interruptionReason(signal))
+      if (targetTurn === undefined) settleRejected(new CliInterruptedError(interruptionReason(signal)))
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    /* v8 ignore next -- closes the race between startup-idle completion and listener registration */
+    if (signal.aborted) onAbort()
+  }
+
+  try {
+    /* v8 ignore next -- skips send only when cancellation wins the listener-registration race above */
+    if (!settled) { // eslint-disable-line @typescript-eslint/no-unnecessary-condition
+      agent.send([{ type: 'text', text: options.task }])
+    }
+    await turnEnded
+  } finally {
+    if (onAbort !== undefined) signal?.removeEventListener('abort', onAbort)
+    disposeListener()
+    await agent.whenIdle()
+  }
+
+  /* v8 ignore next 3 -- turnEnded resolves only from the matching branch that assigns both values */
+  if (targetTurn === undefined || reason === undefined) {
+    throw new Error('task ended without a correlated turn/end event')
+  }
+  await ctx.sessions.flush(agent.session)
+  if (outputError !== undefined) throw outputError
+  return {
+    type: 'result',
+    success: reason.kind === 'completed',
+    sessionId: agent.session.id,
+    turn: targetTurn,
+    result,
+    reason,
+    ...usage === undefined ? {} : { usage },
+  }
+}
+
+function renderResult(outputFormat: OutputFormat, result: CliResult): string {
+  return outputFormat === 'text' ? `${result.result}\n` : `${JSON.stringify(result)}\n`
+}
+
+/**
+ * Race Loader boot with cancellation without abandoning a context that becomes
+ * available after the caller has been released. Waiting for that late context
+ * would recreate the signal hang, so its disposal and diagnostics run detached.
+ */
+async function bootInterruptibly(
+  start: () => Promise<Context>,
+  signal: AbortSignal | undefined,
+  disposeLateContext: (ctx: Context) => Promise<void>,
+  reportLateDisposalFailure: (error: unknown) => void,
+): Promise<Context> {
+  if (signal === undefined) return await start()
+  if (signal.aborted) throw new CliInterruptedError(interruptionReason(signal))
+
+  let onAbort!: () => void
+  const interruptedBoot = new Promise<never>((_resolve, reject) => {
+    onAbort = (): void => {
+      reject(new CliInterruptedError(interruptionReason(signal)))
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    /* v8 ignore next -- closes registration against a non-standard synchronously mutating signal */
+    if (signal.aborted) onAbort()
+  })
+  const booting = Promise.resolve().then(start)
+  try {
+    return await Promise.race([booting, interruptedBoot])
+  } catch (error: unknown) {
+    // The awaited race permits the signal to change after the preflight check.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (signal.aborted) {
+      void booting.then(
+        async (lateContext) => {
+          try {
+            await disposeLateContext(lateContext)
+          } catch (error: unknown) {
+            reportLateDisposalFailure(error)
+          }
+        },
+        () => {},
+      )
+    }
+    throw error
+  } finally {
+    signal.removeEventListener('abort', onAbort)
+  }
+}
+
+/**
+ * Render a non-completed turn reason for stderr.
+ * @param reason - durable turn ending to describe.
+ * @returns a concise diagnostic fragment.
+ */
+export function formatTurnFailure(reason: TurnEndReason): string {
+  switch (reason.kind) {
+    case 'completed': return 'completed'
+    case 'aborted': return reason.reason === undefined ? 'was aborted' : `was aborted: ${reason.reason}`
+    case 'error': return `failed at step ${reason.step}: ${reason.message}`
+    case 'disposed': return 'was disposed'
+    case 'max-tokens': return 'reached the model output-token limit'
+    case 'rejected': return `was rejected: ${reason.reason}`
+    case 'interrupted': return 'was interrupted during persistence recovery'
+    default: return `ended with ${JSON.stringify(reason)}`
+  }
+}
+
+/**
+ * Execute one CLI invocation. Argument and boot failures never write stdout;
+ * context disposal is awaited before return, and its failure does not replace
+ * an earlier diagnostic.
+ * @param args - arguments after the executable name.
+ * @param runtime - optional injected process boundaries for tests and embedding.
+ * @returns the ordinary process exit code; the thin bin overrides it for Unix signals.
+ */
+export async function executeCli(args: readonly string[], runtime: CliRuntime = {}): Promise<number> {
+  /* v8 ignore next -- default process sinks are exercised by the built-bin smoke */
+  const writeStdout = runtime.writeStdout ?? (chunk => process.stdout.write(chunk))
+  /* v8 ignore next -- default process sinks are exercised by the built-bin smoke */
+  const writeStderr = runtime.writeStderr ?? (chunk => process.stderr.write(chunk))
+  let command: CliCommand
+  try {
+    command = parseCliArgs(args)
+  } catch (error: unknown) {
+    writeStderr(`${CLI_NAME}: ${toError(error).message}\n${USAGE}`)
+    return 1
+  }
+  if (command.kind === 'help') {
+    writeStdout(USAGE)
+    return 0
+  }
+
+  /* v8 ignore next -- default process cwd is exercised by the built-bin smoke */
+  const cwd = runtime.cwd ?? process.cwd()
+  /* v8 ignore next -- default env/boot boundaries are exercised by the Loader and built-bin smokes */
+  const loadEnvironment = runtime.loadEnv ?? loadEnv
+  /* v8 ignore next -- default env/boot boundaries are exercised by the Loader and built-bin smokes */
+  const bootContext = runtime.boot ?? boot
+  /* v8 ignore next -- default disposal is exercised by the built-bin smoke */
+  const disposeContext = runtime.dispose ?? (target => target.fiber.dispose())
+  let ctx: Context | undefined
+  let exitCode = 1
+  let diagnostic: string | undefined
+  try {
+    loadEnvironment(CLI_NAME, cwd, line => writeStderr(line))
+    ctx = await bootInterruptibly(
+      () => bootContext(CLI_NAME, resolveConfigPath(command.configPath, undefined, cwd)),
+      runtime.signal,
+      disposeContext,
+      error => writeStderr(`${CLI_NAME}: dispose after interrupted boot failed: ${toError(error).message}\n`),
+    )
+    const result = await runOneShot(ctx, {
+      task: command.task,
+      ...runtime.signal === undefined ? {} : { signal: runtime.signal },
+      ...command.outputFormat === 'stream-json'
+        ? { onEvent: (sessionId: string, event: SessionEvent) => {
+          writeStdout(`${JSON.stringify({ type: 'session_event', sessionId, event })}\n`)
+        } }
+        : {},
+    })
+    writeStdout(renderResult(command.outputFormat, result))
+    exitCode = result.success ? 0 : 1
+    if (!result.success) diagnostic = `${CLI_NAME}: turn ${result.turn} ${formatTurnFailure(result.reason)}\n`
+  } catch (error: unknown) {
+    diagnostic = `${CLI_NAME}: ${toError(error).message}\n`
+  } finally {
+    if (ctx !== undefined) {
+      try {
+        await disposeContext(ctx)
+      } catch (error: unknown) {
+        diagnostic = `${diagnostic ?? ''}${CLI_NAME}: dispose failed: ${toError(error).message}\n`
+        exitCode = 1
+      }
+    }
+  }
+  if (diagnostic !== undefined) writeStderr(diagnostic)
+  return exitCode
+}

packages/examples/cli-demo/src/index.ts

@@ -0,0 +1,82 @@
+/**
+ * Headless one-shot app composition: the default agent spine, JSONL session
+ * persistence, and one fresh top-level agent. The CLI driver owns task
+ * submission and output; the app deliberately mounts no interactive or logging
+ * front door so stdout remains protocol-pure.
+ * @module @deepseek-ai/dsh-cli-demo
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
+import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
+import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
+import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
+
+const DEFAULT_PERSISTENCE_ROOT = './.sessions'
+
+export const name = 'cli-demo'
+
+/** App config forwarded to the spine, configured agent, and JSONL backend. */
+export interface Config {
+  /** Provider route for the configured agent. */
+  provider: string
+  /** Model name for the configured agent; a matching adapter must be registered. */
+  model: string
+  /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */
+  maxParallelToolCalls?: number
+  /** Deployment persona forwarded to the system-prompt plugin. */
+  persona?: string
+  /** Explicit model-facing tool order forwarded to the system-prompt plugin. */
+  toolOrder?: string[]
+  /** Tool-registry presentation config forwarded through agent-spine-demo. */
+  tools?: ToolsConfig
+  /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */
+  dshHome?: string
+  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
+  persistenceRoot?: string
+  /** Skill registry, local-provider, and model-facing consumer config. */
+  skills?: agentCore.SkillConfig
+  /** Model-facing bash tool config forwarded through agent-spine-demo. */
+  toolBash?: NonNullable<agentCore.Config['toolBash']>
+  /** Generic background-task control-tool config forwarded through agent-spine-demo. */
+  toolTasks?: NonNullable<agentCore.Config['toolTasks']>
+  /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
+  workspaceContext: agentCore.Config['workspaceContext']
+}
+
+// Each front door keeps a complete Loader schema so its deployment contract is
+// readable without a cross-package config facade.
+/* jscpd:ignore-start */
+export const Config: z<Config> = z.object({
+  provider: z.string().required(),
+  model: z.string().required(),
+  maxParallelToolCalls: z.number().step(1).min(1),
+  persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT),
+  persona: z.string(),
+  dshHome: z.string(),
+  skills: agentCore.SkillConfigSchema,
+  // Absent means lexicographic order; schemastery's native array default is [].
+  toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
+  tools: ToolRegistry.Config,
+  toolBash: agentCore.ToolBashConfigSchema,
+  toolTasks: agentCore.ToolTasksConfigSchema,
+  workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
+})
+/* jscpd:ignore-end */
+
+/**
+ * Compose the UI-less spine, a fresh top-level agent rooted at the process cwd,
+ * and JSONL persistence. Swappable adapters, executors, and product tools stay
+ * in the leaf `cordis.yml`.
+ * @param ctx - app context that owns the composed child plugins.
+ * @param config - validated app configuration.
+ */
+export function apply(ctx: Context, config: Config): void {
+  ctx.plugin(agentCore, {
+    ...agentCore.pickSpineConfig(config),
+    agents: [{ id: SessionId('main'), provider: config.provider, model: config.model, cwd: process.cwd() }],
+  })
+  ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT })
+}

packages/examples/cli-demo/tests/built-bin.e2e.ts

@@ -0,0 +1,177 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdtemp, mkdir, readFile, readdir, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+
+const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
+const cliBin = join(repoRoot, 'packages/examples/cli-demo/lib/bin.js')
+const dshPackages = [
+  'examples/agent-spine-demo', 'examples/cli-demo', 'core/agent', 'core/session',
+  'core/system-prompt', 'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash',
+  'bash/bash-local', 'bash/tool-bash', 'support/invariants', 'ui/app-boot',
+  'session-persistence/session-persistence', 'session-persistence/session-persistence-jsonl',
+  'context/workspace-context',
+]
+const vendorPackages = ['cordis', 'loader', 'include', 'timer', 'schemastery', 'cosmokit']
+
+async function packageName(dir: string): Promise<string> {
+  return (JSON.parse(await readFile(join(dir, 'package.json'), 'utf8')) as { name: string }).name
+}
+
+async function linkPackage(dir: string, nodeModules: string): Promise<void> {
+  const target = join(nodeModules, await packageName(dir))
+  await mkdir(dirname(target), { recursive: true })
+  await symlink(dir, target)
+}
+
+async function makeConsumer(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'cli-built-bin-'))
+  const nodeModules = join(dir, 'node_modules')
+  for (const rel of dshPackages) await linkPackage(join(repoRoot, 'packages', rel), nodeModules)
+  for (const rel of vendorPackages) await linkPackage(join(repoRoot, 'vendor', rel), nodeModules)
+  await writeFile(join(dir, 'mock-llm.mjs'), [
+    "import { LlmAdapter } from '@deepseek-ai/dsh-llm'",
+    'class Mock extends LlmAdapter {',
+    '  async * stream(options) {',
+    "    const text = options.messages.flatMap(message => message.content).filter(block => block.type === 'text').at(-1)?.text ?? ''",
+    "    yield { type: 'block-start', index: 0, blockType: 'text' }",
+    "    if (text === 'hang') {",
+    "      yield { type: 'text-delta', index: 0, text: 'partial' }",
+    '      await new Promise((resolve, reject) => {',
+    "        const timer = setTimeout(() => reject(new Error('hang timeout')), 30000)",
+    "        const onAbort = () => { clearTimeout(timer); reject(new Error('aborted')) }",
+    '        if (options.signal.aborted) onAbort()',
+    "        else options.signal.addEventListener('abort', onAbort, { once: true })",
+    '      })',
+    '      return',
+    '    }',
+    '    const reply = `BUILT: ${text}`',
+    "    yield { type: 'text-delta', index: 0, text: reply }",
+    "    yield { type: 'block-end', index: 0, block: { type: 'text', text: reply } }",
+    "    yield { type: 'usage', usage: { inputTokens: 4, outputTokens: 2 } }",
+    "    yield { type: 'finish', reason: { kind: 'stop' } }",
+    '  }',
+    '}',
+    "export const name = 'built-cli-mock'",
+    "export const inject = ['llm']",
+    "export function apply(ctx) { ctx.llm.registerAdapter(['built-cli-mock'], new Mock()) }",
+    '',
+  ].join('\n'))
+  await writeFile(join(dir, 'cordis.yml'), [
+    '- id: mock-llm',
+    "  name: './mock-llm.mjs'",
+    '- id: bash',
+    "  name: '@deepseek-ai/dsh-bash-local'",
+    '- id: cli-agent',
+    "  name: '@deepseek-ai/dsh-cli-demo'",
+    '  config:',
+    '    provider: built-cli-mock',
+    '    model: built-cli-mock',
+    "    persona: 'built CLI test'",
+    "    persistenceRoot: './.sessions'",
+    '    workspaceContext: false',
+    '',
+  ].join('\n'))
+  return dir
+}
+
+interface BinResult {
+  readonly code: number
+  readonly signal: NodeJS.Signals | null
+  readonly stdout: string
+  readonly stderr: string
+}
+
+function runBuiltBin(cwd: string, args: readonly string[], interrupt?: NodeJS.Signals): Promise<BinResult> {
+  return new Promise((resolveResult, reject) => {
+    const child = spawn(process.execPath, ['--expose-internals', cliBin, ...args], {
+      cwd,
+      env: { ...process.env, DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+    let interrupted = false
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (chunk: string) => {
+      stdout += chunk
+      if (interrupt !== undefined && !interrupted && stdout.includes('assistant/chunk')) {
+        interrupted = true
+        child.kill(interrupt)
+      }
+    })
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', (chunk: string) => { stderr += chunk })
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL')
+      reject(new Error(`built CLI did not exit. stdout:\n${stdout}\nstderr:\n${stderr}`))
+    }, 25_000)
+    child.once('error', (error) => { clearTimeout(timer); reject(error) })
+    child.once('exit', (code, signal) => {
+      clearTimeout(timer)
+      resolveResult({ code: code ?? -1, signal, stdout, stderr })
+    })
+  })
+}
+
+let consumer: string | undefined
+
+afterEach(async () => {
+  if (consumer !== undefined) await rm(consumer, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })
+  consumer = undefined
+})
+
+describe.skipIf(!existsSync(cliBin))('dsh-cli-demo BUILT bin', () => {
+  it('runs text, json, and stream-json under plain Node and persists fresh sessions', async () => {
+    consumer = await makeConsumer()
+    const text = await runBuiltBin(consumer, ['--config', './cordis.yml', 'hello'])
+    expect(text).toMatchObject({ code: 0, signal: null, stdout: 'BUILT: hello\n', stderr: '' })
+
+    const json = await runBuiltBin(consumer, ['--config', './cordis.yml', '--output-format', 'json', 'json task'])
+    expect(JSON.parse(json.stdout)).toMatchObject({
+      type: 'result', success: true, result: 'BUILT: json task', reason: { kind: 'completed' },
+      usage: { inputTokens: 4, outputTokens: 2 },
+    })
+
+    const stream = await runBuiltBin(consumer, ['--config', './cordis.yml', '--output-format', 'stream-json', 'stream task'])
+    const lines = stream.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record<string, unknown>)
+    expect(lines[0]).toMatchObject({ type: 'session_event', event: { type: 'turn/start' } })
+    expect(lines.at(-1)).toMatchObject({ type: 'result', success: true, result: 'BUILT: stream task' })
+    const files = await readdir(join(consumer, '.sessions'), { recursive: true })
+    expect(files.filter(file => file.endsWith('.jsonl'))).toHaveLength(3)
+  }, 30_000)
+
+  it('keeps stdout empty for invalid argv and missing config', async () => {
+    consumer = await makeConsumer()
+    for (const args of [
+      ['--config', './cordis.yml'],
+      ['--config', './cordis.yml', 'one', 'two'],
+      ['--config', './missing.yml', 'task'],
+    ]) {
+      const result = await runBuiltBin(consumer, args)
+      expect(result.code).not.toBe(0)
+      expect(result.stdout).toBe('')
+      expect(result.stderr.length).toBeGreaterThan(0)
+    }
+  }, 30_000)
+
+  describe.skipIf(process.platform === 'win32')('POSIX signal delivery', () => {
+    it.each([
+      ['SIGINT', 130],
+      ['SIGTERM', 143],
+    ] as const)('cancels and disposes on %s with exit %i', async (signal, code) => {
+      consumer = await makeConsumer()
+      const result = await runBuiltBin(
+        consumer,
+        ['--config', './cordis.yml', '--output-format', 'stream-json', 'hang'],
+        signal,
+      )
+      expect(result, JSON.stringify(result)).toMatchObject({ code, signal: null })
+      expect(result.stdout).toContain('"kind":"aborted"')
+      expect(result.stderr).toContain(`received ${signal}`)
+    }, 30_000)
+  })
+})

packages/examples/cli-demo/tests/cli-demo.spec.ts

@@ -0,0 +1,159 @@
+import { mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
+import { CallId, type Message } from '@deepseek-ai/dsh-llm'
+import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
+import type { ToolExecution } from '@deepseek-ai/dsh-tools'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import * as cliDemo from '../src/index.ts'
+
+const contexts: Context[] = []
+
+async function skillConfig(catalogDescriptionMaxLength?: number): Promise<NonNullable<cliDemo.Config['skills']>> {
+  const home = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-skills-'))
+  return {
+    local: { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') },
+    ...catalogDescriptionMaxLength === undefined ? {} : { tool: { catalogDescriptionMaxLength } },
+  }
+}
+
+async function mount(config: cliDemo.Config, withBash = false): Promise<Context> {
+  const ctx = new Context()
+  if (withBash) ctx.provide('bash', { sandboxMode: undefined })
+  contexts.push(ctx)
+  await ctx.plugin(cliDemo, config)
+  await new Promise(resolve => setTimeout(resolve, 80))
+  return ctx
+}
+
+async function composePrefix(ctx: Context): Promise<Message[]> {
+  const agent = { session: { header: { cwd: '/tmp' } } } as unknown as Agent
+  const empty: Message[] = []
+  return await agentEvents(ctx, agent).waterfall(
+    'agent/session-prefix', empty, new AbortController().signal,
+    () => Promise.resolve(empty),
+  )
+}
+
+afterEach(async () => {
+  await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
+})
+
+describe('dsh-cli-demo app composition', () => {
+  it('composes the UI-less spine, JSONL persistence, and a main agent', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-compose-'))
+    const ctx = await mount({
+      provider: 'mock',
+      model: 'mock',
+      persona: 'Headless.',
+      tools: { mode: 'native' },
+      persistenceRoot: root,
+      skills: await skillConfig(),
+      workspaceContext: false,
+    })
+    const [agent] = ctx.get('agents')?.roots() ?? []
+    expect(ctx.get('agentLoop')).toBeDefined()
+    expect(ctx.get('sessionPersistence')).toBeDefined()
+    expect(agent?.session.header.cwd).toBe(process.cwd())
+    expect(ctx.get('userInteraction')).toBeUndefined()
+    expect(ctx.get('tools')?.get('ask_user_question')).toBeUndefined()
+  })
+
+  it('covers direct-apply defaults and forwards skill and tool-order config', async () => {
+    const oldDshHome = process.env.DSH_HOME
+    const oldAgentsHome = process.env.DSH_AGENTS_HOME
+    const home = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-defaults-'))
+    process.env.DSH_HOME = join(home, '.dsh')
+    process.env.DSH_AGENTS_HOME = join(home, '.agents')
+    try {
+      const ctx = new Context()
+      contexts.push(ctx)
+      cliDemo.apply(ctx, { provider: 'mock', model: 'mock', workspaceContext: false })
+      await new Promise(resolve => setTimeout(resolve, 80))
+      expect(ctx.get('sessionPersistence')).toBeDefined()
+      const [agent] = ctx.get('agents')?.roots() ?? []
+      expect(agent?.session.id).toMatch(/^main-session-/)
+      expect(await ctx.skills.list()).toEqual([])
+    } finally {
+      if (oldDshHome === undefined) delete process.env.DSH_HOME
+      else process.env.DSH_HOME = oldDshHome
+      if (oldAgentsHome === undefined) delete process.env.DSH_AGENTS_HOME
+      else process.env.DSH_AGENTS_HOME = oldAgentsHome
+    }
+
+    const ctx = await mount({
+      provider: 'mock',
+      model: 'mock',
+      toolOrder: ['zulu', TOOL_ORDER_REST],
+      skills: await skillConfig(6),
+      workspaceContext: false,
+    })
+    ctx.skills.register({ name: 'cli-skill', description: 'CLI skill', source: 'runtime', content: 'body' })
+    for (const name of ['alpha', 'zulu']) {
+      ctx.tools.register({ name, description: name, parameters: {}, execute: async () => [] })
+    }
+    expect(JSON.stringify(await composePrefix(ctx))).toContain('- `cli-skill`: CLI...')
+    expect((await ctx.systemPrompt.assemble()).tools.map(tool => tool.name)).toEqual([
+      'zulu',
+      'alpha',
+      'skill',
+      'task_kill',
+      'task_list',
+      'task_output',
+    ])
+  })
+
+  it('forwards the complete shared spine configuration', async () => {
+    const dshHome = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-home-'))
+    const agentsHome = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-agents-'))
+    const ctx = await mount({
+      provider: 'mock',
+      model: 'mock',
+      maxParallelToolCalls: 3,
+      dshHome,
+      skills: { local: { agentsHome } },
+      toolBash: { enableRunInBackground: false },
+      toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
+      workspaceContext: false,
+    }, true)
+
+    expect(ctx.get('agentLoop')?.config.maxParallelToolCalls).toBe(3)
+    const execution: ToolExecution = {
+      token: Symbol('cli-demo-dsh-home-test') as ToolExecution['token'],
+      callId: CallId('cli-demo-dsh-home'),
+      name: 'bash',
+      arguments: { command: 'true' },
+    }
+    expect(ctx.bashEnv.collect(execution)).toMatchObject({ DSH_HOME: dshHome })
+    const bash = ctx.tools.schemas().find(tool => tool.name === 'bash')
+    expect(Object.keys((bash!.parameters as { properties: Record<string, unknown> }).properties))
+      .not.toContain('run_in_background')
+
+    const id = ctx.tasks.start({
+      kind: 'bash',
+      label: 'config forwarding probe',
+      run: () => ({ cancel: () => {}, done: Promise.resolve({ status: 'completed' }) }),
+    })
+    const wait = vi.spyOn(ctx.tasks, 'wait')
+    await ctx.tools.execute({
+      callId: CallId('cli-demo-task-config'),
+      name: 'task_output',
+      arguments: { task_id: id, wait: true },
+    })
+    expect(wait).toHaveBeenCalledWith(id, 7, undefined, undefined)
+  })
+
+  it('exposes the Loader-safe namespace plugin shape and schema', () => {
+    expect(cliDemo.name).toBe('cli-demo')
+    expect(cliDemo.Config).toBeDefined()
+    expect('default' in cliDemo).toBe(false)
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(cliDemo) as Record<string, unknown>
+    expect(unwrapped).toBe(cliDemo)
+    expect(unwrapped.name).toBe('cli-demo')
+    expect(typeof unwrapped.apply).toBe('function')
+  })
+})

packages/examples/cli-demo/tests/cli.spec.ts

@@ -0,0 +1,474 @@
+import { readdir, mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { CallId, LlmAdapter, type GenerateOptions, type StreamChunk, type TokenUsage } from '@deepseek-ai/dsh-llm'
+import { SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session'
+import { afterEach, describe, expect, it } from 'vitest'
+import * as cliDemo from '../src/index.ts'
+import {
+  executeCli,
+  formatTurnFailure,
+  parseCliArgs,
+  runOneShot,
+  type CliResult,
+} from '../src/cli.ts'
+
+type ScriptEntry = readonly StreamChunk[] | 'hang'
+
+class ScriptedAdapter extends LlmAdapter {
+  readonly requests: GenerateOptions[] = []
+  private cursor = 0
+
+  constructor(private readonly script: readonly ScriptEntry[]) {
+    super()
+  }
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    this.requests.push(options)
+    const entry = this.script[this.cursor++]
+    if (entry === undefined) throw new Error('script exhausted')
+    if (entry === 'hang') {
+      yield { type: 'block-start', index: 0, blockType: 'text' }
+      yield { type: 'text-delta', index: 0, text: 'partial' }
+      await new Promise<void>((_resolve, reject) => {
+        if (options.signal?.aborted === true) {
+          reject(new Error('aborted'))
+          return
+        }
+        options.signal?.addEventListener('abort', () => { reject(new Error('aborted')) }, { once: true })
+      })
+      return
+    }
+    for (const chunk of entry) yield chunk
+  }
+}
+
+function textResponse(text: string, usage?: TokenUsage, finish: 'stop' | 'max-tokens' = 'stop'): StreamChunk[] {
+  return [
+    { type: 'block-start', index: 0, blockType: 'text' },
+    { type: 'text-delta', index: 0, text },
+    { type: 'block-end', index: 0, block: { type: 'text', text } },
+    ...usage === undefined ? [] : [{ type: 'usage', usage } as const],
+    { type: 'finish', reason: { kind: finish } },
+  ]
+}
+
+function toolResponse(usage: TokenUsage): StreamChunk[] {
+  const id = CallId('cli-call')
+  const args = JSON.stringify({ text: 'round trip' })
+  return [
+    { type: 'block-start', index: 0, blockType: 'text' },
+    { type: 'text-delta', index: 0, text: 'working' },
+    { type: 'block-end', index: 0, block: { type: 'text', text: 'working' } },
+    { type: 'block-start', index: 1, blockType: 'tool-call' },
+    { type: 'tool-call-delta', index: 1, id, name: 'echo', argumentsDelta: args },
+    { type: 'block-end', index: 1, block: { type: 'tool-call', id, name: 'echo', arguments: args } },
+    { type: 'usage', usage },
+    { type: 'finish', reason: { kind: 'tool-calls' } },
+  ]
+}
+
+function reasoningResponse(text: string): StreamChunk[] {
+  return [
+    { type: 'block-start', index: 0, blockType: 'reasoning' },
+    { type: 'reasoning-delta', index: 0, text },
+    { type: 'block-end', index: 0, block: { type: 'reasoning', text } },
+    { type: 'finish', reason: { kind: 'stop' } },
+  ]
+}
+
+interface Harness {
+  readonly ctx: Context
+  readonly agent: Agent
+  readonly persistenceRoot: string
+}
+
+const liveContexts: Context[] = []
+
+async function harness(script: readonly ScriptEntry[]): Promise<Harness> {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-cli-runner-'))
+  const skillHome = await mkdtemp(join(tmpdir(), 'dsh-cli-runner-skills-'))
+  const ctx = new Context()
+  liveContexts.push(ctx)
+  await ctx.plugin(cliDemo, {
+    provider: 'mock',
+    model: 'mock',
+    persistenceRoot: root,
+    skills: { local: { dshHome: join(skillHome, '.dsh'), agentsHome: join(skillHome, '.agents') } },
+    workspaceContext: false,
+  })
+  await new Promise(resolve => setTimeout(resolve, 80))
+  ctx.llm.registerAdapter(['mock'], new ScriptedAdapter(script))
+  ctx.tools.register({
+    name: 'echo',
+    description: 'Echo text.',
+    parameters: { text: { type: 'string', required: true } },
+    execute: async args => [{ type: 'text', text: `ECHO: ${(args as { text: string }).text}` }],
+  })
+  const [agent] = ctx.agents.roots()
+  if (agent === undefined) throw new Error('test main agent missing')
+  return { ctx, agent, persistenceRoot: root }
+}
+
+async function invoke(
+  ctx: Context,
+  args: readonly string[],
+  options: { signal?: AbortSignal; failStdout?: boolean; failDispose?: boolean } = {},
+): Promise<{ code: number; stdout: string; stderr: string }> {
+  let stdout = ''
+  let stderr = ''
+  const code = await executeCli(args, {
+    cwd: '/tmp/cli-cwd',
+    ...options.signal === undefined ? {} : { signal: options.signal },
+    boot: async () => ctx,
+    loadEnv: () => {},
+    writeStdout: (chunk) => {
+      if (options.failStdout === true) throw new Error('stdout closed')
+      stdout += chunk
+    },
+    writeStderr: (chunk) => { stderr += chunk },
+    ...options.failDispose === true
+      ? { dispose: async (target: Context) => {
+        await target.fiber.dispose()
+        throw new Error('dispose exploded')
+      } }
+      : {},
+  })
+  return { code, stdout, stderr }
+}
+
+afterEach(async () => {
+  await Promise.all(liveContexts.splice(0).map(ctx => ctx.fiber.dispose()))
+})
+
+describe('parseCliArgs', () => {
+  it('parses defaults, explicit options, spaces, and an option-like task after --', () => {
+    expect(parseCliArgs(['task with spaces'])).toEqual({
+      kind: 'run', configPath: './cordis.yml', outputFormat: 'text', task: 'task with spaces',
+    })
+    expect(parseCliArgs(['--config', 'custom.yml', '--output-format', 'stream-json', 'do it'])).toEqual({
+      kind: 'run', configPath: 'custom.yml', outputFormat: 'stream-json', task: 'do it',
+    })
+    expect(parseCliArgs(['--', '-task'])).toMatchObject({ task: '-task' })
+    expect(parseCliArgs(['--help', 'ignored'])).toEqual({ kind: 'help' })
+  })
+
+  it('rejects missing, blank, extra, invalid-format, and unsupported flags', () => {
+    expect(() => parseCliArgs([])).toThrow('received 0')
+    expect(() => parseCliArgs(['   '])).toThrow('must not be blank')
+    expect(() => parseCliArgs(['one', 'two'])).toThrow('received 2')
+    expect(() => parseCliArgs(['--output-format', 'xml', 'task'])).toThrow('unsupported output format')
+    expect(() => parseCliArgs(['-p', 'task'])).toThrow('Unknown option')
+  })
+})
+
+describe('runOneShot and executeCli', () => {
+  it('prints help and argument diagnostics without booting or contaminating stdout', async () => {
+    let booted = false
+    let stdout = ''
+    let stderr = ''
+    const runtime = {
+      boot: async (): Promise<Context> => { booted = true; throw new Error('unexpected') },
+      writeStdout: (chunk: string): void => { stdout += chunk },
+      writeStderr: (chunk: string): void => { stderr += chunk },
+    }
+    expect(await executeCli(['--help'], runtime)).toBe(0)
+    expect(stdout).toContain('Usage: dsh-cli-demo')
+    stdout = ''
+    expect(await executeCli([], runtime)).toBe(1)
+    expect(stdout).toBe('')
+    expect(stderr).toContain('received 0')
+    expect(booted).toBe(false)
+  })
+
+  it('leaves stdout empty for environment and boot failures and resolves the default config', async () => {
+    let bootPath = ''
+    let stderr = ''
+    const code = await executeCli(['task'], {
+      cwd: '/tmp/cli-work',
+      loadEnv: (_name, _dir, warn) => { warn('env warning\n') },
+      boot: async (_name, path) => { bootPath = path; throw 'boot exploded' },
+      writeStdout: () => { throw new Error('stdout must stay empty') },
+      writeStderr: (chunk) => { stderr += chunk },
+    })
+    expect(code).toBe(1)
+    expect(bootPath).toBe(resolve('/tmp/cli-work/cordis.yml'))
+    expect(stderr).toContain('env warning')
+    expect(stderr).toContain('boot exploded')
+  })
+
+  it('contains a thrown value whose inspection and coercion both fail', async () => {
+    const hostile = new Proxy({}, {
+      getPrototypeOf: () => { throw new Error('prototype trap escaped') },
+      get: (target, key, receiver) => {
+        if (key === Symbol.toPrimitive) throw new Error('coercion escaped')
+        return Reflect.get(target, key, receiver) as unknown
+      },
+    })
+    let stdout = ''
+    let stderr = ''
+    const code = await executeCli(['task'], {
+      boot: async () => { throw hostile },
+      loadEnv: () => {},
+      writeStdout: (chunk) => { stdout += chunk },
+      writeStderr: (chunk) => { stderr += chunk },
+    })
+    expect(code).toBe(1)
+    expect(stdout).toBe('')
+    expect(stderr).toBe('dsh-cli-demo: [unrenderable thrown value]\n')
+  })
+
+  it('interrupts Loader boot and contains every late boot outcome', async () => {
+    const abort = new AbortController()
+    const lateContext = new Context()
+    liveContexts.push(lateContext)
+    const boot = Promise.withResolvers<Context>()
+    const disposed = Promise.withResolvers<undefined>()
+    let disposeCalls = 0
+    let stderr = ''
+    const running = executeCli(['task'], {
+      signal: abort.signal,
+      boot: () => boot.promise,
+      loadEnv: () => {},
+      writeStdout: () => {},
+      writeStderr: (chunk) => { stderr += chunk },
+      dispose: async (ctx) => {
+        disposeCalls += 1
+        await ctx.fiber.dispose()
+        disposed.resolve(undefined)
+      },
+    })
+    abort.abort('received SIGTERM')
+    await expect(running).resolves.toBe(1)
+    expect(stderr).toContain('received SIGTERM')
+    expect(disposeCalls).toBe(0)
+    boot.resolve(lateContext)
+    await disposed.promise
+    expect(disposeCalls).toBe(1)
+
+    const rejectedBoot = Promise.withResolvers<Context>()
+    const rejectedAbort = new AbortController()
+    const rejected = executeCli(['task'], {
+      signal: rejectedAbort.signal,
+      boot: () => rejectedBoot.promise,
+      loadEnv: () => {},
+      writeStdout: () => {},
+      writeStderr: () => {},
+    })
+    rejectedAbort.abort('stop rejected boot')
+    await expect(rejected).resolves.toBe(1)
+    rejectedBoot.reject(new Error('late boot rejection'))
+    await Promise.resolve()
+
+    let ordinaryBootStderr = ''
+    const ordinaryBootFailure = await executeCli(['task'], {
+      signal: new AbortController().signal,
+      boot: async () => { throw new Error('ordinary boot failure') },
+      loadEnv: () => {},
+      writeStdout: () => {},
+      writeStderr: (chunk) => { ordinaryBootStderr += chunk },
+    })
+    expect(ordinaryBootFailure).toBe(1)
+    expect(ordinaryBootStderr).toContain('ordinary boot failure')
+
+    const failedCleanupBoot = Promise.withResolvers<Context>()
+    const failedCleanupAbort = new AbortController()
+    const cleanupFailure = Promise.withResolvers<undefined>()
+    const failedCleanupContext = new Context()
+    liveContexts.push(failedCleanupContext)
+    const failedCleanup = executeCli(['task'], {
+      signal: failedCleanupAbort.signal,
+      boot: () => failedCleanupBoot.promise,
+      loadEnv: () => {},
+      writeStdout: () => {},
+      writeStderr: (chunk) => {
+        if (chunk.includes('dispose after interrupted boot failed: late cleanup')) cleanupFailure.resolve(undefined)
+      },
+      dispose: async (ctx) => {
+        await ctx.fiber.dispose()
+        throw new Error('late cleanup')
+      },
+    })
+    failedCleanupAbort.abort('stop failed cleanup boot')
+    await expect(failedCleanup).resolves.toBe(1)
+    failedCleanupBoot.resolve(failedCleanupContext)
+    await cleanupFailure.promise
+  })
+
+  it('renders text, flushes a persisted fresh session, and disposes the context', async () => {
+    const { ctx, agent, persistenceRoot } = await harness([textResponse('final answer')])
+    const output = await invoke(ctx, ['task'])
+    expect(output).toEqual({ code: 0, stdout: 'final answer\n', stderr: '' })
+    expect(agent.status).toBe('disposed')
+    const files = await readdir(persistenceRoot, { recursive: true })
+    expect(files.some(file => file.endsWith('.jsonl'))).toBe(true)
+  })
+
+  it('sums usage across tool steps and selects the last text-bearing assistant message', async () => {
+    const first = { inputTokens: 10, outputTokens: 3, cacheReadTokens: 2, cacheWriteTokens: 1 }
+    const second = { inputTokens: 7, outputTokens: 5, cacheReadTokens: 4, reasoningTokens: 6 }
+    const { ctx } = await harness([toolResponse(first), textResponse('done', second)])
+    const output = await invoke(ctx, ['--output-format', 'json', 'task'])
+    const result = JSON.parse(output.stdout) as CliResult
+    expect(output.code).toBe(0)
+    expect(result).toMatchObject({ type: 'result', success: true, turn: 1, result: 'done', reason: { kind: 'completed' } })
+    expect(result.usage).toEqual({
+      inputTokens: 17,
+      outputTokens: 8,
+      cacheReadTokens: 6,
+      cacheWriteTokens: 1,
+      reasoningTokens: 6,
+    })
+  })
+
+  it('keeps the prior text when a later assistant message has no text blocks', async () => {
+    const { ctx } = await harness([
+      toolResponse({ inputTokens: 1, outputTokens: 1 }),
+      reasoningResponse('reasoning only'),
+    ])
+    const result = await runOneShot(ctx, { task: 'task' })
+    expect(result.result).toBe('working')
+  })
+
+  it('streams only the correlated main message turn and then the result envelope', async () => {
+    const { ctx, agent } = await harness([textResponse('streamed')])
+    const other = ctx.sessions.create(SessionId('unrelated'))
+    let injected = false
+    ctx.on('agent/queued', (subject) => {
+      if (subject !== agent || injected) return
+      injected = true
+      agent.inject([{ type: 'text', text: 'startup injection' }], { source: { kind: 'plugin', plugin: 'test' } })
+      other.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'test' } } })
+      other.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    })
+    const output = await invoke(ctx, ['--output-format', 'stream-json', 'task'])
+    const lines = output.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record<string, unknown>)
+    const events = lines.slice(0, -1).map(line => line['event'] as SessionEvent)
+    expect(lines.at(-1)).toMatchObject({ type: 'result', success: true, turn: 2, result: 'streamed' })
+    expect(events[0]).toMatchObject({ type: 'turn/start', data: { turn: 2, trigger: { kind: 'message' } } })
+    expect(events.at(-1)).toMatchObject({ type: 'turn/end', data: { turn: 2 } })
+    expect(lines.slice(0, -1).every(line => line['sessionId'] === agent.session.id)).toBe(true)
+    expect(events.some(event => event.type === 'context/message')).toBe(false)
+  })
+
+  it('emits partial data and a diagnostic for non-completed turns', async () => {
+    const { ctx } = await harness([textResponse('partial', { inputTokens: 2, outputTokens: 3 }, 'max-tokens')])
+    const output = await invoke(ctx, ['--output-format', 'json', 'task'])
+    expect(JSON.parse(output.stdout)).toMatchObject({ success: false, result: 'partial', reason: { kind: 'max-tokens' } })
+    expect(output.code).toBe(1)
+    expect(output.stderr).toContain('output-token limit')
+  })
+
+  it('cancels an active turn, emits its durable aborted result, and disposes', async () => {
+    const { ctx, agent } = await harness(['hang'])
+    const abort = new AbortController()
+    let started!: () => void
+    const running = new Promise<void>((resolveStarted) => { started = resolveStarted })
+    ctx.on('session/event', (session, event) => {
+      if (session === agent.session && event.type === 'assistant/chunk') started()
+    })
+    const outcome = invoke(ctx, ['--output-format', 'json', 'task'], { signal: abort.signal })
+    await running
+    abort.abort('received SIGINT')
+    const output = await outcome
+    expect(JSON.parse(output.stdout)).toMatchObject({ success: false, reason: { kind: 'aborted', reason: 'received SIGINT' } })
+    expect(output.code).toBe(1)
+    expect(output.stderr).toContain('was aborted: received SIGINT')
+    expect(agent.status).toBe('disposed')
+  })
+
+  it('contains stream-writer failures, cancels, flushes, and returns the output error', async () => {
+    const { ctx, agent } = await harness(['hang'])
+    await expect(runOneShot(ctx, {
+      task: 'task',
+      onEvent: () => { throw new Error('stream sink failed') },
+    })).rejects.toThrow('stream sink failed')
+    expect(agent.status).toBe('idle')
+  })
+
+  it('handles cancellation before submission, a missing main agent, and final-output failure', async () => {
+    const early = await harness([textResponse('unused')])
+    const fakeSignal = {
+      aborted: true,
+      reason: undefined,
+    } as unknown as AbortSignal
+    await expect(runOneShot(early.ctx, { task: 'task', signal: fakeSignal })).rejects.toThrow('interrupted')
+
+    const preBootAbort = new AbortController()
+    preBootAbort.abort('before boot completed')
+    const preBoot = await invoke(early.ctx, ['task'], { signal: preBootAbort.signal })
+    expect(preBoot).toMatchObject({ code: 1, stdout: '' })
+    expect(preBoot.stderr).toContain('before boot completed')
+
+    const empty = new Context()
+    liveContexts.push(empty)
+    await expect(runOneShot(empty, { task: 'task' })).rejects.toThrow('exactly one top-level agent')
+
+    const final = await harness([textResponse('answer')])
+    const output = await invoke(final.ctx, ['task'], { failStdout: true })
+    expect(output.code).toBe(1)
+    expect(output.stdout).toBe('')
+    expect(output.stderr).toContain('stdout closed')
+    expect(final.agent.status).toBe('disposed')
+
+    const disposal = await harness([textResponse('answer')])
+    const disposalOutput = await invoke(disposal.ctx, ['task'], { failDispose: true })
+    expect(disposalOutput).toMatchObject({ code: 1, stdout: 'answer\n' })
+    expect(disposalOutput.stderr).toContain('dispose exploded')
+  })
+
+  it('reports disposal failure alongside an earlier run failure', async () => {
+    const ctx = new Context()
+    liveContexts.push(ctx)
+    const output = await invoke(ctx, ['task'], { failDispose: true })
+    expect(output).toEqual({
+      code: 1,
+      stdout: '',
+      stderr: 'dsh-cli-demo: config must create exactly one top-level agent, found 0\n'
+        + 'dsh-cli-demo: dispose failed: dispose exploded\n',
+    })
+  })
+
+  it('cancels startup work and queued work before the correlated turn begins', async () => {
+    const startup = await harness(['hang'])
+    let started!: () => void
+    const running = new Promise<void>((resolveStarted) => { started = resolveStarted })
+    startup.ctx.on('session/event', (session, event) => {
+      if (session === startup.agent.session && event.type === 'assistant/chunk') started()
+    })
+    startup.agent.send([{ type: 'text', text: 'first' }])
+    await running
+    const startupAbort = new AbortController()
+    const waiting = runOneShot(startup.ctx, { task: 'second', signal: startupAbort.signal })
+    startupAbort.abort('cancel startup')
+    await expect(waiting).rejects.toThrow('cancel startup')
+    await startup.agent.whenIdle()
+
+    const queued = await harness([textResponse('unused')])
+    const queuedAbort = new AbortController()
+    queued.ctx.on('agent/queued', (agent) => {
+      if (agent === queued.agent) queuedAbort.abort('cancel queued')
+    })
+    await expect(runOneShot(queued.ctx, { task: 'task', signal: queuedAbort.signal })).rejects.toThrow('cancel queued')
+    await queued.agent.whenIdle()
+  })
+})
+
+describe('formatTurnFailure', () => {
+  it('diagnoses every durable reason and preserves merge-extensible unknowns', () => {
+    const cases: [TurnEndReason, string][] = [
+      [{ kind: 'completed' }, 'completed'],
+      [{ kind: 'aborted' }, 'was aborted'],
+      [{ kind: 'aborted', reason: 'stop' }, 'was aborted: stop'],
+      [{ kind: 'error', step: 2, message: 'bad' }, 'failed at step 2: bad'],
+      [{ kind: 'disposed' }, 'was disposed'],
+      [{ kind: 'max-tokens' }, 'output-token limit'],
+      [{ kind: 'rejected', reason: 'policy' }, 'was rejected: policy'],
+      [{ kind: 'interrupted' }, 'persistence recovery'],
+    ]
+    for (const [reason, expected] of cases) expect(formatTurnFailure(reason)).toContain(expected)
+    expect(formatTurnFailure({ kind: 'extension' } as unknown as TurnEndReason)).toContain('extension')
+  })
+})

packages/examples/cli-demo/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "../../../.typecheck/cli-demo.tsbuildinfo"
+  },
+  "include": ["src/**/*.ts"],
+  "references": [
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../llm/llm" },
+    { "path": "../../core/session" },
+    { "path": "../../core/agent" },
+    { "path": "../../core/system-prompt" },
+    { "path": "../../core/tools" },
+    { "path": "../agent-spine-demo" },
+    { "path": "../../session-persistence/session-persistence-jsonl" },
+    { "path": "../../ui/app-boot" }
+  ]
+}

packages/examples/cli-demo/tsdown.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'tsdown'
+
+/** Builds the plugin and executable entries from declarations emitted by `tsc -b`. */
+export default defineConfig({
+  entry: ['lib/types/index.js', 'lib/types/bin.js'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+})

packages/examples/jsonrpc-demo/README.md

@@ -20,6 +20,10 @@ stdout carries only JSON-RPC frames. The bin and boot guards diagnose on stderr,
 
 Indirectly, through the plugins loaded from the external `cordis.yml`, which own every model-bound prompt, schema, message, and result; this bin adds none of its own.
 
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
 ## Known Limitations and Deferred Work
 
 - **The bin cannot prove that the config serves JSON-RPC** — a valid config with no `dsh-jsonrpc` entry boots successfully and serves nothing.

packages/examples/stdio-demo/README.md

@@ -1,8 +1,8 @@
 # @deepseek-ai/dsh-stdio-demo
 
-The **terminal stdio chat app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-spine-demo`](../../examples/agent-spine-demo/README.md)) with the front-door cluster a terminal chat needs, and a `bin` that boots a leaf `cordis.yml`.
+The **terminal chat app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-spine-demo`](../../examples/agent-spine-demo/README.md)) with JSONL persistence, human interaction, a pre-created `main` agent, and a TTY-selected pi-tui/readline front door. Its `bin` boots a leaf `cordis.yml`.
 
-It is the readline counterpart to [`@deepseek-ai/dsh-acp-demo`](../acp-demo/README.md): both consume the same spine, but each bakes in the OPPOSITE front-door cluster.
+It is the terminal counterpart to [`@deepseek-ai/dsh-acp-demo`](../acp-demo/README.md): both consume the same spine, while ACP reserves stdout for JSON-RPC and creates sessions from the client.
 
 ## What it bakes in
 
@@ -10,12 +10,13 @@ A terminal chat always wants the same cluster, so the package owns it rather tha
 
 | Plugin | Why it is here |
 |---|---|
-| `@cordisjs/plugin-logger-console` | the console logger — stdout is just the terminal here, so logging to it is correct (the ACP app must NOT have this) |
 | `@deepseek-ai/dsh-agent-spine-demo` | the spine, pre-creating a `main` agent from this app's provider/model pair with `process.cwd()` as the fresh session cwd and carrying its `persona` |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` |
 | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by confirmation tools |
 | `@deepseek-ai/dsh-tool-ask-user` | the model-facing `ask_user_question` tool |
-| `@deepseek-ai/dsh-stdio` | the readline UI, bound to the `main` agent |
+| `@cordisjs/plugin-logger-console` | readline diagnostics for non-TTY operation; omitted from the fullscreen TUI path |
+| `@deepseek-ai/dsh-stdio` | the line-oriented channel for pipes and automation, bound to the exact app-owned agent/session identity |
+| `@deepseek-ai/dsh-tui` | the fullscreen interactive channel for TTY pairs, bound to the same exact identity |
 
 `@cordisjs/plugin-hmr` (the dev/demo edit-reload loop) is deliberately a **leaf** entry, NOT baked in here: it is a Loader-only, subprocess-only dev plugin — its constructor throws without `node --expose-internals` + a live `loader`, and the in-process test tier cannot even import it (so a package whose `apply` statically pulled it in could never carry the per-file coverage gate). Unlike the console logger, a stray `hmr` is not a stdout-purity footgun, so leaving it at the leaf costs no safety. The `demo:echo` / `demo:repl` leaves load it and pass `--expose-internals`.
 
@@ -27,6 +28,7 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte
 |---|---|---|
 | `provider` | (required) | the pre-created `main` agent's registered provider route |
 | `model` | (required) | the pre-created `main` agent's model |
+| `maxParallelToolCalls` | agent-loop default | positive-integer concurrent tool-call cap shared by the bundled loop's agents; `1` is serial |
 | `persona` | — | the deployment persona template (may reference `{{provider}}`/`{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
 | `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
 | `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home exposed to model bash and used by local skill discovery |
@@ -35,10 +37,11 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte
 | `toolBash` | owner defaults | model-facing bash config routed through `dsh-agent-spine-demo`, including bash's producer-local `enableRunInBackground` |
 | `toolTasks` | owner defaults | generic `task_output` wait bounds routed through `dsh-agent-spine-demo` |
 | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
-| `welcome` | `ready.` | the stdin-chat banner |
+| `welcome` | `ready.` | terminal banner / TUI subtitle |
+| `ui` | `{ mode: 'auto' }` | terminal mode (`auto` / `readline` / `tui`) and nested TUI presentation config |
 | `resumeSessionId` | — | resume a persisted session id instead of starting fresh (sourced from an env var in the leaf) |
 
-Fresh stdio sessions use the process launch directory as `session.header.cwd`, so project-scoped features such as skill discovery and default bash workdir follow the directory where `dsh-stdio-demo` was started. Resumed sessions keep the cwd stored in the persisted session header.
+Fresh terminal sessions use the process launch directory as `session.header.cwd` and mint one combined `main-session-<uuid>` agent/session id, so durable restarts cannot collide. The app passes that exact opaque id to the config-created agent and selected UI before agent-core starts; this lets either front door observe `agent-loop/config-start-failed`, and an AgentLoop-only reload restores materialized history under the same id. Readline buffers startup input until `agent/session-start`; the TUI waits to enter fullscreen until the matching root appears. A resumed run binds both components to the exact `resumeSessionId` and keeps the persisted cwd.
 
 ## The bin
 
@@ -66,6 +69,8 @@ Fresh stdio sessions use the process launch directory as `session.header.cwd`, s
     provider: deepseek
     model: deepseek-v4-flash
     persona: 'You are a coding assistant powered by the {{model}} model.'
+    ui:
+      mode: auto
 ```
 
 Swap `llm-deepseek` for a `mock-llm` leaf plugin and you have the echo demo — "swap the backend, keep the app".
@@ -74,18 +79,34 @@ Swap `llm-deepseek` for a `mock-llm` leaf plugin and you have the echo demo —
 
 ### Composed terminal agent request
 
-**What the model sees**: Through `dsh-agent-spine-demo`, the `main` agent receives the harness identity, configured persona, skill catalog, and visible tools; this app also composes the generated [`ask_user_question` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ask-user). Each readline submission becomes a user message.
+#### What the model sees
 
-**Token effect**: Child prompt and schema costs repeat per request; user input and tool history grow until compaction. The welcome banner, logger output, and rendered transcript are terminal-only and add zero model tokens.
+Through `dsh-agent-spine-demo`, the `main` agent receives the harness identity, configured persona, skill catalog, and visible tools; this app also composes the generated [`ask_user_question` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ask-user). Each terminal submission becomes a user message; submissions made while the agent runs steer the active turn.
+
+#### Token effect
+
+Child prompt and schema costs repeat per request; user input and tool history grow until compaction. Terminal banners, logger output, cards, and rendered transcripts add zero model tokens.
+
+#### KV Cache effect
+
+User and tool history is append-only while the composed prompt, schemas, child model route, and session prefix remain fixed. A composition change or compaction may invalidate reuse from its first changed token; terminal rendering has no cache effect.
 
 ### Human-answer result
 
-**What the model sees**: Through `dsh-tool-ask-user`, successful terminal answers use that package's exact compact JSON shape. Interruption becomes exactly `Error: ask_user_question was interrupted before the user answered`; a closed stdin becomes `Error: ask_user_question cannot be answered because stdin is closed`.
+#### What the model sees
 
-**Token effect**: Only a completed or failed tool call adds retained result tokens; prompts printed while waiting are terminal-only.
+Through `dsh-tool-ask-user`, successful terminal answers use that package's exact compact JSON shape. Interruption becomes exactly `Error: ask_user_question was interrupted before the user answered`; a closed stdin becomes `Error: ask_user_question cannot be answered because stdin is closed`.
+
+#### Token effect
+
+Only a completed or failed tool call adds retained result tokens; prompts printed while waiting are terminal-only.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
 ## Known Limitations and Deferred Work
 
-- **One pre-created `main` agent drives the readline UI** — there is no multi-session or concurrent-agent surface in this app; a run is one conversation.
+- **One pre-created `main` agent drives the selected terminal UI** — there is no multi-session or concurrent-agent surface in this app; a run is one conversation.
 - **The front-door cluster is fixed in code** — the JSONL persistence backend and the ask-user tooling are baked; a different composition is a leaf-level sibling entry or another app package.
 - **The question tool is not an approval answerer** — this app mounts `user-interaction` and `ask_user_question`, but not `ctx.approval`; a `tools/pre-execute` `ask` therefore fails closed unless the leaf composes an approval service and terminal answerer.