Merge remote-tracking branch 'origin/master' into codex/trim-ai-prose

# Conflicts: # docs/config-catalog.md # docs/cordis-catalog/services.md # docs/rfc/proposed/feature/2026-07-08-interactive-side-sessions.md # docs/rfc/proposed/simplification/2026-06-20-unify-agent-and-session-id.md # examples/coding-agent/tests/keyless-smoke.e2e.ts # packages/ui/acp/src/index.ts
2026-08-15 21:04:50 +00:00 · 2026-07-13 23:44:44 +08:00
parent 148046b9c8 62eba83f4f
commit 20402b637c
22 changed files with 153 additions and 103 deletions
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -25,7 +25,7 @@ export interface AcpConfig {

 Depends on: `Stream` (`@agentclientprotocol/sdk`)

-Source: [`packages/ui/acp/src/index.ts:203`](../packages/ui/acp/src/index.ts)
+Source: [`packages/ui/acp/src/index.ts:205`](../packages/ui/acp/src/index.ts)

 ## `@deepseek-ai/dsh-acp-agent`

@@ -712,7 +712,7 @@ export interface Config {
 }
 ```

-Source: [`packages/core/system-prompt/src/index.ts:145`](../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:147`](../packages/core/system-prompt/src/index.ts)

 ## `@deepseek-ai/dsh-tool-cordis`

--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -23,7 +23,7 @@ A fully configured agent and live session were published. Setup is composition-o

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:136`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:139`](../../packages/core/agent/src/types.ts)

 ### `agent/disposed` — emit

@@ -35,7 +35,7 @@ An agent left the registry. AgentLoop emits this after driver quiescence; custom

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:144`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:147`](../../packages/core/agent/src/types.ts)

 ### `agent/error` — emit

@@ -47,11 +47,11 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:266`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:278`](../../packages/core/agent/src/types.ts)

 ### `agent/pre-step` — serial

-Awaited checkpoint before `step/start` for outside-step surface mutations. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+Awaited serial checkpoint after prompt assembly and before `step/start`. Listeners may mutate the session surface 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 `signal` cancels listener work. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.

 ```ts cordis-catalog
 'agent/pre-step'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise<void> | void
@@ -59,7 +59,7 @@ Awaited checkpoint before `step/start` for outside-step surface mutations. Scope

 Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:191`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:200`](../../packages/core/agent/src/types.ts)

 ### `agent/prompt-submit` — waterfall

@@ -71,7 +71,7 @@ Allow, rewrite, or block one drained prompt before it becomes a user message. Ca

 Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:201`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:210`](../../packages/core/agent/src/types.ts)

 ### `agent/queued` — emit

@@ -83,7 +83,7 @@ Detached, frozen content entered the agent's inbox. Source defaults have already

 Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:163`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:166`](../../packages/core/agent/src/types.ts)

 ### `agent/request` — waterfall

@@ -95,11 +95,11 @@ Replace the frozen call configuration. Model-visible content must use logged cha

 Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:213`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:222`](../../packages/core/agent/src/types.ts)

 ### `agent/session-prefix` — waterfall

-Compose the frozen session-stable request prefix once per loop instance. Interrupted composition is discarded; changing context belongs in history. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+Compose request-only messages placed before derived history. The frozen 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. 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.

 ```ts cordis-catalog
 'agent/session-prefix'(this: Scoped<Agent>, agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise<Message[]>): Promise<Message[]>
@@ -107,11 +107,11 @@ Compose the frozen session-stable request prefix once per loop instance. Interru

 Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:223`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:235`](../../packages/core/agent/src/types.ts)

 ### `agent/session-start` — emit

-The session lifecycle began, once before the first turn. Use `agent.inject()` to seed model-facing context.
+The session lifecycle began, once before the first turn. Use `agent.inject()` to seed model-facing context. This is a notification, not a veto; disposal requested by a lifecycle owner is rechecked before the driver starts.

 ```ts cordis-catalog
 'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
@@ -119,7 +119,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to

 Types: [Agent](../core-data-structures/core.md) · [SessionStartSource](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:174`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:179`](../../packages/core/agent/src/types.ts)

 ### `agent/status` — emit

@@ -131,7 +131,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does no

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:153`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:156`](../../packages/core/agent/src/types.ts)

 ### `agent/step-result` — waterfall

@@ -143,7 +143,7 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va

 Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:234`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:246`](../../packages/core/agent/src/types.ts)

 ### `agent/turn-continuation` — waterfall

@@ -155,7 +155,7 @@ Override whether the turn continues. The default continues after tool calls or s

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:244`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:256`](../../packages/core/agent/src/types.ts)

 ### `agent/turn-stop` — serial

@@ -167,7 +167,7 @@ Monotonic terminal-stop checkpoint after continuation and steering are folded. A

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/types.ts:253`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:265`](../../packages/core/agent/src/types.ts)

 ## `approval/*`

--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -86,7 +86,7 @@ Source: [`packages/code-runtime/code-runtime/src/index.ts:31`](../../packages/co

 ## `ctx.compact` — `CompactService` (abstract seam)

-Abstract compaction service. Subclass implement the two abstract methods, and load the subclass as a plugin — it registers as `ctx.compact` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+Abstract compaction service. Implementations own token estimation, retention, and summarization, but a successful run must replace the selected surface span with one summary node and prevent concurrent compaction of the same session. Load one implementation per context as `ctx.compact`.

 ```ts cordis-catalog
 abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal, ): Promise<CompactionResult | null>
@@ -95,7 +95,7 @@ abstract compactRegion( session: Session, start: number, end: number, agent: Com

 Types: [Message](../core-data-structures/core.md)

-Source: [`packages/compact/compact/src/index.ts:33`](../../packages/compact/compact/src/index.ts)
+Source: [`packages/compact/compact/src/index.ts:34`](../../packages/compact/compact/src/index.ts)

 ## `ctx.fs` — `FileSystem` (abstract seam)

@@ -212,7 +212,7 @@ variable(name: string, provider: (context: AssembleContext) => string | undefine
 async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
 ```

-Source: [`packages/core/system-prompt/src/index.ts:211`](../../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:213`](../../packages/core/system-prompt/src/index.ts)

 ## `ctx.tools` — `ToolRegistry`

@@ -266,13 +266,13 @@ Source: [`packages/web/web/src/index.ts:78`](../../packages/web/web/src/index.ts

 ## `ctx.workflows` — `WorkflowService` (abstract seam)

-Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound.
+Workflow execution seam. Invalid requests throw before publication; a live run is holder-owned, its result never rejects, cancellation and disposal are bounded, and disposal waits for child cleanup within that bound. Lifecycle listener failures are contained, and `workflow/end` fires exactly once as the result settles.

 ```ts cordis-catalog
 abstract start(request: WorkflowStartRequest): WorkflowRun
 ```

-Source: [`packages/workflow/workflow/src/index.ts:157`](../../packages/workflow/workflow/src/index.ts)
+Source: [`packages/workflow/workflow/src/index.ts:159`](../../packages/workflow/workflow/src/index.ts)

 ## Inherited `ctx` members (cordis core + loader/hmr/timer)

--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -7,19 +7,19 @@ This matrix shows which packages dispatch each harness-owned event and which pac

 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
-| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:136`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`stdio-agent`](../packages/ui/stdio-agent) |
-| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:144`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`stdio-agent`](../packages/ui/stdio-agent) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:266`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
-| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:191`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`user-approval`](../packages/ui/user-approval) |
-| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:201`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) |
-| `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:163`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
-| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:213`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
-| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:223`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill) |
-| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:174`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`invariants`](../packages/support/invariants) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:153`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`invariants`](../packages/support/invariants), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`stdio-agent`](../packages/ui/stdio-agent) |
-| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:234`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
-| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:244`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/turn-stop` | `serial` | [`packages/core/agent/src/types.ts:253`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
+| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:139`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`stdio-agent`](../packages/ui/stdio-agent) |
+| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:147`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`stdio-agent`](../packages/ui/stdio-agent) |
+| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:278`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
+| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:200`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`user-approval`](../packages/ui/user-approval) |
+| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:210`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) |
+| `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:166`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:222`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
+| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:235`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill) |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:179`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`invariants`](../packages/support/invariants) |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:156`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`invariants`](../packages/support/invariants), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`stdio-agent`](../packages/ui/stdio-agent) |
+| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:246`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
+| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:256`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/turn-stop` | `serial` | [`packages/core/agent/src/types.ts:265`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:31`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/ui/acp) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:59`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:68`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) |
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -57,7 +57,7 @@ Raw stream chunk — token-level replay fidelity.

 Types: [StreamChunk](core-data-structures/llm-streaming.md)

-Source: [`packages/core/session/src/types.ts:239`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:242`](../packages/core/session/src/types.ts)

 #### `assistant/message` — surface

@@ -69,7 +69,7 @@ Assembled assistant message for one step (derived history uses this). Carries th

 Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md)

-Source: [`packages/core/session/src/types.ts:246`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:249`](../packages/core/session/src/types.ts)

 ### `bash/*`

@@ -129,7 +129,7 @@ In-session context injection (file-change notices, subdir AGENTS.md, skill conte

 Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md)

-Source: [`packages/core/session/src/types.ts:237`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:240`](../packages/core/session/src/types.ts)

 ### `hook/*`

@@ -165,7 +165,7 @@ Durable record of a prompt veto and its reason. It is log-only: the blocked prom

 Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md)

-Source: [`packages/core/session/src/types.ts:231`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:234`](../packages/core/session/src/types.ts)

 ### `request/*`

@@ -177,7 +177,7 @@ Full EpochHeader for the next request, appended inside its step before dispatch.
 'request/header': { header: EpochHeader; reason: RequestHeaderReason }
 ```

-Source: [`packages/core/session/src/types.ts:274`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:277`](../packages/core/session/src/types.ts)

 #### `request/header-delta` — log-only

@@ -187,7 +187,7 @@ Log-only amendment to the folded EpochHeader. System and tools use their delta c
 'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[] }
 ```

-Source: [`packages/core/session/src/types.ts:280`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:283`](../packages/core/session/src/types.ts)

 ### `steering/*`

@@ -201,7 +201,7 @@ Steering content injected between steps of a running turn.

 Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md)

-Source: [`packages/core/session/src/types.ts:264`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:267`](../packages/core/session/src/types.ts)

 ### `step/*`

@@ -213,7 +213,7 @@ Closes step `step` of turn `turn`.
 'step/end': { turn: number; step: number }
 ```

-Source: [`packages/core/session/src/types.ts:224`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:227`](../packages/core/session/src/types.ts)

 #### `step/start` — log-only

@@ -223,7 +223,7 @@ Opens step `step` of turn `turn` — one model call plus the tool executions it
 'step/start': { turn: number; step: number }
 ```

-Source: [`packages/core/session/src/types.ts:222`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:225`](../packages/core/session/src/types.ts)

 ### `todo/*`

@@ -237,7 +237,7 @@ Whole-list snapshot; the latest write wins on replay. It is log-only UI state an

 Types: [TodoItem](core-data-structures/session.md)

-Source: [`packages/core/session/src/types.ts:269`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:272`](../packages/core/session/src/types.ts)

 ### `tool/*`

@@ -251,7 +251,7 @@ The model requested one tool invocation: `name` with the raw `arguments` JSON st

 Types: [CallId](core-data-structures/core.md)

-Source: [`packages/core/session/src/types.ts:252`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:255`](../packages/core/session/src/types.ts)

 #### `tool/code-dispatch` — log-only

@@ -275,7 +275,7 @@ A completed tool call's model-facing result, plus an optional tool-private `meta

 Types: [CallId](core-data-structures/core.md) · [ContentBlock](core-data-structures/core.md)

-Source: [`packages/core/session/src/types.ts:262`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:265`](../packages/core/session/src/types.ts)

 ### `turn/*`

@@ -289,7 +289,7 @@ Closes turn `turn` with the TurnEndReason that ended it. The loop fires the awai

 Types: [TurnEndReason](core-data-structures/session.md)

-Source: [`packages/core/session/src/types.ts:220`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:223`](../packages/core/session/src/types.ts)

 #### `turn/start` — log-only

@@ -301,7 +301,7 @@ Opens turn `turn`. `trigger` records what started it — a drained message batch

 Types: [TurnTrigger](core-data-structures/session.md)

-Source: [`packages/core/session/src/types.ts:214`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:217`](../packages/core/session/src/types.ts)

 ### `user/*`

@@ -315,4 +315,4 @@ A user-visible prompt (queued message drained at turn start).

 Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md)

-Source: [`packages/core/session/src/types.ts:226`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:229`](../packages/core/session/src/types.ts)
--- a/docs/rfc/proposed/feature/2026-07-08-interactive-side-sessions.md
+++ b/docs/rfc/proposed/feature/2026-07-08-interactive-side-sessions.md
@@ -10,12 +10,12 @@ A user may want to explore a question from a live session without changing its m

 A **side session** is an ordinary live session forked at the source's last completed turn, attached to its own agent, framed as a read-only advisor, and able to **merge back** one condensed note.

- **Fork and attach:** create the child with the parent's balanced completed-turn prefix and stamp `parentSession` and `seedLength`. This composes `ctx.agents.create({ seed, meta })`; it adds no core service or session-store method.
- **Advisor framing:** inject one plugin-sourced `context/message` after creation. Keeping the system prompt byte-identical preserves the provider prefix cache.
+- **Fork and attach:** create the child with the parent's balanced completed-turn prefix and stamp `parentSession` and `seedLength` in its metadata. This composes `ctx.agents.create({ seed, meta })`; it adds no core service or session-store method.
+- **Advisor framing:** inject one plugin-sourced `context/message` after creation that tells the child to explain without mutating or continuing the task. Keeping the system prompt byte-identical preserves the provider prefix cache over inherited history.
 - **Merge-back:** ask the child for a length-capped handback, then inject one plugin-sourced `context/message` into the parent. The next parent request sees it at its logged position, preserving replay and [request reconstructability](../../implemented/architecture/2026-07-05-reconstructable-requests.md) without a new session event.
 - **Presentation:** invocation, session switching, and handback rendering belong to the first client-owned surface. This RFC specifies only the surface-independent mechanics.

-Rewind productization, session-tree views, a model-facing side-session tool, and `forkName`/`mergedInto` metadata are out of scope. A live-adapter spike has validated source-log isolation, inherited context, a multi-turn child exchange, and merge-back visibility in the parent's next turn.
+Rewind productization, session-tree views, a model-facing side-session tool, and `forkName`/`mergedInto` metadata are out of scope. A live-adapter spike validated source-log isolation, inherited context, a multi-turn child exchange, and merge-back visibility in the parent's next turn.

 ## Alternatives considered

@@ -27,7 +27,7 @@ Rewind productization, session-tree views, a model-facing side-session tool, and
 ## Acceptance criteria

 - Forking leaves the source untouched and creates a child with the balanced completed-turn prefix, `parentSession`, `seedLength`, and a byte-identical system prompt.
- Advisor framing adds exactly one plugin-sourced `context/message` at the head of the child's appended history.
+- Advisor framing adds exactly one plugin-sourced `context/message` at the head of the child's appended history, rather than changing its system prompt.
 - Merge-back adds exactly one length-capped `context/message` with source `plugin: sidechat`; the next parent request and replay see it at the same position.
 - Parent and child run concurrently without log or stream cross-talk.
 - Unit tests cover fork/attach and merge-back; snapshot coverage lands with the first bound surface.
--- a/docs/rfc/proposed/simplification/2026-06-20-unify-agent-and-session-id.md
+++ b/docs/rfc/proposed/simplification/2026-06-20-unify-agent-and-session-id.md
@@ -6,23 +6,23 @@ Status: proposed

 The agent factory carries two ids for each live agent/session pair: `agentId`, the `AgentRegistry` routing handle, and `sessionId`, the event-sourced and persisted-log identity. `CreateAgentOptions` takes both; `ResumeAgentOptions` takes `agentId` plus `resumeSessionId`; in-process subagents mint two independent UUIDs despite recording lineage separately.

-ACP already uses the same value for both identities. They diverge for config-created agents, resumed sessions, and in-process children, but no production path reattaches one live agent to several sessions or drives one session through several agent ids. Stdio keeps a session-to-agent map only to recover a display label, and hooks must expose or reconcile both values.
+ACP already uses the same value for both identities. They diverge for config-created agents, resumed sessions, and in-process children, but no production path reattaches one live agent to several sessions or drives one session through several agent ids. Stdio keeps `labelBySession` only to recover an agent label from session events, and hooks expose both values for authors to reconcile.

-The [agent-scope runtime](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md) has no identity-specific reservation state: create and resume use one transaction, and both registry entries arbitrate at final publication. Unification therefore changes API and representation, not rollback or quiescence. It also makes the live-agent registry enforce the session identity used by background-task ownership instead of relying on callers to preserve that association.
+The [agent-scope runtime](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md) has no identity-specific reservation state: create and resume use one `AgentCreationTransaction`, and both registry entries use the same final-entry collision rule. Separate ids do not duplicate liveness, rollback, or quiescence machinery. Unification deletes one caller-supplied id, one UUID per in-process child, and the remaining translation paths without changing the transaction lifecycle; it also makes the live-agent registry enforce the session identity used by background-task ownership.

 `Session` separately exposes `Session.id` and `Session.header.id` even though construction requires them to match. The durable boundary must validate the duplicate, and consumers must choose between two homes for one fact.

 ## Proposal

-Use one id for the agent registry entry and `session.header.id`. `CreateAgentOptions` accepts one identity for both entries; resume registers the agent under the resumed session id; subagent creation mints one combined id; and `Session` keeps one identity home. Preserve the current transaction, collision checks, rollback, quiescence, and entry-bound detach semantics.
+Use one id for the agent registry entry and `session.header.id`. `CreateAgentOptions` accepts one identity for both final entries; resume registers the agent under the resumed session id; subagent creation mints one combined id; and `Session` keeps one identity home. Preserve the current transaction, final-entry collision checks, exact-entry detach, rollback, and quiescence; remove only maps and fields whose sole job is translating between the ids.

-The config-driven path must first settle its resume-or-create policy. Today it uses a stable agent label and a fresh UUID-suffixed session id to avoid colliding with an existing durable log. Under unification it must deliberately resume a fixed id, mint a fresh combined id, or expose that policy; implementation must not choose silently.
+The config-driven path must first settle its resume-or-create policy. Today it uses a stable agent label and a fresh UUID-suffixed session id to avoid colliding with an existing durable log on the next run. Under unification it must deliberately resume a fixed id, mint a fresh combined id, or expose that policy; implementation must not choose silently.

-`agent/created` and `agent/disposed` remain outside this proposal. They are publication lifecycle events rather than identity aliases; removing them requires a separate consumer audit and decision.
+`agent/created` and `agent/disposed` remain outside this proposal. They are publication lifecycle events rather than identity aliases; removing them requires a separate production-consumer audit and decision.

 ## Alternatives considered

-**Keep separate routing and log identities.** A stable configured agent label paired with fresh conversations is a real use of the distinction. If that display or routing identity is required, keep the ids separate and enforce session-id uniqueness explicitly instead of hiding the translation in another map.
+**Keep separate routing and log identities.** A stable configured agent label paired with a fresh conversation is a real use of the distinction. If that display or routing identity is required, reject this proposal and enforce session-id uniqueness explicitly instead of hiding the translation in another map.

 ## Acceptance criteria

@@ -35,6 +35,6 @@ The config-driven path must first settle its resume-or-create policy. Today it u

 ## Risks

-Unification forecloses a stable actor identity spanning several session logs, including a future handoff or fork that deliberately preserves the actor while changing the session. Reintroducing that design would require a new explicit actor identity. It also makes a persisted, possibly client-chosen session id the registry handle and changes every create/resume call site and fixture.
+Unification forecloses a stable actor identity spanning several session logs, including a future handoff or fork that preserves the actor while changing the session. Reintroducing that design would require a new explicit actor identity. It also makes a persisted, possibly client-chosen session id the registry handle and changes every create/resume call site and fixture.

-The config restart policy is the blocking design decision: a fixed combined id may collide with its existing log, while a per-run id gives up the stable configured label. If either independent actor identity or the stable-label/fresh-session pairing is a real requirement, reject this proposal and retain the separate ids with an explicit uniqueness guard.
+The config restart policy is the blocking design decision: a fixed combined id may collide with its existing log, while a per-run id gives up the stable configured label. If either independent actor identity or the stable-label/fresh-session pairing is required, reject this proposal and retain the separate ids with an explicit uniqueness guard.
--- a/examples/coding-agent/tests/keyless-smoke.e2e.ts
+++ b/examples/coding-agent/tests/keyless-smoke.e2e.ts
@@ -6,27 +6,22 @@ import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'

 /**
- * Keyless Loader-path smoke for examples/coding-agent: boot the real example through the
- * `@deepseek-ai/dsh-stdio-agent` bin against its `cordis.yml` (the cordis Loader,
- * `unwrapExports`, the full plugin tree incl. the `@deepseek-ai/dsh-agent-core` bundle and the
- * app's in-package readline UI module), then close stdin with no prompt and assert the ready
- * banner + a clean exit. A dummy key satisfies adapter boot, but no prompt means
- * no network call; with-key suites own the product behavior.
+ * Boots the real example through the stdio bin and `cordis.yml`, covering Loader,
+ * `unwrapExports`, the full plugin tree, the agent-core bundle, and the readline module.
+ * A dummy key permits startup; closing stdin before a prompt prevents network calls,
+ * while with-key suites cover product behavior.
 */

+// TODO(loader-smoke-harness): share spawn/tempdir/timeout/EOF setup with the other keyless smoke tests.
 // The temp-cwd child needs absolute bin and config paths.
 const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url))
 const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
-// Dev/test run UNBUILT: resolve `@deepseek-ai/dsh-*` through the root tsconfig
-// `paths` map; tsx searches UP from cwd, and we spawn from a temp dir outside
-// the repo, so point it at the repo tsconfig (root is four levels up).
+// The temp cwd cannot discover the root tsconfig used for unbuilt package aliases.
 const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
-// Under parallel e2e load, cold tsx/Loader startup can exceed a tight deadline;
-// 30s still detects a wedged child.
+// Allow cold Loader startup under parallel load while still detecting hangs.
 const PROCESS_TIMEOUT_MS = 30_000
-// Leave enough room for the process-owned timeout to report captured output
-// before Vitest aborts the test itself.
+// Let the child timeout report captured output before Vitest aborts.
 const TEST_TIMEOUT_MS = PROCESS_TIMEOUT_MS + 15_000

 let child: ChildProcessWithoutNullStreams | undefined
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -2,6 +2,9 @@
 * Model-facing `bash`, `bash_output`, and `bash_kill` tools over the executor
 * seam. Background tasks are fenced by owning session, completion injects a
 * durable notice, and confining executors add one-shot approval-based escalation.
+ * Notices do not wake idle agents. Ownership is stored with the executor task so
+ * it survives this plugin's reload; per-call authority is escalation grant,
+ * session override, then executor default. See the package README for the tool contract.
 * @module @deepseek-ai/dsh-tool-bash
 */

@@ -104,7 +107,9 @@ const WIDER_MODES: Record<string, readonly SandboxMode[]> = {
 const ESCALATION_TARGETS: readonly SandboxMode[] = ['workspace-write', 'danger-full-access']

 /**
- * The bash tool's static description.
+ * The bash tool's byte-stable base description. Escalation guidance is added
+ * only when the mounted executor can honor it, as the one exception to the
+ * ordinary no-retry guidance.
 */
 function bashDescription(escalationModes: readonly SandboxMode[]): string {
  const base = 'Execute a bash command (`bash -c`) and return its stdout/stderr. '
@@ -190,7 +195,7 @@ export function renderResult(
  return body + markers.join('\n')
 }

-// UI presentation (tool-owned).
+// Pure tool-owned presentation used for both live events and replay.

 /**
 * Present foreground calls as terminals and background starts as generic cards.
@@ -337,6 +342,8 @@ export function apply(ctx: Context): void {
  })

  // The escalation surface exists whenever the mounted executor confines.
+  // Advertise the closed target vocabulary globally, then enforce strict
+  // widening against each call's effective session mode.
  const defaultMode = ctx.bash.sandboxMode
  const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS

@@ -433,9 +440,8 @@ export function apply(ctx: Context): void {
    },
    async execute(args: BashToolArgs, exec) {
      validateBashArgs(args)
-      // `description` is display/logging metadata only (surfaced to UIs via the tool/call
-      // session event); it is intentionally not forwarded to ctx.bash and has no effect on
-      // execution.
+      // `description` is display/logging metadata only. Escalation approval
+      // completes before execution; grant > session override > executor default.
      const sandboxMode = args.sandbox_permissions !== undefined && args.justification !== undefined
        ? await approveEscalation(args.sandbox_permissions, args.justification, exec)
        : sessionOverride(exec)
--- a/packages/compact/compact/src/index.ts
+++ b/packages/compact/compact/src/index.ts
@@ -26,9 +26,10 @@ declare module 'cordis' {
 }

 /**
- * Abstract compaction service. Subclass implement the two abstract methods, and load the
- * subclass as a plugin — it registers as `ctx.compact` (one implementation per context;
- * loading a second throws, which is cordis' standard duplicate-service behavior).
+ * Abstract compaction service. Implementations own token estimation, retention,
+ * and summarization, but a successful run must replace the selected surface span
+ * with one summary node and prevent concurrent compaction of the same session.
+ * Load one implementation per context as `ctx.compact`.
 */
 export abstract class CompactService extends Service {
  constructor(ctx: Context) {
@@ -37,12 +38,17 @@ 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.
   *
   * @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 signal - cancellation signal.
+   * @param signal - cancellation signal; model-backed implementations must forward it.
   * @returns the compaction result, or `null` if no compaction was needed.
   */
  abstract compactIfNeeded(
@@ -54,13 +60,18 @@ export abstract class CompactService extends Service {

  /**
   * Forcibly compact a range of surface nodes into a single summary node.
+   * `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 and rejects active, missing,
+   * reversed, or unbalanced ranges.
   *
   * @param session - session to mutate.
   * @param start - first surface seq, inclusive.
   * @param end - last surface seq, inclusive.
   * @param agent - summarizer context.
   * @param signal - optional cancellation; model-backed implementations must forward it.
-   * @throws when compaction is active or the range is invalid or unbalanced.
+   * @throws when compaction is active or the range is missing, reversed, or unbalanced.
   * @returns the replaced range and summary.
   */
  abstract compactRegion(
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -258,7 +258,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
    name: 'agent/pre-step',
    mode: 'serial',
    signature: '\'agent/pre-step\'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise<void> | void',
-    summary: 'Awaited checkpoint before `step/start` for outside-step surface mutations.',
+    summary: 'Awaited serial checkpoint after prompt assembly and before `step/start`.',
  },
  {
    name: 'agent/prompt-submit',
@@ -282,7 +282,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
    name: 'agent/session-prefix',
    mode: 'waterfall',
    signature: '\'agent/session-prefix\'(this: Scoped<Agent>, agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise<Message[]>): Promise<Message[]>',
-    summary: 'Compose the frozen session-stable request prefix once per loop instance.',
+    summary: 'Compose request-only messages placed before derived history.',
  },
  {
    name: 'agent/session-start',
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -132,6 +132,8 @@ interface FactorySlot {
 */
 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 factory: FactorySlot | undefined

--- a/packages/core/agent/src/types.ts
+++ b/packages/core/agent/src/types.ts
@@ -104,14 +104,17 @@ export interface Agent {

  /**
   * Append model-facing context without running the model. Idle injection uses
-   * a one-shot turn and durability checkpoint; disposal awaits that checkpoint,
-   * and flush failures are reported through `agent/error`.
+   * a one-shot turn and durability checkpoint, while injection during an open
+   * turn joins it at the current log position. Disposal awaits idle checkpoints;
+   * flush failures are reported through `agent/error`, not thrown to the caller.
   */
  inject(content: ContentBlock[], options?: SendOptions): void

  /**
   * Clear queued and steering work, including work waiting to start, and abort
-   * the active step. Idle cancellation is a no-op and does not arm a later cancel.
+   * the active step. The supplied reason is preserved across pre-step and active
+   * cancellation windows, and `whenIdle()` resolves after cancellation reaches
+   * quiescence. Idle cancellation is a no-op and does not arm a later cancel.
   */
  cancel(reason?: string): void

@@ -165,7 +168,9 @@ declare module 'cordis' {
    // ---- session lifecycle (emit) ----
    /**
     * The session lifecycle began, once before the first turn. Use
-     * `agent.inject()` to seed model-facing context.
+     * `agent.inject()` to seed model-facing context. This is a notification, not
+     * a veto; disposal requested by a lifecycle owner is rechecked before the
+     * driver starts.
     * @param agent - the agent whose session lifecycle began.
     * @param source - why the session started (fresh startup, resume, …).
     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
@@ -177,7 +182,11 @@ declare module 'cordis' {

    // ---- step/request extension seams (serial + waterfall) ----
    /**
-     * Awaited checkpoint before `step/start` for outside-step surface mutations.
+     * Awaited serial checkpoint after prompt assembly and before `step/start`.
+     * Listeners may mutate the session surface 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 `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.
@@ -212,8 +221,11 @@ declare module 'cordis' {
     */
    'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
    /**
-     * Compose the frozen session-stable request prefix once per loop instance.
-     * Interrupted composition is discarded; changing context belongs in history.
+     * Compose request-only messages placed before derived history. The frozen
+     * 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. 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.
--- a/packages/core/session/src/types.ts
+++ b/packages/core/session/src/types.ts
@@ -17,6 +17,9 @@ export function SessionId(id: string): SessionId {
 * The on-disk session format version, stamped into every newly-written {@link SessionHeader}
 * and enforced by every persistence backend on load. The single source of truth for the
 * version — write sites and the load-time check all read it.
+ * While the harness is unreleased it is pinned at `0`: no compatibility is
+ * implied, incompatible logs are rejected, and no migration is provided. A
+ * monotonic version policy starts with the first tagged release.
 */
 export const SESSION_FORMAT_VERSION = 0

--- a/packages/core/system-prompt/src/index.ts
+++ b/packages/core/system-prompt/src/index.ts
@@ -65,6 +65,8 @@ export interface PromptSection {
 export interface AssembledSection {
  /** The contributing section's unique name. */
  name: string
+  // TODO(assembled-section-order): drop this output field; registry order has
+  // already sorted the array, and no production renderer/listener reads it.
  /** The contributing section's order (sections arrive sorted ascending). */
  order: number
  /** The resolved (but not yet interpolated) section text. */
--- a/packages/guard/repeat-tool-guard/src/index.ts
+++ b/packages/guard/repeat-tool-guard/src/index.ts
@@ -174,6 +174,8 @@ export function apply(ctx: Context, config: Config): void {
    throw new Error(`repeat-tool-guard: invalid argumentsPreviewChars ${argumentsPreviewChars} — must be an integer >= 1`)
  }

+  // TODO(agent-keyed-repeat-chain): key a WeakMap by the Agent itself; that
+  // removes the disposal-only status listener and cannot collide on id reuse.
  const chains = new Map<AgentId, Chain>()

  /** Whether a tool participates in the chain (untracked calls are transparent: they neither count nor reset). */
--- a/packages/ui/acp-agent/src/index.ts
+++ b/packages/ui/acp-agent/src/index.ts
@@ -51,6 +51,8 @@ export const Config: z<Config> = z.object({
  // schemastery's native [] default would read as an invalid configured list.
  toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
  tools: ToolRegistry.Config,
+  // 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'),
  skills: agentCore.SkillConfigSchema,
 })
--- a/packages/ui/acp/src/index.ts
+++ b/packages/ui/acp/src/index.ts
@@ -1,7 +1,8 @@
 /**
 * Multi-session ACP server bridge over JSON-RPC stdio. Creates or resumes
 * agents, routes their events, settles prompts by turn, and answers approvals.
- * Stdout is reserved for protocol frames.
+ * Each session keeps independent presentation and prompt-correlation state so
+ * concurrent streams cannot cross. Stdout is reserved for protocol frames.
 * @module @deepseek-ai/dsh-acp
 */

@@ -72,7 +73,8 @@ import {
 } from './codec.ts'

 export const name = 'acp'
-// Interface services required by advertised load, presentation, and interaction capabilities.
+// Interface services back advertised loading, tool-owned presentation with a generic fallback, and interaction.
+// TODO(acp-session-inject): remove `sessions`; the bridge never reads it, and ownership is already behind `agents`.
 export const inject = ['agents', 'sessions', 'sessionPersistence', 'tools', 'userInteraction']

 /** Build an ACP invalid-params error with visible human detail. */
@@ -227,7 +229,10 @@ interface SessionRecord {
    reject: (error: Error) => void
    turn: number | undefined
  } | undefined
-  /** Idle config changes awaiting a turn-enclosed log anchor; last write wins. */
+  /**
+   * Idle config changes awaiting a turn-enclosed log anchor; last write wins.
+   * Responses overlay them, but a restart before the next turn restores the logged fold.
+   */
  pendingSwitches: { sandboxMode?: SandboxMode; approvalPolicy?: ApprovalPolicy }
 }

@@ -238,7 +243,7 @@ interface SessionRecord {
 * correlation in a `finally` so presentation failure cannot starve settlement.
 */
 export function apply(ctx: Context, config: AcpConfig): void {
-  // Capture injected services while executing inside this plugin's fiber.
+  // Handlers run later outside this injection scope, so capture services now.
  const agents = ctx.agents
  const sessionPersistence = ctx.sessionPersistence
  const logger = ctx.logger
@@ -247,7 +252,9 @@ export function apply(ctx: Context, config: AcpConfig): void {
  // Presenter failures are logged and contained per session or replay.
  const makePresenter = (agent?: Agent): ToolPresenter => new ToolPresenter(tools, (message) => { logger.warn(message) }, agent)

-  // Keep forward and reverse session indexes in lockstep.
+  // TODO(derive-acp-session-id): derive event ids from `agent.session`, verify ownership, then remove the reverse map.
+  // Agent events currently carry only the Agent, so retain `SessionRecord.sessionId` and update both indexes together.
+  // Dropping the forward record lets the weak reverse entry expire.
  const sessions = new Map<SessionId, SessionRecord>()
  const bySession = new WeakMap<Agent, SessionId>()
  // Reserve ids across asynchronous resume; distinct ids still load concurrently.
@@ -1025,6 +1032,7 @@ export function streamSessionEventUpdate(

 /**
 * Map a whole harness todo list to an ACP plan, assigning medium priority.
+ * Statuses map directly and ACP replaces its whole plan on each update.
 * @param todos - the harness todo list (the whole list, not a diff).
 * @returns the ACP plan body, one entry per todo.
 */
@@ -1045,6 +1053,7 @@ const noTerminalRendering: TerminalRendering = { enabled: false, cwd: undefined
 /**
 * Resolve tool-owned call/result views with generic fallbacks. Per-session
 * call-id state supplies the tool name and arguments omitted from result events.
+ * Each entry is consumed by its result; any remainder dies with the session.
 */
 export class ToolPresenter {
  private readonly pending = new Map<CallId, { name: string; args: unknown; card: ToolCallView['card'] }>()
--- a/packages/ui/stdio-agent/src/index.ts
+++ b/packages/ui/stdio-agent/src/index.ts
@@ -64,6 +64,8 @@ export const Config: z<Config> = z.object({
  // schemastery's native [] default would read as an invalid configured list.
  toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
  tools: ToolRegistry.Config,
+  // TODO(single-default-literal): share these schema defaults and defensive
+  // apply() fallbacks through named constants while retaining both boundaries.
  persistenceRoot: z.string().default('./.sessions'),
  welcome: z.string().default('ready.'),
  skills: agentCore.SkillConfigSchema,
--- a/packages/ui/stdio-agent/src/stdio-chat.ts
+++ b/packages/ui/stdio-agent/src/stdio-chat.ts
@@ -26,6 +26,8 @@ export const inject = ['agents', 'userInteraction']
 export interface Config {
  /** Banner printed once on start, before the first `> ` prompt. */
  welcome?: string
+  // TODO(fixed-stdio-agent): this app-internal plugin is mounted only for the
+  // precreated `main` agent; remove configurability and its config-only test.
  /** Id of the agent stdin drives (`send`/`steer`) and whose status gates the EOF exit; rendering is global. Defaults to `'main'`. */
  agent?: string
 }
--- a/packages/workflow/tool-workflow/README.md
+++ b/packages/workflow/tool-workflow/README.md
@@ -4,7 +4,7 @@ The model-facing **`workflow` tool**: run a JavaScript orchestration script that

 ## What the model sees

-Two parameters: `script` (required — the full `export const meta = {...}` + body text; the tool DESCRIPTION carries the complete authoring contract: hooks, semantics, the supported schema subset) and `args` (optional JSON object exposed to the script as the `args` global; a bare list is wrapped as a field, a deliberate deviation from Claude Code's any-JSON `args` so the wire schema stays honest). The plugin also contributes a `tool:<toolName>` system-prompt section carrying the usage policy — use the tool only on an explicit user ask for a workflow / large orchestration; prefer plain subagent calls for one or two delegations — per the convention that tool guidance ships with the tool plugin, never in the deployment persona.
+Three parameters: `meta` (required identity data: `name`, `description`, and optional progress annotations), `script` (required plain JavaScript body — no `export const meta` statement; the tool description carries the complete authoring contract), and `args` (optional JSON object exposed to the script as the `args` global; wrap a bare list in a field so the wire schema stays honest). The plugin also contributes a `tool:<toolName>` system-prompt section carrying the usage policy — use the tool only on an explicit user ask for a workflow / large orchestration; prefer plain subagent calls for one or two delegations — per the convention that tool guidance ships with the tool plugin, never in the deployment persona.

 ## Lifecycle

@@ -12,7 +12,7 @@ Collection is SYNCHRONOUS this cut (like [`dsh-tool-subagent`](../../subagent/to

 ## Render intent

-Decided up front (per the [render-intent RFC](../../../docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md)): a `generic` card titled `workflow: <meta.name>`, the name sniffed TEXTUALLY from `args.script` (presentation must be a pure function of args, so it cannot ask the engine to parse); the script text rides as `rawInput`. The result keeps the generic card.
+Decided up front (per the [render-intent RFC](../../../docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md)): a `generic` card titled `workflow: <meta.name>`, read directly from `args.meta.name` (presentation is a pure function of args and does not ask the engine to parse); the script text rides as `rawInput`. The result keeps the generic card.

 ## Config

--- a/packages/workflow/workflow/src/index.ts
+++ b/packages/workflow/workflow/src/index.ts
@@ -152,7 +152,9 @@ export function isFatalWorkflowError(error: unknown): boolean {
 /**
 * Workflow execution seam. Invalid requests throw before publication; a live
 * run is holder-owned, its result never rejects, cancellation and disposal are
- * bounded, and disposal waits for child cleanup within that bound.
+ * bounded, and disposal waits for child cleanup within that bound. Lifecycle
+ * listener failures are contained, and `workflow/end` fires exactly once as the
+ * result settles.
 */
 export abstract class WorkflowService extends Service {
  constructor(ctx: Context) {