Merge remote-tracking branch 'origin/master' into codex/ask-user-question

# Conflicts: # docs/module-graph.md
2026-07-08 22:22:25 +08:00
parent d3f86996f7 970971fd53
commit b31399bdc4
99 changed files with 3332 additions and 484 deletions
@@ -128,3 +128,25 @@ jobs:

      - name: Run compatibility gates
        run: pnpm run check:node-compat
+
+  # Single stable required check for branch protection: require "all checks
+  # passed" instead of enumerating matrix legs whose names change as lanes and
+  # node versions evolve. Every other job in THIS workflow must be listed in
+  # `needs` (`needs` cannot reach across workflow files; e2e.yml stays its own
+  # check). `if: always()` is load-bearing: without it a failed dependency
+  # would SKIP this job, and GitHub counts a skipped required check as passing
+  # — so this job always runs and fails on any non-success result, including
+  # 'cancelled' and 'skipped'.
+  all-checks-passed:
+    name: all checks passed
+    runs-on: ubuntu-latest
+    needs: [node-24, node-compat]
+    if: always()
+    steps:
+      - name: Fail if any needed job did not succeed
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped')
+        run: |
+          echo "::error::Needed job results: ${{ join(needs.*.result, ', ') }}"
+          exit 1
+      - name: All checks passed
+        run: echo "All needed jobs succeeded (${{ join(needs.*.result, ', ') }})"
@@ -19,11 +19,12 @@ packages/    Harness packages at packages/<group>/<pkg>/, all named @deepseek-ai
  compact/     compaction seam + basic backend
  subagent/    subagent seam + spawn/fork/ACP backends + delegation tool
  todo/        the todo_write tool
+  guard/       loop-hygiene plugins
  hooks/       Claude Code / Codex hook bridges + shared wire-protocol library
  session-persistence/  persistence seam + JSONL/SQLite backends
  ui/          ACP bridge + app-boot glue + the stdio/ACP app bins
-  support/     dev/test infrastructure: invariants, llm-replay, subagent-mock
-  util/        zero-dependency utilities (Branded<B>)
+  support/     dev/test infrastructure packages
+  util/        zero-dependency utilities
 examples/    Runnable demos: thin cordis.yml leaves over the app packages (see examples/AGENTS.md)
 docs/        architecture, generated catalogs, RFCs, postmortems, cookbook (see docs/AGENTS.md)
 scripts/     repo gates and generators
@@ -26,6 +26,7 @@ The default distribution is a composition, not a hierarchy. `packages/core/` is
 |---|---|---|
 | `ctx.llm` | [`llm/`](../packages/llm/README.md) | adapter registry and streaming model calls |
 | `ctx.bash` | [`bash/`](../packages/bash/README.md) | foreground/background command execution |
+| `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | model-written program execution |
 | `ctx.fs` | [`fs/`](../packages/fs/README.md) | filesystem provider primitives and policy events |
 | `ctx.web` | [`web/`](../packages/web/README.md) | search/fetch provider registries |
 | `ctx.compact` | [`compact/`](../packages/compact/README.md) | session-surface compaction |
@@ -45,6 +45,8 @@ flowchart LR
  pkg_bash_local["bash-local"]
  pkg_hooks_claude["hooks-claude"]
  pkg_hooks_codex["hooks-codex"]
+  pkg_code_runtime["code-runtime"]
+  svc_codeRuntime["ctx.codeRuntime<br/>Code-execution seam"]
  pkg_fs["fs"]
  svc_fs["ctx.fs<br/>Filesystem provider seam"]
  pkg_fs_local["fs-local"]
@@ -68,6 +70,7 @@ flowchart LR
  pkg_agent_loop --> svc_agentLoop
  pkg_bash --> svc_bash
  pkg_bash_local --> svc_bash
+  pkg_code_runtime --> svc_codeRuntime
  pkg_compact --> svc_compact
  pkg_compact_basic --> svc_compact
  pkg_fs --> svc_fs
@@ -145,6 +148,7 @@ flowchart LR
 | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-agent`](../packages/ui/stdio-agent), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles and the create/resume factory seam. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-core`](../packages/core/agent-core) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors can replace bash-local. |
+| `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | - | - | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the Code Mode RFC specifies the worker-thread backend and the tool-registry consumer). |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-policy contributes observed-state checks through the fs/* event gate. |
 | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend currently consumes the pre-step event directly; a model-facing compact tool remains deferred. |
 | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-mock`](../packages/support/subagent-mock) | [`tool-subagent`](../packages/subagent/tool-subagent) | - | Providers implement transports; tool-subagent exposes one configured provider as a model-facing tool name. |
@@ -353,6 +353,38 @@ export interface Config {

 Source: [`packages/support/llm-replay/src/index.ts:429`](../packages/support/llm-replay/src/index.ts)

+## `@deepseek-ai/dsh-repeat-tool-guard`
+
+```ts config-catalog
+/**
+ * Plugin config, validated by the same-named schemastery schema plus the
+ * load-time checks in `apply` (misconfiguration fails loud: an empty
+ * `thresholds` list, a non-integer, a value below 2, or a duplicate throws at
+ * plugin load, never a silent fall-back). `include`/`exclude` entries are
+ * `*`-wildcard predicates over tool names at call time, not references to
+ * registry entries — a pattern matching no currently registered tool is valid
+ * (`exclude: [mcp_*]` must stay legal in a deployment that loads no MCP tools).
+ */
+export interface Config {
+  /** Consecutive-repeat counts that trigger a reminder (default `[3, 5, 8]`). */
+  thresholds?: number[]
+  /** Tool-name patterns to track; empty means every tool is tracked. */
+  include?: string[]
+  /** Tool-name patterns transparent to the chain (neither count nor reset). */
+  exclude?: string[]
+  /**
+   * Maximum characters of canonical arguments quoted in the DETAILED reminder
+   * (default 500). Large payloads (a `write` body, a long command) would
+   * otherwise ride into the next request unbounded — precisely in a loop
+   * scenario; the cap bounds the reminder, never the detection (the chain key
+   * always compares the FULL canonical string).
+   */
+  argumentsPreviewChars?: number
+}
+```
+
+Source: [`packages/guard/repeat-tool-guard/src/index.ts:55`](../packages/guard/repeat-tool-guard/src/index.ts)
+
 ## `@deepseek-ai/dsh-session-persistence-jsonl`

 Requires: `sessions`
@@ -804,6 +836,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 Abstract service classes — a deployment loads a concrete implementation package instead ([capability seams](rfc/implemented/architecture/2026-06-13-capability-seams.md)).

 - `@deepseek-ai/dsh-bash` — abstract `BashExecutor` ([`packages/bash/bash/src/index.ts`](../packages/bash/bash/src/index.ts))
+- `@deepseek-ai/dsh-code-runtime` — abstract `CodeRuntime` ([`packages/code-runtime/code-runtime/src/index.ts`](../packages/code-runtime/code-runtime/src/index.ts))
 - `@deepseek-ai/dsh-compact` — abstract `CompactService` ([`packages/compact/compact/src/index.ts`](../packages/compact/compact/src/index.ts))
 - `@deepseek-ai/dsh-fs` — abstract `FileSystem` ([`packages/fs/fs/src/index.ts`](../packages/fs/fs/src/index.ts))
 - `@deepseek-ai/dsh-session-persistence` — abstract `SessionPersistence` ([`packages/session-persistence/session-persistence/src/index.ts`](../packages/session-persistence/session-persistence/src/index.ts))
@@ -812,6 +845,7 @@ Abstract service classes — a deployment loads a concrete implementation packag

 Imported as libraries by other packages; a `cordis.yml` cannot load them.

+- `@deepseek-ai/dsh-acp-snapshot` ([`packages/support/acp-snapshot/src/index.ts`](../packages/support/acp-snapshot/src/index.ts))
 - `@deepseek-ai/dsh-app-boot` ([`packages/ui/app-boot/src/index.ts`](../packages/ui/app-boot/src/index.ts))
 - `@deepseek-ai/dsh-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts))
 - `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts))
@@ -67,6 +67,25 @@ Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../c

 Source: [`packages/bash/bash/src/index.ts:59`](../../packages/bash/bash/src/index.ts)

+## `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
+
+Abstract code-execution service. Subclass, implement run and the two descriptors, and load the subclass as a plugin — it registers as `ctx.codeRuntime` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
+
+Semantics every implementation must honor:
+
+- run resolves with an error FIELD for every program outcome — parse/transform failures, thrown exceptions, budget expiry, abort, substrate death (CodeRunFailure's taxonomy). It REJECTS only for caller misuse of the seam itself (e.g. a run submitted after disposal).
+- Binding calls bridge to the caller's CodeBindingFunctions verbatim; arguments and resolutions must be structured-cloneable, and the runtime treats the program as a hostile peer (arbitrary binding names are own properties, malformed traffic is rejected or ignored, never crashes the host).
+- Runs are isolated from each other: no state survives from one run to the next through the runtime.
+- Disposal reaches quiescence: in-flight runs are terminated AND awaited before the service's own teardown completes (no orphan substrate survives `fiber.dispose()`).
+
+```ts cordis-catalog
+abstract run(request: CodeRunRequest): Promise<CodeRunResult>
+```
+
+Types: [CodeRunRequest](../core-data-structures/code-runtime.md) · [CodeRunResult](../core-data-structures/code-runtime.md)
+
+Source: [`packages/code-runtime/code-runtime/src/index.ts:59`](../../packages/code-runtime/code-runtime/src/index.ts)
+
 ## `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).
@@ -0,0 +1,94 @@
+# Code Runtime
+
+The code-execution seam — a [capability seam](../rfc/implemented/architecture/2026-06-13-capability-seams.md) whose interface ([dsh-code-runtime](../../packages/code-runtime/code-runtime), `ctx.codeRuntime`) runs one model-written program against host-provided async bindings and reports what it printed and returned. Code execution is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Backends differ by execution substrate and source language, both readonly descriptors on the service; the worker-thread backend and the tool-registry consumer (Code Mode) are specified in the [Code Mode RFC](../rfc/proposed/feature/2026-06-15-code-mode.md).
+
+Source: [`packages/code-runtime/code-runtime/src/types.ts`](../../packages/code-runtime/code-runtime/src/types.ts)
+
+## The run: request in, result out
+
+A `CodeRunRequest` carries **everything the runtime acts on** — per the "explicit > implicit at package seams" rule, defaulting (time budgets, output caps) is the implementation's validated config, never a hidden `??` inside `run()`:
+
+```ts type-equiv
+interface CodeRunRequest {
+  /**
+   * The program source, in the runtime's {@link ../index.ts | language}. It
+   * runs as the body of an async function: top-level `await` and `return`
+   * are available, and the completion value becomes
+   * {@link CodeRunResult.value}.
+   */
+  program: string
+  /** Host functions exposed to the program, one global object per namespace. */
+  bindings: CodeBindingNamespace[]
+  /**
+   * Abort the run: the runtime stops the program (hard, even mid-loop) and
+   * resolves with a {@link CodeRunFailure} of kind `'abort'`. In-flight
+   * binding calls are the CALLER's to settle — the runtime only stops asking.
+   */
+  signal?: AbortSignal
+}
+```
+
+The result reports an error as a **field**, never a rejection of `run()` — reporting a failed program is the caller's job, not an exception path (mirroring `BashExecutor.run`'s resolve-on-failure contract):
+
+```ts type-equiv
+interface CodeRunResult {
+  /**
+   * The program's completion value (its top-level `return`), when it ran to
+   * completion and the value survived the runtime's serialization boundary;
+   * a non-transferable value is replaced by a string rendering, and a failed
+   * or value-less run leaves this absent.
+   */
+  value?: unknown
+  /** Everything the program emitted, in order (capped by the implementation). */
+  logs: CodeLogEntry[]
+  /** Present iff the run failed; see {@link CodeRunFailure} for the taxonomy. */
+  error?: CodeRunFailure
+}
+```
+
+## Bindings: host functions as program globals
+
+Each `CodeBindingNamespace` becomes one global object of async callables inside the program (the Code Mode consumer passes one: `tools`). Arguments and resolutions must be structured-cloneable — a runtime may bridge calls across a serialization boundary — and a runtime treats binding names as hostile input (`__proto__` is an ordinary own property, never a prototype collision):
+
+```ts type-equiv
+interface CodeBindingNamespace {
+  /** The global identifier the program sees (must be a valid JS identifier). */
+  global: string
+  /** The callable members, keyed by the exact name the program calls. */
+  functions: Record<string, CodeBindingFunction>
+}
+```
+
+```ts type-equiv
+type CodeBindingFunction = (args: unknown) => Promise<unknown>
+```
+
+## Captured output and the failure taxonomy
+
+Logs arrive in emission order, attributed to their channel (the runtime's `console` shim, or stray writes to the underlying streams):
+
+```ts type-equiv
+interface CodeLogEntry {
+  /** Which channel produced the text. */
+  source: 'console' | 'stdout' | 'stderr'
+  /** The console method used; present only when `source` is `'console'`. */
+  level?: 'log' | 'info' | 'warn' | 'error' | 'debug'
+  /** The captured text (possibly truncated by the implementation's caps, marked in-band). */
+  text: string
+}
+```
+
+Failure kinds are **orthogonal outcomes reported independently** (per [defensive-patterns](../defensive-patterns.md)): a budget expiry is not an exception, an abort is not a timeout, and a substrate death (e.g. OOM) is neither:
+
+```ts type-equiv
+interface CodeRunFailure {
+  /** The failure class (see the interface doc for each kind's meaning). */
+  kind: 'exception' | 'timeout' | 'abort' | 'worker-exit'
+  /** Human-readable detail, suitable for feeding back to a model to self-correct. */
+  message: string
+}
+```
+
+## The service
+
+`CodeRuntime` (`ctx.codeRuntime`, abstract — defined in [`packages/code-runtime/code-runtime/src/index.ts`](../../packages/code-runtime/code-runtime/src/index.ts)) is `run(request)` plus two readonly descriptors: `language` (what the program must be written in — `'typescript'` is the well-known value; a consumer generating language-specific presentation switches on it and fails loud on one it cannot present) and `isolation` (the execution substrate — `'worker-thread'`, `'process'`, `'container'`; a diagnostic label, **not a security claim**). Implementations must keep runs isolated from each other (no cross-run state) and dispose to quiescence: in-flight runs are terminated and awaited before teardown completes.
@@ -21,6 +21,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, the `tools/pre-execute`/`tools/post-execute` pipeline |
 | [user-interaction.md](user-interaction.md) | the UI-backed human question/answer seam: `AskUserQuestionRequest`, answer/options vocabulary, provider API, error taxonomy |
 | [bash.md](bash.md) | the bash executor seam: `BashExecRequest`/`Spec`, `BashRunResult`, background `BashTask`s |
+| [code-runtime.md](code-runtime.md) | the code-execution seam: `CodeRunRequest`/`Result`, binding namespaces, captured logs, the `CodeRunFailure` taxonomy |
 | [filesystem.md](filesystem.md) | the filesystem seam: `FsTarget`, read/write/edit outcomes, observed-file state, `FsErrorCode` |
 | [compaction.md](compaction.md) | the compaction seam: the `compact/*` session events, `CompactionResult`, the `CompactService` interface |
 | [subagent.md](subagent.md) | the subagent seam: the named-provider registry, `SubagentStartRequest`/`Result`/`Run`, the start-time-vs-runtime capability split |
@@ -11,11 +11,11 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:271`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) |
 | `agent/error` | `emit` | [`packages/core/agent/src/types.ts:420`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
 | `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:349`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) |
-| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:362`](../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/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:362`](../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), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) |
 | `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
 | `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:385`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
 | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:304`](../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) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:280`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:280`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`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:395`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
 | `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:408`](../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) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:123`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
@@ -32,7 +32,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:38`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | - |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:44`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
 | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:97`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
-| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:92`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:92`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) |
 | `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:76`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |

 Maintenance mode: hybrid generated: Cordis event declarations and most producer/listener edges are AST-scanned; dynamic dispatch sites are classified in `scripts/gen-doc-graphs.ts`.
@@ -69,6 +69,7 @@ flowchart TD
    pkg_session_persistence_sqlite["session-persistence-sqlite"]
  end
  subgraph group_support["packages/support"]
+    pkg_acp_snapshot["acp-snapshot"]
    pkg_invariants["invariants"]
    pkg_llm_replay["llm-replay"]
    pkg_subagent_mock["subagent-mock"]
@@ -80,6 +81,12 @@ flowchart TD
    pkg_stdio_agent["stdio-agent"]
    pkg_tool_ask_user["tool-ask-user"]
  end
+  subgraph group_code_runtime["packages/code-runtime"]
+    pkg_code_runtime["code-runtime"]
+  end
+  subgraph group_guard["packages/guard"]
+    pkg_repeat_tool_guard["repeat-tool-guard"]
+  end
  pkg_llm --> pkg_brand
  pkg_bash --> pkg_brand
  pkg_llm_deepseek --> pkg_llm
@@ -164,6 +171,8 @@ flowchart TD
  pkg_tool_ask_user --> pkg_agent
  pkg_tool_ask_user --> pkg_tools
  pkg_tool_ask_user --> pkg_user_interaction
+  pkg_repeat_tool_guard --> pkg_agent
+  pkg_repeat_tool_guard --> pkg_tools
  pkg_agent_core --> pkg_agent
  pkg_agent_core --> pkg_agent_loop
  pkg_agent_core --> pkg_invariants
@@ -219,7 +228,9 @@ flowchart TD
 | Package | Group | Depends on |
 | --- | --- | --- |
 | [`brand`](../packages/util/brand) | `util` | — |
+| [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | — |
 | [`app-boot`](../packages/ui/app-boot) | `ui` | — |
+| [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | — |
 | [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand) |
 | [`bash`](../packages/bash/bash) | `bash` | [`brand`](../packages/util/brand) |
 | [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`llm`](../packages/llm/llm) |
@@ -255,6 +266,7 @@ flowchart TD
 | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools), [`user-interaction`](../packages/core/user-interaction) |
 | [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-interaction`](../packages/core/user-interaction) |
+| [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) |
 | [`agent-core`](../packages/core/agent-core) | `core` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/bash/tool-bash), [`tools`](../packages/core/tools) |
 | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) |
 | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
@@ -10,7 +10,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 |---|---|
 | [Agent Client Protocol (ACP) support — drive the coding agent from external editors](proposed/feature/2026-06-14-acp-agent-client-protocol.md) | 2026-06-14 |
 | [Multiplex concurrent ACP sessions over one connection](proposed/feature/2026-06-14-acp-multi-session.md) | 2026-06-14 |
-| [Optional Code Mode — model writes TypeScript against an SDK of all tools](proposed/feature/2026-06-15-optional-code-mode.md) | 2026-06-15 |
+| [Code Mode — the model writes TypeScript against the tool registry](proposed/feature/2026-06-15-code-mode.md) | 2026-06-15 |
 | [Pre-tool input rewrite — a consistent design](proposed/feature/2026-06-30-pre-tool-input-rewrite.md) | 2026-06-30 |
 | [Claude Code and Codex subagent backends (out-of-process delegation to external coding agents)](proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md) | 2026-07-07 |

@@ -63,6 +63,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [SessionStore fork API](implemented/feature/2026-06-30-session-store-fork-api.md) | 2026-06-30 |
 | [Subagent lifecycle enrichment — lastAssistantMessage (observe-only)](implemented/feature/2026-06-30-subagent-observe-enrich.md) | 2026-06-30 |
 | [Explicit model-facing tool order](implemented/feature/2026-07-06-explicit-tool-order.md) | 2026-07-06 |
+| [Repeat-tool-call guard plugin](implemented/feature/2026-07-08-repeat-tool-guard.md) | 2026-07-08 |

 ### Simplification

@@ -166,6 +167,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Hook snapshot matrix — end-to-end goldens for both bridges](implemented/testing/2026-07-04-hook-snapshot-matrix.md) | 2026-07-04 |
 | [Single-source the acp-agent replay config](implemented/testing/2026-07-04-single-source-acp-replay-config.md) | 2026-07-04 |
 | [Pin request-header content in one snapshot scenario](implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md) | 2026-07-06 |
+| [Extract the ACP snapshot suite into a support package](implemented/testing/2026-07-08-shared-acp-snapshot-package.md) | 2026-07-08 |

 ## Rejected

@@ -0,0 +1,73 @@
+# RFC: Repeat-tool-call guard plugin
+
+Status: implemented
+
+## Problem
+
+A model stuck in a loop re-issues the same tool call with byte-identical arguments — re-running a failing grep, re-reading an unchanged file, polling a command that already gave its answer — and each round trip burns tokens, wall-clock, and (for paid APIs) money without adding information. The harness has nothing that notices: the loop has no step budget, no plugin tracks call repetition, and the model only escapes when it happens to vary its own behavior. The failure mode is real and cheap to detect — [pi-repeat-tool-guard](https://github.com/Kingwl/pi-repeat-tool-guard) ships exactly this as a pi coding-agent extension: count consecutive identical calls and, past a threshold, append a `<system-reminder>` telling the model to stop repeating itself and change course.
+
+The harness already has every seam the pi extension uses, and better ones: [the interception-seams RFC](2026-06-30-interception-seams.md) gives `tools/post-execute` a sanctioned way to attach model-facing context to a finished call, the loop buffers and injects that context with call/result adjacency preserved, and injected context is a logged `context/message` — so a native guard satisfies the model-visible ⟺ logged rule with no new session event. What was missing was only the plugin itself.
+
+## Decision
+
+The guard is a loop-hygiene plugin, not a model-facing tool: it never appears in the tool list, never vetoes or rewrites a call, and adds exactly one behavior — it watches each agent's stream of tool calls, counts runs of consecutive calls to the same tool with identical canonicalized arguments, and at configured run lengths injects an escalating advisory reminder telling the model to stop repeating itself, re-read the last result, and either change approach or conclude. The purpose is to break unproductive loops within a few wasted steps instead of letting them run to the turn's natural end — while leaving the decision (retry differently, gather more evidence, or finish) entirely with the model, so a legitimately repeated call is delayed by nothing and blocked by nothing.
+
+The plugin is `@deepseek-ai/dsh-repeat-tool-guard` at `packages/guard/repeat-tool-guard/`, opening the `guard/` group for loop-hygiene plugins (single-package groups have precedent: [the todo-write RFC](2026-06-29-todo-write-tool.md) shipped `todo/tool-todo`). It registers three listeners and holds all state in plugin-local maps keyed by `AgentId` — the tool registry is a context-level singleton whose waterfalls interleave every agent's calls (subagents run on the same context), so per-agent keying is correctness, not polish.
+
+- **`tools/post-execute` (waterfall)** — the one detection point. The listener receives `(exec, result)` together, so counting and reminder delivery need no cross-event pending map (the pi extension needs one only because its `tool_call`/`tool_result` hooks are separate events). It always delegates via `next()` and, when a threshold is hit, folds a reminder onto the downstream decision's `additionalContext` — the observe-and-enrich posture [the hooks bridges](2026-06-30-hook-bridges.md) already use, honoring the waterfall contract. Counting happens here rather than in `tools/pre-execute` because post-execute also runs for denied calls (`ToolRegistry.execute` routes a deny through the same pipeline), and a model hammering a denied call is exactly the loop worth breaking.
+- **`agent/prompt-submit` (waterfall)** — pure reset hook: delegate via `next()`, clear the submitting agent's chain. A user interjection changes the context; repetition across it is not a loop.
+- **`agent/status` (emit)** — on `disposed`, drop the agent's state, bounding the maps over harness lifetime.
+
+### Detection semantics
+
+The chain key is `(tool name, canonical arguments)`; a call identical to the previous tracked call increments the agent's consecutive counter, a different tracked call resets it to 1. Canonicalization is a deep key-sort plus `JSON.stringify`: `ToolExecution.arguments` is by construction the loop's `JSON.parse` output (or the raw string fallback for malformed argument JSON, which is itself a comparable value), so the pi original's bigint/circular/`undefined` handling has no inputs here and is deliberately dropped.
+
+Two deliberate rules, both documented in [the package README](../../../../packages/guard/repeat-tool-guard/README.md) because they are behavior a reader would otherwise guess at:
+
+- **Untracked calls are transparent to the chain.** A call excluded by `include`/`exclude` neither increments nor resets the counter, so `grep X → todo_write → grep X` still counts as two consecutive `grep X` when `todo_write` is excluded. This is what makes exclusion useful — bookkeeping tools interleaved into a loop must not launder it — and it is the pi extension's (undocumented) semantics, kept on purpose and written down.
+- **Calls without an agent are ignored.** A direct `ctx.tools.execute()` caller (tests, non-loop consumers) has no model to remind and no `AgentId` to key on.
+
+### Reminder delivery
+
+Reminders ride `additionalContext` (source `{kind: 'plugin', plugin: 'repeat-tool-guard'}` — the label is load-bearing per `HookContext`), never a `content` replacement: the `tool/result` event stays the tool's own output for audit, and the loop appends buffered context as `context/message`(s) after the step's results, which the session renders as the tagged synthetic-user envelope and derived history replays. Thresholds escalate: the first configured threshold gets a short "you are repeating yourself, analyze the previous result" nudge; each later threshold gets the detailed form naming the tool, the repeat count, and the canonical arguments (head-truncated at `argumentsPreviewChars`, default 500 — a looping `write`-sized payload must not ride into the next request unbounded; the chain key always compares the full canonical string), and stating that the calls made no progress. The pi original hardcodes the gentle text to the literal count 3; the guard keys it to `thresholds[0]`, fixing that bug in the port. When the downstream decision already carries `additionalContext` (a hook bridge on the same call), the guard concatenates content under its own `source` — a `HookContext` holds one `MessageSource`, and `source.kind` is what framing depends on.
+
+### Config
+
+```yaml
+- id: repeat-tool-guard
+  name: '@deepseek-ai/dsh-repeat-tool-guard'
+  config:
+    thresholds: [3, 5, 8]        # default; consecutive counts that trigger a reminder
+    include: []                  # tool-name patterns to track; empty ⇒ all tools
+    exclude: [todo_write]        # tool-name patterns transparent to the chain
+    argumentsPreviewChars: 500   # default; cap on arguments quoted in the detailed reminder
+```
+
+`thresholds` is validated at load and throws on an empty list, a non-integer, a value below 2, or a duplicate — misconfiguration fails loud, replacing the pi original's silent fall-back to defaults. `include`/`exclude` entries support `*` wildcards. Patterns are predicates over whatever tools exist at call time, not references to a registry entry, so an entry matching no currently registered tool is NOT an error — unlike `toolOrder`'s referent check, `exclude: [mcp_*]` must stay valid in a deployment that loads no MCP tools.
+
+## Testing
+
+**Unit** — the suite drives a real agent loop against a scripted mock adapter (no network) and covers, at per-file 100%: counting/reset semantics (identical, different-tracked, untracked-transparent, prompt-submit reset, disposal cleanup, per-agent isolation), canonicalization (deep key-order insensitivity), threshold escalation including the `thresholds[0]` gentle-text rule, denied-call counting, no-agent transparency, wildcard escaping, config fail-loud cases, and both fold-onto-downstream paths (block and accept-with-replacement). **Snapshot** — the `repeat-tool-guard` scenario in the acp-agent example suite scripts five identical `todo_write` calls and pins both reminder tiers (gentle at the third, detailed at the fifth) as `context/message`s in the ACP transcript and the session log; the guard is loaded in the example's live tree (`cordis.yml`), inert for every other scenario (none repeats a call three times). The scenario is authored keyless (like `error-finish`/`cancel`): deterministically forcing a live model to repeat one call three times is not a stable recording. **e2e** — none: the plugin is provider-independent and deterministic, and the seam contracts it relies on are e2e-covered by their owners.
+
+## Alternatives considered
+
+- **Append the reminder into the tool result** (`accept` with replaced `content` — the pi extension's mechanism, which patches result content because that is the only channel its API offers) — rejected: it makes the logged `tool/result` lie about what the tool returned, and `additionalContext` exists precisely as the separate sanctioned channel for post-execute commentary, with loop-level buffering that preserves call/result adjacency.
+- **Count in `tools/pre-execute` with a pending-reminder map** (the pi two-phase shape) — rejected: post-execute alone sees `(exec, result)` together and also fires for denied calls, so one listener with no cross-event state covers strictly more attempts with less machinery.
+- **Escalate to `block` at the highest threshold** — rejected for the initial scope: a blocked call punishes legitimate identical repeats (polling a long-running terminal, re-checking a file the agent expects to change), and an advisory reminder keeps the model in control. Revisit with evidence; the decision shape (`PostToolDecision`) already supports it.
+- **A per-deployment external hook via the CC/Codex bridges** (a `PostToolUse` script) — rejected as the answer: it works for one deployment, but a shipped, unit-tested, `cordis.yml`-configurable plugin is the harness-native form, without per-call subprocess cost.
+- **A loop-level step or repetition budget in `agent-loop`** — rejected: "plugins, not loop changes"; a hard step budget is a blunter, orthogonal control that would need its own proposal.
+- **Fuzzy/near-identical detection** (normalized paths, similar-but-not-equal arguments) — rejected: exact match after canonicalization is cheap, deterministic, and explainable to the model; similarity thresholds invite false positives and need evidence before they earn complexity.
+- **Placing the package in `core/`** — rejected: core is the product spine; a behavioral guard is an optional leaf plugin, and the `todo/` precedent is a small dedicated group per plugin family.
+
+## Consequences
+
+- The reminder is advisory by design: idempotent polling patterns that repeat identical calls on purpose still receive nudges past the thresholds, and the pressure valves are config (`thresholds`, `exclude`) plus reminder text that explicitly allows finishing when enough evidence has been gathered. Each trigger costs reminder tokens on the next request; thresholds bound the frequency.
+- Chain state is in-memory only: a session resumed from persistence starts with a fresh chain, so a loop spanning a resume draws its reminders later than a live one — accepted, the guard is a heuristic nudge, not a logged invariant, and persisting counter state would buy little for real complexity.
+- When multiple post-execute producers attach context on one call, the fold concatenates under the guard's `source`; ordering between plugins follows listener registration order. The seam cannot represent mixed provenance — a limit inherited from `HookContext`, not owned by this plugin.
+- Implementing the snapshot tier surfaced a hidden assumption in the suite kit: the fixture guard equated "authored model scenario" with "override-driven". The `Scenario` table now carries an explicit `overridden` flag, and the sidecar's presence is checked BOTH ways against it (an unregistered stray sidecar would silently replace the derived script) — the suite kit is stricter than it was before this plugin existed.
+
+## Deferred
+
+- Compaction does not reset chains: a compacted history changes what the model sees, but the repetition risk usually survives compaction.
+- Escalating to `block` at a high threshold is not implemented; `PostToolDecision` already supports it if evidence arrives.
+- Subagent chains stay isolated per agent; no sharing mechanism exists until a concrete case appears.
@@ -68,7 +68,7 @@ The replay plugin lives in its own package, `@deepseek-ai/dsh-llm-replay` (`pack

 ### Two subcommands, replay in the default gate

-`pnpm run test:snapshot` runs replay (keyless) and is composed into the default `pnpm run test` gate so every PR gets the regression check (the main `vitest.config.ts` include stays narrow; the gate is `test && test:snapshot`). `pnpm run test:snapshot:record` requires `DEEPSEEK_API_KEY` (loaded from repo `.env` first), hits the real API, harvests the produced `session.jsonl` (the replay source AND the expected-log artifact), and `--update`s the stdout golden in one pass. Both forward a scenario filter. A missing fixture in replay **fails loud** with a "record first" message rather than self-skipping (the e2e self-skip rule is a CI-secret accommodation, not appropriate here — a committed-fixture test that silently vanishes is a coverage hole). A no-model scenario's `session.jsonl` simply has no `assistant/chunk` events (empty derived script); fail-loud still applies if a model call happens with no entry. An orphan-fixture guard test fails on a golden/fixture not referenced by any scenario (Vitest does not prune orphaned raw goldens), and a per-kind required-fixture guard asserts each scenario ships exactly the files its kind needs (`input.json` + `stdout.golden.jsonl` + `session.jsonl` for ALL scenarios — the harness passes `<dir>/session.jsonl` to `llm-replay` unconditionally, so even a no-model scenario needs its header-only fixture or `loadReplayScript()` fails; `replay.override.json` additionally for authored model scenarios).
+`pnpm run test:snapshot` runs replay (keyless) and is composed into the default `pnpm run test` gate so every PR gets the regression check (the main `vitest.config.ts` include stays narrow; the gate is `test && test:snapshot`). `pnpm run test:snapshot:record` requires `DEEPSEEK_API_KEY` (loaded from repo `.env` first), hits the real API, harvests the produced `session.jsonl` (the replay source AND the expected-log artifact), and `--update`s the stdout golden in one pass. Both forward a scenario filter. A missing fixture in replay **fails loud** with a "record first" message rather than self-skipping (the e2e self-skip rule is a CI-secret accommodation, not appropriate here — a committed-fixture test that silently vanishes is a coverage hole). A no-model scenario's `session.jsonl` simply has no `assistant/chunk` events (empty derived script); fail-loud still applies if a model call happens with no entry. An orphan-fixture guard test fails on a golden/fixture not referenced by any scenario (Vitest does not prune orphaned raw goldens), and a per-kind required-fixture guard asserts each scenario ships exactly the files its kind needs (`input.json` + `stdout.golden.jsonl` + `session.jsonl` for ALL scenarios — the harness passes `<dir>/session.jsonl` to `llm-replay` unconditionally, so even a no-model scenario needs its header-only fixture or `loadReplayScript()` fails; `replay.override.json` exactly for the scenarios whose table entry sets `overridden` — required with the flag, forbidden without it, because the harness forwards the sidecar purely on file existence and an unregistered stray would silently replace the derived script).

 ## Alternatives considered

@@ -32,4 +32,4 @@ Reviewers lose one artifact name that made the expected persisted log visually s

 ## Implementation note

-The comparison normalizes BOTH sides, but each against its OWN volatile values, not a shared context. A raw harvested `session.jsonl` bakes in the recording run's session id, cwd, and timestamps; the replay run produces fresh ones. `normalizeSessionLog` scrubs cwd by exact string match, so normalizing the fixture against the *replay* run's cwd would leave the recorded cwd in the header unscrubbed and the compare would fail. The harness therefore derives the fixture's normalize context from its OWN header line (`{ type:'session', id, cwd }`) — `fixtureContext()` in `acp.snapshot.ts` — so both sides scrub to the same `{{sessionId}}`/`{{cwd}}` tokens. An authored fixture copied from the old golden already carries the normalized header (`id:'{{sessionId}}'`, `cwd:'{{cwd}}'`), which yields those tokens as the volatile values and scrubs idempotently. The session-log side uses a plain normalized-string `toEqual`, NOT `toMatchFileSnapshot`, so a run never overwrites the fixture.
+The comparison normalizes BOTH sides, but each against its OWN volatile values, not a shared context. A raw harvested `session.jsonl` bakes in the recording run's session id, cwd, and timestamps; the replay run produces fresh ones. `normalizeSessionLog` scrubs cwd by exact string match, so normalizing the fixture against the *replay* run's cwd would leave the recorded cwd in the header unscrubbed and the compare would fail. The harness therefore derives the fixture's normalize context from its OWN header line (`{ type:'session', id, cwd }`) — `fixtureContext()` in `dsh-acp-snapshot`'s suite module — so both sides scrub to the same `{{sessionId}}`/`{{cwd}}` tokens. An authored fixture copied from the old golden already carries the normalized header (`id:'{{sessionId}}'`, `cwd:'{{cwd}}'`), which yields those tokens as the volatile values and scrubs idempotently. The session-log side uses a plain normalized-string `toEqual`, NOT `toMatchFileSnapshot`, so a run never overwrites the fixture.
@@ -8,7 +8,7 @@ Every model-driving ACP snapshot fixture (`session.jsonl`) embedded the full com

 ## Decision

-Exactly one scenario — `text-turn`, flagged `pinsHeader` in `acp.snapshot.ts` — commits and compares the full request-header content. Every other fixture stores and compares that content as stable tokens via the pure normalizer `scrubRequestHeaders` in `snapshot-normalize.ts`: a `request/header` event's `header.system` becomes `"{{system}}"` and `header.tools` becomes `"{{tools}}"`; a `request/header-delta` keeps its structural facts — the system delta's `keepStart`/`keepEnd` line positions with one `{{system}}` token per inserted line, the tools delta's added/removed/changed tool names — and tokenizes only the bulk (prompt text, schema bodies), so two different deltas still compare different. The scrub is composed in front of `normalizeSessionLog` on BOTH sides of a non-pinning scenario's log compare and applied to the harvested logs record mode writes, so a re-record cannot smuggle the content back. Absent fields stay absent — WHETHER a header carried a prompt or tools is behavior and stays visible — and `config`/`reason` stay verbatim: a model swap churns every fixture by design (it invalidates the recorded responses), while a prompt or schema edit churns none of them (replay derives model behavior exclusively from `assistant/chunk` events and never reads header content — see `dsh-llm-replay`).
+Exactly one scenario — `text-turn`, flagged `pinsHeader` in the `acp.snapshot.ts` scenario table — commits and compares the full request-header content; the pin mechanics live in [`dsh-acp-snapshot`](../../../../packages/support/acp-snapshot/README.md), whose suite factory enforces one pin per consuming suite. Every other fixture stores and compares that content as stable tokens via the pure normalizer `scrubRequestHeaders` in that package's `normalize.ts`: a `request/header` event's `header.system` becomes `"{{system}}"` and `header.tools` becomes `"{{tools}}"`; a `request/header-delta` keeps its structural facts — the system delta's `keepStart`/`keepEnd` line positions with one `{{system}}` token per inserted line, the tools delta's added/removed/changed tool names — and tokenizes only the bulk (prompt text, schema bodies), so two different deltas still compare different. The scrub is composed in front of `normalizeSessionLog` on BOTH sides of a non-pinning scenario's log compare and applied to the harvested logs record mode writes, so a re-record cannot smuggle the content back. Absent fields stay absent — WHETHER a header carried a prompt or tools is behavior and stays visible — and `config`/`reason` stay verbatim: a model swap churns every fixture by design (it invalidates the recorded responses), while a prompt or schema edit churns none of them (replay derives model behavior exclusively from `assistant/chunk` events and never reads header content — see `dsh-llm-replay`).

 A system-prompt or tool-schema change therefore lands as exactly one committed-fixture diff — the pinned `text-turn` header line — updated by hand or by re-recording that one scenario (`pnpm run test:snapshot:record` with `-t text-turn`).

@@ -0,0 +1,36 @@
+# RFC: Extract the ACP snapshot suite into a support package
+
+Status: implemented
+
+## Problem
+
+The ACP snapshot tier ([snapshot RFC](2026-06-19-acp-snapshot-tests.md)) was built from three modules living inside one example's test directory: `snapshot-harness.ts` (boot the real bin subprocess, drive it over ACP JSON-RPC, harvest the persisted logs), `snapshot-normalize.ts` (the pure golden normalizers), and the ~150-line scenario body plus fixture guards in `acp.snapshot.ts` (record/replay modes, the stdout-golden and log compares, the pinned-header uniformity guard, the orphan/required-file/single-pin meta-tests).
+
+A second ACP example wanting snapshot coverage — the sandbox/approval composition is the immediate consumer — could only copy those modules, forking exactly the logic that must not drift: record write-back, header scrubbing, child-session harvest ordering. The spawn/client glue was already triplicated across `acp.e2e.ts`, `hooks.e2e.ts`, and the harness (`TODO(acp-test-harness)`). Location also decided test rigor: the per-file 100% coverage gate measures `packages/*/*/src` only, so none of this machinery was measured — the same gap that had moved `dsh-llm-replay` out of `examples/` into [packages/support](../../../../packages/support/README.md). And the harness's ACP client hardcoded `requestPermission → cancelled`, so an approval round-trip — the headline behavior of the sandbox composition — could not be expressed at the snapshot tier at all.
+
+## Decision
+
+The machinery lives in [`packages/support/acp-snapshot`](../../../../packages/support/acp-snapshot/README.md) (`@deepseek-ai/dsh-acp-snapshot`); an example's `*.snapshot.ts` is its scenario table, its agent paths, and one factory call, over its own `snapshots/` fixtures and `cordis.snapshot.yml` overlay ([single-source replay config](2026-07-04-single-source-acp-replay-config.md)). Reading `DSH_SNAPSHOT` stays at that edge — the library takes a resolved `mode`.
+
+**`src/harness.ts`** — `runScenario` and the input-script/result types, parameterized by an `AgentUnderTest` (`binScript`, `configPath`, `tsconfigPath`; absolute paths the consuming suite resolves from its own `import.meta.url`). The client's `session/request_permission` handler consumes an optional `InputScript.permissionAnswers` FIFO queue, each entry selecting by option **kind** (ids are agent-issued randoms a committed script cannot know; kinds are the ACP-stable vocabulary, mapped to the offered `optionId` at answer time); an absent or exhausted queue answers `cancelled`, and a kind the request never offered rejects the run — the agent itself is answered `cancelled`, so the scenario bug fails the harness rather than being absorbed as an agent-side denial. This is what lets an approval suite drive allow/reject round-trips deterministically from `input.json`.
+
+**`src/normalize.ts`** — the pure normalizers, hook-free by policy: when a future event carries a new volatile field (an approval duration, say), the shared normalizer learns it in the same change, keeping one home for what "normalized" means rather than per-suite scrub extensions.
+
+**`src/suite.ts`** — the `Scenario` type and `defineAcpSnapshotSuite(options)`, registering the per-scenario compares, record-mode fixture write-back, the header pin with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin, non-pinning fixtures are `scrubRequestHeaders` fixed points). The pinned-header contract ([pinned-header RFC](2026-07-06-pin-request-header-content-in-one-scenario.md)) is per-suite: each suite flags exactly one `pinsHeader` scenario (the factory throws on zero, a meta-test rejects more than one; WHICH scenario pins is the table's reviewable choice), and the uniformity guard compares only that suite's sessions. The pure helpers (`childFixturePaths`, `fixtureContext`, `normalizedHeaders`, `headerDeltaCount`) are exported for direct unit coverage.
+
+## Alternatives considered
+
+- **Copy the modules into each example** — the fork this RFC exists to prevent: the record/guard logic is exactly the code that must stay byte-identical across suites, and examples are outside the coverage gate, so each copy is also unmeasured.
+- **A shared module directory under `examples/`** — keeps the code outside the coverage gate and forces relative imports across example boundaries, against the package-name import convention; `examples/` leaves stay thin by design.
+- **A `/testing` subpath export of `dsh-acp-agent`** — couples test infrastructure into a product package's surface and dependency set; `packages/support/` exists precisely for real-but-lower-compatibility dev/test packages, with `dsh-llm-replay` as the precedent this package completes.
+- **Export raw test-body functions instead of a suite factory** — each example would re-own the `describe`/`it` skeleton (~80 lines of registration boilerplate per suite) for no flexibility gain; the factory keeps consumers to a scenario table plus one call, and the exported pure helpers preserve unit-testability inside the factory design.
+- **An injectable ACP `Client` factory instead of declarative `permissionAnswers`** — maximally flexible, but it leaks SDK client construction to every consumer and reopens per-example drift in exactly the layer being unified; a declarative queue keeps `input.json` the single scripting surface and stays golden-normalizable.
+- **Generalize beyond ACP (a transport-agnostic snapshot harness)** — no second transport exists; the harness is ACP-shaped end to end (SDK client, JSON-RPC frames, `session/update` waiters), and a speculative abstraction would be a seam split ahead of any consumer.
+
+## Testing
+
+Extraction parity was proven mechanically: after the move, `pnpm run test:snapshot` matched the base commit's result with zero byte changes under `examples/acp-agent/tests/snapshots/`. The package's `src/` holds per-file 100% statements/branches/functions/lines under the gating unit run, driven through the REAL spawn path by a scripted fake ACP bin (`tests/fixtures/fake-acp-agent.ts`, behavior scripted per scenario via a `behavior.json` beside the fixture): `harness.spec.ts` covers every step op, both expect-error arms, the permission queue (selection, fallback, impossible-click), env forwarding, workspace seeding, and the harvest ordering/noise/fallback branches; `suite.spec.ts` runs the factory for real at collection time — a replay suite over committed synthetic fixtures and a record suite over a temp copy (write-back never touches the committed tree; `ACP_SNAPSHOT_SPEC_BOOTSTRAP=1` re-bootstraps it) — plus direct cases for the pure helpers. Two structurally unreachable guards carry reasoned `v8 ignore` comments. The fake bin substitutes the `session/new` cwd, not `process.cwd()`, into scripted logs, matching what the real bin's header carries (darwin realpaths `/var/folders/…` to `/private/var/folders/…`).
+
+## Consequences
+
+A new example gets the whole snapshot tier from a scenario table plus fixtures — the sandbox branch merges master down and adds its own suite (own pin scenario, own overlay, fixtures via `test:snapshot:record`, approvals via `permissionAnswers`). The costs: `suite.ts` imports vitest, so the package is importable only inside a vitest run — a shape no other package has, stated in its README; each suite pins its own ~8 KB header fixture (a genuinely distinct composition deserves its own pin; an identical one would be caught by that suite's uniformity guard); and the e2e launcher duplication remains (`TODO(acp-test-harness)`) — the harness is the extraction target when that migration lands.
@@ -0,0 +1,139 @@
+# RFC: Code Mode — the model writes TypeScript against the tool registry
+
+Status: proposed
+
+## Problem
+
+Today the agent loop advertises every registered tool to the model as a native JSON-schema function definition. `ToolRegistry` contributes its schemas to the system-prompt assembly, the assembly's `tools` land on the wire (and in the logged request header), the model invokes one `tool-call` block per step, and the loop dispatches each call through `ctx.tools.execute()` **sequentially** (parallel tool execution is an explicit open TODO in `dsh-tools` and [docs/architecture.md](../../../architecture.md)), with **every** intermediate `tool-result` re-entering the model's context on the next request.
+
+For multi-step tool work this is token-heavy and serial. The model cannot compose tools — loop over a result set, branch on an intermediate value, fan out, post-process — without a full model round-trip per call, and each round-trip drags the entire intermediate result back into context whether the model needs it or not.
+
+Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) proposes an alternative grounded in a simple observation: LLMs are better at writing code than at emitting tool calls, because they have seen millions of lines of real code and comparatively few contrived tool-calling traces. Instead of one tool call per step, the model writes a TypeScript program against a generated API over the tools, the program executes in a sandboxed runtime, and the model curates what comes back — only what it prints or returns — instead of every intermediate result.
+
+An earlier draft of this RFC designed Code Mode as an add-on consumer plugin with zero core changes, deferring the execution substrate to a follow-up. Both constraints are dropped here, deliberately. First, the harness is pre-release and optimizes for the correct foundation over blast radius: tool presentation is the registry's own concern, and bolting a second presentation onto it from outside means transforming the registry's contribution after the fact — a waterfall listener whose correctness depends on listener ordering, which fights the [reconstructable-requests](../../implemented/architecture/2026-07-05-reconstructable-requests.md) design instead of riding it (that refactor removed request mutation from `agent/request`, the seam the old draft relied on). Second, the substrate question is answerable now: a Node `worker_threads` runtime gives real containment — separate isolate, empty environment, heap caps, and a `terminate()` that reliably stops a hot synchronous loop — where the old draft's `node:vm` stub had none of those, and it fits the harness's existing trust model (§Trust posture) without a hardening follow-up.
+
+## Proposal
+
+Three decisions, each elaborated in its own section below:
+
+1. **Code Mode is a first-class presentation mode of `ToolRegistry`** (`dsh-tools`), selected by a validated `mode` config: `'native'` (today's behavior, the default), `'code'` (the wire carries exactly one tool, `run_code`, plus a generated SDK `.d.ts` in the system prompt), or `'both'` (native schemas *and* `run_code` + SDK). The registry's existing tool-schema provider contributes whatever the mode dictates, so the wire tool list is shaped at its source — no interception, no listener-ordering caveats — and the logged request header records it for free.
+2. **Code execution is a capability seam** — a new group `packages/code-runtime/` with the interface package `@deepseek-ai/dsh-code-runtime` owning `ctx.codeRuntime` ([capability seams](../../implemented/architecture/2026-06-13-capability-seams.md); consumer = `dsh-tools`, with core-consumes-a-seam precedent in `agent-loop` → `dsh-llm`). The runtime knows nothing about tools: it is handed a program and named async bindings, runs the program, and reports `{ value, logs, error? }`. Language and substrate are backend properties, so a future Python or container backend is a new implementation package, not a redesign.
+3. **The shipped implementation is `@deepseek-ai/dsh-code-runtime-worker`**: one fresh Node worker thread per run, executing the model's TypeScript after type-strip, with bindings bridged over the message port, an empty environment, configurable heap/output/time caps, and hard termination. Its trust posture is bash-equivalent by design — no unsafe-acknowledgement flags — because the harness already ships `dsh-bash-local`, which executes arbitrary model-written shell commands with strictly *more* ambient authority.
+
+### The registry owns the mode
+
+`ToolRegistry` gains a schemastery-validated config (`static Config`), its first: `mode: 'native' | 'code' | 'both'`, default `'native'`. A deployment flips it from `cordis.yml` (`tools: { mode: code }`) — no code edit, per the no-hardcoded-tunables convention.
+
+**Wire tool list = the registry's contribution.** The registry already feeds the assembly through `ctx.systemPrompt.tools(() => this.schemas())`; the provider becomes mode-aware: `'native'` contributes all schemas (unchanged), `'code'` contributes only `run_code`'s schema, `'both'` contributes all schemas plus `run_code`. Because [`PromptAssembly.tools` is the single source the loop's request header snapshots](../../../../packages/core/system-prompt/src/index.ts), the collapse is automatically logged and reconstructable — model-visible ⟺ logged holds with zero new mechanism. Scope of the guarantee, stated honestly: the mode governs the **registry's** contribution, and the registry is the only shipped schema source — but `systemPrompt.tools()` is a public multi-provider API and the `system-prompt/assemble` waterfall may transform the assembly, so a deployment that wires a second direct provider (or a mutating listener) owns what it adds, exactly as in native mode. Those are deliberate acts; what the design eliminates is the *accidental* leak the old draft worried about — a listener-ordering race around an after-the-fact collapse — and the shipped-configuration invariant (`'code'` ⇒ assembled tools exactly `[run_code]`) is pinned by tests and, like every request, by the logged header.
+
+**Interaction with `toolOrder`, stated up front:** a configured `systemPrompt.toolOrder` naming native tools rejects every assembly under `mode: 'code'` (those names are no longer contributed), by the existing fail-loud rule for unlisted names. This is correct behavior, not a bug: a deployment switching modes updates its order config or drops it.
+
+**The SDK prompt section.** Under `'code'` and `'both'` the registry registers one lazy prompt section (`tools:sdk`, in the 100–199 tool-guidance order band) whose thunk regenerates, at each assembly, a TypeScript declaration of every registered tool except `run_code` itself, plus fixed usage instructions. The thunk reads the live store and emits tools in lexicographic name order, so its output is deterministic and stable across steps — an unchanged tool set produces byte-identical text (prefix-cache-friendly; a mid-session registration surfaces as one logged header delta, exactly like a native-mode tool change).
+
+**Codegen.** A pure `jsonSchemaToTs(schema)` module inside `dsh-tools` (sibling of `json-schema.ts` — `schemas()` and the SDK are two projections of the same store) maps the JSON-Schema subset the `defineTool` DSL emits (object/string/number/boolean/array, `properties`, `required`, string `enum` → literal union, nested objects, array `items`, `description` → JSDoc) to a TS type literal. It is **total**: any construct outside that subset (`$ref`, `oneOf`/`anyOf`, `integer`, future MCP shapes, …) degrades to `unknown` without throwing. Because `ToolSchema.name` is an arbitrary string, the SDK is declared as one object constant — `declare const tools: { "some-mcp-tool"(args: …): Promise<string>; bash(args: …): Promise<string>; … }` — quoted keys make every name reachable with no sanitization or alias-collision logic. Typing is advisory (the runtime executes type-stripped JS); the instructions say so.
+
+### The run_code tool and the dispatch bridge
+
+Under `'code'` and `'both'` the registry registers `run_code` in itself as an ordinary tool — one required parameter `{ code: string }` — so the unchanged loop dispatches it through the normal pipeline and `tools/pre-execute` / `tools/post-execute` gate it like any other call (a permission plugin can inspect the program text before it runs). Its `execute(args, exec)`:
+
+1. **Builds the bindings**: the bridge owns a **run-scoped `AbortController`** whose signal follows `exec.signal` (an outer cancel propagates in) and which the bridge itself fires the moment the run settles for any reason — completion, program exception, `computeMs`/`maxWallMs` expiry, worker exit. For every registered tool except `run_code`, the binding is an async function that (a) checks the run signal before and after (throwing stops the program — necessary because `ctx.tools.execute()` converts errors to `isError` data), (b) **JSON-normalizes the argument** — a `JSON.parse(JSON.stringify(args))` round-trip, rejecting that one call with a descriptive `Error` when the value does not survive (`BigInt`, circular structures) — because the seam's structured-clone boundary is wider than JSON while the session log accepts only JSON: normalizing BEFORE dispatch makes the dispatched form and the logged form the same JSON value by construction, so an executed sub-call can never fail at logging time, (c) awaits its turn on the **per-run serialization queue** (below), (d) calls `this.execute({ callId, name, arguments, agent: exec.agent, signal: runSignal })` with a deterministic sub-id `` CallId(`${exec.callId}:code:${n}`) `` — the run signal, not the bare outer one, so a budget expiry aborts an in-flight sub-tool (`bash-local` kills on its spec signal) instead of orphaning it, (e) appends a `tool/code-dispatch` session event, and (f) maps the result: success → the text-block contents joined as a `string` (non-text blocks become placeholders, an MVP limitation), `isError` → **the binding rejects** with an `Error` carrying the result text. Rejection is the deliberate model-facing contract — real code signals failure by throwing, `try/catch` and `Promise.all` short-circuiting behave as every model has seen them behave — where the old draft's `{ output, isError }` envelope made error handling a bespoke convention.
+2. **Runs the program**: `ctx.codeRuntime.run({ program: args.code, bindings: [{ global: 'tools', functions }], signal: exec.signal })`.
+3. **Surfaces the outcome — after reaching quiescence.** When `ctx.codeRuntime.run()` resolves, the bridge fires the run-scoped abort (cancelling any in-flight sub-dispatch and abandoning queued-unstarted ones), then **awaits the dispatch queue's drain before returning**, per the dispose-to-quiescence rule in [defensive patterns](../../../defensive-patterns.md): an aborted in-flight sub-call still settles and logs its `isError` `tool/code-dispatch` event *inside* the open turn, and nothing can append after `run_code` returns. A successful run then returns one text block — the captured console/stdout output followed by the rendered return value (if any) — plus a `meta` payload (capped logs, dispatch count) for presentation. A run with `result.error` throws a `CodeRunFailedError extends HarnessError` (`code: 'CODE_RUN_FAILED'`, message = the error kind and text plus captured logs so the model can self-correct); the registry's existing catch turns it into a structured `isError` result.
+
+**Sub-call `additionalContext` is suppressed, deliberately.** A `tools/post-execute` hook may attach `additionalContext` to a call; for loop-dispatched calls the loop buffers those and appends each as a `context/message` only after the step's `tool/result`s, preserving call/result adjacency. A sub-dispatch result's `additionalContext` has no such safe outlet from inside a running `run_code`: injecting immediately would land a `context/message` between the parent's `tool/call` and its `tool/result` (breaking the adjacency the buffering exists to protect), and `PostToolDecision.additionalContext` is singular where a program may produce many. The MVP therefore drops sub-call `additionalContext`, pinned by a test and stated in the hooks bridge's docs; the follow-up (a plural context channel or loop-level sub-dispatch buffering) is deferred until a real hook needs it through Code Mode.
+
+**Concurrency: serialized, enforced by the binding.** The bindings are async, so a model writing `Promise.all([tools.a(…), tools.b(…)])` starts both immediately — concurrent dispatch would be the *default*, while the tool contract still carries no concurrency-safety metadata (the open parallel-execution TODO). Each `run_code` invocation therefore owns a dispatch queue and every binding call chains onto it, so even `Promise.all` executes the underlying `ctx.tools.execute()` calls one at a time in submission order; when the run settles, queued-but-unstarted dispatches are abandoned. Lifting this per-tool once tools can declare themselves concurrency-safe is deferred work, same as before.
+
+**Presentation.** `run_code`'s render intent is decided here per the [render-intent RFC](../../implemented/architecture/2026-07-02-tool-render-intent-union.md): `presentCall` → a `generic` card, `kind: 'execute'`, title `Run code`, `rawInput` = the program text; `presentResult` → a `generic` card whose content is the captured output (from `meta`). Not a `terminal` card: that card's semantics are "a shell command in a working directory", which a program is not.
+
+### Observability: `tool/code-dispatch`
+
+Each sub-dispatch appends one session event, declared by `dsh-tools` via `SessionEventMap` declaration merging (the map is merge-extensible for exactly this; `todo/write` is the log-only precedent): `tool/code-dispatch` with `{ parentCallId, subCallId, name, arguments, isError, resultSummary }` — `arguments` being the bridge's JSON-normalized value, the very one dispatched, so the append cannot fail on payload shape. It is log-only — `deriveEventMessage()` ignores unknown event types by design, so sub-calls never re-enter model context — but persistence and UIs get every call. As a log event it carries JSDoc prose but **no `@mode` tag** (that vocabulary belongs to cordis bus events; the persistence-catalog generator hard-errors on one) and lands in the regenerated `docs/persistence-catalog.md`; appends happen inside `run_code`'s execution, so the turn-enclosure invariant is satisfied by construction. A `run_code` execution arriving without `exec.agent` (the loop always supplies it; direct programmatic calls may not) still runs and simply skips event logging, exactly as the `ToolExecution` contract allows.
+
+### The code-runtime seam
+
+`packages/code-runtime/code-runtime/` — `@deepseek-ai/dsh-code-runtime`, depending only on `cordis`. An abstract `CodeRuntime extends Service` (`super(ctx, 'codeRuntime')`) plus the vocabulary:
+
+- `CodeRunRequest = { program: string; bindings: CodeBindingNamespace[]; signal?: AbortSignal }`
+- `CodeBindingNamespace = { global: string; functions: Record<string, (args: unknown) => Promise<unknown>> }` — the runtime exposes each namespace as a global object of async functions inside the program; binding arguments and resolutions must be structured-cloneable (a runtime may cross a serialization boundary; ours does).
+- `CodeRunResult = { value?: unknown; logs: CodeLogEntry[]; error?: CodeRunFailure }` — an error is a field on a resolved result, never a rejection of `run()`.
+- `CodeLogEntry = { source: 'console' | 'stdout' | 'stderr'; level?: 'log' | 'info' | 'warn' | 'error' | 'debug'; text: string }`
+- `CodeRunFailure = { kind: 'exception' | 'timeout' | 'abort' | 'worker-exit'; message: string }` — orthogonal outcomes reported independently per [defensive patterns](../../../defensive-patterns.md); a timed-out run is not an exception, an abort is not a timeout.
+- Two readonly backend descriptors, informational not gating: `language` (what the program must be written in — `'typescript'` for the shipped backend; a Python backend would say so, and pair with its own SDK generator on the presentation side) and `isolation` (`'worker-thread'` for the shipped backend; `'process'`, `'container'`, … for future ones). `dsh-tools` requires `language === 'typescript'` in the MVP — its codegen emits TS — and fails the assembly loudly otherwise, the same misconfiguration idiom as `toolOrder` violations (as when `mode` is non-native with no `ctx.codeRuntime` loaded at all).
+
+Per explicit-over-implicit at seams, the request spells out everything the runtime acts on; defaulting (timeouts, caps) is the implementation's validated config, never a hidden `??` inside `run()`. Consumption uses the loop's established optional-backend idiom: cordis has no optional injection — every `inject` entry gates activation — so a static `inject` on the registry would hold `ctx.tools` (and every tool plugin behind it) hostage to a code runtime existing even under `mode: 'native'`; instead the registry reads `ctx.get('codeRuntime')` at use time, exactly as `agent-loop` consumes `sessionPersistence`, with absence failing loud in the provider thunk as above. The seam split is justified by real planned divergence on both axes — substrate (worker now; container/microVM later) and language (the Python/AssemblyScript direction sketched in the earlier draft survives as future work) — not by speculation: `dsh-tools` consumes the interface today and tests against a trivial in-repo fake, exactly the interface/implementation/consumer shape of the bash template.
+
+### The worker-thread runtime
+
+`@deepseek-ai/dsh-code-runtime-worker`, the second package of the `packages/code-runtime/` group. Per `run()`:
+
+1. **Type-strip host-side** with Node's built-in `stripTypeScriptTypes` (`node:module`; present across the repo's whole engines range, `^22.19.0 || >=24.0.0`, and position-preserving, so runtime error line numbers match the model's source). Strip-only mode rejects non-erasable syntax (`enum`, namespaces) — that rejection returns as `error.kind: 'exception'` with Node's message, the SDK instructions say "erasable TypeScript only", and the model self-corrects like any other program error. A syntax-level failure never spawns a worker.
+2. **Spawn one fresh `Worker` per run** from the package's own bootstrap module: `env: {}` (truly empty — stronger than the scrubbed-env rule for spawned commands), `resourceLimits` from config, `stdout`/`stderr` captured into `logs` rather than inherited. No pooling and no cross-run state: a program's world dies with its worker, which keeps runs reconstructable from the log alone and makes state bleed unrepresentable.
+3. **Execute** in the bootstrap: the stripped program becomes the body of an `AsyncFunction` whose parameters are the binding globals and a capturing `console` shim, so top-level `await` and `return` work and the program's completion value is the run's `value` (structured-cloneable values cross as-is; anything else is replaced by its `util.inspect` rendering, documented).
+4. **Bridge bindings over the message port**: each binding function in the worker posts `{ id, global, name, args }` and awaits the reply; the host validates the name against the request's bindings, invokes, and replies `{ id, ok, value }` or `{ id, ok: false, message }` (a host-side binding rejection becomes a program-side rejection). The worker-side namespace objects are built null-prototype via `defineProperty`, so a binding named `__proto__`, `constructor`, or `toString` is an ordinary own property, not a prototype collision. Unknown names, duplicate ids, and post-settlement messages are rejected or ignored — the port protocol assumes a hostile peer, because the peer runs model code.
+5. **Enforce caps — two independent budgets, because the peer is hostile.** The compute budget (`computeMs`) meters the worker's *measured busy time* via `worker.performance.eventLoopUtilization()` polling — not host-side "is an RPC pending" bookkeeping, which a program defeats by firing an un-awaited call at a slow tool and then spinning hot while the host thinks it is waiting. Measured busy time cannot be gamed: a hot loop accrues it whether or not a dispatch is in flight, and a program genuinely awaiting a slow tool accrues none, so a long-running `bash` sub-call still does not kill an innocent run. The wall ceiling (`maxWallMs`) never pauses for anything and backstops what busy-time cannot see (a program awaiting a promise nobody will resolve). Budget expiry, `signal` abort, and run completion all funnel into `worker.terminate()`, which ends hot synchronous loops too (measured; this was `node:vm`'s unfixable gap); the failure reports which budget fired. Heap overflow surfaces as the worker's OOM exit → `error.kind: 'worker-exit'`. Log and value sizes are capped by config, truncation marked in-band. All caps are validated config fields with defaults (`computeMs: 60_000`, `maxWallMs: 600_000`, `maxLogBytes: 65_536`, `maxValueBytes: 32_768`, `maxOldGenerationSizeMb: 512`), changeable from `cordis.yml`.
+6. **Dispose to quiescence**: the service's own disposal terminates in-flight workers and *awaits* their exits before resolving, per [defensive patterns](../../../defensive-patterns.md).
+
+### Trust posture
+
+The worker runtime is **containment, not a security boundary**, and the RFC says so without ceremony. Model code in the worker can reach Node globals — `fetch`, `process` (with an empty env), dynamic `import()` of built-ins — so a deliberately adversarial program has ambient authority comparable to what the harness's own `bash` tool already grants every model turn: `dsh-bash-local` runs arbitrary model-written commands with the host filesystem, network, and a scrubbed-but-populated environment. One asymmetry runs the other way and is stated plainly: `worker.terminate()` ends the thread, not OS processes a program may have spawned via `node:child_process` — weaker than `bash-local`'s process-group kill for direct children (equivalent for double-forked daemons, which survive both); the wall-clock ceiling bounds the worker itself, and orphan cleanup is the same deployment-level concern it already is for bash. Code Mode is gated where bash is gated — `tools/pre-execute`, where permission/sandbox plugins veto or approve the program before it runs — and adds containment bash does not have: empty env, heap caps, hard termination of the program itself, a separate isolate. The earlier draft's two-flag unsafe ceremony (`{ unsafe: true }` constructor + `allowUnsafeRuntime`) existed for a `node:vm` stub with *no* containment and is dropped with it; demanding scarier flags for the better-contained executor than for bash would be posture theater. A deployment that needs a hard boundary (untrusted multi-tenant input) needs it for bash too; that is a future `isolation: 'container'` backend, and the `isolation` descriptor exists so such a deployment can tell backends apart.
+
+### What the model sees
+
+The `tools:sdk` section carries the `.d.ts` plus fixed instructions: the program is the body of an async TypeScript function (erasable syntax only — no `enum`/namespaces; type annotations are advisory); call tools as `await tools.name(args)` (quoted access for exotic names); a failed tool call **rejects** with an `Error` carrying the tool's error text — catch it to handle and continue; calls run **sequentially** even under `Promise.all`; emit results via `return` and/or `console.log`, and only that curated output returns to the context — intermediate tool results never do. That last line is the payoff the whole design serves: output-side context cost becomes the model's own editorial decision. On the input side the `.d.ts` is not free — for a large tool surface it can rival the native JSON schemas it replaces (and `'both'` pays for the two side by side) — but it is prefix-stable, so provider prefix caching amortizes it; the win is workload-dependent and the RFC claims no more.
+
+## Plan
+
+Four stacked PRs, each gates-green (`typecheck`, `lint`, `test:coverage`, `test:snapshot`, `doc-sync`, `verify-module-graph`, `build`, `hygiene`) with docs updated in the same change:
+
+1. **This RFC revision** (docs-only): the file rewritten as above (renamed `2026-06-15-code-mode.md`, same first-proposed date), regenerated RFC index.
+2. **`dsh-code-runtime`** (interface package): the group `packages/code-runtime/`, abstract `CodeRuntime`, vocabulary types, ctx-key declaration; docs in the same change — group README + package README, the `packages/README.md` group table row, the `ctx.codeRuntime` row in [docs/architecture.md](../../../architecture.md)'s service map, and the regenerated cordis catalog (the new service class). Unit tier: HMR safety (dispose removes `ctx.codeRuntime`), contract docs. This package has no behavior to snapshot or e2e; its coverage story is unit-only by design.
+3. **`dsh-code-runtime-worker`**: the implementation above, plus the regenerated config catalog (its `Config`). Unit tier (real workers, no mocks — they are cheap and local): output/value capture, log source attribution, error kinds (exception incl. non-erasable syntax, abort, worker-exit under OOM), the two budgets from both sides (a hot loop with an un-awaited pending dispatch still dies at `computeMs` busy time; a program idling on a slow binding outlives `computeMs` and dies only at `maxWallMs`), binding bridge hostility cases (unknown name, duplicate id, post-settlement message, `__proto__`/`constructor`/`toString` binding names), structured-clone fallback, cap truncation, `env` emptiness verified from inside the program, dispose-awaits-exit. A real-load-path test runs the built package (`lib/`) so the worker entry resolves both unbuilt (tsx) and built — the published-bin guard from [docs/testing.md](../../../testing.md).
+4. **Native code mode in `dsh-tools`** + the end-to-end surface: mode config, provider switch, `tools:sdk` section, `jsonSchemaToTs`, `run_code` + dispatch bridge + serialization queue, `tool/code-dispatch` event; regenerated tool, config, and persistence catalogs; [docs/architecture.md](../../../architecture.md) (tool-pipeline prose) and the [adding-a-tool cookbook](../../../cookbook/adding-a-tool.md) cross-reference updated in the same change; an `examples/` leaf + `demo:code` script wiring the worker runtime with `mode: 'code'`; move this RFC to `implemented/`. Coverage named per tier now, per the plan-time rule: **unit** — codegen table (DSL subset, quoted names, `unknown` degradation, determinism), provider contribution per mode, `toolOrder × mode` rejection, missing-runtime/wrong-language loud failures, serialization non-overlap (a probe tool records enter/exit under `Promise.all`), abort stops the queue, binding rejection on `isError`, `CodeRunFailedError` → structured `isError`, event payloads, `deriveMessages()` ignores the event, HMR safety (mode flip via config reload removes tool + section); **e2e (with-key, self-skips)** — a real model, `mode: 'code'`, a task requiring two tool calls and curation, asserting the wire tool list was exactly `run_code` and the transcript's dispatch events; **snapshot (keyless replay)** — goldens for a `run_code` turn in `'code'` and `'both'`, pinning the SDK section text, the collapsed header tools, dispatch events, and the result card.
+
+The four PRs land in order (each on the previous); per stacked-review practice, review fixes land on the PR that introduced them and merge down.
+
+## Alternatives considered
+
+**An add-on consumer plugin, zero core changes (the previous draft of this RFC).** Rejected on both halves. The wire-collapse half aged out from under it: it targeted the `agent/request` waterfall, which [reconstructable requests](../../implemented/architecture/2026-07-05-reconstructable-requests.md) has since re-typed to call-config-only, and the surviving alternative — transforming the assembly a waterfall listener receives — is strictly worse than contributing the right list in the first place (transformation must undo `toolOrder` canonicalization it cannot see the config for, and its correctness depends on where it sits in a listener chain). The deeper reason is ownership: which tools the model is offered, in which representation, is the registry's single concern — `schemas()` for function calling and the SDK for Code Mode are two projections of one store, and splitting the second projection into a satellite package would preserve a boundary the domain does not have.
+
+**`node:vm` as the reference runtime, hardening deferred (also the previous draft).** Rejected: `node:vm` is not isolation (prototype-chain escapes reach the host realm), cannot interrupt a hot loop, and forced the draft into a two-flag unsafe ceremony plus a mandatory follow-up RFC. The worker thread delivers the missing properties now — separate isolate, empty env, `resourceLimits`, reliable `terminate()` (all verified by probe before this revision) — at bash-equivalent trust, so the reference implementation and the production one are the same package and the ceremony dissolves.
+
+**Result elision / summarization over native tool-calling.** Addresses only the context-bloat half of the problem: trimming old `tool-result`s (now cheap to add as a logged surface replace, per the reconstructable-requests consequences) still pays one model round-trip per call and cannot express loops, branches, or joins. Complementary, not competing; it can layer under Code Mode for residual native calls.
+
+**Parallel native dispatch in the loop.** The other answer to round-trip cost; still valid future work (the open TODO), still blocked on concurrency-safety metadata, and still no composition — it parallelizes calls the model already decided on in one step. Code Mode's serialized-queue decision keeps the two compatible: when the metadata lands, both native parallel dispatch and per-tool binding parallelism unlock together.
+
+**Always-exclusive (Cloudflare-faithful, no mode).** Rejected for this SDK's primary consumer: a coding agent's bread-and-butter single calls (`bash`, `read`, `edit`) are already ideal as native calls, and forcing every edit through a program taxes the common case. The mode config keeps the faithful form (`'code'`) one line away without imposing it.
+
+**Per-tool visibility tiers (this tool native, that tool code-only).** Deferred again, knowingly: it needs per-tool metadata and a presentation split that `'native' | 'code' | 'both'` does not, and every learning it depends on (how models actually split usage under `'both'`) arrives only after this ships.
+
+**Sanitized identifier aliases in the SDK** (`my-tool` → `my_tool`, Cloudflare's approach). Rejected: quoted keys on a `declare const` make every name reachable with zero alias-collision logic; models handle `tools["my-tool"](…)` fine.
+
+**A REPL-style persistent kernel** (state survives across `run_code` calls). Rejected for the MVP: cross-call state would be invisible to the session log, breaking the reconstructability guarantee that every request is a pure function of the log; fresh-per-run keeps it. A kernel-style backend remains expressible behind the seam later, with its own logging story.
+
+## Acceptance criteria
+
+- `mode: 'native'` (and unset) is byte-for-byte today's behavior: same assemblies, same headers, same snapshots.
+- Under `mode: 'code'`, the assembled tool list (and thus the logged `request/header`) is exactly `[run_code]`; under `'both'`, every native schema plus `run_code`; the `tools:sdk` section is present in both, absent under `'native'`, and its text is deterministic for a fixed tool set (byte-identical across consecutive assemblies).
+- The generated `.d.ts` covers every registered tool except `run_code`, non-identifier names via quoted keys, unsupported schema constructs as `unknown`, without codegen ever throwing.
+- A program calling two tools returns only its curated output; each sub-call appears as a `tool/code-dispatch` event ordered by log `seq`, flows through `tools/pre-execute`/`post-execute` (a deny reaches the program as a binding rejection), and never enters derived messages; a binding argument that does not survive JSON normalization (`BigInt`, a circular structure) rejects before dispatch — nothing executes unlogged.
+- `Promise.all` over three bindings produces non-overlapping `ctx.tools.execute()` intervals (probe-tool assertion); aborting mid-program stops the worker and dispatches nothing further; a budget expiry during a slow sub-dispatch aborts that dispatch (the probe tool observes its signal fire), `run_code` returns only after the queue drains, and no `tool/code-dispatch` event lands after `run_code`'s own `tool/result` in the log.
+- Worker runtime: a hot `for(;;){}` run ends at the `computeMs` busy-time budget with `error.kind: 'timeout'` — including when the program fired an un-awaited binding call first (the pending-RPC decoy); a program idling on a slow binding does not consume `computeMs` and is bounded only by `maxWallMs`; OOM under `resourceLimits` yields `kind: 'worker-exit'` with the host process healthy; `process.env` inside a program is empty; non-erasable syntax yields `kind: 'exception'` without a worker spawn; disposal awaits worker exit.
+- Misconfiguration is loud before any model request: non-native mode with no `ctx.codeRuntime`, a runtime whose `language ≠ 'typescript'`, and `toolOrder` naming a non-contributed tool all reject the assembly with actionable messages.
+- The demo runs against the real API via `demo:code`; the snapshot goldens replay keylessly; all repo gates pass on every PR of the stack.
+
+## Risks
+
+**The worker is not a hard security boundary.** Deliberate and documented (§Trust posture): posture equals the existing bash tool, containment exceeds it, gating uses the same seams. Deployments needing more need a future `isolation: 'container'` backend — tracked as the seam's designed extension, not a TODO on this design.
+
+**`stripTypeScriptTypes` is marked experimental.** It is the same engine (amaro/swc) behind Node's own native `.ts` execution, exposed as an API across this repo's whole engines range. Mitigations: the runtime's unit suite pins the behaviors relied on (position preservation, erasable-only rejection message shape loosely), the call sits behind one private function, and `amaro`/`sucrase` are drop-in replacements if the API shifts. The erasable-only subset is a model-facing contract line, and the error path is a working feedback loop, not a dead end.
+
+**Prompt cost of the SDK, especially under `'both'`.** The `.d.ts` can rival the native schemas it complements; `'both'` carries two representations. Prefix stability + provider caching amortize per-session cost; the mode is per-deployment; the RFC makes no unconditional-savings claim. Measured guidance (when to prefer which mode) is explicitly post-ship learning.
+
+**Registry scope growth.** `dsh-tools` absorbs codegen, a tool, a bridge, and an event. Contained by module boundaries inside the package (`ts-types.ts`, `code-mode.ts` beside `schema.ts`/`json-schema.ts`/`presentation.ts`) and by the seam: everything substrate-shaped lives behind `ctx.codeRuntime`.
+
+**Structured-clone limits at the binding boundary.** The seam's clone boundary admits values JSON does not (`Date`, `Map`, `BigInt`), and the session log accepts only JSON — left unhandled, a sub-call could execute and then fail at `tool/code-dispatch` append time. Closed by the bridge's JSON-normalization step (§ the dispatch bridge): what does not survive the round-trip rejects that binding call before dispatch, so every executed sub-call is loggable by construction. The seam itself keeps the wider structured-clone contract (it is about the port, and stated so a future binding producer cannot discover it in production); consumers with stricter payload needs enforce them at their own boundary, as the bridge does. Non-text sub-result content is reduced to placeholders — a known MVP limitation, recorded in the SDK instructions.
+
+**Serialized-only sub-dispatch.** `Promise.all` gains no wall-clock parallelism yet, only fewer round-trips; models may over-expect. The instructions state it; lifting it is tied to the same concurrency-safety metadata the native parallel-dispatch TODO needs.
+
+**Budget metering reads the event loop, not a flag.** Busy-time polling (`eventLoopUtilization()`) is coarser than an exact CPU meter — a budget expires up to one poll interval late — and its correctness claim ("a pending dispatch cannot pause it") is load-bearing against a hostile program. Both sides are unit-tested (hot loop with a pending decoy dispatch dies at `computeMs`; idle-on-slow-binding survives to `maxWallMs`), and the poll interval is an internal constant, not config — nothing a deployment could mis-tune into a bypass.
@@ -1,119 +0,0 @@
-# RFC: Optional Code Mode — model writes TypeScript against an SDK of all tools
-
-Status: proposed
-
-> Premise partially stale: this proposal predates [request reconstructability](../../implemented/architecture/2026-07-05-reconstructable-requests.md) — `agent/request` now shapes call config only (no request/content mutation), so the interception points named below need re-mapping onto the log channels and `system-prompt/assemble` before implementation.
-
-## Problem
-
-Today the agent loop advertises every registered tool to the model as a native JSON-schema function definition. `ToolRegistry` feeds its schemas into `ctx.systemPrompt`, the loop puts them on `GenerateOptions.tools`, and the adapter serializes them to the provider's function-calling wire format. The model then invokes one `tool-call` block per step, the loop dispatches each call through `ctx.tools.execute()` **sequentially** (parallel tool execution is an explicit open TODO in `dsh-tools` and [docs/architecture.md](../../../architecture.md)), and **every** intermediate `tool-result` re-enters the model's context on the next request.
-
-For multi-step tool work this is token-heavy and serial. The model cannot compose tools — loop over a result set, branch on an intermediate value, fan out, post-process — without a full model round-trip per call, and each of those round-trips drags the entire intermediate result back into context whether the model needs it or not.
-
-Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) (shipped as the `@cloudflare/codemode` npm package) proposes an alternative grounded in a simple observation: LLMs are better at writing code than at emitting tool calls, because they have seen millions of lines of real code and comparatively few contrived tool-calling traces. Instead of one tool call per step, the model writes a TypeScript program against a generated SDK that wraps all the tools, and that program is executed. The model curates what comes back — only what it `console.log`s and/or returns — instead of every intermediate result. The SDK functions are async, so the model can *express* fan-out (`Promise.all`) naturally in code; this RFC initially **serializes** those dispatches (§ Concurrency) until the tool contract grows concurrency-safety metadata, so the early win is composition and fewer round-trips, not parallelism.
-
-This RFC proposes an **optional** Code Mode for the DeepSeek Harness, covering **all** tools uniformly — built-in and future MCP — with no per-tool work, implemented Cordis-style with **zero core-package changes**. It fully specifies the code-execution seam and the SDK-generation pipeline, but ships only a minimal `node:vm` reference stub for execution; the hardened, sandboxed execution substrate is **deferred to a follow-up RFC** (see Risks). This RFC does not change the agent loop, and it leaves native tool-calling exactly as it is — Code Mode is a plugin you load, not a replacement.
-
-## Proposal
-
-The design follows the codebase's capability-seam pattern ([capability seams](../../implemented/architecture/2026-06-13-capability-seams.md), the `bash` template) as a three-package split, plus one consumer plugin. Nothing in `dsh-session`, `dsh-agent`, `dsh-agent-loop`, `dsh-llm`, `dsh-tools`, or `dsh-system-prompt` changes.
-
-**Prior art.** `@cloudflare/codemode` validates this shape directly and several of its decisions are adopted below. Its `Executor` interface is deliberately tiny — `execute(code, fns) → { result, error?, logs? }` — with a production `DynamicWorkerExecutor` (isolated Workers) and a six-line `NodeVMExecutor` example as two implementations behind it: exactly the interface/implementation split [the capability-seam pattern](../../implemented/architecture/2026-06-13-capability-seams.md) prescribes. It generates TypeScript type definitions from tools for the model's context and runs the generated JavaScript in a sandbox, capturing console output alongside the return value. It normalizes model output into an async arrow function via AST parsing (acorn) and sanitizes tool names into valid JS identifiers (`my-tool` → `my_tool`, `delete` → `delete_`). It blocks outbound network by default. The transferable lessons — minimal executor contract, host-side type derivation, capture-output-and-return-value, name sanitization, AST-normalize the code, isolate by default — are folded into the design below. What does **not** transfer is the substrate: Cloudflare's isolation is Workers-specific; our equivalent hardened substrate is the deferred follow-up.
-
-**Prompt-budget tradeoff (Code Mode is not unconditionally cheaper).** Deriving the SDK types host-side costs no extra *discovery* round-trip, but the generated `.d.ts` is injected into the system prompt (§3a), so the type definitions themselves **do** consume context — and for an all-tools SDK that cost scales with every registered tool and can be comparable to, or larger than, the native JSON schemas it replaces. Code Mode's saving is on the **output/result** side (the model curates what comes back; intermediate results never re-enter context) and on **round-trips** (compose many calls in one program), not on the input-side tool description. The net win is workload-dependent: it pays off for multi-call, large-intermediate-result workflows and can cost *more* for a single call against a large tool surface. The `.d.ts` section is a prefix-stable prompt prefix, so prompt caching amortizes its per-turn cost across a session; the RFC notes that caching is what keeps the injected SDK affordable, and that a deployment with a very large tool surface should weigh the SDK size against native schemas rather than assume Code Mode is strictly cheaper.
-
-**1. Interface package `packages/code-runtime/`** — a new package `@deepseek-ai/dsh-code-runtime` owning `ctx.codeRuntime`, depending only on `cordis`. It defines an abstract `CodeRuntime extends Service` plus the execution vocabulary. The runtime knows **nothing** about `ctx.tools`: it is handed a set of named async functions (the resolved SDK bindings), runs the program, and captures output. The result shape mirrors Cloudflare's proven-minimal contract so an error is a *field on a resolved result*, not a throw the runtime is expected to make:
-
- `CodeRunRequest = { code: string; sdk: SdkBinding[]; signal?: AbortSignal }`
- `CodeRunResult = { result: unknown; logs: string[]; error?: string }`
- a readonly `safe: boolean` on the `CodeRuntime` service — `false` for an unsandboxed stub, `true` only for a real isolating substrate; consumers gate on it (§2).
- `SdkBinding = { namespace: string; fns: Record<string, (args: unknown) => Promise<unknown>> }`
-
-Per the "explicit > implicit at seams" convention, the request spells out every field the runtime acts on; defaulting (e.g. an output cap, a timeout derived from `signal`) is the implementation's explicit job, not a hidden `?? default` inside `run()`. The split into interface + implementation is justified under [the capability-seam pattern](../../implemented/architecture/2026-06-13-capability-seams.md) because there is **genuinely more than one planned implementation** — the node:vm stub *and* the hardened substrate (a real isolate, or the generated program run as a sandboxed process through the existing `ctx.bash` seam) that is scheduled follow-up work, not speculative optionality. The capability-seam pattern warns against splitting preemptively when only one implementation is conceivable; here a second is not just conceivable but required before any untrusted use, so the seam earns its keep.
-
-**Backends can differ by language/runtime, not only by trust level.** The two implementations above (unsafe stub vs. hardened substrate) differ along the *trust* axis while staying TypeScript/JS, but nothing in the `CodeRuntime` contract — a program string plus a set of named async SDK bindings in, and a `{ result, logs, error? }` out — is bound to one source language. The same seam can host backends that differ along the *language* axis, executing a program written in something other than TypeScript. Two illustrative directions:
-
- **An AssemblyScript backend.** AssemblyScript is a strict TypeScript subset that compiles to WebAssembly, so a program stays familiar to a TS-fluent model while the WASM boundary supplies exactly the sandboxing the hardened substrate is meant to provide — memory isolation and no ambient host authority come from the runtime rather than from after-the-fact hardening of `node:vm`. This is an appealing route to a `safe = true` backend.
- **A Python backend.** Python is arguably the model's most native language — it has seen far more real Python than any tool-calling trace — which is the same "LLMs write better code than tool calls" argument that motivates Code Mode, taken one step further. A Python backend is itself a sub-seam over different Python *runtimes*: **CPython** (in-process or a sandboxed subprocess via `ctx.bash`) for maximum fidelity and ecosystem access, or a more controllable / embeddable interpreter — Pyodide (CPython on WASM), RustPython, or a restricted embedded interpreter — when isolation, deterministic resource limits, or a clean capability boundary matter more than running arbitrary native extensions.
-
-These are illustrations of the seam's reach, **not commitments** — the MVP ships only the TypeScript path. The honest caveat is that the *execution* contract is language-agnostic but the *presentation* is not: the SDK-generation pipeline below (§3a and the `jsonSchemaToTs` codegen, which emits a TypeScript `.d.ts`) is TypeScript-specific, so a non-TS backend pairs the shared `CodeRuntime` contract with its own language-appropriate SDK generator and system-prompt section (a `.pyi` stub and Python usage instructions for the Python backend, AssemblyScript-flavored types for that one). The runtime seam is reused as-is; only the codegen/prompt half is per-language.
-
-**2. Implementation package `packages/code-runtime-vm/`** — a new package `@deepseek-ai/dsh-code-runtime-vm`, the `node:vm` reference stub. It type-erases the model's TypeScript via the compiler's `transpileModule` (or sucrase) — the types exist only to guide the model; the runtime is plain JS — then wraps the body in an async IIFE for top-level `await` (Cloudflare's `NodeVMExecutor` does literally `new AsyncFunction("codemode", "return await (${code})()")`), runs it in a `vm.Context` whose globals are a capturing `console` and the SDK namespace objects, awaits the IIFE, and captures the return value, the buffered logs, and any thrown error (as `error: string`). It applies an **output cap** (truncate captured logs) and a **timeout tied to `request.signal`**. These caps limit blast radius; **they are not a security boundary**. node:vm is **not** isolation: withholding `require`/`process` does not contain anything (code escapes via `constructor`/prototype reflection), and per [AGENTS.md](../../../../AGENTS.md) the harness must never hand model output the ambient environment.
-
-**The unsafe-runtime guard is enforceable, not a README warning.** Because a README caveat is not a control — and AGENTS.md's "never hand model output ambient authority" is a hard rule, not advice — the design makes the danger refuse to run by construction. Two layers:
-
- **The runtime declares its trust level.** `CodeRuntime` carries a readonly `safe: boolean` (a `node:vm`-class stub returns `safe = false`; a real isolate/sandboxed-process substrate returns `safe = true`). The `code-runtime-vm` constructor *additionally* requires an explicit opt-in — `new VmCodeRuntime({ unsafe: true })` — and **throws** if that flag is absent, so merely depending on the package and wiring it cannot silently produce a live unsafe runtime; the operator must type the word `unsafe`.
- **The consumer refuses to expose `run_code` over an unsafe runtime by default.** When `code-mode` initializes, if `ctx.codeRuntime.safe === false` it does **not** register `run_code` unless the plugin itself is configured with an explicit acknowledgement (e.g. `code-mode` config `allowUnsafeRuntime: true`). Absent that, it logs a typed error and registers nothing — so a real model never reaches an unsandboxed runtime by a single config slip. The refusal path is tested: with the acknowledgement unset and an unsafe runtime, `run_code` is absent (and the wire tool list is unchanged from native); with both opt-ins set, it registers and runs. This keeps the unsafe reference backend usable for tests and trusted local demos while making production misuse take two deliberate, greppable flags rather than one mistake.
-
-`code-runtime-vm` is therefore documented as **reference / test-only / unsafe-for-untrusted-input**, acceptable in the MVP only because the code runs at harness trust *and* both opt-in flags must be set. Signal handling is best-effort: it aborts in-flight sub-dispatches but cannot reliably interrupt a hot synchronous loop (`while(true){}`) in node:vm — another reason the hardened substrate is deferred, not optional-forever.
-
-**3. Consumer plugin `packages/code-mode/`** — a new package `@deepseek-ai/dsh-code-mode`, the plugin that wires everything together. It declares `inject = ['tools', 'systemPrompt', 'codeRuntime']` — Cordis throws on access to a service that is not injected, and keeps the plugin inactive until all three exist (the same pattern as `tool-bash`'s `inject = ['tools', 'bash']`), which also gives correct load-ordering relative to `code-runtime`/`code-runtime-vm`. The plugin contributes four things, all through existing seams:
-
-**3a. Tool presentation — a lazy system-prompt section (the injection seam already exists).** `dsh-system-prompt` already provides the Cordis-idiomatic way for any plugin to inject prompt snippets: `ctx.systemPrompt.section({ name, order, text })`, fiber-scoped and auto-disposed via `ctx.effect()`, where `text` may be a lazy `() => string` re-evaluated at each assembly. No new mechanism is needed or invented. Code Mode registers a lazy section (high `order` so it lands last) whose thunk reads `ctx.tools.schemas()` at assembly time and regenerates the SDK `.d.ts` plus usage instructions from the currently-registered tool set. Because the thunk reads the live registry, coverage of every tool — built-in, MCP, future — is automatic.
-
-**3b. Wire tool-list enforcement — an `agent/request` listener (the authoritative seam).** The goal "exactly one tool reaches the wire" must be enforced where the wire request is finalized. The loop calls `ctx.systemPrompt.assemble()` first, *then* builds `GenerateOptions` (seeding `tools` from `assembly.tools`), *then* runs the `agent/request` waterfall, *then* calls `ctx.llm.stream()`. A `system-prompt/assemble` listener can only influence the *seed*; `agent/request` is the last seam before the model call, so it is authoritative. The plugin registers an `agent/request` listener that does `const final = await next(); return { ...final, tools: [runCodeSchema] }` — overriding the value *returned by* `next()`, not the inbound argument, so it dominates the cooperative request listeners it wraps. It registers with `prepend: true` to sit at the outer edge of the waterfall chain. One honest caveat, stated in the RFC body: `ctx.llm.stream()` itself runs a further `llm/stream` waterfall before the adapter, so the guarantee is "authoritative within the agent request pipeline," not an absolute wire invariant; if a hard invariant is ever required, a defensive `llm/stream` assertion with a spy adapter covers it in tests.
-
-**3c. The single tool — `run_code`.** Registered normally in `ctx.tools` with one parameter `{ code: string (required) }`. Because it is an ordinary tool, the unchanged loop dispatches it through the normal path — this is the crux of "zero loop changes." Its `execute(args, exec)`:
-
-1. Builds the SDK bindings. For each real tool, an async `invoke(callArgs)` that **checks `exec.signal?.aborted` (throwing if set) before and after** calling `ctx.tools.execute({ callId: <deterministic sub-id>, name, arguments: callArgs, agent: exec.agent, signal: exec.signal })`, then maps the resulting `ContentBlock[]` to a simplified `{ output, isError }` (text blocks for the MVP), and emits an observability event. The explicit abort check matters because `ctx.tools.execute()` *catches* thrown tool errors and converts them to `isError` results — without the check, an aborted sub-call would look like ordinary error data and the program would keep running instead of stopping. Sub-dispatch still flows through the `tools/pre-execute`/`tools/post-execute` waterfalls, so permission/sandbox/hook plugins apply to code-mode calls exactly as to native ones.
-2. Calls `ctx.codeRuntime.run({ code: args.code, sdk: bindings, signal: exec.signal })`.
-3. Surfaces the outcome. A *successful* run returns `[{ type: 'text', text: <console logs + return value> }]`. A *runtime-error* result cannot be reported by returning content, because a normal `ToolDefinition.execute()` returns only `Promise<ContentBlock[]>` and `ToolRegistry.execute()` hardcodes `isError: false` on any successful return — `isError: true` arises only from the registry's catch path. So on an error result the tool **throws a `CodeRunError extends HarnessError`** (`HarnessError` is exported from `dsh-llm`; the registry catch turns any throw into `isError: true` with the message as text, and a `HarnessError` additionally carries structured `{ name, code }`). An alternative — registering `run_code` handling as a `tools/execute` listener that returns a full `ToolExecutionResult` and can set `isError` directly — is noted; the throw is simpler and preferred.
-
-**3d. Result discipline — what the model receives.** The model gets back **only the captured console output and/or the program's return value** (the model chooses which to surface). Intermediate sub-call results are **never** returned to the model. This is the core context-saving benefit: the agent curates its own output, exactly as a script's stdout curates a pipeline's intermediate state.
-
-**Sub-call CallIds.** Real tool calls dispatched from inside `run_code` need ids, but `CallId` is normally provider-issued (a branded string for correlating a call with its result — only brand-wrapped via `CallId()`, with no generator and no documented session-global-uniqueness guarantee). The plugin mints deterministic sub-ids scoped to the parent: `` `${exec.callId}:code:${n}` `` with a per-run counter `n`. These are unique within one `run_code` run (assuming the parent `callId` is unique, which the provider guarantees per turn); the `code/dispatch` event additionally carries the session log's `seq` so the UI and persistence can order and disambiguate globally without relying on the id alone. `ToolExecution.agent` is optional; the normal loop always supplies it (and with it `exec.agent.session`, the log `code/dispatch` appends to). A `run_code` execution arriving without `exec.agent` still runs (sub-calls propagate `agent: undefined`, exactly as the loop's own contract allows) but **skips session-log observability** — with no session to append to, those direct runs are simply not logged.
-
-**Observability without context cost.** Each sub-dispatch emits a session event **declared by the `dsh-code-mode` plugin itself** via `SessionEventMap` declaration merging (the map is merge-extensible precisely so plugins can add events without touching `dsh-session`). Shape: `code/dispatch` with `{ parentCallId, subCallId, name, arguments (or redacted), isError, summary }`, ordered by the session log's own `seq`. `deriveMessages()` does **not** translate it into a model message — an unknown event type falls through its `default`, per the merge-extensible-union convention — so the UI and persistence ([session persistence](../../implemented/architecture/2026-06-14-session-persistence.md)) can render every sub-call while the model's context only ever receives the single `run_code` tool-result. Because the event lives in the plugin, this adds no core change.
-
-**SDK codegen.** A pure `jsonSchemaToTs(schema)` in `code-mode` maps the JSON-schema subset the `defineTool` DSL produces (object/string/number/boolean/array, `properties`, `required[]`, `enum` → string-literal union, nested objects, array `items`) to a TS type literal. It is **total**: any unsupported construct (`$ref`, `oneOf`/`anyOf`, `integer`, `null`, `additionalProperties`, or any raw MCP shape it does not recognize) degrades to `unknown` without throwing — it never crashes codegen. Typing is best-effort, not a guarantee, because MCP tools accept arbitrary JSON Schema and `ToolSchema.parameters` is typed only as `Record<string, unknown>`. Because `ToolSchema.name` is an arbitrary string (not necessarily a valid TS identifier), the SDK is generated as a **namespace with quoted access** (e.g. `tools["some-mcp-tool"](args)`) plus safe camelCase aliases where the name is a clean identifier; alias collisions and TS reserved words fall back to quoted-only access (no duplicate alias emitted). This mirrors Cloudflare's `sanitizeToolName`. `run_code` itself is filtered out of the SDK. The MVP surfaces text content only; image and other block types in sub-results are deferred (noted as a limitation).
-
-**Concurrency — serialized by default (the binding must enforce it).** The SDK functions are async, so a model writing `await Promise.all([tools.a(...), tools.b(...)])` would *start both* immediately, and each would call `ctx.tools.execute` right away — i.e. the binding shape makes concurrent dispatch the **default**, not an opt-in. Because the tool contract carries **no concurrency-safety metadata today** (parallel tool execution and a concurrency-safety hint are an open TODO in both `dsh-tools` and [docs/architecture.md](../../../architecture.md): "phase 1 executes tool calls sequentially"), concurrent dispatch through a not-yet-hardened tool may race. So a prose "may serialize" is not sufficient. **Decision: the MVP SDK bindings enforce serialization** — each `run_code` invocation owns a per-run dispatch queue, and every `invoke()` chains onto it (`tail = tail.then(() => ctx.tools.execute(...))`), so even `Promise.all` over SDK calls executes them one at a time in submission order. This is a hard acceptance criterion, with a test that issues `Promise.all([...])` from a program and asserts the underlying `ctx.tools.execute` calls did **not** overlap (e.g. a probe tool records enter/exit and the test asserts no interleaving). The `.d.ts` may *describe* the model-visible functions as async (they are), but the implementation guarantees serial execution. Lifting serialization is deferred: only once a tool can declare itself read-only / concurrency-safe does the binding allow those specific tools to overlap. The same per-run queue is where the before/after abort checks (§3c) live, so an aborted run drains no further queued dispatches.
-
-**Tool visibility tiers (design intentionally skipped).** A natural extension is to mark each tool with a *visibility tier*: some tools "direct-call eligible" (still offered as native wire tools alongside `run_code`), some "code-mode only" (reachable solely from within a `run_code` program, never on the wire), and the default "both." This would let a deployment keep a few high-frequency or approval-gated tools as direct calls while routing the long tail through Code Mode, or hide composition-only primitives from the native surface entirely. This RFC notes the possibility but **intentionally skips the detailed design** — the per-tool metadata, how it interacts with the `agent/request` enforcement in 3b, and the presentation split in 3a are left to a follow-up. The MVP is the simple two-state model: Code Mode on (everything via `run_code`) or off (everything native).
-
-**Optionality / toggle.** Loading the `code-mode` plugin enables Code Mode for that context; not loading it leaves today's native tool-calling untouched. The two are mutually exclusive within one ctx, because Code Mode rewrites the wire tool list down to `[run_code]`. Per-agent selection via ctx forks, and the visibility tiers above, are future work; the MVP toggle is plugin presence.
-
-## Alternatives considered
-
-**Result elision / summarization over native tool-calling (the narrower route).** The Problem has two halves — context bloat (every intermediate `tool-result` re-enters context) and serial composition (one tool call per round-trip). The context-bloat half can be addressed *without* any code-execution runtime: keep provider tool-calling exactly as it is, and add a plugin on the `agent/request` waterfall (or a compaction pass akin to [the session-persistence work](../../implemented/architecture/2026-06-14-session-persistence.md)) that elides or summarizes older `tool-result` blocks before they re-enter the model's context — drop them past a window, replace large payloads with a digest, or keep only the blocks the model still references. This is strictly less invasive than Code Mode: no new runtime seam, no model-written programs, no new safety surface. It is the right tool if context growth is the only pain.
-
-It is insufficient for the **composition / round-trip** half, which is the decisive reason this RFC does not stop there. Elision still pays one model round-trip per tool call: a loop over N items is N turns, a branch on an intermediate value is a turn to fetch then a turn to act, and post-processing (filter, join, reduce) either happens in the model's head over full payloads or not at all. Code Mode collapses all of that into one program — the loop, the branch, the join run in the runtime, and only the curated result returns. Elision also cannot express fan-out or data-dependent control flow; it only shrinks what comes back. So the two are complementary, not competing: elision could even layer *under* Code Mode for the residual native-tool paths. The RFC chooses Code Mode because the round-trip/composition cost is the larger structural limit, and accepts the new code-execution surface as the price — which is exactly why the execution substrate is gated behind the enforceable safety guard (§2) and the hardened backend is a hard prerequisite for untrusted use.
-
-**Why not change the loop to dispatch native tool calls in parallel instead?** That is the other obvious answer to the round-trip cost, and it remains valid future work (it is the open `dsh-tools`/architecture.md TODO). But it is a core-loop change requiring the same concurrency-safety metadata Code Mode defers, and it still does not give the model *composition* (branch/loop/post-process between calls) — only parallelism of independent calls the model already decided to make in one step. Code Mode delivers composition with zero core change; parallel native dispatch and Code Mode can coexist later.
-
-## Plan
-
-1. Scaffold the interface package `packages/code-runtime/` per [the cookbook](../../../cookbook/adding-a-package.md): abstract `CodeRuntime extends Service` (`super(ctx, 'codeRuntime')`) with a readonly `safe: boolean`, the `declare module 'cordis'` ctx key, the `CodeRunRequest`/`CodeRunResult`/`SdkBinding` vocabulary, method contracts documented in JSDoc (what `run` captures, abort semantics, that an error is a result field not a throw, what `safe` means). HMR-safety test (dispose the contributing fiber, assert `ctx.codeRuntime` is gone).
-2. Scaffold the implementation package `packages/code-runtime-vm/`: the node:vm stub — `safe = false`, a constructor that **throws unless given `{ unsafe: true }`**, transpile/type-erase, async-IIFE wrap, capturing `console`, SDK globals, return-value/logs/error capture, output cap, signal-tied timeout. Tests for output capture, return value, error-as-field, abort, the constructor refusal without `unsafe`, and a README documenting the "not a sandbox, trusted-only" caveat prominently.
-3. Scaffold the consumer plugin `packages/code-mode/`: `jsonSchemaToTs` codegen with namespace/quoted-access + alias handling (unit tests, including non-identifier MCP names and unsupported-shape → `unknown`); the registered lazy `ctx.systemPrompt.section()` carrying the SDK `.d.ts`; the `agent/request` listener (`prepend: true`) collapsing `request.tools` to `[run_code]` after `await next()`; the **unsafe-runtime gate** (refuse to register `run_code` when `ctx.codeRuntime.safe === false` unless `allowUnsafeRuntime` is set); the `run_code` tool with the dispatch bridge (per-run serialization queue, deterministic sub-call ids, before/after abort checks, `CodeRunError` on error results); and the `code/dispatch` event declared here via `SessionEventMap` merge. Declare `inject = ['tools', 'systemPrompt', 'codeRuntime']`.
-4. Tests: HMR-safety (dispose removes the tool, the section, and the listener); a waterfall test that the wire tool list is exactly `[run_code]` (spy adapter, asserting via `agent/request` and optionally `llm/stream`); an integration test that a program calling two tools returns only its printed/returned output (verify the world, not the self-report); a **serialization test** that `Promise.all([...])` over SDK calls does not overlap the underlying `ctx.tools.execute` invocations (a probe tool records enter/exit; assert no interleaving); `deriveMessages()` ignores `code/dispatch`; abort mid-program stops further dispatches; `CodeRunError` surfaces as `isError: true`; and the **unsafe-runtime refusal test** (§3, the VM-guard): with the unsafe flag unset, a non-mock agent's `run_code` is refused; with it set, the program runs.
-5. Wire an example: `examples/coding-agent-code-mode` (or a config flag on the existing example) loading the trio. Running it against the node:vm stub requires both opt-ins (`VmCodeRuntime({ unsafe: true })` and `code-mode`'s `allowUnsafeRuntime`); the example sets them explicitly and comments why, or uses a mock model — a real model never reaches the unsandboxed stub without those deliberate flags. Add a `pnpm run demo:*` entry.
-6. Docs: update [docs/architecture.md](../../../architecture.md) (a `ctx.codeRuntime` row in the service map, a Code Mode note under the tool pipeline / capability seams sections); add a [cookbook](../../../cookbook) note on writing a `CodeRuntime` backend; and **file the follow-up RFC for the hardened execution substrate** (the isolate/sandboxed-process design, the additional-language backends sketched in §1 — AssemblyScript/WASM, Python — with their per-language SDK generators, plus the tool-visibility-tier design skipped here). On landing, move this file to `implemented/` and update its row in [the RFC index](../../README.md).
-
-## Acceptance criteria
-
- The three packages exist and pass their suites: `dsh-code-runtime` (the abstract seam), `dsh-code-runtime-vm` (the reference stub whose constructor throws without `{ unsafe: true }`), and `dsh-code-mode` (SDK codegen, the lazy prompt section, the `agent/request` collapse, the `run_code` tool).
- The wire tool list is exactly `[run_code]` under the plugin (spy-adapter test); the generated SDK covers every registered tool, with non-identifier names reachable via quoted access.
- A program calling two tools returns only its curated output; `code/dispatch` events land in the session log and never enter derived history.
- `Promise.all` over SDK calls does not overlap the underlying `ctx.tools.execute` invocations (the per-run serialization queue holds); an abort stops further dispatches.
- With `allowUnsafeRuntime` unset over an unsafe runtime, `run_code` is not registered and the wire tool list is unchanged from native.
-
-## Risks
-
-node:vm is not a sandbox. This is the single biggest caveat. Withholding `require`/`process` is not a boundary; the MVP runs at harness trust only; the hardened substrate is a hard prerequisite before any untrusted use and is the explicit subject of a follow-up RFC. The guard is enforceable, not just documented: the runtime exposes `safe: boolean`, the VM stub throws unless constructed with `{ unsafe: true }`, and `code-mode` refuses to register `run_code` over an unsafe runtime unless separately acknowledged (`allowUnsafeRuntime`) — production misuse requires two deliberate, greppable flags, and the refusal path is tested.
-
-Wrong seam would leak tools. If the wire tool list were enforced only in `system-prompt/assemble`, a later `agent/request` listener could re-add tools. Mitigation: enforce `request.tools = [run_code]` in the `agent/request` waterfall (the authoritative seam, run last before `llm.stream()`) with `prepend: true`, and assert exactly one wire tool in tests. The residual `llm/stream` caveat is documented, not hidden.
-
-Concurrency before the contract supports it. The binding shape makes concurrent dispatch the default, and the tool contract has no concurrency-safety metadata yet, so unguarded `Promise.all` over SDK calls could race a not-yet-hardened tool. Mitigation: the MVP bindings enforce a per-run serialization queue (every `invoke` chains onto the previous), with a test asserting `Promise.all` from a program does not overlap the underlying `ctx.tools.execute` calls. Per-tool parallelism is unlocked only once a tool can declare itself concurrency-safe.
-
-Two presentation modes to keep coherent. A tool added later must work in both native and Code Mode. Mitigation: both the codegen thunk and the `agent/request` listener read `ctx.tools.schemas()`, so coverage is automatic; a test asserts every registered schema produces valid `.d.ts`, including non-identifier MCP names via quoted access.
-
-Type-erased runtime is not type-checked. The model can write code that type-checks against the advisory `.d.ts` but throws at runtime, and MCP-schema typing is best-effort. Mitigation: errors are captured as `CodeRunResult.error` and surfaced so the model can self-correct; the `.d.ts` is explicitly advisory.
-
-Lost observability of sub-calls. Routing everything through one `run_code` result hides the individual calls from the model — and could hide them from operators too. Mitigation: the plugin-declared `code/dispatch` event keeps every sub-call in the session log and UI without polluting model context.
-
-Abort granularity. node:vm cannot reliably interrupt hot synchronous code, and `ctx.tools.execute()` converts thrown aborts into `isError` data. Mitigation: the SDK bindings check `signal.aborted` and throw before/after each dispatch so an aborted sub-call stops the program; the vm stub wraps the run in a signal-tied timeout; the hardened substrate addresses the hot-loop case.
-
-Unsafe example wiring. A demo running a real model through the node:vm stub would hand model output ambient authority. Mitigation: examples are mock-model or explicitly marked unsafe; `code-runtime-vm` is labeled reference/test-only.
-
-Non-text sub-results dropped in the MVP. Image and other block types from sub-calls are not surfaced into the program yet. Mitigation: noted as a known limitation; block-type handling deferred.
@@ -30,4 +30,4 @@ An e2e assertion re-runs the command or re-reads the file externally; a keyword

 ## When a snapshot test is required

-Any change affecting the editor-facing transcript or end-to-end agent UX — the ACP bridge, the loop's observable output, tool presentation — adds or updates a scenario under `examples/acp-agent/tests/snapshots/` (or states in the PR why none applies). New capability seams, lifecycle shapes, or transcript surfaces name their coverage at every tier at plan time and verify the harness can express it — a harness gap is scheduled work, not a mid-build surprise.
+Any change affecting the editor-facing transcript or end-to-end agent UX — the ACP bridge, the loop's observable output, tool presentation — adds or updates a scenario in the owning example's snapshot suite (`examples/<name>/tests/snapshots/`, a scenario table over the [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) suite factory; `examples/acp-agent` is the primary suite), or states in the PR why none applies. New capability seams, lifecycle shapes, or transcript surfaces name their coverage at every tier at plan time and verify the harness can express it — a harness gap is scheduled work, not a mid-build surprise.
@@ -6,7 +6,7 @@ The DeepSeek Harness SDK agent demo exposed as an **Agent Client Protocol (ACP)*
 pnpm run demo:acp          # needs DEEPSEEK_API_KEY (repo-root .env or env)
 ```

-This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent) app (which bundles the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) spine, JSONL session persistence, and the `@deepseek-ai/dsh-acp` bridge — with **no pre-created agents**, since ACP `session/new` creates them on demand), the swappable DeepSeek, bash, and filesystem backends, and the model-facing `read`/`write`/`edit`/`subagent`/`subagent_fork`/`todo_write` tool entries. The app package bakes in the no-stdout-logger cluster, so a leaf has no logger entry to get wrong by default — keeping stdout pure for JSON-RPC.
+This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent) app (which bundles the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) spine, JSONL session persistence, and the `@deepseek-ai/dsh-acp` bridge — with **no pre-created agents**, since ACP `session/new` creates them on demand), the swappable DeepSeek, bash, and filesystem backends, the model-facing `read`/`write`/`edit`/`subagent`/`subagent_fork`/`todo_write` tool entries, and the advisory `repeat-tool-guard` loop-hygiene plugin. The app package bakes in the no-stdout-logger cluster, so a leaf has no logger entry to get wrong by default — keeping stdout pure for JSON-RPC.

 ## stdout is the protocol

@@ -33,6 +33,8 @@ flowchart LR
  cfg --> plugin_acp_tool_subagent_fork
  plugin_acp_tool_todo["tool-todo<br/>@deepseek-ai/dsh-tool-todo"]
  cfg --> plugin_acp_tool_todo
+  plugin_acp_repeat_tool_guard["repeat-tool-guard<br/>@deepseek-ai/dsh-repeat-tool-guard"]
+  cfg --> plugin_acp_repeat_tool_guard
  plugin_acp_fs_local["fs-local<br/>@deepseek-ai/dsh-fs-local"]
  cfg --> plugin_acp_fs_local
  plugin_acp_fs_policy["fs-policy<br/>@deepseek-ai/dsh-fs-policy"]
@@ -56,6 +58,7 @@ flowchart LR
 | `tool-subagent` | `@deepseek-ai/dsh-tool-subagent` |
 | `tool-subagent-fork` | `@deepseek-ai/dsh-tool-subagent` |
 | `tool-todo` | `@deepseek-ai/dsh-tool-todo` |
+| `repeat-tool-guard` | `@deepseek-ai/dsh-repeat-tool-guard` |
 | `fs-local` | `@deepseek-ai/dsh-fs-local` |
 | `fs-policy` | `@deepseek-ai/dsh-fs-policy` |
 | `tool-fs` | `@deepseek-ai/dsh-tool-fs` |
@@ -86,6 +86,14 @@
 - id: tool-todo
  name: '@deepseek-ai/dsh-tool-todo'

+# The repeat-tool-call guard: advisory reminders (injected context, never a
+# block) when the model re-issues the same tool call with identical arguments;
+# defaults [3, 5, 8]. Loaded here so the snapshot tier exercises the reminder
+# transcript (the repeat-tool-guard scenario) — no other scenario repeats a
+# call three times, so it is inert everywhere else.
+- id: repeat-tool-guard
+  name: '@deepseek-ai/dsh-repeat-tool-guard'
+
 # Filesystem capability stack: local provider, read-before-write/edit policy
 # gate, then the model-facing read/write/edit tools. Relative filesystem paths
 # resolve from the server launch cwd; the documented Zed setup launches this
@@ -57,8 +57,8 @@ interface Spawned {
 }

 // TODO(acp-test-harness): this subprocess/client boot glue is duplicated with
-// hooks.e2e.ts and partly with snapshot-harness.ts. Extract one shared ACP test
-// launcher before the TSX/env/permission-stub details drift again.
+// hooks.e2e.ts and partly with dsh-acp-snapshot's harness. Migrate both e2e
+// files onto that launcher before the TSX/env/permission-stub details drift.
 function spawnAcpAgent(cwd: string, env: NodeJS.ProcessEnv = process.env): Spawned {
  const child = spawn(
    process.execPath,
@@ -1,86 +1,24 @@
-import { readFile, readdir, writeFile } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
-import { describe, expect, it } from 'vitest'
-import { type HarvestedLog, type InputScript, runScenario } from './snapshot-harness.ts'
-import { type NormalizeContext, normalizeSessionLog, normalizeStdout, scrubRequestHeaders } from './snapshot-normalize.ts'
+import { defineAcpSnapshotSuite, type Scenario } from '@deepseek-ai/dsh-acp-snapshot'

 /**
- * ACP snapshot tests (REPLAY by default, keyless). Each scenario under
- * `snapshots/<name>/` ships an `input.json` (the client stdin script) and a
- * `session.jsonl` fixture; replay boots the real acp-agent subprocess, drives
- * it, and diffs the normalized stdout transcript against the committed
- * `stdout.golden.jsonl`. For model scenarios it ALSO checks the re-persisted
- * session log — against the `session.jsonl` fixture itself, not a separate
- * golden: the fixture doubles as the replay source (recorded scenarios) and the
- * expected produced log (both sides normalized before comparing).
- *
- * Request-header content (the composed system prompt + tool schemas riding on
- * `request/header` events) is pinned by exactly ONE scenario — the one with
- * `pinsHeader` — and scrubbed to `{{system}}`/`{{tools}}` tokens in every
- * other fixture and compare, so a prompt or tool-schema edit churns one
- * committed line instead of every fixture. A per-run uniformity guard keeps
- * the single pin sound: every live header must equal the pinned one, and no
- * header-delta may appear outside the pinning scenario (see the
- * pinned-header RFC,
- * docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md).
- *
- * `pnpm run test:snapshot:record` (DSH_SNAPSHOT=record + -u) re-records the
- * `session.jsonl` fixtures against the real API and refreshes the stdout golden
- * in one pass.
+ * The acp-agent example's snapshot suite: the scenario table for
+ * `dsh-acp-snapshot`'s suite factory, which owns every compare/guard mechanic
+ * (golden + re-persisted-log diffs, record write-back, the pinned-header
+ * uniformity guard, the fixture guards). Fixtures live under `snapshots/<name>/`;
+ * `pnpm run test:snapshot:record` re-records the `recorded` scenarios against
+ * the real API. See the package README (packages/support/acp-snapshot) and the
+ * snapshot RFC, docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md.
 */

-const SNAPSHOTS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'snapshots')
-const RECORDING = process.env.DSH_SNAPSHOT === 'record'
-
-/** A snapshot scenario and how its fixtures are produced. */
-interface Scenario {
-  name: string
-  /** Whether the scenario drives at least one model turn (so a JSONL golden applies). */
-  hasModelTurn: boolean
-  /**
-   * Whether the run persists a comparable session log to diff against the
-   * `session.jsonl` fixture. Defaults to {@link hasModelTurn} (a model turn
-   * always produces a log worth comparing). Set it independently for a scenario
-   * that produces a non-trivial log WITHOUT a model turn — e.g. a prompt blocked
-   * by a `UserPromptSubmit` hook, which opens a `rejected` turn carrying `hook/*`
-   * events but never calls the model.
-   */
-  comparesLog?: boolean
-  /**
-   * Whether `test:snapshot:record` regenerates this scenario's `session.jsonl`
-   * from the LIVE API. `recorded` scenarios are model-driven and reproducible;
-   * `authored` scenarios (a hand-written `replay.override.json` sidecar drives
-   * replay — e.g. a provider error or a cancel, which the live API can't be
-   * coaxed into deterministically — or a deterministic hook scenario whose
-   * derived empty script needs no sidecar) are NEVER re-recorded.
-   */
-  recorded: boolean
-  /**
-   * How many SUBAGENT child sessions this scenario records beyond the top-level
-   * one (0 for a single-session scenario). Each child rides in a sibling fixture
-   * `session.<n>.jsonl` (1-based); replay forwards them to `dsh-llm-replay` so
-   * each child session replays from its own script, and record mode writes the
-   * harvested child logs back to those files. Defaults to 0.
-   */
-  childSessions?: number
-  /**
-   * Whether THIS scenario's fixtures keep the full request-header content (the
-   * composed system prompt and tool schema list on `request/header` /
-   * `request/header-delta` events) and compare it verbatim. Exactly one
-   * scenario pins it; every other scenario stores and compares that content as
-   * `{{system}}`/`{{tools}}` tokens ({@link scrubRequestHeaders}), so a system
-   * prompt or tool-schema change shows up as ONE committed-fixture diff, not
-   * one per scenario. One pin suffices because header composition is
-   * suite-uniform (parent, spawn child, and fork child all compose the same
-   * prompt-modulo-cwd and the same tools) — and that premise is ASSERTED, not
-   * assumed: every non-pinning run's live headers must equal the pinned
-   * fixture's (normalized), so a session-dependent header (say, a restricted
-   * subagent toolset) fails loud until it gets its own pinning scenario.
-   * Defaults to false.
-   */
-  pinsHeader?: boolean
+// The dsh-acp-agent bin (the demo:acp entry), this example's cordis.yml, and
+// the repo-root tsconfig (four levels up from examples/acp-agent/tests) — all
+// ABSOLUTE: the subprocess cwd is a temp dir outside the repo.
+const AGENT = {
+  binScript: fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url)),
+  configPath: fileURLToPath(new URL('../cordis.yml', import.meta.url)),
+  tsconfigPath: fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)),
 }

 const SCENARIOS: Scenario[] = [
@@ -101,8 +39,13 @@ const SCENARIOS: Scenario[] = [
  { name: 'fs-read-window', hasModelTurn: true, recorded: true },
  { name: 'fs-policy-reject', hasModelTurn: true, recorded: true },
  { name: 'multi-turn', hasModelTurn: true, recorded: true },
-  { name: 'error-finish', hasModelTurn: true, recorded: false },
-  { name: 'cancel', hasModelTurn: true, recorded: false },
+  { name: 'error-finish', hasModelTurn: true, recorded: false, overridden: true },
+  // Keyless, authored (like error-finish/cancel): deterministically forcing a
+  // LIVE model to repeat one call three times is not a stable recording, so
+  // the fixture scripts five identical todo_write calls and pins BOTH reminder
+  // tiers (gentle at 3, detailed at 5) as context/message in transcript and log.
+  { name: 'repeat-tool-guard', hasModelTurn: true, recorded: false },
+  { name: 'cancel', hasModelTurn: true, recorded: false, overridden: true },
  { name: 'subagent-spawn', hasModelTurn: true, recorded: true, childSessions: 1 },
  { name: 'subagent-multi', hasModelTurn: true, recorded: true, childSessions: 2 },
  { name: 'subagent-fork', hasModelTurn: true, recorded: true, childSessions: 1 },
@@ -148,238 +91,9 @@ const SCENARIOS: Scenario[] = [
  { name: 'hook-codex-stop-continue', hasModelTurn: true, recorded: true },
 ]

-/** The single header-pinning scenario. Guarded here (and by a meta-test) so the pin cannot silently vanish. */
-const pinningScenario = SCENARIOS.find(s => s.pinsHeader === true)
-if (pinningScenario === undefined) throw new Error('acp.snapshot: no scenario pins the request-header content')
-
-/** The sibling child-fixture paths for a scenario (`session.1.jsonl` …). */
-function childFixturePaths(dir: string, childSessions: number): string[] {
-  return Array.from({ length: childSessions }, (_, i) => join(dir, `session.${i + 1}.jsonl`))
-}
-
-/**
- * Derive the {@link NormalizeContext} for a `session.jsonl` fixture from its own
- * header line (`{ type: 'session', id, cwd }`). A committed fixture carries the
- * session id and cwd of the run that harvested it — different from the live
- * replay run — so normalizing it against the live run's ctx would leave those
- * recorded values unscrubbed. Reading them from the header scrubs the fixture's
- * own id/cwd to the same `{{sessionId}}`/`{{cwd}}` tokens the replay output gets.
- * An authored fixture whose header is already normalized (`id:'{{sessionId}}'`,
- * `cwd:'{{cwd}}'`) yields those tokens as the volatile values, so scrubbing them
- * is an idempotent no-op. A header with no `cwd` falls back to a sentinel that
- * cannot occur in a log (NOT `''`, which `String.split` would match on every
- * character boundary and corrupt the output).
- */
-function fixtureContext(fixture: string): NormalizeContext {
-  const firstLine = fixture.split('\n').find(line => line.trim().length > 0) ?? '{}'
-  const header = JSON.parse(firstLine) as { id?: unknown; cwd?: unknown }
-  return {
-    sessionIds: typeof header.id === 'string' ? [header.id] : [],
-    cwd: typeof header.cwd === 'string' ? header.cwd : '\0no-cwd\0',
-  }
-}
-
-/**
- * The `data.header` payload of every `request/header` event in a session
- * JSONL, in log order, with the log's volatile values scrubbed first
- * ({@link normalizeSessionLog}) so headers harvested from different runs —
- * each embedding its own temp cwd in the composed prompt — compare on equal
- * footing.
- */
-function normalizedHeaders(rawLog: string, ctx: NormalizeContext): unknown[] {
-  return normalizeSessionLog(rawLog, ctx)
-    .split('\n')
-    .filter(line => line.trim().length > 0)
-    .map(line => JSON.parse(line) as { type?: unknown; data?: { header?: unknown } })
-    .filter(record => record.type === 'request/header')
-    .map(record => record.data?.header)
-}
-
-/** Count the `request/header-delta` events in a session JSONL. */
-function headerDeltaCount(rawLog: string): number {
-  return rawLog.split('\n')
-    .filter(line => line.trim().length > 0)
-    .filter(line => (JSON.parse(line) as { type?: unknown }).type === 'request/header-delta')
-    .length
-}
-
-for (const scenario of SCENARIOS) {
-  describe(`snapshot: ${scenario.name}`, () => {
-    // In RECORD mode, only re-run the `recorded` (live-API) scenarios; the
-    // `authored` ones (sidecar-driven errors/cancel) are never re-recorded.
-    it.skipIf(RECORDING && !scenario.recorded)('matches the goldens', async () => {
-      const dir = join(SNAPSHOTS_DIR, scenario.name)
-      const input = JSON.parse(await readFile(join(dir, 'input.json'), 'utf8')) as InputScript
-      const overrideFile = join(dir, 'replay.override.json')
-      const workspaceDir = join(dir, 'workspace')
-      const childSessions = scenario.childSessions ?? 0
-      const result = await runScenario(input, {
-        mode: RECORDING ? 'record' : 'replay',
-        fixtureFile: join(dir, 'session.jsonl'),
-        ...existsSync(overrideFile) ? { overrideFile } : {},
-        // In REPLAY, forward the recorded child fixtures so each subagent session
-        // replays from its own script. In RECORD they are harvested, not read.
-        ...!RECORDING && childSessions > 0 ? { childFiles: childFixturePaths(dir, childSessions) } : {},
-        ...existsSync(workspaceDir) ? { workspaceDir } : {},
-      })
-
-      // Scrub every volatile id the run produced: the ACP server-issued session
-      // id plus every harvested log's recorded id (a subagent child id never
-      // surfaces over ACP, but it appears in the child's own log header). The
-      // normalizer's UUID catch-all covers any we don't enumerate.
-      const ctx: NormalizeContext = {
-        sessionIds: [
-          ...result.sessionId !== undefined ? [result.sessionId] : [],
-          ...result.sessionLogs.map(l => l.id),
-        ],
-        cwd: result.cwd,
-      }
-
-      // RECORD mode (recorded model scenarios only): persist the freshly-harvested
-      // logs back to their fixtures — the primary to session.jsonl, each child to
-      // session.<n>.jsonl in harvest order. `--update` refreshes the Vitest
-      // goldens but NOT these fixtures, so write them here. A non-pinning
-      // scenario's fixtures are written header-scrubbed, so a re-record can
-      // never smuggle the full prompt/schema content back into every fixture.
-      const scrub = scenario.pinsHeader === true
-        ? (log: string): string => log
-        : scrubRequestHeaders
-      if (RECORDING && scenario.recorded && scenario.hasModelTurn) {
-        expect(result.sessionLogs.length, 'record produced no session log to harvest').toBeGreaterThan(0)
-        expect(result.sessionLogs.length, `expected ${childSessions + 1} session logs (parent + children)`)
-          .toBe(childSessions + 1)
-        await writeFile(join(dir, 'session.jsonl'), scrub((result.sessionLogs[0] as HarvestedLog).content))
-        for (let i = 1; i < result.sessionLogs.length; i++) {
-          await writeFile(join(dir, `session.${i}.jsonl`), scrub((result.sessionLogs[i] as HarvestedLog).content))
-        }
-      }
-
-      await expect(normalizeStdout(result.rawStdout, ctx))
-        .toMatchFileSnapshot(join(dir, 'stdout.golden.jsonl'))
-
-      // A model turn always produces a log worth comparing; a hook scenario can
-      // produce one without a model turn (a `rejected` turn carrying `hook/*`).
-      const comparesLog = scenario.comparesLog ?? scenario.hasModelTurn
-      if (comparesLog) {
-        // The harvested logs (primary-first) must match their committed fixtures
-        // 1:1. Each side passes through normalizeSessionLog, scrubbed against ITS
-        // OWN volatile values — the live run's via `ctx`, the committed fixture's
-        // via its own header (a committed file cannot share the live run's ids).
-        // Unless this scenario pins the header, both sides ALSO pass through
-        // scrubRequestHeaders: the live log carries the real prompt/schemas, the
-        // fixture carries the `{{system}}`/`{{tools}}` tokens, and the scrub is
-        // idempotent — so the compare checks the header's presence, position,
-        // reason, and config, but not its bulk content (pinned once, in the
-        // `pinsHeader` scenario).
-        expect(result.sessionLogs.length, 'this scenario must persist a session log').toBe(childSessions + 1)
-        const fixtureFiles = ['session.jsonl', ...Array.from({ length: childSessions }, (_, i) => `session.${i + 1}.jsonl`)]
-        for (let i = 0; i < fixtureFiles.length; i++) {
-          const harvested = scrub((result.sessionLogs[i] as HarvestedLog).content)
-          const fixture = scrub(await readFile(join(dir, fixtureFiles[i] as string), 'utf8'))
-          expect(normalizeSessionLog(harvested, ctx), `${fixtureFiles[i]} mismatch`)
-            .toEqual(normalizeSessionLog(fixture, fixtureContext(fixture)))
-        }
-      }
-
-      // Header-uniformity guard: the single pin is sound only while every
-      // session in the suite composes the SAME header and keeps it for the
-      // whole run. Assert both halves live. (1) Every request/header the run
-      // produced (parent, spawn child, fork child, initial or resume) must
-      // equal the pinned fixture's header after each side is normalized
-      // against its own volatile values. (2) No request/header-delta may
-      // appear at all — a mid-run header change diverges from the pin by
-      // construction, and its content would be invisible under the scrub. If
-      // either fails, either the header changed (update the pin: re-record or
-      // hand-edit the pinning scenario's fixture) or composition became
-      // session-dependent by design (give the divergent shape its own
-      // pinning scenario).
-      if (scenario.pinsHeader !== true) {
-        const pinnedFixture = await readFile(join(SNAPSHOTS_DIR, pinningScenario.name, 'session.jsonl'), 'utf8')
-        const pinned = normalizedHeaders(pinnedFixture, fixtureContext(pinnedFixture))
-        expect(pinned.length, `the pinning fixture (${pinningScenario.name}) must carry exactly one request/header`)
-          .toBe(1)
-        for (const log of result.sessionLogs) {
-          expect(headerDeltaCount(log.content), `session ${log.id}: a request/header-delta in a non-pinning scenario`)
-            .toBe(0)
-          const headers = normalizedHeaders(log.content, ctx)
-          for (const [k, header] of headers.entries()) {
-            expect(header, `session ${log.id}: request/header #${k + 1} diverged from the pinned (${pinningScenario.name}) header`)
-              .toEqual(pinned[0])
-          }
-        }
-      }
-    })
-  })
-}
-
-describe('snapshot fixtures', () => {
-  it('every scenario directory is registered (no orphans)', async () => {
-    // toMatchFileSnapshot does not prune orphaned golden/fixture files, so a
-    // renamed/removed scenario could leave a stale dir that nothing exercises.
-    // Fail loud on any snapshots/<dir> not present in SCENARIOS.
-    const entries = await readdir(SNAPSHOTS_DIR, { withFileTypes: true })
-    const onDisk = entries.filter(e => e.isDirectory()).map(e => e.name).sort()
-    const registered = SCENARIOS.map(s => s.name).sort()
-    expect(onDisk).toEqual(registered)
-  })
-
-  it('every registered scenario has its required fixture files', async () => {
-    // Every scenario has an input script and an stdout golden. EVERY scenario
-    // also needs `session.jsonl`: the harness boots `llm-replay` with that path
-    // as the replay source for ALL scenarios (acp.snapshot.ts passes
-    // `fixtureFile: <dir>/session.jsonl` unconditionally), and `loadReplayScript`
-    // throws "fixture not found" when it is absent and no override replaces it.
-    // A no-model scenario ships a header-only `session.jsonl` (it derives to an
-    // empty script — no model call is made); a model scenario's fixture also
-    // doubles as the expected-log artifact the run is diffed against. An authored
-    // (non-`recorded`) model scenario additionally ships a `replay.override.json`
-    // sidecar for the throw/hang cases a derived script cannot express.
-    for (const { name, hasModelTurn, recorded, childSessions } of SCENARIOS) {
-      const dir = join(SNAPSHOTS_DIR, name)
-      expect(existsSync(join(dir, 'input.json')), `${name}/input.json`).toBe(true)
-      expect(existsSync(join(dir, 'stdout.golden.jsonl')), `${name}/stdout.golden.jsonl`).toBe(true)
-      expect(existsSync(join(dir, 'session.jsonl')), `${name}/session.jsonl`).toBe(true)
-      if (hasModelTurn && !recorded) {
-        expect(existsSync(join(dir, 'replay.override.json')), `${name}/replay.override.json`).toBe(true)
-      }
-      // A nested-agent scenario ships one child fixture per recorded subagent
-      // session (`session.1.jsonl` …), the replay source for that child session.
-      for (const childFixture of childFixturePaths(dir, childSessions ?? 0)) {
-        expect(existsSync(childFixture), childFixture).toBe(true)
-      }
-    }
-  })
-
-  it('exactly one scenario pins the request-header content', () => {
-    // Zero pins would drop the prompt/schema surface from the suite entirely;
-    // two would split it. The single pin is the design (pinned-header RFC).
-    expect(SCENARIOS.filter(s => s.pinsHeader === true).map(s => s.name)).toEqual(['text-turn'])
-  })
-
-  it('committed fixtures carry request-header content ONLY in the pinning scenario', async () => {
-    // The whole point of the pin: a system-prompt or tool-schema change must
-    // churn exactly one committed line. A non-pinning fixture that carries the
-    // full header (a hand-recorded file, or a header line hand-edited out of
-    // its canonical JSON form) silently reopens the suite-wide churn, so fail
-    // loud here: every non-pinning session*.jsonl must be a fixed point of
-    // scrubRequestHeaders (apply the scrub to fix a violation), and the
-    // pinning scenario's fixtures must NOT be (their content IS the pin).
-    for (const scenario of SCENARIOS) {
-      const dir = join(SNAPSHOTS_DIR, scenario.name)
-      const files = [
-        'session.jsonl',
-        ...Array.from({ length: scenario.childSessions ?? 0 }, (_, i) => `session.${i + 1}.jsonl`),
-      ]
-      for (const file of files) {
-        const fixture = await readFile(join(dir, file), 'utf8')
-        if (scenario.pinsHeader === true) {
-          expect(scrubRequestHeaders(fixture), `${scenario.name}/${file} must PIN the full header content`)
-            .not.toEqual(fixture)
-        } else {
-          expect(scrubRequestHeaders(fixture), `${scenario.name}/${file} carries unscrubbed header content`)
-            .toEqual(fixture)
-        }
-      }
-    }
-  })
+defineAcpSnapshotSuite({
+  agent: AGENT,
+  snapshotsDir: join(dirname(fileURLToPath(import.meta.url)), 'snapshots'),
+  scenarios: SCENARIOS,
+  mode: process.env.DSH_SNAPSHOT === 'record' ? 'record' : 'replay',
 })
@@ -0,0 +1,7 @@
+{
+  "steps": [
+    { "op": "initialize" },
+    { "op": "newSession" },
+    { "op": "prompt", "text": "Write the todo list 'watch the kettle boil' five times in a row without changing it, then reply DONE." }
+  ]
+}
@@ -0,0 +1,70 @@
+{"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}"}
+{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Write the todo list 'watch the kettle boil' five times in a row without changing it, then reply DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":0,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_1","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}
+{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_1","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}}
+{"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":9,"time":0,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"call_1","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[4,5,6,7,8],"surfaceOp":"append"}
+{"type":"tool/call","seq":10,"time":0,"data":{"turn":1,"step":1,"callId":"call_1","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}
+{"type":"todo/write","seq":11,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}}
+{"type":"tool/result","seq":12,"time":0,"data":{"turn":1,"step":1,"callId":"call_1","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[10],"surfaceOp":"append"}
+{"type":"step/end","seq":13,"time":0,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":14,"time":0,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"call_2","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}
+{"type":"assistant/chunk","seq":17,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_2","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}}
+{"type":"assistant/chunk","seq":18,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":19,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":20,"time":0,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"call_2","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[15,16,17,18,19],"surfaceOp":"append"}
+{"type":"tool/call","seq":21,"time":0,"data":{"turn":1,"step":2,"callId":"call_2","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}
+{"type":"todo/write","seq":22,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}}
+{"type":"tool/result","seq":23,"time":0,"data":{"turn":1,"step":2,"callId":"call_2","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[21],"surfaceOp":"append"}
+{"type":"step/end","seq":24,"time":0,"data":{"turn":1,"step":2}}
+{"type":"step/start","seq":25,"time":0,"data":{"turn":1,"step":3}}
+{"type":"assistant/chunk","seq":26,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":27,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"tool-call-delta","index":0,"id":"call_3","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}
+{"type":"assistant/chunk","seq":28,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_3","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}}
+{"type":"assistant/chunk","seq":29,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":30,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":31,"time":0,"data":{"turn":1,"step":3,"content":[{"type":"tool-call","id":"call_3","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[26,27,28,29,30],"surfaceOp":"append"}
+{"type":"tool/call","seq":32,"time":0,"data":{"turn":1,"step":3,"callId":"call_3","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}
+{"type":"todo/write","seq":33,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}}
+{"type":"tool/result","seq":34,"time":0,"data":{"turn":1,"step":3,"callId":"call_3","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[32],"surfaceOp":"append"}
+{"type":"context/message","seq":35,"time":0,"data":{"content":[{"type":"text","text":"You are repeating the exact same tool call with identical arguments. Carefully analyze the previous result before calling again: if the task is not complete, try a different approach or different arguments instead of repeating the call."}],"source":{"kind":"plugin","plugin":"repeat-tool-guard"}},"surfaceOp":"append"}
+{"type":"step/end","seq":36,"time":0,"data":{"turn":1,"step":3}}
+{"type":"step/start","seq":37,"time":0,"data":{"turn":1,"step":4}}
+{"type":"assistant/chunk","seq":38,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":39,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"tool-call-delta","index":0,"id":"call_4","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}
+{"type":"assistant/chunk","seq":40,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_4","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}}
+{"type":"assistant/chunk","seq":41,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":42,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":43,"time":0,"data":{"turn":1,"step":4,"content":[{"type":"tool-call","id":"call_4","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[38,39,40,41,42],"surfaceOp":"append"}
+{"type":"tool/call","seq":44,"time":0,"data":{"turn":1,"step":4,"callId":"call_4","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}
+{"type":"todo/write","seq":45,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}}
+{"type":"tool/result","seq":46,"time":0,"data":{"turn":1,"step":4,"callId":"call_4","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[44],"surfaceOp":"append"}
+{"type":"step/end","seq":47,"time":0,"data":{"turn":1,"step":4}}
+{"type":"step/start","seq":48,"time":0,"data":{"turn":1,"step":5}}
+{"type":"assistant/chunk","seq":49,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":50,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"tool-call-delta","index":0,"id":"call_5","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}
+{"type":"assistant/chunk","seq":51,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_5","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}}
+{"type":"assistant/chunk","seq":52,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":53,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":54,"time":0,"data":{"turn":1,"step":5,"content":[{"type":"tool-call","id":"call_5","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[49,50,51,52,53],"surfaceOp":"append"}
+{"type":"tool/call","seq":55,"time":0,"data":{"turn":1,"step":5,"callId":"call_5","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}
+{"type":"todo/write","seq":56,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}}
+{"type":"tool/result","seq":57,"time":0,"data":{"turn":1,"step":5,"callId":"call_5","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[55],"surfaceOp":"append"}
+{"type":"context/message","seq":58,"time":0,"data":{"content":[{"type":"text","text":"Repeated tool call detected:\n- tool: todo_write\n- consecutive_calls: 5\n- arguments: {\"todos\":[{\"content\":\"watch the kettle boil\",\"status\":\"in_progress\"}]}\nThe repeated calls are not making progress. Do not call this tool with these exact arguments again. Inspect the latest result and choose a different action, different arguments, or finish the task if enough evidence has been gathered."}],"source":{"kind":"plugin","plugin":"repeat-tool-guard"}},"surfaceOp":"append"}
+{"type":"step/end","seq":59,"time":0,"data":{"turn":1,"step":5}}
+{"type":"step/start","seq":60,"time":0,"data":{"turn":1,"step":6}}
+{"type":"assistant/chunk","seq":61,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":62,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"text-delta","index":0,"text":"DONE."}}}
+{"type":"assistant/chunk","seq":63,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE."}}}}
+{"type":"assistant/chunk","seq":64,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":65,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":66,"time":0,"data":{"turn":1,"step":6,"content":[{"type":"text","text":"DONE."}],"usage":{"inputTokens":10,"outputTokens":3}},"sourceEventSeqs":[61,62,63,64,65],"surfaceOp":"append"}
+{"type":"step/end","seq":67,"time":0,"data":{"turn":1,"step":6}}
+{"type":"turn/end","seq":68,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}
@@ -0,0 +1,19 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_1","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_1","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_2","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_2","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_3","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_3","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_4","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_4","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_5","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_5","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"DONE."}}}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}
@@ -9,7 +9,7 @@
        "examples/echo-agent/tests/**/*.e2e.ts",
        "examples/coding-agent/tests/**/*.e2e.ts",
        "examples/acp-agent/tests/**/*.e2e.ts",
-        "examples/acp-agent/tests/**/*.snapshot.ts"
+        "examples/*/tests/**/*.snapshot.ts"
      ],
      "project": ["scripts/**/*.ts", "examples/**/*.ts"]
    },
@@ -21,6 +21,11 @@
      "project": ["src/**/*.ts"],
      "ignoreDependencies": ["cordis"]
    },
+    "packages/support/acp-snapshot": {
+      "entry": ["tests/**/*.spec.ts", "tests/fixtures/fake-acp-agent.ts"],
+      "project": ["src/**/*.ts", "tests/**/*.ts"],
+      "ignoreDependencies": ["cordis"]
+    },
    "packages/core/agent-loop": {
      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
      "project": ["src/**/*.ts", "tests/**/*.ts"]
@@ -11,11 +11,13 @@ Packages are grouped by modular role at `packages/<group>/<pkg>/`. The group dir
 | [`core/`](core/README.md) | Product API spine: session, system-prompt, tools, agent, 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 | Product — stable surface |
 | [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools | Product — stable surface |
 | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
 | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface |
 | [`web/`](web/README.md) | Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface |
-| [`todo/`](todo/README.md) | Todo/planning family: the model-facing `todo_write` tool (whole-list task tracking on the session log) | Product — stable surface |
+| [`todo/`](todo/README.md) | Todo/planning family: the model-facing `todo_write` tool | Product — stable surface |
+| [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders | Product — stable surface |
 | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
 | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface |
 | [`ui/`](ui/README.md) | Editor/client integration surfaces (the ACP bridge) + the app packages | Product — stable surface |
@@ -0,0 +1,9 @@
+# code-runtime/ — code-execution capability family
+
+The code-execution capability seam (see [capability seams](../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)): an abstract runtime interface for executing one model-written program against host-provided async bindings, capturing what it printed and returned. The consumer is the tool registry's Code Mode, and the first implementation (a Node worker-thread backend) is specified alongside it in the [Code Mode RFC](../../docs/rfc/proposed/feature/2026-06-15-code-mode.md). **Product** packages.
+
+| Package | Role | ctx key |
+|---|---|---|
+| `code-runtime/` | Abstract code-execution seam (interface + vocabulary) | `ctx.codeRuntime` |
+
+The interface lives at `code-runtime/code-runtime/`. Backends differ by execution substrate (worker thread, process, container) and by source language — both readonly descriptors on the service — and register `ctx.codeRuntime` without touching the interface or its consumer; that split is what makes a hardened backend a drop-in later.
@@ -0,0 +1,19 @@
+# @deepseek-ai/dsh-code-runtime
+
+The **code-execution seam**: an abstract `CodeRuntime` service (`ctx.codeRuntime`) defining WHAT a code runtime does — run one model-written program against a set of host-provided async bindings and report `{ value, logs, error? }` — without saying HOW.
+
+This package is the interface third of the capability (the bash trio is the template — see [capability seams](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)): implementations subclass `CodeRuntime` and register the service; the consumer is the tool registry's Code Mode, which generates the model-facing SDK and bridges tool dispatch — both specified in the [Code Mode RFC](../../../docs/rfc/proposed/feature/2026-06-15-code-mode.md), whose first implementation is a Node worker-thread backend. The runtime knows nothing about tools or sessions: it is handed named async functions and a program string, and everything tool-shaped stays with the consumer.
+
+## Service API (`ctx.codeRuntime`)
+
+| Member | Semantics |
+|---|---|
+| `run(request)` | Execute one program against the request's bindings. **Resolves with an error FIELD for every program outcome** — parse/transform failure, thrown exception, budget expiry, abort, substrate death (`CodeRunFailure`'s orthogonal `kind` taxonomy); it rejects only for caller misuse of the seam itself (e.g. a run submitted after disposal). The program runs as the body of an async function: top-level `await`/`return` work, and the completion value becomes `result.value` when it survives the serialization boundary. |
+| `language` | Readonly descriptor: the source language `run` expects (`'typescript'` is the well-known value). Informational, not gating — a consumer that generates language-specific presentation switches on it and fails loud on a language it cannot present. |
+| `isolation` | Readonly descriptor: the execution substrate (`'worker-thread'`, `'process'`, `'container'`). A label for deployments and diagnostics, **not a security claim**. |
+
+Semantics every implementation must honor (contract details in the class JSDoc): binding calls bridge to the caller's functions verbatim with structured-cloneable arguments/resolutions; the program is treated as a hostile peer (arbitrary binding names are own properties, malformed traffic never crashes the host); no state survives between runs; disposal terminates in-flight runs AND awaits their exit before completing.
+
+## Vocabulary
+
+`CodeRunRequest` (`program`, `bindings`, `signal?`) carries everything the runtime acts on — defaulting (time budgets, output caps) is the implementation's validated config, never a hidden `??` inside `run()`. `bindings` is a list of `CodeBindingNamespace`s (`global` + `functions`), each exposed to the program as one global object of async callables. `CodeRunResult` reports the completion `value?`, the ordered `logs` (`CodeLogEntry`: `console`/`stdout`/`stderr` source, console `level`, capped text), and the `error?` (`CodeRunFailure`: `kind` + model-feedable `message`). See `src/types.ts` for the full contracts.
@@ -0,0 +1,30 @@
+{
+  "name": "@deepseek-ai/dsh-code-runtime",
+  "description": "Abstract code-execution seam (ctx.codeRuntime) for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "cordis": "^4.0.0-rc.6"
+  }
+}
@@ -0,0 +1,93 @@
+/**
+ * The code-execution seam (`ctx.codeRuntime`): an abstract service defining
+ * WHAT a code runtime does — run one model-written program against a set of
+ * host-provided async bindings and report `{ value, logs, error? }` — without
+ * saying HOW. Implementations subclass {@link CodeRuntime} and register
+ * themselves as the `codeRuntime` service; backends may differ by execution
+ * substrate (worker thread, separate process, container) and by source
+ * language, both declared as readonly descriptors. The design and its
+ * consumer (the tool registry's Code Mode) are specified in the Code Mode RFC
+ * (docs/rfc/proposed/feature/2026-06-15-code-mode.md).
+ *
+ * The split mirrors the bash seam (`BashExecutor`): the runtime knows nothing
+ * about tools or sessions — it is handed named async functions and a program,
+ * and everything tool-shaped stays with the consumer.
+ *
+ * @module @deepseek-ai/dsh-code-runtime
+ */
+
+import { Context, Service } from 'cordis'
+import type { CodeRunRequest, CodeRunResult } from './types.ts'
+
+export type {
+  CodeBindingFunction,
+  CodeBindingNamespace,
+  CodeLogEntry,
+  CodeRunFailure,
+  CodeRunRequest,
+  CodeRunResult,
+} from './types.ts'
+
+declare module 'cordis' {
+  interface Context {
+    codeRuntime: CodeRuntime
+  }
+}
+
+/**
+ * Abstract code-execution service. Subclass, implement {@link run} and the
+ * two descriptors, and load the subclass as a plugin — it registers as
+ * `ctx.codeRuntime` (one implementation per context; loading a second throws,
+ * cordis' standard duplicate-service behavior).
+ *
+ * Semantics every implementation must honor:
+ * - {@link run} resolves with an error FIELD for every program outcome —
+ *   parse/transform failures, thrown exceptions, budget expiry, abort,
+ *   substrate death ({@link CodeRunFailure}'s taxonomy). It REJECTS only for
+ *   caller misuse of the seam itself (e.g. a run submitted after disposal).
+ * - Binding calls bridge to the caller's {@link CodeBindingFunction}s
+ *   verbatim; arguments and resolutions must be structured-cloneable, and the
+ *   runtime treats the program as a hostile peer (arbitrary binding names are
+ *   own properties, malformed traffic is rejected or ignored, never crashes
+ *   the host).
+ * - Runs are isolated from each other: no state survives from one run to the
+ *   next through the runtime.
+ * - Disposal reaches quiescence: in-flight runs are terminated AND awaited
+ *   before the service's own teardown completes (no orphan substrate survives
+ *   `fiber.dispose()`).
+ */
+export abstract class CodeRuntime extends Service {
+  /**
+   * The source language {@link run} expects `program` to be written in, as a
+   * lowercase identifier. Informational, not gating — a consumer that
+   * generates language-specific presentation (typed SDK stubs, usage
+   * instructions) switches on it and fails loud on a language it cannot
+   * present. Well-known value: `'typescript'`.
+   */
+  abstract readonly language: string
+
+  /**
+   * The execution substrate, as a lowercase identifier. Informational, not
+   * gating — a descriptor so deployments and diagnostics can tell backends
+   * apart, not a security claim. Well-known values: `'worker-thread'`,
+   * `'process'`, `'container'`.
+   */
+  abstract readonly isolation: string
+
+  constructor(ctx: Context) {
+    super(ctx, 'codeRuntime')
+  }
+
+  /**
+   * Execute one program against the request's bindings and capture what it
+   * emitted. See the class doc for the resolution contract (error is a result
+   * field; rejection means seam misuse only).
+   * @param request - the program, its bindings, and the abort signal; the
+   *   request carries everything the runtime acts on, with no hidden defaults.
+   * @returns the run's outcome: completion value (when transferable), the
+   *   ordered log capture, and the failure (if any).
+   */
+  abstract run(request: CodeRunRequest): Promise<CodeRunResult>
+}
+
+export default CodeRuntime
@@ -0,0 +1,105 @@
+/**
+ * Vocabulary types for the code-execution seam: what a caller hands a
+ * {@link ../index.ts | CodeRuntime} and what it gets back. Pure types — no
+ * runtime code lives here.
+ *
+ * @module @deepseek-ai/dsh-code-runtime/src/types
+ */
+
+/**
+ * One host-side function exposed to the program as an async callable. The
+ * runtime bridges calls to it (possibly across a serialization boundary), so
+ * `args` and the resolution value MUST be structured-cloneable; a runtime
+ * rejects a non-cloneable value with a descriptive error rather than
+ * corrupting the run. A rejection of this function surfaces inside the
+ * program as a rejection of the corresponding call.
+ */
+export type CodeBindingFunction = (args: unknown) => Promise<unknown>
+
+/**
+ * A named group of {@link CodeBindingFunction}s the runtime exposes to the
+ * program as one global object (e.g. `tools`). Function names are arbitrary
+ * strings — a runtime must treat names like `__proto__` or `constructor` as
+ * ordinary own properties (null-prototype construction), never as prototype
+ * collisions.
+ */
+export interface CodeBindingNamespace {
+  /** The global identifier the program sees (must be a valid JS identifier). */
+  global: string
+  /** The callable members, keyed by the exact name the program calls. */
+  functions: Record<string, CodeBindingFunction>
+}
+
+/**
+ * One run: the program source plus everything the runtime acts on. Per the
+ * explicit-over-implicit convention, defaulting (time budgets, output caps)
+ * is the implementation's validated config — a request carries no optional
+ * tuning knobs for a hidden `??` to fill in.
+ */
+export interface CodeRunRequest {
+  /**
+   * The program source, in the runtime's {@link ../index.ts | language}. It
+   * runs as the body of an async function: top-level `await` and `return`
+   * are available, and the completion value becomes
+   * {@link CodeRunResult.value}.
+   */
+  program: string
+  /** Host functions exposed to the program, one global object per namespace. */
+  bindings: CodeBindingNamespace[]
+  /**
+   * Abort the run: the runtime stops the program (hard, even mid-loop) and
+   * resolves with a {@link CodeRunFailure} of kind `'abort'`. In-flight
+   * binding calls are the CALLER's to settle — the runtime only stops asking.
+   */
+  signal?: AbortSignal
+}
+
+/**
+ * One captured output entry, in emission order. `source` says which channel
+ * produced it: the program's `console` (shimmed by the runtime), or a stray
+ * write to the underlying stdout/stderr streams.
+ */
+export interface CodeLogEntry {
+  /** Which channel produced the text. */
+  source: 'console' | 'stdout' | 'stderr'
+  /** The console method used; present only when `source` is `'console'`. */
+  level?: 'log' | 'info' | 'warn' | 'error' | 'debug'
+  /** The captured text (possibly truncated by the implementation's caps, marked in-band). */
+  text: string
+}
+
+/**
+ * Why a run failed. The kinds are orthogonal outcomes reported independently
+ * (per docs/defensive-patterns.md): a budget expiry is not an exception, an
+ * abort is not a timeout, and a substrate death is neither.
+ *
+ * - `'exception'` — the program threw or failed to parse/transform.
+ * - `'timeout'` — an implementation-owned budget expired; the message says which.
+ * - `'abort'` — {@link CodeRunRequest.signal} fired.
+ * - `'worker-exit'` — the execution substrate died without settling (e.g. OOM).
+ */
+export interface CodeRunFailure {
+  /** The failure class (see the interface doc for each kind's meaning). */
+  kind: 'exception' | 'timeout' | 'abort' | 'worker-exit'
+  /** Human-readable detail, suitable for feeding back to a model to self-correct. */
+  message: string
+}
+
+/**
+ * The outcome of one run. An error is a FIELD on a resolved result, never a
+ * rejection of `run()` — reporting a failed program is the caller's job, not
+ * an exception path.
+ */
+export interface CodeRunResult {
+  /**
+   * The program's completion value (its top-level `return`), when it ran to
+   * completion and the value survived the runtime's serialization boundary;
+   * a non-transferable value is replaced by a string rendering, and a failed
+   * or value-less run leaves this absent.
+   */
+  value?: unknown
+  /** Everything the program emitted, in order (capped by the implementation). */
+  logs: CodeLogEntry[]
+  /** Present iff the run failed; see {@link CodeRunFailure} for the taxonomy. */
+  error?: CodeRunFailure
+}
@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
+import type { CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtime'
+
+/**
+ * Minimal concrete runtime: records requests, "executes" by invoking every
+ * binding once in declaration order, and lets tests script the outcome. The
+ * seam package ships no implementation, so the contract is exercised through
+ * the smallest subclass that honors it.
+ */
+class StubRuntime extends CodeRuntime {
+  readonly language = 'typescript'
+  readonly isolation = 'in-process-stub'
+  requests: CodeRunRequest[] = []
+  nextResult: CodeRunResult = { logs: [] }
+
+  async run(request: CodeRunRequest): Promise<CodeRunResult> {
+    this.requests.push(request)
+    if (request.signal?.aborted) {
+      return { logs: [], error: { kind: 'abort', message: String(request.signal.reason) } }
+    }
+    for (const namespace of request.bindings) {
+      for (const fn of Object.values(namespace.functions)) {
+        await fn({ from: 'stub' })
+      }
+    }
+    return this.nextResult
+  }
+}
+
+async function setup() {
+  const ctx = new Context()
+  await ctx.plugin(StubRuntime)
+  const runtime = ctx.codeRuntime as StubRuntime
+  return { ctx, runtime }
+}
+
+describe('CodeRuntime service seam', () => {
+  it('registers as ctx.codeRuntime and serves the abstract API', async () => {
+    const { runtime } = await setup()
+    expect(runtime.language).toBe('typescript')
+    expect(runtime.isolation).toBe('in-process-stub')
+
+    const calls: unknown[] = []
+    const result = await runtime.run({
+      program: 'return 1',
+      bindings: [{ global: 'tools', functions: { probe: async args => void calls.push(args) } }],
+    })
+    expect(result).toEqual({ logs: [] })
+    expect(calls).toEqual([{ from: 'stub' }])
+    expect(runtime.requests).toHaveLength(1)
+  })
+
+  it('reports a failed run as an error field on a resolved result, never a rejection', async () => {
+    const { runtime } = await setup()
+    runtime.nextResult = {
+      logs: [{ source: 'console', level: 'error', text: 'boom' }],
+      error: { kind: 'exception', message: 'boom' },
+    }
+    const result = await runtime.run({ program: 'throw new Error("boom")', bindings: [] })
+    expect(result.error).toEqual({ kind: 'exception', message: 'boom' })
+    expect(result.value).toBeUndefined()
+  })
+
+  it('reports a pre-aborted signal as an abort failure', async () => {
+    const { runtime } = await setup()
+    const controller = new AbortController()
+    controller.abort('cancelled')
+    const result = await runtime.run({ program: 'return 1', bindings: [], signal: controller.signal })
+    expect(result.error).toEqual({ kind: 'abort', message: 'cancelled' })
+  })
+
+  it('is removed from the context when the providing fiber disposes (HMR safety)', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(StubRuntime)
+    expect(ctx.get('codeRuntime')).toBeInstanceOf(StubRuntime)
+
+    await fiber.dispose()
+    expect(ctx.get('codeRuntime')).toBeUndefined()
+  })
+
+  it('rejects a second implementation in the same context (duplicate service)', async () => {
+    const { ctx } = await setup()
+    await expect(ctx.plugin(StubRuntime)).rejects.toThrow(/registered/)
+  })
+})
@@ -0,0 +1,18 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    }
+  ]
+}
@@ -0,0 +1,9 @@
+# guard/ — loop-hygiene guard family
+
+Behavioral guard plugins that watch the agent loop for unproductive patterns and nudge the model back on course. A single **product** package — there is no interface/implementation seam here, because a guard is a self-contained consumer of existing core seams (`tools/post-execute`, `agent/prompt-submit`, `agent/status`), not a swappable capability.
+
+| Package | Role | ctx key |
+|---|---|---|
+| `repeat-tool-guard/` | Advisory reminders when an agent loops on identical tool calls | (listens on `ctx.tools`' waterfalls) |
+
+Reminders travel as `additionalContext` on the `tools/post-execute` decision; the agent loop appends them as logged `context/message` events after the step's tool results (see [the tools package](../core/tools)), so everything a guard says to the model is reconstructable from the session log.
@@ -0,0 +1,37 @@
+# @deepseek-ai/dsh-repeat-tool-guard
+
+An advisory loop-breaker, not a model-facing tool: it never appears in the tool list, never vetoes or rewrites a call, and adds exactly one behavior — it watches each agent's stream of tool calls, counts runs of consecutive calls to the same tool with identical canonicalized arguments, and at configured run lengths injects an escalating advisory reminder telling the model to stop repeating itself, re-read the last result, and either change approach or conclude. The decision (retry differently, gather more evidence, or finish) stays entirely with the model: a legitimately repeated call is delayed by nothing and blocked by nothing. Decision record: [the repeat-tool-guard RFC](../../../docs/rfc/implemented/feature/2026-07-08-repeat-tool-guard.md).
+
+## Config
+
+```yaml
+- id: repeat-tool-guard
+  name: '@deepseek-ai/dsh-repeat-tool-guard'
+  config:
+    thresholds: [3, 5, 8]        # default; consecutive counts that trigger a reminder
+    include: []                  # tool-name patterns to track; empty ⇒ all tools
+    exclude: [todo_write]        # tool-name patterns transparent to the chain
+    argumentsPreviewChars: 500   # default; cap on arguments quoted in the detailed reminder
+```
+
+`thresholds` fails loud at plugin load: an empty list, a non-integer, a value below 2, or a duplicate throws, never a silent fall-back to defaults; `argumentsPreviewChars` equally rejects anything but an integer >= 1. The list is normalized to ascending order; the FIRST threshold delivers a short generic nudge, every later threshold delivers the detailed form naming the tool, the run length, and the canonical arguments — head-truncated at `argumentsPreviewChars` with an omitted-count marker, so a looping `write`/`edit` payload cannot ride into the next request unbounded (the chain key always compares the FULL canonical string; the cap bounds the reminder, never the detection).
+
+`include`/`exclude` entries support `*` wildcards and are predicates over whatever tools exist at call time, not references to registry entries — a pattern matching no currently registered tool is NOT an error (`exclude: [mcp_*]` stays valid in a deployment that loads no MCP tools), unlike `toolOrder`'s referent check.
+
+## Chain semantics
+
+The chain key is `(tool name, canonical arguments)` — canonicalization is a deep key-sort plus `JSON.stringify`, so argument objects differing only in property order count as identical. A call identical to the previous tracked call increments the agent's consecutive counter; a different tracked call resets it to 1.
+
+- **Untracked calls are transparent to the chain.** A call excluded by `include`/`exclude` neither increments nor resets the counter, so `grep X → todo_write → grep X` still counts as two consecutive `grep X` when `todo_write` is excluded. This is what makes exclusion useful: bookkeeping tools interleaved into a loop must not launder it.
+- **Denied calls count.** Detection sits on `tools/post-execute`, which also runs for calls a `tools/pre-execute` listener denied — a model hammering a denied call is exactly the loop worth breaking.
+- **Calls without an agent are ignored.** A direct `ctx.tools.execute()` caller has no model to remind and no `AgentId` to key on.
+- **Per-agent keying.** The tool registry is context-level and subagents interleave through the same waterfall, so chains are keyed by `AgentId`; one agent's repetition never trips another's reminder. A user prompt (`agent/prompt-submit`) resets the submitting agent's chain; agent disposal drops its state.
+- **In-memory only.** A session resumed from persistence starts with a fresh chain — the guard is a heuristic nudge, not a logged invariant, later reminders are the accepted cost.
+
+## Reminder delivery
+
+Reminders ride the post-execute decision's `additionalContext` (source `{kind: 'plugin', plugin: 'repeat-tool-guard'}`), never a `content` replacement: the `tool/result` event stays the tool's own output for audit. The loop buffers the context and appends it as a `context/message` after the step's tool results, which the session renders as the tagged synthetic-user envelope — so the reminder is model-visible, source-attributed, and reconstructable from the session log with no new session event. The guard always delegates via `next()` and folds its reminder onto the downstream decision (both variants — a blocked call still gets the nudge); when a downstream listener attached its own `additionalContext`, the fold concatenates content and carries the guard's `source` (a `HookContext` holds one `MessageSource`; `source.kind` is what framing depends on).
+
+## Testing
+
+Unit suites drive a real agent loop against a mock adapter (no network) and cover the chain semantics above to per-file 100%. The snapshot tier owns the transcript surface: a scripted-replay scenario repeats a call five times and pins both reminder tiers (gentle at 3, detailed at 5) as `context/message`s in the ACP transcript.
@@ -0,0 +1,41 @@
+{
+  "name": "@deepseek-ai/dsh-repeat-tool-guard",
+  "description": "Repeat-tool-call guard plugin: advisory reminders when an agent loops on identical tool calls",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}
@@ -0,0 +1,268 @@
+/**
+ * Repeat-tool-call guard: advisory loop-breaker for agents stuck re-issuing
+ * the same tool call with identical arguments.
+ *
+ * Not a model-facing tool — it registers no tool, never vetoes or rewrites a
+ * call, and adds exactly one behavior: watch each agent's stream of tool calls
+ * through the `tools/post-execute` waterfall, count runs of consecutive calls
+ * to the same tool with identical canonicalized arguments, and at configured
+ * run lengths fold an escalating advisory reminder onto the decision's
+ * `additionalContext`. The loop appends that context as a logged
+ * `context/message` after the step's tool results, so the reminder is
+ * model-visible, source-attributed, and reconstructable from the session log
+ * with no new session event. Decision record:
+ * docs/rfc/implemented/feature/2026-07-08-repeat-tool-guard.md.
+ *
+ * ```yaml
+ * - id: repeat-tool-guard
+ *   name: '@deepseek-ai/dsh-repeat-tool-guard'
+ *   config:
+ *     thresholds: [3, 5, 8]   # consecutive counts that trigger a reminder
+ *     include: []             # tool-name patterns to track; empty = all tools
+ *     exclude: [todo_write]   # tool-name patterns transparent to the chain
+ * ```
+ *
+ * Chain state is keyed per {@link AgentId} — the tool registry is a
+ * context-level singleton whose waterfalls interleave every agent's calls, so
+ * a shared counter would let one agent's repetition trip another's reminder.
+ * State is in-memory only: a session resumed from persistence starts with a
+ * fresh chain (the guard is a heuristic nudge, not a logged invariant).
+ *
+ * Plugin export shape: named exports, NO default. The cordis Loader's
+ * `unwrapExports` does `exports.default ?? exports`, so a stray default would
+ * collapse the module to the bare `apply` (see docs/postmortem/0001).
+ *
+ * @module @deepseek-ai/dsh-repeat-tool-guard
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import type { AgentId, HookContext, PromptDecision } from '@deepseek-ai/dsh-agent'
+import type { MessageSource } from '@deepseek-ai/dsh-llm'
+import type { PostToolDecision, ToolExecution } from '@deepseek-ai/dsh-tools'
+
+export const name = 'repeat-tool-guard'
+
+/**
+ * Plugin config, validated by the same-named schemastery schema plus the
+ * load-time checks in `apply` (misconfiguration fails loud: an empty
+ * `thresholds` list, a non-integer, a value below 2, or a duplicate throws at
+ * plugin load, never a silent fall-back). `include`/`exclude` entries are
+ * `*`-wildcard predicates over tool names at call time, not references to
+ * registry entries — a pattern matching no currently registered tool is valid
+ * (`exclude: [mcp_*]` must stay legal in a deployment that loads no MCP tools).
+ */
+export interface Config {
+  /** Consecutive-repeat counts that trigger a reminder (default `[3, 5, 8]`). */
+  thresholds?: number[]
+  /** Tool-name patterns to track; empty means every tool is tracked. */
+  include?: string[]
+  /** Tool-name patterns transparent to the chain (neither count nor reset). */
+  exclude?: string[]
+  /**
+   * Maximum characters of canonical arguments quoted in the DETAILED reminder
+   * (default 500). Large payloads (a `write` body, a long command) would
+   * otherwise ride into the next request unbounded — precisely in a loop
+   * scenario; the cap bounds the reminder, never the detection (the chain key
+   * always compares the FULL canonical string).
+   */
+  argumentsPreviewChars?: number
+}
+
+export const Config: z<Config> = z.object({
+  thresholds: z.array(z.number()).default([3, 5, 8]),
+  include: z.array(z.string()).default([]),
+  exclude: z.array(z.string()).default([]),
+  argumentsPreviewChars: z.number().default(500),
+})
+
+/**
+ * The `{kind:'plugin'}` source stamped on every reminder this guard injects —
+ * the label is load-bearing (an unlabeled context would render as a user
+ * prompt in derived history).
+ */
+const PLUGIN_SOURCE: MessageSource = { kind: 'plugin', plugin: 'repeat-tool-guard' }
+
+/**
+ * The gentle first-threshold reminder. Keyed to `thresholds[0]`, not a literal
+ * count, so a custom first threshold keeps the gentle-then-detailed escalation.
+ */
+const GENTLE_REMINDER =
+  'You are repeating the exact same tool call with identical arguments. '
+  + 'Carefully analyze the previous result before calling again: if the task is '
+  + 'not complete, try a different approach or different arguments instead of '
+  + 'repeating the call.'
+
+/** The detailed later-threshold reminder naming the tool, the run length, and the canonical arguments. */
+function detailedReminder(toolName: string, count: number, canonicalArguments: string): string {
+  return 'Repeated tool call detected:\n'
+    + `- tool: ${toolName}\n`
+    + `- consecutive_calls: ${count}\n`
+    + `- arguments: ${canonicalArguments}\n`
+    + 'The repeated calls are not making progress. Do not call this tool with '
+    + 'these exact arguments again. Inspect the latest result and choose a '
+    + 'different action, different arguments, or finish the task if enough '
+    + 'evidence has been gathered.'
+}
+
+/**
+ * Deep key-sort of a parsed-JSON value so two argument objects that differ
+ * only in property order canonicalize identically. Arguments reach the guard
+ * as the loop's `JSON.parse` output (or its raw-string fallback for malformed
+ * argument JSON), so JSON's value domain is the whole input domain — no
+ * bigint, cycle, or `undefined` handling exists because no input path can
+ * produce them.
+ */
+function sortJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortJsonValue)
+  if (value !== null && typeof value === 'object') {
+    const record = value as Record<string, unknown>
+    const sorted: Record<string, unknown> = {}
+    for (const key of Object.keys(record).sort()) {
+      sorted[key] = sortJsonValue(record[key])
+    }
+    return sorted
+  }
+  return value
+}
+
+/** Canonical string form of a call's arguments: deep key-sort, then stringify. */
+function canonicalize(argumentsValue: unknown): string {
+  return JSON.stringify(sortJsonValue(argumentsValue))
+}
+
+/** Compile one `*`-wildcard pattern to an anchored RegExp (every other regex metacharacter is matched literally). */
+function wildcardToRegExp(pattern: string): RegExp {
+  const escaped = pattern.replace(/[|\\{}()[\]^$+?.]/g, String.raw`\$&`)
+  return new RegExp(`^${escaped.replaceAll('*', '.*')}$`)
+}
+
+/**
+ * Head-truncate the canonical arguments for quoting in the detailed reminder,
+ * marking how much was omitted. Bounds only the model-visible text — the
+ * chain key always uses the full canonical string.
+ */
+function previewArguments(canonical: string, cap: number): string {
+  if (canonical.length <= cap) return canonical
+  return `${canonical.slice(0, cap)}… (+${canonical.length - cap} more chars)`
+}
+
+/**
+ * Validate `thresholds` per the fail-loud contract and return them sorted
+ * ascending (the escalation rule reads `thresholds[0]` as the gentle tier, so
+ * order is normalized here, once).
+ */
+function validateThresholds(values: number[]): number[] {
+  if (values.length === 0) {
+    throw new Error('repeat-tool-guard: `thresholds` must not be empty')
+  }
+  for (const value of values) {
+    if (!Number.isInteger(value) || value < 2) {
+      throw new Error(`repeat-tool-guard: invalid threshold ${value} — every threshold must be an integer >= 2`)
+    }
+  }
+  if (new Set(values).size !== values.length) {
+    throw new Error('repeat-tool-guard: `thresholds` must not contain duplicates')
+  }
+  return [...values].sort((a, b) => a - b)
+}
+
+/**
+ * Concatenate the guard's reminder context with a downstream listener's
+ * optional one so folding drops neither. The merged block carries the guard's
+ * `source` — a `HookContext` holds one `MessageSource` and the seam cannot
+ * represent mixed provenance; the rendered `context/message` only
+ * distinguishes by `source.kind`, so a downstream plugin's text is still
+ * correctly framed as plugin context.
+ */
+function concatContext(ours: HookContext, theirs: HookContext | undefined): HookContext {
+  if (!theirs) return ours
+  return { content: [...ours.content, ...theirs.content], source: ours.source }
+}
+
+/** One agent's consecutive-repeat chain: the last tracked call's identity key and its run length. */
+interface Chain {
+  key: string
+  count: number
+}
+
+/**
+ * Install the guard's listeners.
+ * @param ctx - plugin context; listeners are scoped to it and disposed with it.
+ * @param config - validated {@link Config}; `thresholds` is re-checked fail-loud here.
+ */
+export function apply(ctx: Context, config: Config): void {
+  // schemastery's .default() guarantees the fields are set after validation.
+  const thresholds = validateThresholds(config.thresholds as number[])
+  const thresholdSet = new Set(thresholds)
+  const includePatterns = (config.include as string[]).map(wildcardToRegExp)
+  const excludePatterns = (config.exclude as string[]).map(wildcardToRegExp)
+  const argumentsPreviewChars = config.argumentsPreviewChars as number
+  if (!Number.isInteger(argumentsPreviewChars) || argumentsPreviewChars < 1) {
+    throw new Error(`repeat-tool-guard: invalid argumentsPreviewChars ${argumentsPreviewChars} — must be an integer >= 1`)
+  }
+
+  const chains = new Map<AgentId, Chain>()
+
+  /** Whether a tool participates in the chain (untracked calls are transparent: they neither count nor reset). */
+  function tracked(toolName: string): boolean {
+    if (includePatterns.length > 0 && !includePatterns.some(pattern => pattern.test(toolName))) return false
+    return !excludePatterns.some(pattern => pattern.test(toolName))
+  }
+
+  /**
+   * Advance the calling agent's chain for one attempt and return the reminder
+   * to deliver, if this attempt's run length hits a configured threshold.
+   * Counting happens here — in post-execute — because denied calls also flow
+   * through this waterfall (`ToolRegistry.execute` routes a deny through the
+   * same pipeline), and a model hammering a denied call is exactly the loop
+   * worth breaking.
+   */
+  function observe(exec: ToolExecution): HookContext | undefined {
+    // A direct `ctx.tools.execute()` caller has no model to remind and no id
+    // to key on; only agent-loop calls participate.
+    if (!exec.agent) return undefined
+    if (!tracked(exec.name)) return undefined
+    const canonical = canonicalize(exec.arguments)
+    const key = JSON.stringify([exec.name, canonical])
+    const chain = chains.get(exec.agent.id)
+    const count = chain !== undefined && chain.key === key ? chain.count + 1 : 1
+    chains.set(exec.agent.id, { key, count })
+    if (!thresholdSet.has(count)) return undefined
+    const text = count === thresholds[0]
+      ? GENTLE_REMINDER
+      : detailedReminder(exec.name, count, previewArguments(canonical, argumentsPreviewChars))
+    return { content: [{ type: 'text', text }], source: PLUGIN_SOURCE }
+  }
+
+  // Observe-and-enrich, never veto: count first (state advances regardless of
+  // the downstream outcome), DELEGATE so a later listener can still block or
+  // replace, then fold the reminder onto whatever came back — additionalContext
+  // rides both decision variants, so a blocked call still gets the nudge.
+  ctx.on('tools/post-execute', async (exec, _result, next): Promise<PostToolDecision> => {
+    const reminder = observe(exec)
+    const downstream = await next()
+    if (!reminder) return downstream
+    if (downstream.kind === 'block') {
+      return { kind: 'block', feedback: downstream.feedback, additionalContext: concatContext(reminder, downstream.additionalContext) }
+    }
+    return {
+      kind: 'accept',
+      ...downstream.content !== undefined ? { content: downstream.content } : {},
+      additionalContext: concatContext(reminder, downstream.additionalContext),
+    }
+  })
+
+  // A user interjection changes the context; repetition across it is not a
+  // loop. Pure reset hook: always delegates (attaching nothing, vetoing
+  // nothing).
+  ctx.on('agent/prompt-submit', (agent, _content, _source, next): Promise<PromptDecision> => {
+    chains.delete(agent.id)
+    return next()
+  })
+
+  // Drop state when an agent goes away, bounding the map over harness lifetime.
+  ctx.on('agent/status', (agent, status) => {
+    if (status === 'disposed') chains.delete(agent.id)
+  })
+}
@@ -0,0 +1,401 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import LlmService, { CallId } from '@deepseek-ai/dsh-llm'
+import SessionStore, { 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, { type ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import * as RepeatToolGuard from '@deepseek-ai/dsh-repeat-tool-guard'
+import type { Config } from '@deepseek-ai/dsh-repeat-tool-guard'
+import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+
+/**
+ * Behavior suite for the repeat-tool-call guard: chain semantics (identical /
+ * different-tracked / untracked-transparent / per-agent / resets), threshold
+ * escalation incl. the `thresholds[0]` gentle-text rule, canonicalization,
+ * fold-onto-downstream-decision, and fail-loud config validation — all driven
+ * through a real agent loop against a scripted mock adapter (no network).
+ */
+
+/** Boot the core spine + the guard; the caller registers adapters and extra listeners. */
+async function harness(config: Config = {}): 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: [] })
+  await ctx.plugin(RepeatToolGuard, config)
+  ctx.tools.register(defineTool({ name: 'probe', description: 'p', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+  ctx.tools.register(defineTool({ name: 'other', description: 'o', parameters: {}, async execute() { return [{ type: 'text', text: 'ok' }] } }))
+  return ctx
+}
+
+function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+  return new Promise((resolve) => { const d = ctx.on('agent/status', (s, st) => { if (s === agent && st === 'idle') { d(); resolve() } }) })
+}
+
+/** Every `context/message` in the agent's log, flattened to joined text + source for terse assertions. */
+function reminders(agent: ReactLoopAgent): { text: string; source: unknown }[] {
+  return [...agent.session.events]
+    .filter((e): e is SessionEvent<'context/message'> => e.type === 'context/message')
+    .map(e => ({
+      text: e.data.content.map(block => block.type === 'text' ? block.text : '').join('|'),
+      source: e.data.source,
+    }))
+}
+
+const GUARD_SOURCE = { kind: 'plugin', plugin: 'repeat-tool-guard' }
+
+describe('threshold escalation', () => {
+  it('reminds gently at the first default threshold (3) and in detail at the second (5)', async () => {
+    const ctx = await harness()
+    const adapter = new MockAdapter([
+      ...Array.from({ length: 5 }, (_, i) => toolCallResponse(`c${i}`, 'probe', { q: 'same' })),
+      textResponse('done'),
+    ])
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    const found = reminders(agent)
+    expect(found).toHaveLength(2)
+    expect(found[0]!.text).toContain('repeating the exact same tool call')
+    expect(found[0]!.source).toEqual(GUARD_SOURCE)
+    expect(found[1]!.text).toContain('consecutive_calls: 5')
+    expect(found[1]!.text).toContain('- tool: probe')
+    expect(found[1]!.text).toContain('{"q":"same"}')
+    expect(found[1]!.source).toEqual(GUARD_SOURCE)
+  })
+
+  it('keys the gentle text to thresholds[0], not the literal 3', async () => {
+    const ctx = await harness({ thresholds: [4, 2] }) // unsorted on purpose: normalized ascending
+    const adapter = new MockAdapter([
+      ...Array.from({ length: 4 }, (_, i) => toolCallResponse(`c${i}`, 'probe', {})),
+      textResponse('done'),
+    ])
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    const found = reminders(agent)
+    expect(found).toHaveLength(2)
+    expect(found[0]!.text).toContain('repeating the exact same tool call') // gentle at 2
+    expect(found[1]!.text).toContain('consecutive_calls: 4') // detailed at 4
+  })
+})
+
+describe('chain semantics', () => {
+  it('caps the detailed reminder arguments at argumentsPreviewChars (detection still keys on the full string)', async () => {
+    const ctx = await harness({ thresholds: [2, 3], argumentsPreviewChars: 24 })
+    const bigPayload = 'x'.repeat(400)
+    const adapter = new MockAdapter([
+      toolCallResponse('c1', 'probe', { body: bigPayload }),
+      toolCallResponse('c2', 'probe', { body: bigPayload }),
+      toolCallResponse('c3', 'probe', { body: bigPayload }),
+      textResponse('done'),
+    ])
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    const found = reminders(agent)
+    expect(found).toHaveLength(2) // gentle at 2, detailed at 3 — full-key matching survived the cap
+    const detailed = found[1]!.text
+    expect(detailed).toContain('- arguments: {"body":"xxxxxxxxxxxxxx') // 24-char head
+    expect(detailed).toContain('… (+387 more chars)')
+    expect(detailed).not.toContain(bigPayload)
+  })
+
+  it('a different tracked call resets the chain', async () => {
+    const ctx = await harness()
+    const adapter = new MockAdapter([
+      toolCallResponse('c1', 'probe', { q: 1 }),
+      toolCallResponse('c2', 'probe', { q: 1 }),
+      toolCallResponse('c3', 'other', {}), // tracked, different → reset
+      toolCallResponse('c4', 'probe', { q: 1 }),
+      toolCallResponse('c5', 'probe', { q: 1 }),
+      toolCallResponse('c6', 'probe', { q: 1 }), // 3rd consecutive AFTER the reset
+      textResponse('done'),
+    ])
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    expect(reminders(agent)).toHaveLength(1)
+  })
+
+  it('excluded calls are transparent: they neither count nor reset', async () => {
+    const ctx = await harness({ exclude: ['other'] })
+    const adapter = new MockAdapter([
+      toolCallResponse('c1', 'probe', { q: 1 }),
+      toolCallResponse('c2', 'other', {}), // excluded → invisible to the chain
+      toolCallResponse('c3', 'probe', { q: 1 }),
+      toolCallResponse('c4', 'other', {}),
+      toolCallResponse('c5', 'probe', { q: 1 }), // 3rd consecutive probe
+      textResponse('done'),
+    ])
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    const found = reminders(agent)
+    expect(found).toHaveLength(1)
+    expect(found[0]!.text).toContain('repeating the exact same tool call')
+  })
+
+  it('include patterns track only matching tools (wildcard star)', async () => {
+    const ctx = await harness({ include: ['pro*'] })
+    const adapter = new MockAdapter([
+      toolCallResponse('c1', 'other', {}),
+      toolCallResponse('c2', 'other', {}),
+      toolCallResponse('c3', 'other', {}), // 3 identical, but untracked
+      toolCallResponse('c4', 'probe', {}),
+      toolCallResponse('c5', 'probe', {}),
+      toolCallResponse('c6', 'probe', {}), // 3 identical, tracked
+      textResponse('done'),
+    ])
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    const found = reminders(agent)
+    expect(found).toHaveLength(1)
+    expect(found[0]!.text).toContain('repeating the exact same tool call')
+  })
+
+  it('escapes regex metacharacters in patterns (a dot matches only a literal dot)', async () => {
+    const ctx = await harness({ exclude: ['pr.be'] }) // would match 'probe' as a regex; must not as a wildcard
+    const adapter = new MockAdapter([
+      ...Array.from({ length: 3 }, (_, i) => toolCallResponse(`c${i}`, 'probe', {})),
+      textResponse('done'),
+    ])
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    expect(reminders(agent)).toHaveLength(1) // probe was NOT excluded
+  })
+
+  it('canonicalization ignores property order, deeply', async () => {
+    const ctx = await harness()
+    const adapter = new MockAdapter([
+      toolCallResponse('c1', 'probe', { a: 1, nested: { x: [1, 2], y: null } }),
+      toolCallResponse('c2', 'probe', { nested: { y: null, x: [1, 2] }, a: 1 }),
+      toolCallResponse('c3', 'probe', { a: 1, nested: { x: [1, 2], y: null } }),
+      textResponse('done'),
+    ])
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    expect(reminders(agent)).toHaveLength(1) // all three canonicalize identically
+  })
+
+  it('keys chains per agent: one agent repeating never trips another', async () => {
+    const ctx = await harness()
+    ctx.llm.registerAdapter(['mock-a'], new MockAdapter([
+      toolCallResponse('a1', 'probe', { q: 1 }),
+      toolCallResponse('a2', 'probe', { q: 1 }),
+      textResponse('done'),
+    ]))
+    ctx.llm.registerAdapter(['mock-b'], new MockAdapter([
+      toolCallResponse('b1', 'probe', { q: 1 }),
+      toolCallResponse('b2', 'probe', { q: 1 }),
+      toolCallResponse('b3', 'probe', { q: 1 }),
+      textResponse('done'),
+    ]))
+    const agentA = ctx.agentLoop.create(AgentId('a'), { model: 'mock-a' })
+    const agentB = ctx.agentLoop.create(AgentId('b'), { model: 'mock-b' })
+    agentA.send([{ type: 'text', text: 'go' }])
+    agentB.send([{ type: 'text', text: 'go' }])
+    await Promise.all([waitForIdle(ctx, agentA), waitForIdle(ctx, agentB)])
+
+    expect(reminders(agentA)).toHaveLength(0) // 2 repeats < 3, despite B's 3 in the same registry
+    expect(reminders(agentB)).toHaveLength(1)
+  })
+
+  it('a new user prompt resets the chain', async () => {
+    const ctx = await harness()
+    const adapter = new MockAdapter([
+      toolCallResponse('c1', 'probe', { q: 1 }),
+      toolCallResponse('c2', 'probe', { q: 1 }),
+      textResponse('turn one done'),
+      toolCallResponse('c3', 'probe', { q: 1 }), // without the reset this would be the 3rd
+      textResponse('turn two done'),
+    ])
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+    agent.send([{ type: 'text', text: 'again' }])
+    await waitForIdle(ctx, agent)
+
+    expect(reminders(agent)).toHaveLength(0)
+  })
+
+  it('drops an agent chain on disposal', async () => {
+    const ctx = await harness({ thresholds: [2] })
+    ctx.llm.registerAdapter(['mock'], new MockAdapter([
+      toolCallResponse('c1', 'probe', { q: 1 }),
+      textResponse('done'),
+      toolCallResponse('c2', 'probe', { q: 1 }), // same id, fresh agent: count 1, not 2
+      textResponse('done'),
+    ]))
+    // Loop agents are torn down by disposing the scope that created them
+    // (the loop.spec pattern): a child plugin fiber owns `first`.
+    let first!: ReactLoopAgent
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      first = inner.agentLoop.create(AgentId('reused'), { model: 'mock' })
+    }, { inject: ['agentLoop'] }))
+    first.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, first)
+    await fiber.dispose()
+    await first.done
+
+    const second = ctx.agentLoop.create(AgentId('reused'), { model: 'mock' })
+    second.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, second)
+
+    expect(reminders(second)).toHaveLength(0)
+  })
+
+  it('counts denied calls: hammering a denied tool still draws the reminder', async () => {
+    const ctx = await harness({ thresholds: [2] })
+    ctx.on('tools/pre-execute', async () => ({ kind: 'deny' as const, reason: 'sealed' }))
+    const adapter = new MockAdapter([
+      toolCallResponse('c1', 'probe', { q: 1 }),
+      toolCallResponse('c2', 'probe', { q: 1 }),
+      textResponse('done'),
+    ])
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    expect(reminders(agent)).toHaveLength(1)
+  })
+
+  it('ignores direct executes with no agent (they neither crash nor advance any chain)', async () => {
+    const ctx = await harness({ thresholds: [2] })
+    const direct = await ctx.tools.execute({ callId: CallId('d1'), name: 'probe', arguments: { q: 1 } })
+    expect(direct.isError).toBe(false)
+
+    ctx.llm.registerAdapter(['mock'], new MockAdapter([
+      toolCallResponse('c1', 'probe', { q: 1 }), // if the direct call had counted, this would be #2
+      textResponse('done'),
+    ]))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    expect(reminders(agent)).toHaveLength(0)
+  })
+})
+
+describe('fold onto the downstream decision', () => {
+  it('folds the reminder onto a downstream block and keeps its feedback', async () => {
+    const ctx = await harness({ thresholds: [2] })
+    ctx.on('tools/post-execute', async () => ({
+      kind: 'block' as const,
+      feedback: [{ type: 'text' as const, text: 'nope' }],
+      additionalContext: { content: [{ type: 'text' as const, text: 'downstream-ctx' }], source: { kind: 'plugin' as const, plugin: 'test' } },
+    }))
+    const adapter = new MockAdapter([
+      toolCallResponse('c1', 'probe', { q: 1 }),
+      toolCallResponse('c2', 'probe', { q: 1 }),
+      textResponse('done'),
+    ])
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    const found = reminders(agent)
+    expect(found).toHaveLength(2)
+    // Call 1: below threshold — the downstream context passes through untouched.
+    expect(found[0]!.text).toBe('downstream-ctx')
+    expect(found[0]!.source).toEqual({ kind: 'plugin', plugin: 'test' })
+    // Call 2: reminder folded in front, single merged context, the guard's source.
+    expect(found[1]!.text).toContain('repeating the exact same tool call')
+    expect(found[1]!.text).toContain('|downstream-ctx')
+    expect(found[1]!.source).toEqual(GUARD_SOURCE)
+    // The block's feedback reached the tool result unchanged.
+    const results = [...agent.session.events].filter((e): e is SessionEvent<'tool/result'> => e.type === 'tool/result')
+    expect(results.every(r => r.data.isError)).toBe(true)
+    expect(results[1]!.data.content).toEqual([{ type: 'text', text: 'nope' }])
+  })
+
+  it('preserves a downstream accept content replacement while folding', async () => {
+    const ctx = await harness({ thresholds: [2] })
+    ctx.on('tools/post-execute', async () => ({
+      kind: 'accept' as const,
+      content: [{ type: 'text' as const, text: 'replaced' }],
+    }))
+    const adapter = new MockAdapter([
+      toolCallResponse('c1', 'probe', { q: 1 }),
+      toolCallResponse('c2', 'probe', { q: 1 }),
+      textResponse('done'),
+    ])
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+
+    const found = reminders(agent)
+    expect(found).toHaveLength(1)
+    expect(found[0]!.text).toContain('repeating the exact same tool call')
+    const results = [...agent.session.events].filter((e): e is SessionEvent<'tool/result'> => e.type === 'tool/result')
+    expect(results[1]!.data.content).toEqual([{ type: 'text', text: 'replaced' }])
+  })
+})
+
+describe('config validation fails loud', () => {
+  async function spine(): 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: [] })
+    return ctx
+  }
+
+  it('rejects an empty thresholds list', async () => {
+    const ctx = await spine()
+    await expect(ctx.plugin(RepeatToolGuard, { thresholds: [] })).rejects.toThrow(/must not be empty/)
+  })
+
+  it('rejects a threshold below 2', async () => {
+    const ctx = await spine()
+    await expect(ctx.plugin(RepeatToolGuard, { thresholds: [1, 3] })).rejects.toThrow(/integer >= 2/)
+  })
+
+  it('rejects a non-integer threshold', async () => {
+    const ctx = await spine()
+    await expect(ctx.plugin(RepeatToolGuard, { thresholds: [2.5] })).rejects.toThrow(/integer >= 2/)
+  })
+
+  it('rejects duplicate thresholds', async () => {
+    const ctx = await spine()
+    await expect(ctx.plugin(RepeatToolGuard, { thresholds: [3, 3] })).rejects.toThrow(/duplicates/)
+  })
+
+  it('rejects a non-positive or fractional argumentsPreviewChars', async () => {
+    const ctx = await spine()
+    await expect(ctx.plugin(RepeatToolGuard, { argumentsPreviewChars: 0 })).rejects.toThrow(/argumentsPreviewChars/)
+    const ctx2 = await spine()
+    await expect(ctx2.plugin(RepeatToolGuard, { argumentsPreviewChars: 12.5 })).rejects.toThrow(/argumentsPreviewChars/)
+  })
+})
@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../llm/llm"
+    }
+  ]
+}
@@ -4,8 +4,9 @@ Packages that exist to serve development, testing, and the examples rather than

 | Package | Role | ctx key |
 |---|---|---|
+| `acp-snapshot/` | ACP snapshot suite kit: subprocess scenario harness + golden normalizers + the `defineAcpSnapshotSuite` factory | (library — imported by example `*.snapshot.ts` suites) |
 | `invariants/` | Dev-mode event-contract invariants + session-log freeze | (listens on `session/*`, `agent/*`) |
 | `llm-replay/` | Record/replay adapter: short-circuits `llm/stream` from a recorded session JSONL (keyless snapshot tests) | (listens on `llm/stream`) |
 | `subagent-mock/` | Scripted `SubagentProvider` for deterministic seam/tool tests | (registers on `ctx.subagents`) |

-`invariants` runs only in dev mode (contract checks, not runtime behavior). `llm-replay` backs the demos and the snapshot test tier under the per-file coverage gate. `subagent-mock` exercises the real `ctx.subagents` load path without a model or child agent. A package graduates OUT of `support/` into a product group only when it gains documented product consumers.
+`invariants` runs only in dev mode (contract checks, not runtime behavior). `llm-replay` backs the demos and the snapshot test tier under the per-file coverage gate. `acp-snapshot` carries the snapshot tier's harness/normalizer/suite machinery so every example's suite is a scenario table over one shared, gate-covered implementation. `subagent-mock` exercises the real `ctx.subagents` load path without a model or child agent. A package graduates OUT of `support/` into a product group only when it gains documented product consumers.
@@ -0,0 +1,36 @@
+# `@deepseek-ai/dsh-acp-snapshot`
+
+The ACP snapshot suite kit: the shared machinery behind the keyless snapshot tier (`pnpm run test:snapshot`, [testing policy](../../../docs/testing.md)). An example gets a full snapshot suite from a scenario table plus a fixtures directory; every compare/guard mechanic lives here, under the per-file coverage gate, instead of being copied per example.
+
+Three layers, importable separately:
+
+- **`runScenario` (harness)** — boots the real agent bin as a subprocess via tsx (unbuilt, Loader path), drives it over ACP JSON-RPC stdio from a deterministic `input.json` script, tees raw stdout for the golden + purity check, and harvests every persisted session JSONL (parent + subagent children, primary-first) after a graceful stdin-EOF shutdown. Parameterized by `AgentUnderTest` (`binScript`, `configPath`, `tsconfigPath` — absolute paths; the subprocess cwd is a temp dir outside the repo).
+- **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept), and the composable `scrubRequestHeaders` (header bulk → `{{system}}`/`{{tools}}`, structure kept — [pinned-header RFC](../../../docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
+- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario golden + re-persisted-log compares, record-mode fixture write-back, the per-suite header pin with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin, non-pinning fixtures header-scrubbed). Must be called at vitest collection time.
+
+A consuming `*.snapshot.ts` is the scenario table plus one factory call:
+
+```ts
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineAcpSnapshotSuite, type Scenario } from '@deepseek-ai/dsh-acp-snapshot'
+
+const SCENARIOS: Scenario[] = [
+  { name: 'text-turn', hasModelTurn: true, recorded: true, pinsHeader: true },
+]
+
+defineAcpSnapshotSuite({
+  agent: { // absolute paths, resolved from the suite's own location
+    binScript: fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url)),
+    configPath: fileURLToPath(new URL('../cordis.yml', import.meta.url)),
+    tsconfigPath: fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)),
+  },
+  snapshotsDir: join(dirname(fileURLToPath(import.meta.url)), 'snapshots'),
+  scenarios: SCENARIOS, // exactly one entry sets pinsHeader
+  mode: process.env.DSH_SNAPSHOT === 'record' ? 'record' : 'replay',
+})
+```
+
+The example also ships a `cordis.snapshot.yml` replay overlay next to its `cordis.yml` (the bin swaps them under `DSH_SNAPSHOT=replay` — [single-source replay config RFC](../../../docs/rfc/implemented/testing/2026-07-04-single-source-acp-replay-config.md)); replay fixtures are served by [`dsh-llm-replay`](../llm-replay/README.md), which this package points at via the `DSH_SNAPSHOT_*` env vars it sets on the child. Fixture roles, record/replay semantics, and scenario-table fields are documented on `Scenario` and in the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md).
+
+Constraints: `suite.ts` imports vitest, so the package is importable only inside a vitest run (the harness and normalizers have no such dependency but ship from the same entry). ACP-specific by design — the harness speaks the SDK's `ClientSideConnection`. Permission round-trips are scriptable: `InputScript.permissionAnswers` is a FIFO queue of option-kind selections (`allow_once`, `reject_once`, …) the client maps to the agent-issued `optionId` at answer time; an absent or exhausted queue answers `cancelled`, and a kind the request never offered rejects the run (the agent is answered `cancelled`, so a tolerant agent cannot absorb the scenario bug).
@@ -0,0 +1,35 @@
+{
+  "name": "@deepseek-ai/dsh-acp-snapshot",
+  "description": "ACP snapshot suite kit: real-subprocess scenario harness, golden normalizers, and the suite factory behind the keyless snapshot tier",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@agentclientprotocol/sdk": "0.25.1",
+    "tsx": "^4.22.4",
+    "vitest": "^4.1.8"
+  },
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "cordis": "^4.0.0-rc.6"
+  }
+}
@@ -1,16 +1,19 @@
 /**
- * Shared harness for the ACP snapshot tests. A plain module (NOT a *.spec.ts /
- * *.snapshot.ts) so importing it never re-registers another file's tests.
+ * Shared subprocess harness for ACP snapshot suites. A library module driven by
+ * the suite factory in ./suite.ts (and directly by harness-level specs); each
+ * example's `*.snapshot.ts` names its own agent-under-test paths.
 *
- * It boots the REAL examples/acp-agent subprocess via the cordis Loader (so the
+ * It boots the REAL agent bin subprocess via the cordis Loader (so the
 * export-shape bug class stays guarded — see docs/postmortem/0001), drives it
 * over real ACP JSON-RPC stdio with a deterministic input script, tees raw
 * stdout (for the golden + a purity check) into an SDK `ClientSideConnection`,
 * and — in record mode — harvests the persisted session JSONL after a graceful
- * shutdown flush. Two pure normalizers turn the captured stdout frames and the
- * session-log events into stable, snapshot-able text.
+ * shutdown flush. The pure normalizers in ./normalize.ts turn the captured
+ * stdout frames and the session-log events into stable, snapshot-able text.
 *
 * See docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md.
+ *
+ * @module @deepseek-ai/dsh-acp-snapshot/harness
 */

 import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
@@ -31,19 +34,36 @@ import {
  type SessionNotification,
 } from '@agentclientprotocol/sdk'

-// The dsh-acp-agent bin (the demo:acp entry) and this example's cordis.yml.
-// The bin resolves its config-path arg from CWD and, under DSH_SNAPSHOT=replay,
-// swaps it for the sibling cordis.snapshot.yml. The child's cwd is a temp dir
-// OUTSIDE the repo, so pass the example config's ABSOLUTE path.
-const binScript = fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url))
-const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
+// Resolve tsx's ESM loader to an ABSOLUTE path once: the child runs with its
+// cwd in a temp dir OUTSIDE the repo, where a bare `--import tsx` would not
+// resolve from node_modules. import.meta.resolve gives this package's tsx
+// regardless of the child cwd.
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
-// The repo-root tsconfig: dev/test run UNBUILT and the `@deepseek-ai/dsh-*`
-// imports resolve through its `paths` map. The child's cwd is a temp dir
-// OUTSIDE the repo, so tsx's upward search would miss it — point tsx at the
-// repo tsconfig explicitly (same fix the e2e harness uses). Repo root is four
-// levels up from this file (examples/acp-agent/tests).
-const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+
+/**
+ * The agent composition a scenario runs against: which bin to boot and which
+ * leaf config it loads. All paths are ABSOLUTE — the subprocess cwd is a temp
+ * dir outside the repo, so relative resolution would miss; a suite resolves
+ * them from its own `import.meta.url`.
+ */
+export interface AgentUnderTest {
+  /** The agent bin entry (e.g. `packages/ui/acp-agent/src/bin.ts`), run unbuilt via tsx. */
+  binScript: string
+  /**
+   * The example's live `cordis.yml`. Under `DSH_SNAPSHOT=replay` the bin swaps
+   * it for the sibling `cordis.snapshot.yml` (the keyless replay overlay), so
+   * one path serves both modes.
+   */
+  configPath: string
+  /**
+   * The repo-root tsconfig whose `paths` map resolves the unbuilt workspace
+   * imports. Passed to the child as `TSX_TSCONFIG_PATH`: tsx finds a tsconfig
+   * by searching UP from the child's cwd — a temp dir outside the repo — so
+   * without the explicit pin the dsh-* imports fail before the bin writes a
+   * byte.
+   */
+  tsconfigPath: string
+}

 /**
 * One step of a scenario's deterministic input script (`input.json`). The
@@ -57,7 +77,7 @@ const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta
 * the only way to exercise a cancel deterministically (a plain `prompt` step
 * awaits the response, which a cancel/hang scenario would block on forever).
 */
-type InputStep =
+export type InputStep =
  | { op: 'initialize'; terminalOutput?: boolean }
  | { op: 'newSession' }
  | { op: 'newSessionExpectError'; additionalDirectories?: string[] }
@@ -69,6 +89,25 @@ type InputStep =
 /** A scenario's `input.json`: an ordered list of input steps. */
 export interface InputScript {
  steps: InputStep[]
+  /**
+   * Ordered answers for the agent's `session/request_permission` round-trips,
+   * consumed FIFO — the Nth request gets the Nth answer. Each answer selects
+   * by option KIND: option ids are agent-issued randoms a committed script
+   * cannot know, while kinds are the ACP-stable vocabulary, so the client maps
+   * kind → the offered `optionId` at answer time. A request beyond the queue
+   * (or with no queue at all) is answered `cancelled` — the stub behavior a
+   * scenario without approvals relies on. A scripted kind the request does
+   * not offer REJECTS the run: the scenario scripted an impossible click,
+   * and {@link runScenario} throws once the in-flight step settles (the
+   * agent itself just sees `cancelled`, so it cannot absorb the bug).
+   */
+  permissionAnswers?: PermissionAnswer[]
+}
+
+/** One scripted answer to a permission request: which offered option kind to select. */
+export interface PermissionAnswer {
+  /** The `PermissionOption.kind` to select (`allow_once`, `reject_always`, …). */
+  kind: 'allow_once' | 'allow_always' | 'reject_once' | 'reject_always'
 }

 /** One harvested session log plus the identifying facts off its header line. */
@@ -102,7 +141,10 @@ export interface RunResult {
  sessionLogs: HarvestedLog[]
 }

-interface RunOptions {
+/** How to run one scenario: the agent to boot, the mode, and the fixture wiring. */
+export interface RunOptions {
+  /** The agent composition to boot. */
+  agent: AgentUnderTest
  /** `replay` (default, keyless) or `record` (real API, harvests the log). */
  mode: 'replay' | 'record'
  /** The recorded session JSONL fixture path (replay reads it; record writes near it). */
@@ -130,6 +172,10 @@ interface RunOptions {
 * Run a scenario end-to-end against a freshly-spawned subprocess. Owns the
 * child and its temp dirs; always tears them down. Returns the captured stdout
 * and (record mode) the harvested session-log path.
+ *
+ * @param input The scenario's input script (steps + optional permission answers).
+ * @param opts The agent to boot, the mode, and the fixture wiring.
+ * @returns The captured stdout/stderr, session id, temp cwd, and harvested logs.
 */
 export async function runScenario(input: InputScript, opts: RunOptions): Promise<RunResult> {
  const cwd = await mkdtemp(join(tmpdir(), 'acp-snap-cwd-'))
@@ -151,7 +197,7 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
    }
    const env: NodeJS.ProcessEnv = {
      ...process.env,
-      TSX_TSCONFIG_PATH: repoTsconfig,
+      TSX_TSCONFIG_PATH: opts.agent.tsconfigPath,
      DSH_SNAPSHOT: opts.mode,
      DSH_SNAPSHOT_FILE: opts.fixtureFile,
      DSH_SNAPSHOT_SESSIONS_ROOT: sessionsRoot,
@@ -163,7 +209,7 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise

    child = spawn(
      process.execPath,
-      ['--import', tsxLoader, binScript, configPath],
+      ['--import', tsxLoader, opts.agent.binScript, opts.agent.configPath],
      { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] },
    )

@@ -193,25 +239,59 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
    const waitForUpdate = (match: (u: SessionNotification['update']) => boolean): Promise<void> =>
      new Promise<void>(resolve => updateWaiters.push({ match, resolve }))

+    // Permission answers are consumed FIFO across the whole run; exhaustion
+    // falls back to `cancelled` so approval-free scenarios keep the plain stub.
+    const permissionQueue = [...input.permissionAnswers ?? []]
+    // A scenario bug detected inside a client callback (a scripted permission
+    // kind the agent never offered). It cannot fail the run from in there: a
+    // callback throw only becomes a JSON-RPC error RESPONSE to the agent, and
+    // a tolerant agent treats that as a denial and carries on — the run (or
+    // worse, a record) would absorb the impossible click silently. So the
+    // callback answers `cancelled` (a well-defined path for the agent),
+    // captures the error here, and the step loop fails the run on it.
+    let scriptError: Error | undefined
    const makeClient = (_agent: AcpAgent): Client => ({
      sessionUpdate(params: SessionNotification): Promise<void> {
        for (let i = updateWaiters.length - 1; i >= 0; i--) {
          const waiter = updateWaiters[i]
-          if (waiter !== undefined && waiter.match(params.update)) {
+          // The index is always in-bounds (i only decreases; splice removes at
+          // i, so lower entries stay valid); the guard satisfies
+          // noUncheckedIndexedAccess.
+          /* v8 ignore next 1 -- unreachable in-bounds guard, see above */
+          if (waiter === undefined) continue
+          if (waiter.match(params.update)) {
            updateWaiters.splice(i, 1)
            waiter.resolve()
          }
        }
        return Promise.resolve()
      },
-      requestPermission(_params: RequestPermissionRequest): Promise<RequestPermissionResponse> {
-        return Promise.resolve({ outcome: { outcome: 'cancelled' } })
+      requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse> {
+        const answer = permissionQueue.shift()
+        if (answer === undefined) return Promise.resolve({ outcome: { outcome: 'cancelled' } })
+        const option = params.options.find(o => o.kind === answer.kind)
+        if (option === undefined) {
+          // The scenario scripted a click the agent never offered — a scenario
+          // bug. Captured (last one wins; same bug class either way) and
+          // answered `cancelled`; the step loop rejects the run on it.
+          scriptError = new Error(
+            `snapshot-harness: scripted permission answer ${answer.kind} not among `
+            + `the offered options [${params.options.map(o => o.kind).join(', ')}]`,
+          )
+          return Promise.resolve({ outcome: { outcome: 'cancelled' } })
+        }
+        return Promise.resolve({ outcome: { outcome: 'selected', optionId: option.optionId } })
      },
    })
    const client = new ClientSideConnection(makeClient, stream)

    for (const step of input.steps) {
      await runStep(client, step, cwd, waitForUpdate, () => sessionId, (id) => { sessionId = id })
+      // A permission exchange happens while a step's request is in flight, so
+      // by the time the step settles any script bug it exposed is captured —
+      // fail the run HERE, as a harness error, rather than hoping the agent's
+      // reaction to the answer perturbs the transcript.
+      if (scriptError !== undefined) throw scriptError
    }
    // Done driving: close stdin so the server disposes gracefully (flushing
    // persistence) and exits. Then await exit so the harvested log is complete.
@@ -302,9 +382,9 @@ async function runStep(
      // its own). To pin frame order deterministically, wait until the client
      // has OBSERVED the hang's streamed agent_message_chunk before cancelling —
      // so those update frames always precede the cancelled prompt response in
-      // the transcript (without this, the late chunk and the response race; see
-      // the Codex review of commit 5). Then cancel and await the prompt, which
-      // the bridge settles as `cancelled` once the abort propagates.
+      // the transcript (without this, the late chunk and the response race).
+      // Then cancel and await the prompt, which the bridge settles as
+      // `cancelled` once the abort propagates.
      const promptDone = client.prompt({ sessionId, prompt: [{ type: 'text', text: step.text }] })
      await waitForUpdate(u => u.sessionUpdate === 'agent_message_chunk')
      await client.cancel({ sessionId })
@@ -324,6 +404,10 @@ async function runStep(

 /** Resolve once the child process exits (any code/signal). */
 function waitForExit(child: ChildProcessWithoutNullStreams): Promise<void> {
+  // Race guard: both call sites run within one synchronous frame of
+  // stdin.end()/kill(), so the exit event cannot have been delivered yet;
+  // kept for any future caller that awaits in between.
+  /* v8 ignore next 1 -- unreachable race guard, see above */
  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
  return new Promise<void>(resolve => child.once('exit', () => { resolve() }))
 }
@@ -335,8 +419,8 @@ function waitForExit(child: ChildProcessWithoutNullStreams): Promise<void> {
 *
 * The JSONL backend lays sessions out as `<root>/<cwd-bucket>/<encoded-id>.jsonl`
 * (one bucket per cwd), so a parent and its same-cwd in-process child land in
- * the SAME bucket — collecting all files across all buckets catches both (the
- * old first-match short-circuit silently dropped the child). Returns `[]` if no
+ * the SAME bucket — collecting all files across all buckets catches both (a
+ * first-match short-circuit would silently drop the child). Returns `[]` if no
 * log was produced (a no-session scenario).
 */
 async function harvestSessionLogs(root: string): Promise<HarvestedLog[]> {
@@ -0,0 +1,38 @@
+/**
+ * ACP snapshot suite kit — the shared machinery behind the keyless snapshot
+ * tier (`pnpm run test:snapshot`). Three layers, composable per example:
+ * the subprocess scenario harness ({@link runScenario}), the pure golden
+ * normalizers ({@link normalizeStdout} / {@link normalizeSessionLog} /
+ * {@link scrubRequestHeaders}), and the suite factory
+ * ({@link defineAcpSnapshotSuite}) that registers a scenario table as a full
+ * describe/it tree. An example's `*.snapshot.ts` supplies only its
+ * {@link AgentUnderTest} paths, its snapshots directory, and its
+ * {@link Scenario} table.
+ *
+ * NOTE: ./suite.ts imports vitest, so this package is importable only inside a
+ * vitest run — a support-tier constraint stated in the README.
+ *
+ * @module @deepseek-ai/dsh-acp-snapshot
+ */
+
+export {
+  runScenario,
+  type AgentUnderTest,
+  type HarvestedLog,
+  type InputScript,
+  type InputStep,
+  type PermissionAnswer,
+  type RunOptions,
+  type RunResult,
+} from './harness.ts'
+export {
+  normalizeSessionLog,
+  normalizeStdout,
+  scrubRequestHeaders,
+  type NormalizeContext,
+} from './normalize.ts'
+export {
+  defineAcpSnapshotSuite,
+  type Scenario,
+  type SnapshotSuiteOptions,
+} from './suite.ts'
@@ -15,12 +15,15 @@
 * A separate, composable normalizer — {@link scrubRequestHeaders} — replaces
 * the bulky request-header CONTENT (the composed system prompt and the tool
 * schema list) with `{{system}}`/`{{tools}}` tokens. It is deliberately NOT
- * folded into {@link normalizeSessionLog}: the one header-pinning scenario
- * compares that content verbatim, every other scenario composes the scrub in
- * (the `pinsHeader` flag in acp.snapshot.ts; see the pinned-header RFC,
+ * folded into {@link normalizeSessionLog}: each suite's one header-pinning
+ * scenario compares that content verbatim, every other scenario composes the
+ * scrub in (the `pinsHeader` flag on the scenario table, consumed by the suite
+ * factory in ./suite.ts; see the pinned-header RFC,
 * docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md).
 *
 * See docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md.
+ *
+ * @module @deepseek-ai/dsh-acp-snapshot/normalize
 */

 const SESSION_ID = '{{sessionId}}'
@@ -69,6 +72,10 @@ function scrubValue(value: unknown, ctx: NormalizeContext): unknown {
 * (1, 2, 3, …) and all volatile strings scrubbed. Throws if any non-empty line
 * is not valid JSON — that doubles as the stdout-purity check (no logger leaked
 * onto the protocol).
+ *
+ * @param rawStdout The captured stdout bytes, decoded utf8.
+ * @param ctx The run's volatile values to scrub.
+ * @returns The normalized NDJSON transcript, one frame per line.
 */
 export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): string {
  const lines = rawStdout.split('\n').filter(line => line.trim().length > 0)
@@ -97,6 +104,10 @@ export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): strin
 * zeroed/scrubbed, all volatile strings scrubbed, and `seq` is LEFT INTACT
 * (deterministic by contract). Output is JSONL in the same shape as the input —
 * one compact record per line.
+ *
+ * @param rawLog The raw session `.jsonl` content.
+ * @param ctx The run's volatile values to scrub.
+ * @returns The normalized JSONL log, one record per line.
 */
 export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): string {
  const lines = rawLog.split('\n').filter(line => line.trim().length > 0)
@@ -140,7 +151,10 @@ export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): stri
 * Only lines with something to scrub are re-serialized; every other line
 * passes through byte-for-byte, so the transform is idempotent and applying
 * it to an already-scrubbed fixture is a no-op — the on-disk-fixtures guard
- * in acp.snapshot.ts relies on exactly that.
+ * in ./suite.ts relies on exactly that.
+ *
+ * @param rawLog The raw session `.jsonl` content.
+ * @returns The JSONL with header content tokenized, other lines byte-identical.
 */
 export function scrubRequestHeaders(rawLog: string): string {
  const lines = rawLog.split('\n')
@@ -0,0 +1,384 @@
+/**
+ * The ACP snapshot suite factory (REPLAY by default, keyless). A suite is a
+ * scenario table plus a snapshots directory: each scenario under
+ * `<snapshotsDir>/<name>/` ships an `input.json` (the client stdin script) and
+ * a `session.jsonl` fixture; replay boots the real agent subprocess
+ * (./harness.ts), drives it, and diffs the normalized stdout transcript
+ * against the committed `stdout.golden.jsonl`. For model scenarios it ALSO
+ * checks the re-persisted session log — against the `session.jsonl` fixture
+ * itself, not a separate golden: the fixture doubles as the replay source
+ * (recorded scenarios) and the expected produced log (both sides normalized
+ * before comparing).
+ *
+ * Request-header content (the composed system prompt + tool schemas riding on
+ * `request/header` events) is pinned by exactly ONE scenario per suite — the
+ * one with `pinsHeader` — and scrubbed to `{{system}}`/`{{tools}}` tokens in
+ * every other fixture and compare, so a prompt or tool-schema edit churns one
+ * committed line instead of every fixture. A per-run uniformity guard keeps
+ * the single pin sound: every live header must equal the pinned one, and no
+ * header-delta may appear outside the pinning scenario (see the
+ * pinned-header RFC,
+ * docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md).
+ *
+ * `pnpm run test:snapshot:record` (DSH_SNAPSHOT=record + -u) re-records the
+ * `session.jsonl` fixtures against the real API and refreshes the stdout golden
+ * in one pass; the caller resolves that env into {@link SnapshotSuiteOptions}
+ * (env reading stays at the suite edge, not in this library).
+ *
+ * @module @deepseek-ai/dsh-acp-snapshot/suite
+ */
+
+import { readFile, readdir, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { type AgentUnderTest, type HarvestedLog, type InputScript, runScenario } from './harness.ts'
+import { type NormalizeContext, normalizeSessionLog, normalizeStdout, scrubRequestHeaders } from './normalize.ts'
+
+/** A snapshot scenario and how its fixtures are produced. */
+export interface Scenario {
+  name: string
+  /** Whether the scenario drives at least one model turn (so a JSONL golden applies). */
+  hasModelTurn: boolean
+  /**
+   * Whether the run persists a comparable session log to diff against the
+   * `session.jsonl` fixture. Defaults to {@link hasModelTurn} (a model turn
+   * always produces a log worth comparing). Set it independently for a scenario
+   * that produces a non-trivial log WITHOUT a model turn — e.g. a prompt blocked
+   * by a `UserPromptSubmit` hook, which opens a `rejected` turn carrying `hook/*`
+   * events but never calls the model.
+   */
+  comparesLog?: boolean
+  /**
+   * Whether `test:snapshot:record` regenerates this scenario's `session.jsonl`
+   * from the LIVE API. `recorded` scenarios are model-driven and reproducible;
+   * `authored` scenarios (fixtures hand-written or hand-harvested — e.g. a
+   * provider error or a cancel the live API can't be coaxed into
+   * deterministically, a deterministic hook scenario, or a scripted repetition
+   * a live model won't reproduce) are NEVER re-recorded.
+   */
+  recorded: boolean
+  /**
+   * Whether replay is driven by a hand-written `replay.override.json` sidecar
+   * (a `ReplayEntry[]` that REPLACES the script derived from `session.jsonl`)
+   * — the throw/hang cases chunks cannot express. The fixture guard requires
+   * the sidecar exactly when this is set: the harness forwards the file purely
+   * on existence, so an unregistered stray sidecar would silently replace the
+   * derived script — the guard fails loud on either mismatch. Defaults to
+   * false (replay derives from the fixture's `assistant/chunk` events).
+   */
+  overridden?: boolean
+  /**
+   * How many SUBAGENT child sessions this scenario records beyond the top-level
+   * one (0 for a single-session scenario). Each child rides in a sibling fixture
+   * `session.<n>.jsonl` (1-based); replay forwards them to `dsh-llm-replay` so
+   * each child session replays from its own script, and record mode writes the
+   * harvested child logs back to those files. Defaults to 0.
+   */
+  childSessions?: number
+  /**
+   * Whether THIS scenario's fixtures keep the full request-header content (the
+   * composed system prompt and tool schema list on `request/header` /
+   * `request/header-delta` events) and compare it verbatim. Exactly one
+   * scenario per suite pins it; every other scenario stores and compares that
+   * content as `{{system}}`/`{{tools}}` tokens ({@link scrubRequestHeaders}),
+   * so a system prompt or tool-schema change shows up as ONE committed-fixture
+   * diff, not one per scenario. One pin suffices because header composition is
+   * suite-uniform (parent, spawn child, and fork child all compose the same
+   * prompt-modulo-cwd and the same tools) — and that premise is ASSERTED, not
+   * assumed: every non-pinning run's live headers must equal the pinned
+   * fixture's (normalized), so a session-dependent header (say, a restricted
+   * subagent toolset) fails loud until it gets its own pinning scenario.
+   * Defaults to false.
+   */
+  pinsHeader?: boolean
+}
+
+/** One suite's inputs: the agent to boot, where its fixtures live, and its scenario table. */
+export interface SnapshotSuiteOptions {
+  /** The agent composition every scenario boots. */
+  agent: AgentUnderTest
+  /** Absolute path of the suite's `snapshots/` directory (one subdir per scenario). */
+  snapshotsDir: string
+  /** The scenario table; exactly one entry must set `pinsHeader`. */
+  scenarios: Scenario[]
+  /**
+   * `replay` (keyless, the default tier) or `record` (live API; re-records the
+   * `recorded` scenarios' fixtures and refreshes the vitest goldens under
+   * `--update`). The caller derives this from `$DSH_SNAPSHOT` — env reading
+   * stays outside this library.
+   */
+  mode: 'replay' | 'record'
+}
+
+/**
+ * The sibling child-fixture paths for a scenario (`session.1.jsonl` …).
+ *
+ * @param dir The scenario's snapshots directory (`<snapshotsDir>/<name>`).
+ * @param childSessions How many subagent child sessions the scenario records.
+ * @returns One path per child, 1-based, in fixture order.
+ */
+export function childFixturePaths(dir: string, childSessions: number): string[] {
+  return Array.from({ length: childSessions }, (_, i) => join(dir, `session.${i + 1}.jsonl`))
+}
+
+/**
+ * Derive the {@link NormalizeContext} for a `session.jsonl` fixture from its own
+ * header line (`{ type: 'session', id, cwd }`). A committed fixture carries the
+ * session id and cwd of the run that harvested it — different from the live
+ * replay run — so normalizing it against the live run's ctx would leave those
+ * recorded values unscrubbed. Reading them from the header scrubs the fixture's
+ * own id/cwd to the same `{{sessionId}}`/`{{cwd}}` tokens the replay output gets.
+ * An authored fixture whose header is already normalized (`id:'{{sessionId}}'`,
+ * `cwd:'{{cwd}}'`) yields those tokens as the volatile values, so scrubbing them
+ * is an idempotent no-op. A header with no `cwd` falls back to a sentinel that
+ * cannot occur in a log (NOT `''`, which `String.split` would match on every
+ * character boundary and corrupt the output).
+ *
+ * @param fixture The committed `session.jsonl` content.
+ * @returns The fixture's own volatile values, ready for {@link normalizeSessionLog}.
+ */
+export function fixtureContext(fixture: string): NormalizeContext {
+  const firstLine = fixture.split('\n').find(line => line.trim().length > 0) ?? '{}'
+  const header = JSON.parse(firstLine) as { id?: unknown; cwd?: unknown }
+  return {
+    sessionIds: typeof header.id === 'string' ? [header.id] : [],
+    cwd: typeof header.cwd === 'string' ? header.cwd : '\0no-cwd\0',
+  }
+}
+
+/**
+ * The `data.header` payload of every `request/header` event in a session
+ * JSONL, in log order, with the log's volatile values scrubbed first
+ * ({@link normalizeSessionLog}) so headers harvested from different runs —
+ * each embedding its own temp cwd in the composed prompt — compare on equal
+ * footing.
+ *
+ * @param rawLog The session `.jsonl` content to extract headers from.
+ * @param ctx The volatile values of the run that produced it.
+ * @returns The normalized `data.header` payloads, in log order.
+ */
+export function normalizedHeaders(rawLog: string, ctx: NormalizeContext): unknown[] {
+  return normalizeSessionLog(rawLog, ctx)
+    .split('\n')
+    .filter(line => line.trim().length > 0)
+    .map(line => JSON.parse(line) as { type?: unknown; data?: { header?: unknown } })
+    .filter(record => record.type === 'request/header')
+    .map(record => record.data?.header)
+}
+
+/**
+ * Count the `request/header-delta` events in a session JSONL.
+ *
+ * @param rawLog The session `.jsonl` content.
+ * @returns How many `request/header-delta` events the log carries.
+ */
+export function headerDeltaCount(rawLog: string): number {
+  return rawLog.split('\n')
+    .filter(line => line.trim().length > 0)
+    .filter(line => (JSON.parse(line) as { type?: unknown }).type === 'request/header-delta')
+    .length
+}
+
+/**
+ * Register the suite: one `describe` per scenario (the golden/log compares and
+ * the header-uniformity guard) plus the fixture guard block (no orphan
+ * scenario dirs, required files present, exactly one pin, non-pinning fixtures
+ * header-scrubbed). Must run at vitest collection time — it calls
+ * `describe`/`it`. Throws immediately if no scenario pins the header (the
+ * uniformity guard would have nothing to compare against).
+ *
+ * @param options The agent, snapshots directory, scenario table, and mode.
+ */
+export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
+  const { agent, snapshotsDir, scenarios, mode } = options
+  const RECORDING = mode === 'record'
+
+  /** The suite's single header-pinning scenario. Guarded here (and by a meta-test) so the pin cannot silently vanish. */
+  const pinningScenario = scenarios.find(s => s.pinsHeader === true)
+  if (pinningScenario === undefined) throw new Error('acp-snapshot: no scenario pins the request-header content')
+
+  for (const scenario of scenarios) {
+    describe(`snapshot: ${scenario.name}`, () => {
+      // In RECORD mode, only re-run the `recorded` (live-API) scenarios; the
+      // `authored` ones (sidecar-driven errors/cancel) are never re-recorded.
+      it.skipIf(RECORDING && !scenario.recorded)('matches the goldens', async () => {
+        const dir = join(snapshotsDir, scenario.name)
+        const input = JSON.parse(await readFile(join(dir, 'input.json'), 'utf8')) as InputScript
+        const overrideFile = join(dir, 'replay.override.json')
+        const workspaceDir = join(dir, 'workspace')
+        const childSessions = scenario.childSessions ?? 0
+        const result = await runScenario(input, {
+          agent,
+          mode,
+          fixtureFile: join(dir, 'session.jsonl'),
+          ...existsSync(overrideFile) ? { overrideFile } : {},
+          // In REPLAY, forward the recorded child fixtures so each subagent session
+          // replays from its own script. In RECORD they are harvested, not read.
+          ...!RECORDING && childSessions > 0 ? { childFiles: childFixturePaths(dir, childSessions) } : {},
+          ...existsSync(workspaceDir) ? { workspaceDir } : {},
+        })
+
+        // Scrub every volatile id the run produced: the ACP server-issued session
+        // id plus every harvested log's recorded id (a subagent child id never
+        // surfaces over ACP, but it appears in the child's own log header). The
+        // normalizer's UUID catch-all covers any we don't enumerate.
+        const ctx: NormalizeContext = {
+          sessionIds: [
+            ...result.sessionId !== undefined ? [result.sessionId] : [],
+            ...result.sessionLogs.map(l => l.id),
+          ],
+          cwd: result.cwd,
+        }
+
+        // RECORD mode (recorded model scenarios only): persist the freshly-harvested
+        // logs back to their fixtures — the primary to session.jsonl, each child to
+        // session.<n>.jsonl in harvest order. `--update` refreshes the Vitest
+        // goldens but NOT these fixtures, so write them here. A non-pinning
+        // scenario's fixtures are written header-scrubbed, so a re-record can
+        // never smuggle the full prompt/schema content back into every fixture.
+        const scrub = scenario.pinsHeader === true
+          ? (log: string): string => log
+          : scrubRequestHeaders
+        if (RECORDING && scenario.recorded && scenario.hasModelTurn) {
+          expect(result.sessionLogs.length, 'record produced no session log to harvest').toBeGreaterThan(0)
+          expect(result.sessionLogs.length, `expected ${childSessions + 1} session logs (parent + children)`)
+            .toBe(childSessions + 1)
+          await writeFile(join(dir, 'session.jsonl'), scrub((result.sessionLogs[0] as HarvestedLog).content))
+          for (let i = 1; i < result.sessionLogs.length; i++) {
+            await writeFile(join(dir, `session.${i}.jsonl`), scrub((result.sessionLogs[i] as HarvestedLog).content))
+          }
+        }
+
+        await expect(normalizeStdout(result.rawStdout, ctx))
+          .toMatchFileSnapshot(join(dir, 'stdout.golden.jsonl'))
+
+        // A model turn always produces a log worth comparing; a hook scenario can
+        // produce one without a model turn (a `rejected` turn carrying `hook/*`).
+        const comparesLog = scenario.comparesLog ?? scenario.hasModelTurn
+        if (comparesLog) {
+          // The harvested logs (primary-first) must match their committed fixtures
+          // 1:1. Each side passes through normalizeSessionLog, scrubbed against ITS
+          // OWN volatile values — the live run's via `ctx`, the committed fixture's
+          // via its own header (a committed file cannot share the live run's ids).
+          // Unless this scenario pins the header, both sides ALSO pass through
+          // scrubRequestHeaders: the live log carries the real prompt/schemas, the
+          // fixture carries the `{{system}}`/`{{tools}}` tokens, and the scrub is
+          // idempotent — so the compare checks the header's presence, position,
+          // reason, and config, but not its bulk content (pinned once, in the
+          // `pinsHeader` scenario).
+          expect(result.sessionLogs.length, 'this scenario must persist a session log').toBe(childSessions + 1)
+          const fixtureFiles = ['session.jsonl', ...Array.from({ length: childSessions }, (_, i) => `session.${i + 1}.jsonl`)]
+          for (let i = 0; i < fixtureFiles.length; i++) {
+            const harvested = scrub((result.sessionLogs[i] as HarvestedLog).content)
+            const fixture = scrub(await readFile(join(dir, fixtureFiles[i] as string), 'utf8'))
+            expect(normalizeSessionLog(harvested, ctx), `${fixtureFiles[i]} mismatch`)
+              .toEqual(normalizeSessionLog(fixture, fixtureContext(fixture)))
+          }
+        }
+
+        // Header-uniformity guard: the single pin is sound only while every
+        // session in the suite composes the SAME header and keeps it for the
+        // whole run. Assert both halves live. (1) Every request/header the run
+        // produced (parent, spawn child, fork child, initial or resume) must
+        // equal the pinned fixture's header after each side is normalized
+        // against its own volatile values. (2) No request/header-delta may
+        // appear at all — a mid-run header change diverges from the pin by
+        // construction, and its content would be invisible under the scrub. If
+        // either fails, either the header changed (update the pin: re-record or
+        // hand-edit the pinning scenario's fixture) or composition became
+        // session-dependent by design (give the divergent shape its own
+        // pinning scenario).
+        if (scenario.pinsHeader !== true) {
+          const pinnedFixture = await readFile(join(snapshotsDir, pinningScenario.name, 'session.jsonl'), 'utf8')
+          const pinned = normalizedHeaders(pinnedFixture, fixtureContext(pinnedFixture))
+          expect(pinned.length, `the pinning fixture (${pinningScenario.name}) must carry exactly one request/header`)
+            .toBe(1)
+          for (const log of result.sessionLogs) {
+            expect(headerDeltaCount(log.content), `session ${log.id}: a request/header-delta in a non-pinning scenario`)
+              .toBe(0)
+            const headers = normalizedHeaders(log.content, ctx)
+            for (const [k, header] of headers.entries()) {
+              expect(header, `session ${log.id}: request/header #${k + 1} diverged from the pinned (${pinningScenario.name}) header`)
+                .toEqual(pinned[0])
+            }
+          }
+        }
+      })
+    })
+  }
+
+  describe('snapshot fixtures', () => {
+    it('every scenario directory is registered (no orphans)', async () => {
+      // toMatchFileSnapshot does not prune orphaned golden/fixture files, so a
+      // renamed/removed scenario could leave a stale dir that nothing exercises.
+      // Fail loud on any snapshots/<dir> not present in the scenario table.
+      const entries = await readdir(snapshotsDir, { withFileTypes: true })
+      const onDisk = entries.filter(e => e.isDirectory()).map(e => e.name).sort()
+      const registered = scenarios.map(s => s.name).sort()
+      expect(onDisk).toEqual(registered)
+    })
+
+    it('every registered scenario has its required fixture files', () => {
+      // Every scenario has an input script and an stdout golden. EVERY scenario
+      // also needs `session.jsonl`: the suite boots `llm-replay` with that path
+      // as the replay source for ALL scenarios (the factory passes
+      // `fixtureFile: <dir>/session.jsonl` unconditionally), and `loadReplayScript`
+      // throws "fixture not found" when it is absent and no override replaces it.
+      // A no-model scenario ships a header-only `session.jsonl` (it derives to an
+      // empty script — no model call is made); a model scenario's fixture also
+      // doubles as the expected-log artifact the run is diffed against. The
+      // `replay.override.json` sidecar is matched BOTH ways against the table's
+      // `overridden` flag: required when set, forbidden when not — the harness
+      // forwards the file purely on existence, so an unregistered stray sidecar
+      // would silently replace the derived script.
+      for (const { name, overridden, childSessions } of scenarios) {
+        const dir = join(snapshotsDir, name)
+        expect(existsSync(join(dir, 'input.json')), `${name}/input.json`).toBe(true)
+        expect(existsSync(join(dir, 'stdout.golden.jsonl')), `${name}/stdout.golden.jsonl`).toBe(true)
+        expect(existsSync(join(dir, 'session.jsonl')), `${name}/session.jsonl`).toBe(true)
+        expect(existsSync(join(dir, 'replay.override.json')), `${name}/replay.override.json presence must match \`overridden\``)
+          .toBe(overridden === true)
+        // A nested-agent scenario ships one child fixture per recorded subagent
+        // session (`session.1.jsonl` …), the replay source for that child session.
+        for (const childFixture of childFixturePaths(dir, childSessions ?? 0)) {
+          expect(existsSync(childFixture), childFixture).toBe(true)
+        }
+      }
+    })
+
+    it('exactly one scenario pins the request-header content', () => {
+      // Zero pins would drop the prompt/schema surface from the suite entirely;
+      // two would split it. One pin per suite is the design (pinned-header RFC);
+      // WHICH scenario pins is the scenario table's reviewable choice.
+      expect(scenarios.filter(s => s.pinsHeader === true).map(s => s.name)).toEqual([pinningScenario.name])
+    })
+
+    it('committed fixtures carry request-header content ONLY in the pinning scenario', async () => {
+      // The whole point of the pin: a system-prompt or tool-schema change must
+      // churn exactly one committed line. A non-pinning fixture that carries the
+      // full header (a hand-recorded file, or a header line hand-edited out of
+      // its canonical JSON form) silently reopens the suite-wide churn, so fail
+      // loud here: every non-pinning session*.jsonl must be a fixed point of
+      // scrubRequestHeaders (apply the scrub to fix a violation), and the
+      // pinning scenario's fixtures must NOT be (their content IS the pin).
+      for (const scenario of scenarios) {
+        const dir = join(snapshotsDir, scenario.name)
+        const files = [
+          'session.jsonl',
+          ...Array.from({ length: scenario.childSessions ?? 0 }, (_, i) => `session.${i + 1}.jsonl`),
+        ]
+        for (const file of files) {
+          const fixture = await readFile(join(dir, file), 'utf8')
+          if (scenario.pinsHeader === true) {
+            expect(scrubRequestHeaders(fixture), `${scenario.name}/${file} must PIN the full header content`)
+              .not.toEqual(fixture)
+          } else {
+            expect(scrubRequestHeaders(fixture), `${scenario.name}/${file} carries unscrubbed header content`)
+              .toEqual(fixture)
+          }
+        }
+      }
+    })
+  })
+}
@@ -0,0 +1,232 @@
+/**
+ * Scripted fake ACP agent bin for `dsh-acp-snapshot`'s unit specs. Speaks
+ * newline-delimited JSON-RPC on stdio like the real `dsh-acp-agent` bin, but
+ * every behavior — how prompts settle, whether session/new rejects, which
+ * session logs get persisted, what filesystem noise to leave — comes from a
+ * `behavior.json` sitting NEXT to the `$DSH_SNAPSHOT_FILE` fixture, so a spec
+ * scripts a whole subprocess run from data. The specs launch it through the
+ * REAL `runScenario` spawn path (tsx loader, temp cwd, env plumbing), so the
+ * harness plumbing is exercised for real; only the agent behind the protocol
+ * is scripted.
+ *
+ * The specs (not the golden tier) own this bin: it asserts nothing, echoes
+ * observable facts into `session/update` text chunks (env probe, permission
+ * outcome, seeded-workspace listing) for the spec to read off `rawStdout`, and
+ * exits 0 on stdin EOF after writing the scripted logs — mirroring the real
+ * bin's dispose-flush-exit shape.
+ */
+
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { createInterface } from 'node:readline'
+
+/** One scripted session log: a file path under the sessions root plus its JSONL lines. */
+interface ScriptedLog {
+  /** Path relative to `$DSH_SNAPSHOT_SESSIONS_ROOT`, e.g. `bucket/a.jsonl` (an empty dir segment is invalid). */
+  file: string
+  /**
+   * The JSONL records. String templates `{{CWD}}` and `{{SID}}` are replaced
+   * with the run's real cwd and the ACP session id this bin issued, so a
+   * written log carries genuine volatile values for the normalizers to scrub.
+   */
+  lines: unknown[]
+}
+
+/** The whole scripted behavior for one run. Every field defaults to the least surprising choice. */
+interface Behavior {
+  /** Reject every `session/new` (exercises the expect-error step without extra dirs). */
+  rejectNewSession?: boolean
+  /** Reject `session/new` only when `additionalDirectories` is non-empty (the real bridge's rule). */
+  rejectExtraDirs?: boolean
+  /** How `session/prompt` settles: a clean response, a JSON-RPC error, or a hang until `session/cancel`. */
+  prompt?: 'respond' | 'error' | 'hang-until-cancel'
+  /** Before responding to a prompt, send a `session/request_permission` request and echo its outcome as a chunk. */
+  permissionProbe?: boolean
+  /** Echo the `DSH_SNAPSHOT_*` env the harness set as a chunk (spec-side env-plumbing assertions). */
+  echoEnv?: boolean
+  /** Echo the sorted cwd listing as a chunk (spec-side workspace-seeding assertions). */
+  echoWorkspace?: boolean
+  /** Write a line to stderr on boot (spec-side stderr-capture assertions). */
+  stderrNote?: string
+  /** Session logs to persist on stdin EOF. */
+  logs?: ScriptedLog[]
+  /** Leave a stray FILE directly under the sessions root (harvest must skip it). */
+  strayRootFile?: boolean
+  /** Leave a stray non-`.jsonl` file inside a bucket (harvest must skip it). */
+  strayBucketFile?: boolean
+  /** Delete the sessions root entirely (harvest must yield no logs). */
+  deleteSessionsRoot?: boolean
+}
+
+const sessionsRoot = process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? ''
+const fixtureFile = process.env.DSH_SNAPSHOT_FILE ?? ''
+const behavior: Behavior = fixtureFile === ''
+  ? {}
+  : JSON.parse(readFileSync(join(dirname(fixtureFile), 'behavior.json'), 'utf8')) as Behavior
+
+if (behavior.stderrNote !== undefined) process.stderr.write(`${behavior.stderrNote}\n`)
+
+let nextOutboundId = 1000
+let sessionId = ''
+/**
+ * The cwd the client passed to `session/new` — used verbatim for `{{CWD}}`
+ * substitution, mirroring the real bin (whose persisted header carries the
+ * session cwd as given, NOT `process.cwd()`, which the OS realpaths — on
+ * macOS `/var/folders/…` vs `/private/var/folders/…`).
+ */
+let sessionCwd = ''
+/** The parked prompt request id while `hang-until-cancel` waits for the cancel notification. */
+let parkedPromptId: number | string | null = null
+/** Resolvers for permission-probe responses, keyed by outbound request id. */
+const pendingPermission = new Map<number, (outcome: unknown) => void>()
+
+function send(frame: Record<string, unknown>): void {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', ...frame })}\n`)
+}
+
+function respond(id: number | string, result: unknown): void {
+  send({ id, result })
+}
+
+function respondError(id: number | string, message: string): void {
+  send({ id, error: { code: -32603, message } })
+}
+
+function chunk(text: string): void {
+  send({
+    method: 'session/update',
+    params: { sessionId, update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text } } },
+  })
+}
+
+/** Substitute the `{{CWD}}`/`{{SID}}` templates through a scripted log record. */
+function instantiate(value: unknown): unknown {
+  if (typeof value === 'string') return value.split('{{CWD}}').join(sessionCwd).split('{{SID}}').join(sessionId)
+  if (Array.isArray(value)) return value.map(instantiate)
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(value)) out[k] = instantiate(v)
+    return out
+  }
+  return value
+}
+
+async function handlePrompt(id: number | string): Promise<void> {
+  if ((behavior.prompt ?? 'respond') === 'hang-until-cancel') {
+    // A thought chunk BEFORE any message chunk: a promptAndCancel waiter
+    // watches for agent_message_chunk, so this exercises its non-matching
+    // update path while the waiter is armed.
+    send({
+      method: 'session/update',
+      params: { sessionId, update: { sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: 'mulling' } } },
+    })
+  }
+  chunk('thinking about it')
+  if (behavior.echoEnv === true) {
+    chunk(`env:${JSON.stringify({
+      mode: process.env.DSH_SNAPSHOT,
+      override: process.env.DSH_SNAPSHOT_OVERRIDE ?? null,
+      childFiles: process.env.DSH_SNAPSHOT_CHILD_FILES ?? null,
+    })}`)
+  }
+  if (behavior.echoWorkspace === true) {
+    chunk(`workspace:${readdirSync(process.cwd()).sort().join(',')}`)
+  }
+  if (behavior.permissionProbe === true) {
+    const requestId = nextOutboundId++
+    const outcome = await new Promise<unknown>((resolve) => {
+      pendingPermission.set(requestId, resolve)
+      send({
+        id: requestId,
+        method: 'session/request_permission',
+        params: {
+          sessionId,
+          toolCall: { toolCallId: 'call_fake_1', title: 'fake tool', kind: 'execute', status: 'pending' },
+          options: [
+            { optionId: 'opt-allow', name: 'Allow once', kind: 'allow_once' },
+            { optionId: 'opt-reject', name: 'Reject once', kind: 'reject_once' },
+          ],
+        },
+      })
+    })
+    chunk(`permission:${JSON.stringify(outcome)}`)
+  }
+  switch (behavior.prompt ?? 'respond') {
+    case 'respond':
+      respond(id, { stopReason: 'end_turn' })
+      return
+    case 'error':
+      respondError(id, 'model exploded')
+      return
+    case 'hang-until-cancel':
+      parkedPromptId = id
+      return
+  }
+}
+
+function handleFrame(frame: Record<string, unknown>): void {
+  const id = frame.id as number | string | undefined
+  const method = frame.method as string | undefined
+  const params = (frame.params ?? {}) as Record<string, unknown>
+  // A response to one of OUR outbound requests (the permission probe).
+  if (method === undefined && id !== undefined && typeof id === 'number' && pendingPermission.has(id)) {
+    const resolve = pendingPermission.get(id) as (outcome: unknown) => void
+    pendingPermission.delete(id)
+    resolve((frame.result as { outcome?: unknown } | undefined)?.outcome ?? null)
+    return
+  }
+  switch (method) {
+    case 'initialize':
+      respond(id as number | string, { protocolVersion: 1, agentCapabilities: { loadSession: false } })
+      return
+    case 'session/new': {
+      const extra = params.additionalDirectories as unknown[] | undefined
+      if (behavior.rejectNewSession === true || (behavior.rejectExtraDirs === true && extra !== undefined && extra.length > 0)) {
+        respondError(id as number | string, 'unsupported workspace scope')
+        return
+      }
+      sessionId = randomUUID()
+      sessionCwd = typeof params.cwd === 'string' ? params.cwd : process.cwd()
+      respond(id as number | string, { sessionId })
+      return
+    }
+    case 'session/prompt':
+      void handlePrompt(id as number | string)
+      return
+    case 'session/cancel':
+      if (parkedPromptId !== null) {
+        const parked = parkedPromptId
+        parkedPromptId = null
+        respond(parked, { stopReason: 'cancelled' })
+      }
+      return
+    default:
+      // Unknown method: a notification is ignored; a request gets an error so
+      // the SDK never waits forever on a frame this fake doesn't model.
+      if (id !== undefined) respondError(id, `unhandled method ${String(method)}`)
+  }
+}
+
+function flushLogsAndExit(): void {
+  for (const log of behavior.logs ?? []) {
+    const target = join(sessionsRoot, log.file)
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, log.lines.map(l => JSON.stringify(instantiate(l))).join('\n') + '\n')
+  }
+  if (behavior.strayRootFile === true) writeFileSync(join(sessionsRoot, 'stray.txt'), 'not a bucket\n')
+  if (behavior.strayBucketFile === true) {
+    mkdirSync(join(sessionsRoot, 'bucket-noise'), { recursive: true })
+    writeFileSync(join(sessionsRoot, 'bucket-noise', 'notes.txt'), 'not a session log\n')
+  }
+  if (behavior.deleteSessionsRoot === true) rmSync(sessionsRoot, { recursive: true, force: true })
+  process.exit(0)
+}
+
+const rl = createInterface({ input: process.stdin })
+rl.on('line', (line) => {
+  if (line.trim().length === 0) return
+  handleFrame(JSON.parse(line) as Record<string, unknown>)
+})
+rl.on('close', () => { flushLogsAndExit() })
@@ -0,0 +1,13 @@
+{
+  "prompt": "respond",
+  "logs": [
+    { "file": "b/parent.jsonl", "lines": [
+      { "type": "session", "id": "{{SID}}", "createdAt": 700, "cwd": "{{CWD}}" },
+      { "type": "request/header", "seq": 0, "time": 3, "data": { "header": { "config": { "model": "fake" }, "system": "SYS PROMPT", "tools": [{ "name": "t1", "description": "D1", "parameters": { "type": "object" } }] }, "reason": "initial" } }
+    ]},
+    { "file": "b/child.jsonl", "lines": [
+      { "type": "session", "id": "abababab-cdcd-4efe-8ada-badabadabada", "createdAt": 800, "cwd": "{{CWD}}", "parentSession": "{{SID}}" },
+      { "type": "request/header", "seq": 0, "time": 2, "data": { "header": { "config": { "model": "fake" }, "system": "SYS PROMPT", "tools": [{ "name": "t1", "description": "D1", "parameters": { "type": "object" } }] }, "reason": "initial" } }
+    ]}
+  ]
+}
@@ -0,0 +1 @@
+{ "steps": [{ "op": "initialize" }, { "op": "newSession" }, { "op": "prompt", "text": "rec child" }] }
@@ -0,0 +1,2 @@
+{"type":"session","id":"abababab-cdcd-4efe-8ada-badabadabada","createdAt":800,"cwd":"/var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-KBQJbW","parentSession":"f6fa7fcf-dd9c-4b39-8815-b25ddcebfd88"}
+{"type":"request/header","seq":0,"time":2,"data":{"header":{"config":{"model":"fake"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
@@ -0,0 +1,2 @@
+{"type":"session","id":"f6fa7fcf-dd9c-4b39-8815-b25ddcebfd88","createdAt":700,"cwd":"/var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-KBQJbW"}
+{"type":"request/header","seq":0,"time":3,"data":{"header":{"config":{"model":"fake"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
@@ -0,0 +1,4 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentCapabilities":{"loadSession":false}}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"thinking about it"}}}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}
@@ -0,0 +1,10 @@
+{
+  "prompt": "respond",
+  "logs": [{
+    "file": "b/main.jsonl",
+    "lines": [
+      { "type": "session", "id": "{{SID}}", "createdAt": 600, "cwd": "{{CWD}}" },
+      { "type": "request/header", "seq": 0, "time": 4, "data": { "header": { "config": { "model": "fake" }, "system": "SYS PROMPT", "tools": [{ "name": "t1", "description": "D1", "parameters": { "type": "object" } }] }, "reason": "initial" } }
+    ]
+  }]
+}
@@ -0,0 +1 @@
+{ "steps": [{ "op": "initialize" }, { "op": "newSession" }, { "op": "prompt", "text": "rec pin" }] }
@@ -0,0 +1,2 @@
+{"type":"session","id":"ccdc749f-56f3-4267-9750-598b5c60b7b2","createdAt":600,"cwd":"/var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-nOQ4Gy"}
+{"type":"request/header","seq":0,"time":4,"data":{"header":{"config":{"model":"fake"},"system":"SYS PROMPT","tools":[{"name":"t1","description":"D1","parameters":{"type":"object"}}]},"reason":"initial"}}
@@ -0,0 +1,4 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentCapabilities":{"loadSession":false}}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"thinking about it"}}}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}
@@ -0,0 +1 @@
+{}
@@ -0,0 +1 @@
+{ "steps": [{ "op": "initialize" }] }
@@ -0,0 +1 @@
+[{ "kind": "hang" }]
@@ -0,0 +1 @@
+{"type":"session","id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}"}
@@ -0,0 +1 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentCapabilities":{"loadSession":false}}}
@@ -0,0 +1,10 @@
+{
+  "prompt": "error",
+  "logs": [{
+    "file": "b/main.jsonl",
+    "lines": [
+      { "type": "session", "id": "{{SID}}", "createdAt": 500, "cwd": "{{CWD}}" },
+      { "type": "turn/end", "seq": 1, "time": 9, "data": { "error": "model exploded" } }
+    ]
+  }]
+}
@@ -0,0 +1 @@
+{ "steps": [{ "op": "initialize" }, { "op": "newSession" }, { "op": "promptExpectError", "text": "boom" }] }
@@ -0,0 +1 @@
+[{ "kind": "throw", "chunks": [], "message": "model exploded", "code": "PROVIDER" }]
@@ -0,0 +1,2 @@
+{"type":"session","id":"44444444-3333-4222-8111-000000000000","createdAt":17,"cwd":"/rec/authored-cwd"}
+{"type":"turn/end","seq":1,"time":17,"data":{"error":"model exploded"}}
@@ -0,0 +1,4 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentCapabilities":{"loadSession":false}}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"thinking about it"}}}}
+{"jsonrpc":"2.0","id":3,"error":{"code":-32603,"message":"model exploded"}}
@@ -0,0 +1,10 @@
+{
+  "prompt": "error",
+  "logs": [{
+    "file": "b/main.jsonl",
+    "lines": [
+      { "type": "session", "id": "{{SID}}", "createdAt": 400, "cwd": "{{CWD}}" },
+      { "type": "hook/result", "seq": 1, "time": 8, "data": { "decision": "block", "durationMs": 37 } }
+    ]
+  }]
+}
@@ -0,0 +1 @@
+{ "steps": [{ "op": "initialize" }, { "op": "newSession" }, { "op": "promptExpectError", "text": "blocked" }] }
@@ -0,0 +1,2 @@
+{"type":"session","id":"99999999-8888-4777-8666-555555555555","createdAt":13,"cwd":"/rec/blocked-cwd"}
+{"type":"hook/result","seq":1,"time":13,"data":{"decision":"block","durationMs":99}}
@@ -0,0 +1,4 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentCapabilities":{"loadSession":false}}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"thinking about it"}}}}
+{"jsonrpc":"2.0","id":3,"error":{"code":-32603,"message":"model exploded"}}
@@ -0,0 +1 @@
+{}
@@ -0,0 +1 @@
+{ "steps": [{ "op": "initialize" }] }
@@ -0,0 +1 @@
+{"type":"session","id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}"}
@@ -0,0 +1 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentCapabilities":{"loadSession":false}}}
@@ -0,0 +1,11 @@
+{
+  "prompt": "respond",
+  "logs": [{
+    "file": "b/main.jsonl",
+    "lines": [
+      { "type": "session", "id": "{{SID}}", "createdAt": 100, "cwd": "{{CWD}}" },
+      { "type": "request/header", "seq": 0, "time": 100, "data": { "header": { "config": { "model": "fake" }, "system": "SYS PROMPT", "tools": [{ "name": "t1", "description": "D1", "parameters": { "type": "object" } }] }, "reason": "initial" } },
+      { "type": "turn/start", "seq": 1, "time": 100, "data": { "turn": 1 } }
+    ]
+  }]
+}
@@ -0,0 +1 @@
+{ "steps": [{ "op": "initialize" }, { "op": "newSession" }, { "op": "prompt", "text": "pin" }] }
@@ -0,0 +1,3 @@
+{"type":"session","id":"12121212-3434-4545-8686-787878787878","createdAt":7,"cwd":"/rec/pin-cwd"}
+{"type":"request/header","seq":0,"time":7,"data":{"header":{"config":{"model":"fake"},"system":"SYS PROMPT","tools":[{"name":"t1","description":"D1","parameters":{"type":"object"}}]},"reason":"initial"}}
+{"type":"turn/start","seq":1,"time":7,"data":{"turn":1}}
@@ -0,0 +1,4 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentCapabilities":{"loadSession":false}}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"thinking about it"}}}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}
@@ -0,0 +1,15 @@
+{
+  "prompt": "respond",
+  "echoWorkspace": true,
+  "logs": [
+    { "file": "b/parent.jsonl", "lines": [
+      { "type": "session", "id": "{{SID}}", "createdAt": 200, "cwd": "{{CWD}}" },
+      { "type": "request/header", "seq": 0, "time": 5, "data": { "header": { "config": { "model": "fake" }, "system": "SYS PROMPT", "tools": [{ "name": "t1", "description": "D1", "parameters": { "type": "object" } }] }, "reason": "initial" } },
+      { "type": "assistant/chunk", "seq": 1, "time": 5, "data": { "turn": 1, "step": 1, "chunk": { "type": "text-delta", "index": 0, "text": "hi" } } }
+    ]},
+    { "file": "b/child.jsonl", "lines": [
+      { "type": "session", "id": "eeeeeeee-1111-4222-8333-444444444444", "createdAt": 300, "cwd": "{{CWD}}", "parentSession": "{{SID}}" },
+      { "type": "request/header", "seq": 0, "time": 6, "data": { "header": { "config": { "model": "fake" }, "system": "SYS PROMPT", "tools": [{ "name": "t1", "description": "D1", "parameters": { "type": "object" } }] }, "reason": "initial" } }
+    ]}
+  ]
+}
@@ -0,0 +1 @@
+{ "steps": [{ "op": "initialize" }, { "op": "newSession" }, { "op": "prompt", "text": "plain" }] }
@@ -0,0 +1,2 @@
+{"type":"session","id":"eeeeeeee-1111-4222-8333-444444444444","createdAt":12,"cwd":"/rec/plain-cwd","parentSession":"56565656-7878-4989-8a9a-9b9b9b9b9b9b"}
+{"type":"request/header","seq":0,"time":12,"data":{"header":{"config":{"model":"fake"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
@@ -0,0 +1,3 @@
+{"type":"session","id":"56565656-7878-4989-8a9a-9b9b9b9b9b9b","createdAt":11,"cwd":"/rec/plain-cwd"}
+{"type":"request/header","seq":0,"time":11,"data":{"header":{"config":{"model":"fake"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":1,"time":11,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"hi"}}}
@@ -0,0 +1,5 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentCapabilities":{"loadSession":false}}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"thinking about it"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"workspace:seed.txt"}}}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}
@@ -0,0 +1 @@
+seeded
@@ -0,0 +1,272 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { delimiter, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, describe, expect, it } from 'vitest'
+import { runScenario, type AgentUnderTest, type InputStep } from '../src/harness.ts'
+
+/**
+ * Unit tests for the subprocess harness, driven through the REAL spawn path
+ * (tsx loader, temp cwd, env plumbing) against the scripted fake ACP bin in
+ * ./fixtures/fake-acp-agent.ts. Each case writes a `behavior.json` next to a
+ * throwaway fixture path; the fake bin echoes observable facts (env, seeded
+ * workspace, permission outcomes) into `agent_message_chunk` text, so the
+ * assertions read plain `rawStdout`.
+ */
+
+const AGENT: AgentUnderTest = {
+  binScript: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)),
+  // The fake bin ignores its config argv; any real path documents the shape.
+  configPath: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)),
+  tsconfigPath: fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)),
+}
+
+/** Temp scenario dirs to drop after the suite. */
+const tempDirs: string[] = []
+afterAll(async () => {
+  for (const dir of tempDirs) await rm(dir, { recursive: true, force: true })
+})
+
+/** Write a behavior.json into a fresh temp dir; return the sibling fixture path the harness points the bin at. */
+async function scenario(behavior: object): Promise<{ dir: string; fixtureFile: string }> {
+  const dir = await mkdtemp(join(tmpdir(), 'acp-snap-spec-'))
+  tempDirs.push(dir)
+  await writeFile(join(dir, 'behavior.json'), JSON.stringify(behavior))
+  return { dir, fixtureFile: join(dir, 'session.jsonl') }
+}
+
+const boot: InputStep[] = [{ op: 'initialize' }, { op: 'newSession' }]
+
+describe('runScenario', () => {
+  it('drives a full turn: initialize (terminal caps), session, prompt, permission stub, harvest', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({
+      permissionProbe: true,
+      logs: [{
+        file: 'bucket/main.jsonl',
+        lines: [
+          { type: 'session', id: '{{SID}}', createdAt: 42, cwd: '{{CWD}}' },
+          { type: 'turn/start', seq: 1, time: 9, data: { turn: 1 } },
+        ],
+      }],
+    })
+    const result = await runScenario(
+      { steps: [{ op: 'initialize', terminalOutput: true }, { op: 'newSession' }, { op: 'prompt', text: 'go' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    expect(result.sessionId).toBeDefined()
+    // The harness's client answers a permission request with `cancelled`; the
+    // fake bin echoes the outcome it received back as a chunk.
+    expect(result.rawStdout).toContain('permission:{\\"outcome\\":\\"cancelled\\"}')
+    expect(result.sessionLogs).toHaveLength(1)
+    expect(result.sessionLogs[0]?.id).toBe(result.sessionId)
+    expect(result.sessionLogs[0]?.createdAt).toBe(42)
+    expect(result.sessionLogs[0]?.content).toContain('turn/start')
+    // The harvested log embeds the run's REAL temp cwd (template-substituted).
+    expect(result.sessionLogs[0]?.content).toContain(result.cwd)
+  })
+
+  it('forwards override/child fixture paths into the child env and captures stderr', { timeout: 20_000 }, async () => {
+    const { dir, fixtureFile } = await scenario({ echoEnv: true, stderrNote: 'fake bin booted' })
+    const childFiles = [join(dir, 'session.1.jsonl'), join(dir, 'session.2.jsonl')]
+    const result = await runScenario(
+      { steps: [...boot, { op: 'prompt', text: 'env?' }] },
+      {
+        agent: AGENT,
+        mode: 'replay',
+        fixtureFile,
+        overrideFile: join(dir, 'replay.override.json'),
+        childFiles,
+        // A workspaceDir that does not exist is skipped, not an error.
+        workspaceDir: join(dir, 'no-such-workspace'),
+      },
+    )
+    expect(result.stderr).toContain('fake bin booted')
+    expect(result.rawStdout).toContain('replay.override.json')
+    // Child paths ride one env var, joined with the platform delimiter.
+    expect(result.rawStdout).toContain(JSON.stringify(childFiles.join(delimiter)).slice(1, -1))
+  })
+
+  it('seeds the workspace dir into the temp cwd before the run', { timeout: 20_000 }, async () => {
+    const { dir, fixtureFile } = await scenario({ echoWorkspace: true })
+    const workspaceDir = join(dir, 'workspace')
+    await writeFile(join(dir, 'behavior.json'), JSON.stringify({ echoWorkspace: true }))
+    const { mkdir } = await import('node:fs/promises')
+    await mkdir(workspaceDir, { recursive: true })
+    await writeFile(join(workspaceDir, 'seeded.txt'), 'hello')
+    const result = await runScenario(
+      { steps: [...boot, { op: 'prompt', text: 'ls' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile, workspaceDir },
+    )
+    expect(result.rawStdout).toContain('workspace:seeded.txt')
+  })
+
+  it('promptAndCancel waits for the streamed chunk, cancels, and settles the prompt', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({ prompt: 'hang-until-cancel' })
+    const result = await runScenario(
+      { steps: [...boot, { op: 'promptAndCancel', text: 'hang' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    expect(result.rawStdout).toContain('"stopReason":"cancelled"')
+    // The streamed chunk deterministically precedes the cancelled response.
+    expect(result.rawStdout.indexOf('thinking about it')).toBeLessThan(result.rawStdout.indexOf('cancelled'))
+  })
+
+  it('promptExpectError swallows a model-error response as the expected outcome', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({ prompt: 'error' })
+    const result = await runScenario(
+      { steps: [...boot, { op: 'promptExpectError', text: 'boom' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    expect(result.rawStdout).toContain('model exploded')
+  })
+
+  it('promptExpectError throws when the prompt unexpectedly succeeds (and teardown kills the live child)', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({ prompt: 'respond' })
+    await expect(runScenario(
+      { steps: [...boot, { op: 'promptExpectError', text: 'fine' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )).rejects.toThrow(/expected the prompt to fail/)
+  })
+
+  it('newSessionExpectError swallows the rejection, with and without extra dirs', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({ rejectExtraDirs: true })
+    const result = await runScenario(
+      { steps: [{ op: 'initialize' }, { op: 'newSessionExpectError', additionalDirectories: ['/elsewhere'] }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    // No session was created, so no id and no logs.
+    expect(result.sessionId).toBeUndefined()
+    expect(result.sessionLogs).toHaveLength(0)
+
+    const rejectAll = await scenario({ rejectNewSession: true })
+    const second = await runScenario(
+      { steps: [{ op: 'initialize' }, { op: 'newSessionExpectError' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile: rejectAll.fixtureFile },
+    )
+    expect(second.rawStdout).toContain('unsupported workspace scope')
+  })
+
+  it('newSessionExpectError throws when session/new unexpectedly succeeds', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({})
+    await expect(runScenario(
+      { steps: [{ op: 'initialize' }, { op: 'newSessionExpectError' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )).rejects.toThrow(/expected session\/new to be rejected/)
+  })
+
+  it('a plain cancel step is forwarded (and ignored by an idle agent)', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({})
+    const result = await runScenario(
+      { steps: [...boot, { op: 'cancel' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    expect(result.sessionId).toBeDefined()
+  })
+
+  it.each([
+    [{ op: 'prompt', text: 'x' }, /prompt before newSession/],
+    [{ op: 'promptExpectError', text: 'x' }, /promptExpectError before newSession/],
+    [{ op: 'promptAndCancel', text: 'x' }, /promptAndCancel before newSession/],
+    [{ op: 'cancel' }, /cancel before newSession/],
+  ] as [InputStep, RegExp][])('rejects %j before newSession', { timeout: 20_000 }, async (step, message) => {
+    const { fixtureFile } = await scenario({})
+    await expect(runScenario(
+      { steps: [{ op: 'initialize' }, step] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )).rejects.toThrow(message)
+  })
+
+  it('rejects an unknown input op', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({})
+    const bogus = { op: 'reticulate' } as unknown as InputStep
+    await expect(runScenario(
+      { steps: [bogus] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )).rejects.toThrow(/unknown input op/)
+  })
+
+  it('harvests all logs primary-first, children by createdAt then id, skipping filesystem noise', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({
+      strayRootFile: true,
+      strayBucketFile: true,
+      logs: [
+        // File names chosen so readdir feeds the sort children-first AND
+        // parent-in-the-middle: the comparator then sees a parent on both
+        // sides of a pair, plus the same-createdAt (localeCompare) tiebreak.
+        { file: 'b1/aa-child-c.jsonl', lines: [{ type: 'session', id: 'cccccccc-0000-4000-8000-000000000000', createdAt: 500, parentSession: '{{SID}}' }] },
+        { file: 'b1/bb-parent.jsonl', lines: [{ type: 'session', id: '{{SID}}', createdAt: 900 }] },
+        { file: 'b1/cc-child-a.jsonl', lines: [{ type: 'session', id: 'aaaaaaaa-0000-4000-8000-000000000000', createdAt: 500, parentSession: '{{SID}}' }] },
+        // Missing id/createdAt fall back to ''/0; earliest child by createdAt.
+        { file: 'b2/orphan-fields.jsonl', lines: [{ type: 'session', parentSession: '{{SID}}' }] },
+      ],
+    })
+    const result = await runScenario(
+      { steps: [...boot, { op: 'prompt', text: 'go' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    expect(result.sessionLogs.map(l => [l.id, l.createdAt])).toEqual([
+      [result.sessionId, 900],
+      ['', 0],
+      ['aaaaaaaa-0000-4000-8000-000000000000', 500],
+      ['cccccccc-0000-4000-8000-000000000000', 500],
+    ])
+    expect(result.sessionLogs[1]?.parentSession).toBe(result.sessionId)
+  })
+
+  it('treats an empty log file as a header-less primary with default fields', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({ logs: [{ file: 'b/empty.jsonl', lines: [] }] })
+    const result = await runScenario(
+      { steps: boot },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    expect(result.sessionLogs.map(l => [l.id, l.createdAt, l.parentSession])).toEqual([['', 0, undefined]])
+  })
+
+  it('yields no logs when the sessions root vanished', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({ deleteSessionsRoot: true })
+    const result = await runScenario(
+      { steps: boot },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    expect(result.sessionLogs).toHaveLength(0)
+  })
+
+  it('answers permission requests from the scripted queue by option kind, falling back to cancelled', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({ permissionProbe: true })
+    // Two prompts → two permission round-trips; one scripted answer, so the
+    // second request exercises the exhausted-queue fallback.
+    const result = await runScenario(
+      {
+        steps: [...boot, { op: 'prompt', text: 'one' }, { op: 'prompt', text: 'two' }],
+        permissionAnswers: [{ kind: 'allow_once' }],
+      },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    const first = result.rawStdout.indexOf('permission:{\\"outcome\\":\\"selected\\",\\"optionId\\":\\"opt-allow\\"}')
+    const second = result.rawStdout.indexOf('permission:{\\"outcome\\":\\"cancelled\\"}')
+    expect(first).toBeGreaterThanOrEqual(0)
+    expect(second).toBeGreaterThan(first)
+  })
+
+  it('selects a non-first offered option by kind', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({ permissionProbe: true })
+    const result = await runScenario(
+      { steps: [...boot, { op: 'prompt', text: 'deny it' }], permissionAnswers: [{ kind: 'reject_once' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    expect(result.rawStdout).toContain('permission:{\\"outcome\\":\\"selected\\",\\"optionId\\":\\"opt-reject\\"}')
+  })
+
+  it('rejects the run on a scripted permission kind the agent never offered', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({ permissionProbe: true })
+    // The fake bin offers allow_once/reject_once; scripting allow_always is a
+    // scenario bug. The agent is answered `cancelled` (it must not be able to
+    // absorb the bug as an error-means-denial), and the RUN fails: a callback
+    // throw would only reach the agent as a JSON-RPC error response, letting
+    // a tolerant agent carry on and the scenario pass — or record.
+    await expect(runScenario(
+      { steps: [...boot, { op: 'prompt', text: 'impossible click' }], permissionAnswers: [{ kind: 'allow_always' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )).rejects.toThrow(/allow_always not among the offered options \[allow_once, reject_once\]/)
+  })
+})
@@ -1,9 +1,9 @@
 import { describe, expect, it } from 'vitest'
-import { type NormalizeContext, normalizeSessionLog, normalizeStdout, scrubRequestHeaders } from '../tests/snapshot-normalize.ts'
+import { type NormalizeContext, normalizeSessionLog, normalizeStdout, scrubRequestHeaders } from '../src/normalize.ts'

 /**
 * Unit tests for the pure snapshot normalizers. Live as a *.spec.ts (runs in
- * the default unit gate) and import the harness-side normalizers directly.
+ * the default unit gate) and import the normalizers directly.
 */

 const ctx: NormalizeContext = {
@@ -107,6 +107,17 @@ describe('normalizeSessionLog', () => {
    const out = normalizeSessionLog(`${header({})}\n${ev}\n`, ctx)
    expect(out).toContain('"durationMs":88')
  })
+
+  it('tolerates records missing the volatile fields it would zero', () => {
+    const bareHeader = JSON.stringify({ type: 'session', id: 's' })
+    const timeless = JSON.stringify({ type: 'note', seq: 1 })
+    const bareHook = JSON.stringify({ type: 'hook/result', seq: 2, time: 5, data: { decision: 'allow' } })
+    const nullDataHook = JSON.stringify({ type: 'hook/result', seq: 3, time: 6, data: null })
+    const out = normalizeSessionLog(`${bareHeader}\n${timeless}\n${bareHook}\n${nullDataHook}\n`, ctx)
+    expect(out).toContain('"type":"note","seq":1')
+    expect(out).toContain('"decision":"allow"')
+    expect(out).not.toContain('durationMs')
+  })
 })

 describe('scrubRequestHeaders', () => {
@@ -135,6 +146,40 @@ describe('scrubRequestHeaders', () => {
    expect(out).not.toContain('{{tools}}')
  })

+  it('scrubs a header carrying only one of system/tools, leaving the other absent', () => {
+    const systemOnly = scrubRequestHeaders(`${headerLine}\n${headerEvent({ system: 'secret prompt' })}\n`)
+    expect(systemOnly).toContain('"system":"{{system}}"')
+    expect(systemOnly).not.toContain('{{tools}}')
+    const toolsOnly = scrubRequestHeaders(`${headerLine}\n${headerEvent({ tools: [{ name: 't' }] })}\n`)
+    expect(toolsOnly).toContain('"tools":"{{tools}}"')
+    expect(toolsOnly).not.toContain('{{system}}')
+  })
+
+  it('leaves a delta with no scrubbable payload byte-identical (config-only, or non-array shapes)', () => {
+    const configOnly = JSON.stringify({ type: 'request/header-delta', seq: 8, time: 9, data: { config: { model: 'm2' } } })
+    const oddShapes = JSON.stringify({ type: 'request/header-delta', seq: 9, time: 9, data: { system: { insert: 'not-an-array' }, tools: null } })
+    const headerless = JSON.stringify({ type: 'request/header', seq: 10, time: 9, data: { reason: 'initial' } })
+    const nullData = JSON.stringify({ type: 'request/header', seq: 11, time: 9, data: null })
+    const raw = `${headerLine}\n${configOnly}\n${oddShapes}\n${headerless}\n${nullData}\n`
+    expect(scrubRequestHeaders(raw)).toBe(raw)
+  })
+
+  it('scrubs a one-sided tools delta and passes non-object schema entries through', () => {
+    const addedOnly = JSON.stringify({
+      type: 'request/header-delta', seq: 8, time: 9,
+      data: { tools: { added: [null, 'weird', { name: 'x', description: 'D' }] } },
+    })
+    const out = scrubRequestHeaders(`${headerLine}\n${addedOnly}\n`)
+    // Non-object entries survive untouched; the object entry keeps only name.
+    expect(out).toContain('"added":[null,"weird",{"name":"x","description":"{{tools}}"}]')
+    const changedOnly = JSON.stringify({
+      type: 'request/header-delta', seq: 8, time: 9,
+      data: { tools: { changed: [{ name: 'y', parameters: {} }] } },
+    })
+    expect(scrubRequestHeaders(`${headerLine}\n${changedOnly}\n`))
+      .toContain('"changed":[{"name":"y","parameters":"{{tools}}"}]')
+  })
+
  it('scrubs a header-delta system payload but keeps its line positions and arity', () => {
    const delta = JSON.stringify({
      type: 'request/header-delta', seq: 8, time: 9,
@@ -0,0 +1,145 @@
+import { cpSync, mkdtempSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, describe, expect, it } from 'vitest'
+import { defineAcpSnapshotSuite, type Scenario } from '../src/index.ts'
+import { childFixturePaths, fixtureContext, headerDeltaCount, normalizedHeaders } from '../src/suite.ts'
+
+/**
+ * Unit tests for the suite factory, by running it: two synthetic suites over
+ * the scripted fake ACP bin (./fixtures/fake-acp-agent.ts) register REAL
+ * describe/it trees at collection time, so every factory path — golden and log
+ * compares, the per-suite header pin and its uniformity guard, record-mode
+ * fixture write-back, skip semantics, and the fixture guard block — executes
+ * as an ordinary green test. The pure helpers get direct cases below.
+ *
+ * The replay suite runs against the committed fixtures in ./fixtures/suite.
+ * The record suite runs against a TEMP COPY of ./fixtures/record-suite
+ * (record mode writes session fixtures back into its snapshots dir; a run must
+ * never touch the committed tree). To re-bootstrap the record tree's goldens
+ * after changing the fake bin's output, run this spec once with
+ * `ACP_SNAPSHOT_SPEC_BOOTSTRAP=1` (points the record suite at the committed
+ * tree so vitest creates/updates the goldens and the write-back lands there),
+ * then commit the result.
+ */
+
+const AGENT = {
+  binScript: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)),
+  configPath: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)),
+  tsconfigPath: fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)),
+}
+
+const REPLAY_DIR = fileURLToPath(new URL('./fixtures/suite', import.meta.url))
+const RECORD_SRC = fileURLToPath(new URL('./fixtures/record-suite', import.meta.url))
+
+const REPLAY_SCENARIOS: Scenario[] = [
+  { name: 'pin-turn', hasModelTurn: true, recorded: true, pinsHeader: true },
+  { name: 'plain-turn', hasModelTurn: true, recorded: true, childSessions: 1 },
+  { name: 'no-model', hasModelTurn: false, recorded: false },
+  { name: 'blocked-log', hasModelTurn: false, comparesLog: true, recorded: false },
+  { name: 'authored-error', hasModelTurn: true, recorded: false, overridden: true },
+]
+
+const RECORD_SCENARIOS: Scenario[] = [
+  { name: 'rec-pin', hasModelTurn: true, recorded: true, pinsHeader: true },
+  { name: 'rec-child', hasModelTurn: true, recorded: true, childSessions: 1 },
+  // recorded:false in record mode → registered but skipped (never re-recorded).
+  { name: 'rec-skip', hasModelTurn: true, recorded: false, overridden: true },
+]
+
+// Record mode mutates its snapshots dir, so run it on a throwaway copy —
+// except under the documented bootstrap knob, which regenerates the committed
+// fixtures/goldens in place.
+const BOOTSTRAP = process.env.ACP_SNAPSHOT_SPEC_BOOTSTRAP === '1'
+const recordDir = BOOTSTRAP ? RECORD_SRC : mkdtempSync(join(tmpdir(), 'acp-snap-record-suite-'))
+if (!BOOTSTRAP) cpSync(RECORD_SRC, recordDir, { recursive: true })
+afterAll(async () => {
+  if (!BOOTSTRAP) await rm(recordDir, { recursive: true, force: true })
+})
+
+describe('defineAcpSnapshotSuite: replay mode', () => {
+  defineAcpSnapshotSuite({ agent: AGENT, snapshotsDir: REPLAY_DIR, scenarios: REPLAY_SCENARIOS, mode: 'replay' })
+})
+
+// The record suite's tests run in registration order: rec-pin re-records the
+// pinned fixture FIRST, so rec-child's uniformity guard reads the fresh pin.
+describe('defineAcpSnapshotSuite: record mode', () => {
+  defineAcpSnapshotSuite({ agent: AGENT, snapshotsDir: recordDir, scenarios: RECORD_SCENARIOS, mode: 'record' })
+})
+
+describe('defineAcpSnapshotSuite: registration contract', () => {
+  it('throws when no scenario pins the request-header content', () => {
+    expect(() => {
+      defineAcpSnapshotSuite({
+        agent: AGENT,
+        snapshotsDir: REPLAY_DIR,
+        scenarios: [{ name: 'pinless', hasModelTurn: true, recorded: true }],
+        mode: 'replay',
+      })
+    }).toThrow(/no scenario pins/)
+  })
+})
+
+describe('childFixturePaths', () => {
+  it('yields one sibling path per child, 1-based', () => {
+    expect(childFixturePaths('/snap/s', 2)).toEqual(['/snap/s/session.1.jsonl', '/snap/s/session.2.jsonl'])
+  })
+
+  it('yields nothing for a single-session scenario', () => {
+    expect(childFixturePaths('/snap/s', 0)).toEqual([])
+  })
+})
+
+describe('fixtureContext', () => {
+  it('reads the fixture header id and cwd', () => {
+    const ctx = fixtureContext('{"type":"session","id":"abc","cwd":"/rec"}\n{"type":"turn/start"}\n')
+    expect(ctx).toEqual({ sessionIds: ['abc'], cwd: '/rec' })
+  })
+
+  it('yields no session ids for a header without a string id', () => {
+    expect(fixtureContext('{"type":"session","cwd":"/rec"}\n').sessionIds).toEqual([])
+  })
+
+  it('falls back to an impossible sentinel cwd (never the empty string)', () => {
+    const ctx = fixtureContext('{"type":"session","id":"abc"}\n')
+    expect(ctx.cwd).toBe('\0no-cwd\0')
+    expect(ctx.cwd).not.toBe('')
+  })
+
+  it('treats an empty fixture as an empty header', () => {
+    expect(fixtureContext('')).toEqual({ sessionIds: [], cwd: '\0no-cwd\0' })
+  })
+})
+
+describe('normalizedHeaders', () => {
+  const header = (system: string): string => JSON.stringify({
+    type: 'request/header', seq: 0, time: 9, data: { header: { config: { model: 'm' }, system }, reason: 'initial' },
+  })
+
+  it('extracts every request/header payload in log order, normalized', () => {
+    const id = '11111111-2222-4333-8444-555555555555'
+    const log = `${JSON.stringify({ type: 'session', id, createdAt: 5, cwd: '/w' })}\n${header('one')}\n`
+      + `${JSON.stringify({ type: 'turn/start', seq: 1, time: 9, data: { turn: 1 } })}\n${header('two')}\n`
+    const headers = normalizedHeaders(log, { sessionIds: [id], cwd: '/w' })
+    expect(headers).toEqual([
+      { config: { model: 'm' }, system: 'one' },
+      { config: { model: 'm' }, system: 'two' },
+    ])
+  })
+
+  it('yields nothing for a log without header events', () => {
+    const log = `${JSON.stringify({ type: 'session', id: 'a', createdAt: 5 })}\n`
+    expect(normalizedHeaders(log, { sessionIds: [], cwd: '/w' })).toEqual([])
+  })
+})
+
+describe('headerDeltaCount', () => {
+  it('counts request/header-delta events, ignoring blanks and other lines', () => {
+    const delta = JSON.stringify({ type: 'request/header-delta', seq: 2, time: 9, data: {} })
+    const other = JSON.stringify({ type: 'request/header', seq: 0, time: 9, data: {} })
+    expect(headerDeltaCount(`${other}\n\n${delta}\n${delta}\n`)).toBe(2)
+    expect(headerDeltaCount(`${other}\n`)).toBe(0)
+  })
+})
@@ -0,0 +1,11 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": []
+}
@@ -127,6 +127,12 @@ importers:
        specifier: ^4.0.0-rc.6
        version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)

+  packages/code-runtime/code-runtime:
+    devDependencies:
+      cordis:
+        specifier: ^4.0.0-rc.6
+        version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
+
  packages/compact/compact:
    devDependencies:
      '@deepseek-ai/dsh-llm':
@@ -393,6 +399,34 @@ importers:
        specifier: ^4.0.0-rc.6
        version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)

+  packages/guard/repeat-tool-guard:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: 3.18.0
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-agent-loop':
+        specifier: workspace:^
+        version: link:../../core/agent-loop
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      cordis:
+        specifier: ^4.0.0-rc.6
+        version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
+
  packages/hooks/hook-protocol:
    devDependencies:
      '@deepseek-ai/dsh-bash':
@@ -760,6 +794,22 @@ importers:
        specifier: ^4.0.0-rc.6
        version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)

+  packages/support/acp-snapshot:
+    dependencies:
+      '@agentclientprotocol/sdk':
+        specifier: 0.25.1
+        version: 0.25.1(zod@4.4.3)
+      tsx:
+        specifier: ^4.22.4
+        version: 4.22.4
+      vitest:
+        specifier: ^4.1.8
+        version: 4.1.8(@types/node@25.9.3)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))
+    devDependencies:
+      cordis:
+        specifier: ^4.0.0-rc.6
+        version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
+
  packages/support/invariants:
    devDependencies:
      '@deepseek-ai/dsh-agent':
@@ -5292,6 +5342,14 @@ snapshots:
    optionalDependencies:
      vite: 8.0.16(@types/node@22.20.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)

+  '@vitest/mocker@4.1.8(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))':
+    dependencies:
+      '@vitest/spy': 4.1.8
+      estree-walker: 3.0.3
+      magic-string: 0.30.21
+    optionalDependencies:
+      vite: 8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)
+
  '@vitest/pretty-format@4.1.8':
    dependencies:
      tinyrainbow: 3.1.0
@@ -6942,6 +7000,21 @@ snapshots:
      tsx: 4.22.4
      yaml: 2.9.0

+  vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0):
+    dependencies:
+      lightningcss: 1.32.0
+      picomatch: 4.0.4
+      postcss: 8.5.15
+      rolldown: 1.0.3
+      tinyglobby: 0.2.17
+    optionalDependencies:
+      '@types/node': 25.9.3
+      esbuild: 0.28.1
+      fsevents: 2.3.3
+      jiti: 2.7.0
+      tsx: 4.22.4
+      yaml: 2.9.0
+
  vitest@4.1.8(@types/node@22.20.0)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@22.20.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)):
    dependencies:
      '@vitest/expect': 4.1.8
@@ -6971,6 +7044,35 @@ snapshots:
    transitivePeerDependencies:
      - msw

+  vitest@4.1.8(@types/node@25.9.3)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)):
+    dependencies:
+      '@vitest/expect': 4.1.8
+      '@vitest/mocker': 4.1.8(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0))
+      '@vitest/pretty-format': 4.1.8
+      '@vitest/runner': 4.1.8
+      '@vitest/snapshot': 4.1.8
+      '@vitest/spy': 4.1.8
+      '@vitest/utils': 4.1.8
+      es-module-lexer: 2.1.0
+      expect-type: 1.3.0
+      magic-string: 0.30.21
+      obug: 2.1.3
+      pathe: 2.0.3
+      picomatch: 4.0.4
+      std-env: 4.1.0
+      tinybench: 2.9.0
+      tinyexec: 1.2.4
+      tinyglobby: 0.2.17
+      tinyrainbow: 3.1.0
+      vite: 8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)
+      why-is-node-running: 2.3.0
+    optionalDependencies:
+      '@types/node': 25.9.3
+      '@vitest/coverage-v8': 4.1.8(vitest@4.1.8)
+      jsdom: 29.1.1
+    transitivePeerDependencies:
+      - msw
+
  w3c-xmlserializer@5.0.0:
    dependencies:
      xml-name-validator: 5.0.0
@@ -1,7 +1,7 @@
 {
  "AGENTS.md": 1691,
  "docs/AGENTS.md": 1315,
-  "docs/architecture.md": 1630,
+  "docs/architecture.md": 1640,
  "docs/cordis-primer.md": 550,
  "docs/defensive-patterns.md": 550,
  "docs/testing.md": 800,
@@ -97,6 +97,8 @@ export const LINK_MAP: Record<string, string> = {
  BashRunResult: 'bash.md',
  BashTask: 'bash.md',
  BashTaskRead: 'bash.md',
+  CodeRunRequest: 'code-runtime.md',
+  CodeRunResult: 'code-runtime.md',
  FsEditOutcome: 'filesystem.md',
  FsEditRequest: 'filesystem.md',
  FsInfo: 'filesystem.md',
@@ -158,6 +158,15 @@ const SERVICE_ROLES: ServiceRole[] = [
    consumers: ['tool-bash', 'hooks-claude', 'hooks-codex'],
    note: 'The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors can replace bash-local.',
  },
+  {
+    key: 'codeRuntime',
+    pkg: 'code-runtime',
+    title: 'Code-execution seam',
+    mode: 'seam',
+    implementations: [],
+    consumers: [],
+    note: 'Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the Code Mode RFC specifies the worker-thread backend and the tool-registry consumer).',
+  },
  {
    key: 'fs',
    pkg: 'fs',
@@ -63,6 +63,13 @@
    { "doc": "docs/core-data-structures/bash.md", "symbol": "BashTask", "source": "packages/bash/bash/src/types.ts" },
    { "doc": "docs/core-data-structures/bash.md", "symbol": "BashTaskRead", "source": "packages/bash/bash/src/types.ts" },

+    { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeRunRequest", "source": "packages/code-runtime/code-runtime/src/types.ts" },
+    { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeRunResult", "source": "packages/code-runtime/code-runtime/src/types.ts" },
+    { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeBindingNamespace", "source": "packages/code-runtime/code-runtime/src/types.ts" },
+    { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeBindingFunction", "source": "packages/code-runtime/code-runtime/src/types.ts" },
+    { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeLogEntry", "source": "packages/code-runtime/code-runtime/src/types.ts" },
+    { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeRunFailure", "source": "packages/code-runtime/code-runtime/src/types.ts" },
+
    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsTarget", "source": "packages/fs/fs/src/types.ts" },
    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsTargetKey", "source": "packages/fs/fs/src/types.ts" },
    { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsVersion", "source": "packages/fs/fs/src/types.ts" },
@@ -43,8 +43,10 @@
        "./packages/core/*/src",
        "./packages/llm/*/src",
        "./packages/bash/*/src",
+        "./packages/code-runtime/*/src",
        "./packages/fs/*/src",
        "./packages/compact/*/src",
+        "./packages/guard/*/src",
        "./packages/subagent/*/src",
        "./packages/web/*/src",
        "./packages/todo/*/src",
@@ -24,6 +24,7 @@
    { "path": "./packages/core/agent-loop" },
    { "path": "./packages/core/agent-core" },
    { "path": "./packages/bash/bash" },
+    { "path": "./packages/code-runtime/code-runtime" },
    { "path": "./packages/compact/compact" },
    { "path": "./packages/compact/compact-basic" },
    { "path": "./packages/llm/llm-deepseek" },
@@ -46,6 +47,7 @@
    { "path": "./packages/ui/app-boot" },
    { "path": "./packages/ui/stdio-agent" },
    { "path": "./packages/support/llm-replay" },
+    { "path": "./packages/support/acp-snapshot" },
    { "path": "./packages/subagent/subagent" },
    { "path": "./packages/support/subagent-mock" },
    { "path": "./packages/subagent/tool-subagent" },
@@ -54,6 +56,7 @@
    { "path": "./packages/subagent/subagent-fork" },
    { "path": "./packages/subagent/subagent-acp" },
    { "path": "./packages/todo/tool-todo" },
+    { "path": "./packages/guard/repeat-tool-guard" },
    { "path": "./packages/hooks/hook-protocol" },
    { "path": "./packages/hooks/hooks-claude" },
    { "path": "./packages/hooks/hooks-codex" }
@@ -35,6 +35,7 @@
    { "path": "./packages/core/agent-loop" },
    { "path": "./packages/core/agent-core" },
    { "path": "./packages/bash/bash" },
+    { "path": "./packages/code-runtime/code-runtime" },
    { "path": "./packages/llm/llm-deepseek" },
    { "path": "./packages/llm/llm-pi-ai" },
    { "path": "./packages/bash/bash-local" },
@@ -57,6 +58,7 @@
    { "path": "./packages/ui/app-boot" },
    { "path": "./packages/ui/stdio-agent" },
    { "path": "./packages/support/llm-replay" },
+    { "path": "./packages/support/acp-snapshot" },
    { "path": "./packages/subagent/subagent" },
    { "path": "./packages/support/subagent-mock" },
    { "path": "./packages/subagent/tool-subagent" },
@@ -65,6 +67,7 @@
    { "path": "./packages/subagent/subagent-fork" },
    { "path": "./packages/subagent/subagent-acp" },
    { "path": "./packages/todo/tool-todo" },
+    { "path": "./packages/guard/repeat-tool-guard" },
    { "path": "./packages/hooks/hook-protocol" },
    { "path": "./packages/hooks/hooks-claude" },
    { "path": "./packages/hooks/hooks-codex" }
				`@@ -0,0 +1 @@`
				`{ "steps": [{ "op": "initialize" }, { "op": "newSession" }, { "op": "prompt", "text": "rec child" }] }`
				`@@ -0,0 +1 @@`
				`{"type":"session","id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}"}`
				`@@ -0,0 +1 @@`
				`{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentCapabilities":{"loadSession":false}}}`
				`@@ -0,0 +1 @@`
				`[{ "kind": "throw", "chunks": [], "message": "model exploded", "code": "PROVIDER" }]`