Merge remote-tracking branch 'origin/master' into session-query-search

# Conflicts: # docs/config-catalog.md # docs/cordis-catalog/services.md # docs/module-graph.md # packages/session-persistence/session-persistence-jsonl/README.md # packages/session-persistence/session-persistence-jsonl/src/index.ts # packages/session-persistence/session-persistence-sqlite/README.md # packages/session-persistence/session-persistence-sqlite/src/index.ts # packages/session-persistence/session-persistence-sqlite/src/schema.ts # packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts # packages/session-persistence/session-persistence/README.md # packages/session-persistence/session-persistence/src/coordinator.ts # packages/session-persistence/session-persistence/tests/persistence.spec.ts # packages/session-query/session-query/README.md
2026-07-15 16:17:59 +08:00
parent 9eb49f61a9 b4ec4060a7
commit aa82ba4abc
841 changed files with 18816 additions and 16117 deletions
--- a/packages/AGENTS.md
+++ b/packages/AGENTS.md
@@ -1,18 +1,17 @@
 # AGENTS.md — Harness Packages

-This directory contains all `@deepseek-ai/dsh-*` harness packages. Repo-wide conventions (effects, declaration merging, waterfall semantics, ESM, testing policy) are in the root [AGENTS.md](../AGENTS.md) § Conventions; the points below are packages-specific.
+These package-specific rules supplement the repo-wide [conventions](../AGENTS.md#conventions).

- **Plugin export shape — namespace OR default, never both.** A *service* package exports the service class as `export default` (the Loader instantiates it). A *function/namespace* plugin exports `name` / `inject` / `Config` / `apply` as separate named exports and **must NOT add `export default`** — the cordis Loader's `unwrapExports` does `exports.default ?? exports`, so a stray default export collapses the module to the bare `apply` function and silently discards the `inject`/`name`/`Config` namespace, leaving the plugin with no injected services (it then throws `cannot get property … without inject` at load). See [docs/postmortem/0001](../docs/postmortem/0001-acp-default-export-drops-inject.md).
- **Read an optional (non-injected) service via `ctx.get(name)`, not `ctx.<name>`.** For a service a plugin reads opportunistically but deliberately leaves out of `static inject` (e.g. `AgentLoop` reading `sessionPersistence`), the `ctx.<name>` property proxy resolves by an ancestor-only fiber walk that throws when the call arrives through a foreign traceable shadow (the service lives on a sibling fiber). `ctx.get(name)` is the topology-independent global-store lookup, strict by default (an inactive/absent backend reads as `undefined` — prefer it over the `ctx.get(name, false)` overload, which also skips the active-state check). Services that ARE in `static inject` resolve fine via `ctx.<name>`. See [docs/postmortem/0001](../docs/postmortem/0001-acp-default-export-drops-inject.md).
- **A plugin shipped via `cordis.yml` needs at least one test through the REAL Loader/export path** — hand-built `ctx.plugin({...})` mounts bypass `unwrapExports` and cannot catch a broken export shape. Full testing policy (tiers, with-key generosity, real-entry-path guards): [docs/testing.md](../docs/testing.md).
+- **Plugin export shape:** service packages default-export their service class; function plugins named-export `name` / `inject` / `Config` / `apply` and have no default export. Mixing the forms makes the Loader discard the function plugin's namespace ([postmortem](../docs/postmortem/0001-acp-default-export-drops-inject.md)).
+- **Optional services use `ctx.get(name)`.** Reserve `ctx.<name>` for declared injections; the property proxy is topology-sensitive, while strict `ctx.get` reads the global service store ([postmortem](../docs/postmortem/0001-acp-default-export-drops-inject.md)).
+- **Product-visible plugins require a non-unit REAL-composition test.** Hand-built `ctx.plugin(...)` suites are insufficient. Boot test-only `cordis.yml` through the Loader and app/process; mock only external/nondeterministic boundaries and assert model-visible, durable, or user-visible output. Keep opt-ins out of shipped defaults. [Policy](../docs/testing.md).
 - **Typed same-process service and plugin calls are contracts, not serialization boundaries.** Prefer readonly borrowed values; materialize or defensively validate only at parser/config, queued, model/tool JSON, durable/file, worker, process, or wire boundaries.
 - **Represent one asynchronous operation with one lifecycle controller or transaction.** Separate readiness, cancellation, disposal, reservation, or sentinel state requires an independent owner or settlement boundary; otherwise fold it while preserving rollback, callback containment, and quiescence.

 Naming notes:

- A *service* `src/index.ts` exports the service class as `export default` + all public types; a *function/namespace plugin* `src/index.ts` exports `name`/`inject`/`Config`/`apply` as named exports and NO default (the export-shape rule above).
 - `src/types.ts` contains only types — no runtime code.
 - Tests live at package level under `tests/`, not `src/__tests__/`.
- A package's README and JSDoc are part of the change: altered behavior (config keys, defaults, error codes, wire fields) updates them in the same commit. `doc-sync` gates what it can; prose accuracy stays on the author ([the documentation standard](../docs/AGENTS.md)).
-
-Read the per-package README.md for package-specific details: service API, events, extension points, TODOs.
+- A package's README and JSDoc are part of the change: altered behavior (config keys, defaults, error codes, wire fields) updates them in the same commit. `doc-sync` gates what it can; apply [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for complete, concise prose and verify accuracy against code.
+- Package READMEs document model/token effects using the [canonical Model Experience format](../docs/cookbook/adding-a-package.md#4-write-the-package-readme).
+- Package READMEs put durable consumer gaps and non-obvious maintainer constraints under `## Known Limitations and Deferred Work`; ordinary cleanup stays in its TODO or RFC. Packages with none use a justified [allowlist entry](../scripts/verify-package-readme-limitations.ts) ([rationale](../docs/rfc/implemented/process/2026-07-10-readme-known-limitations-gate.md)).
--- a/packages/README.md
+++ b/packages/README.md
@@ -1,6 +1,6 @@
 # Packages

-Harness packages use the `@deepseek-ai/dsh-*` scope. Each is a Cordis plugin: a default `Service` subclass or functional plugin declaring ctx keys/events through declaration merging and contributing through `ctx.effect()`, `ctx.on()`, or `ctx.waterfall()`. Authoring conventions: [AGENTS.md](AGENTS.md) and root [AGENTS.md](../AGENTS.md) § Conventions.
+Packages use the `@deepseek-ai/dsh-*` scope. Each is a Cordis `Service` subclass or function plugin; contributions use `ctx.effect()`, `ctx.on()`, or `ctx.waterfall()`. Authoring rules: [package](AGENTS.md) and [root](../AGENTS.md#conventions).

 ## Hierarchy

@@ -16,6 +16,7 @@ Packages are grouped by modular role at `packages/<group>/<pkg>/`. The group dir
 | [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools | Product — stable surface |
 | [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable surface |
 | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
+| [`context/`](context/README.md) | Opt-in request-context enrichment | Product — stable surface |
 | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface |
 | [`workflow/`](workflow/README.md) | Workflow capability family: the script-engine seam, the worker-thread engine, and the model-facing `workflow` 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 |
@@ -27,7 +28,7 @@ Packages are grouped by modular role at `packages/<group>/<pkg>/`. The group dir
 | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface |
 | [`session-query/`](session-query/README.md) | Session retrieval family: exact reads, semantic filtering, and SQLite full-text search | Product — stable surface |
 | [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, app packages, user-approval and user-interaction seams, ask-user tool | Product — stable surface |
-| [`support/`](support/README.md) | Dev/test/example infrastructure (invariants, replay adapter, subagent mock) | Support — lower compatibility expectations |
+| [`support/`](support/README.md) | Support infrastructure (invariants, replay, Loader smokes) | Support — lower compatibility expectations |
 | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (the `Branded<B>` primitive) | Support — small, stable, harness-dep-free |

 The split is the point: a package's group says whether it is part of the product API or support/test/example infrastructure, so release and removal decisions do not treat every package as an equal public contract. New packages join an existing group; adding a new top-level group is a deliberate act (extend the group READMEs and this table).
@@ -38,4 +39,4 @@ The inter-package dependency graph is generated: [docs/module-graph.md](../docs/

 The rule it must obey: **extension plugins depend on interfaces, never on the concrete loop.** `dsh-agent-loop` is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced. The sanctioned exception is a **composition/bundle** package like `dsh-agent-core`, whose whole job is to assemble the concrete spine: it depends on `dsh-agent-loop` (and the other concrete spine plugins) on purpose. The rule constrains plugins that EXTEND the system, not the bundle that COMPOSES it. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — see [capability seams](../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)).

-Each package has its own `README.md` with purpose, service API, events, extension points, and deliberate non-goals (TODOs).
+Package READMEs cover purpose, APIs, extension points, and [Model Experience](../docs/cookbook/adding-a-package.md#4-write-the-package-readme) unless on the model-agnostic [omission allowlist](../scripts/verify-package-readme-model-experience.ts). They also carry `## Known Limitations and Deferred Work` or use its [allowlist](../scripts/verify-package-readme-limitations.ts).
--- a/packages/bash/README.md
+++ b/packages/bash/README.md
@@ -9,4 +9,4 @@ The canonical three-package capability seam (see [capability seams](../../docs/r
 | `bash-sandbox/` | Sandbox-consuming `BashExecutor` (wraps every command argv via `ctx.sandbox`, stamps denial/enforcement facts; extends `bash-local`'s mechanics) | (registers `ctx.bash`) |
 | `tool-bash/` | Model-facing `bash`/`bash_output`/`bash_kill` tool schemas | (registers on `ctx.tools`) |

-The interface lives at `bash/bash/`. `bash-sandbox` replacing `bash-local` without touching the interface or the tool is the split doing exactly what it exists for — a leaf `cordis.yml` picks one executor entry, plus a `ctx.sandbox` provider entry for the confined one (see [examples/sandbox-acp-agent](../../examples/sandbox-acp-agent/)).
+The interface lives at `bash/bash/`. `bash-sandbox` replacing `bash-local` without touching the interface or the tool is the split doing exactly what it exists for — a leaf `cordis.yml` picks one executor entry, plus a `ctx.sandbox` provider entry for the confined one (see [the acp-agent example's default composition](../../examples/acp-agent/)).
--- a/packages/bash/bash-local/README.md
+++ b/packages/bash/bash-local/README.md
@@ -2,6 +2,8 @@

 Local-subprocess implementation of the `@deepseek-ai/dsh-bash` executor seam: `LocalBashExecutor` spawns `bash -c <command>` per call in its own process group, collects bounded output with full-stream spill files, and escalates kills SIGTERM→SIGKILL across the whole group.

+The package root exports the default and named `LocalBashExecutor` plugin plus its `Config`; subprocess plumbing stays internal to the implementation package.
+
 ## Config

 ```yaml
@@ -22,9 +24,20 @@ Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi;
 - **Spawn per call, no shell state** — every call is a fresh non-login `bash -c` (deterministic; no rc files). All four surveyed tools spawn per call. `XXX(stateful-shell)` in `src/run.ts` records the two proven stateful designs (Claude Code's cwd-only persistence; Codex's PTY exec sessions) for when real workflows demand them.
 - **Process-group kills with escalation** — children are spawned `detached` (own process group); kills send SIGTERM to the group, then SIGKILL after the `graceMs` grace (default 3s — OpenCode's escalation; pipelines and subshells die with the parent). ESRCH is tolerated; daemons that re-parent away from the group can still survive — same caveat as the surveyed tools.
 - **Tail-keep truncation + spill files** — output beyond `maxOutputBytes` keeps the in-memory TAIL (errors/results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a temp file whose path is reported when available. If the final spill close reports a delayed writeback failure, the executor still returns the tail but withholds the path rather than advertising a possibly incomplete file.
- **Model-friendly env + credential scrub** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`), then `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` (Codex's hardcoded set) so pagers and ANSI color don't garble results. This scrub is the security control that keeps the harness's *ambient* credentials out of a spawned command. A spec's `env` is merged LAST (after the scrub), so a caller's explicit entry — a value it already holds — wins even on a credential-shaped name. The spec's `stdin`, when supplied, is written to the child and closed; with none supplied, fd 0 is `/dev/null` — the exact pre-seam default, so a command that probes stdin's file type is unaffected. Both `env`/`stdin` are set by in-process plugins (the hooks bridges); the model-facing tool doesn't expose them. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
+- **Model-friendly environment** — ambient credential-shaped variables are removed before noninteractive terminal defaults and explicit caller entries are applied. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. Trusted plugins use `env` and `stdin`, but the model-facing tool does not expose them. See the [bash stdin/env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
 - **Background tasks** — `start()` returns immediately, no timeout applies (Claude Code detaches timeouts when backgrounding), `readOutput()` is incremental with whole-stream byte offsets, and disposal kills everything. The spec's opaque `owner` token is stored on the tracked task and returned by `ownerOf(id)` — the executor never interprets it (the consumer's access policy does), and because it lives with the task here it survives a `tool-bash` HMR reload.

-## Sandboxing
+## Model Experience

-Execution policy does NOT belong in this package: this executor always runs commands unconfined. Confinement is [`dsh-bash-sandbox`](../bash-sandbox/README.md), which extends this executor verbatim and confines commands under the `ctx.sandbox` seam's bwrap/Landlock/Seatbelt backends ([sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)); per-call allow/deny/ask policy belongs on the `tools/pre-execute` gate.
+Indirectly, through `dsh-tool-bash`, which renders this executor's bounded stdout/stderr tails, background-task deltas and state, spill-file path, exact `Error: unknown bash task "<taskId>"` and `Error: aborted before spawn: <reason>` failures, and retains each resulting tool message until compaction.
+
+## Known Limitations and Deferred Work
+
+- **Unconfined by itself** — this executor always runs commands with the harness process's authority; deployments needing confinement compose [`dsh-bash-sandbox`](../bash-sandbox/README.md), while per-call allow/deny/ask policy belongs on `tools/pre-execute`.
+- **No persistent shell or PTY** — every call starts a fresh non-login `bash -c`; cwd-only persistence and interactive terminal sessions remain deferred until a real workflow requires them.
+- **POSIX-only** — the `bash` binary, detached process groups, group kills, and SIGTERM→SIGKILL escalation are hardcoded; Windows is unsupported.
+- **The credential scrub is a name heuristic** — `*KEY*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSWORD*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
+- **Spill files are never deleted** — full-output recovery files (and the private per-process spill dir) accumulate under the OS tmpdir until something external cleans them.
+- **Finished background tasks are never evicted** — they stay in the task map, retaining their in-memory output tails, until executor disposal.
+
+The raw process handling lives in `src/run.ts`; `src/index.ts` is the service wiring.
--- a/packages/bash/bash-local/package.json
+++ b/packages/bash/bash-local/package.json
@@ -24,7 +24,7 @@
  "peerDependencies": {
    "@deepseek-ai/dsh-bash": "^0.0.1",
    "@deepseek-ai/dsh-timeout": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  },
  "dependencies": {
    "schemastery": "^3.18.0"
@@ -32,6 +32,6 @@
  "devDependencies": {
    "@deepseek-ai/dsh-bash": "workspace:^",
    "@deepseek-ai/dsh-timeout": "workspace:^",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/bash/bash-local/src/index.ts
+++ b/packages/bash/bash-local/src/index.ts
@@ -1,16 +1,8 @@
 /**
- * `LocalBashExecutor`: the local-subprocess implementation of the
- * `@deepseek-ai/dsh-bash` executor seam. Spawns `bash -c` per call in its
- * own process group (see `./run.ts` for the plumbing and the agent-tool
- * survey notes), tracks background tasks, and kills everything on dispose.
- *
- * TODO(permissions/sandbox): execution policy does NOT belong here — use
- * the `tools/pre-execute` deny/ask gate (see docs/architecture.md
- * § Extending The Harness) or implement a sandboxing `BashExecutor`.
- * Reference points:
- * Claude Code wraps commands in sandbox-exec/bubblewrap; Codex applies
- * seatbelt/landlock plus an execpolicy prefix-rule engine.
- *
+ * Local-subprocess implementation of the bash seam. Each call runs in its own
+ * process group, background tasks are tracked, and disposal kills and awaits
+ * them. Execution policy belongs in `tools/pre-execute` or a sandboxing
+ * executor, not this local process layer.
 * @module @deepseek-ai/dsh-bash-local
 */

@@ -22,9 +14,6 @@ import { clampTimeout, deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
 import { DEFAULT_GRACE_MS, runBash } from './run.ts'
 import type { RunInternals, RunningBash } from './run.ts'

-export { DEFAULT_GRACE_MS, ENV_OVERRIDES, killGroup, OutputCollector, runBash } from './run.ts'
-export type { RunInternals, RunningBash, SpawnOutcome, SpawnSpec } from './run.ts'
-
 /** Plugin config (all optional — `static Config` supplies the defaults). */
 export interface Config {
  /** Default working directory for commands (default: process.cwd()). */
@@ -90,10 +79,9 @@ export class LocalBashExecutor extends BashExecutor {
    assertPositiveFinite('maxOutputBytes', this.config.maxOutputBytes)
    assertPositiveFinite('graceMs', this.config.graceMs)
    ctx.effect(() => async () => {
-      // Kill every live process group and WAIT for the processes to close so
-      // nothing outlives the fiber (HMR safety) — a TERM-trapping child is
-      // held until the SIGKILL escalation lands. The base class already
-      // silenced listeners, so these kills complete without notices.
+      // Kill every live process group and WAIT for the processes to close so nothing outlives
+      // the fiber (HMR safety) — a TERM-trapping child is held until the SIGKILL escalation
+      // lands.
      const pending: Promise<void>[] = []
      for (const task of this.tasks.values()) {
        if (task.status === 'running') {
@@ -154,23 +142,18 @@ export class LocalBashExecutor extends BashExecutor {
      stdin: spec.stdin,
      env: spec.env,
    }, this.internals).done
-    // Classify the FIRST abort reason: a BASH_TIMEOUT TimeoutReason means our
-    // timeout cut the command short; any other abort — an upstream cancel, or a
-    // foreign (outer) deadline's timeout under nesting — is aborted. Scoping to
-    // our own code keeps a nested outer deadline from reading as our timeout.
-    // Mutually exclusive by construction — the fused signal reports one cause.
+    // Classify the FIRST abort reason: a BASH_TIMEOUT TimeoutReason means our timeout cut the
+    // command short; any other abort — an upstream cancel, or a foreign (outer) deadline's
+    // timeout under nesting — is aborted.
    const timedOut = timeoutOf(d.signal, 'BASH_TIMEOUT') !== undefined
    const aborted = d.signal.aborted && !timedOut
    return { ...outcome, timedOut, aborted, timeoutMs: spec.timeoutMs }
  }

  start(spec: BashExecSpec): BashTask {
-    // No timeout for background tasks (matches Claude Code, which detaches
-    // the timeout when backgrounding); callers stop tasks via kill() — or
-    // via spec.signal, which the seam contract honors for background runs
-    // too (runBash wires it to the group kill). No deadline is created here,
-    // so spec.timeoutMs is ignored by design — background tasks stay
-    // timeout-free (see the timeout-library RFC).
+    // No timeout for background tasks (matches Claude Code, which detaches the timeout when
+    // backgrounding); callers stop tasks via kill() — or via spec.signal, which the seam
+    // contract honors for background runs too (runBash wires it to the group kill).
    const running = runBash({
      command: spec.command,
      cwd: spec.workdir,
@@ -184,7 +167,6 @@ export class LocalBashExecutor extends BashExecutor {
    const id = BashTaskId(`bash-${this.nextTaskId++}`)
    const task: TrackedTask = {
      id,
-      command: spec.command,
      status: 'running',
      exitCode: null,
      signal: null,
--- a/packages/bash/bash-local/src/run.ts
+++ b/packages/bash/bash-local/src/run.ts
@@ -1,23 +1,7 @@
 /**
- * Process plumbing for the local bash executor: spawn, output collection
- * with tail-keep + spill-to-disk truncation, and process-group kill with
- * SIGTERM→SIGKILL escalation.
- *
- * Everything here is deliberately free of Cordis concepts so it can be unit
- * tested in isolation; `LocalBashExecutor` owns lifecycle and configuration.
- *
- * runBash owns NO timing: it kills the process group when its `spec.signal`
- * fires and does not distinguish a timeout from a cancel. The executor fuses
- * timeout + upstream cancellation into that one signal via
- * `@deepseek-ai/dsh-timeout`'s `deadline`, and classifies the outcome from the
- * signal afterward — the timing/classification half is shared, the kill is not.
- *
- * Design notes (surveyed against Claude Code, OpenCode, Codex, and pi — see
- * the package README): spawn-per-call with `detached: true` so the child
- * leads its own process group; kills target the group (`kill(-pid)`) so
- * pipelines and subshells die with the parent. SIGTERM first, SIGKILL after a
- * grace period (OpenCode's escalation; Codex/pi jump straight to SIGKILL).
- *
+ * Process plumbing for the local bash executor: detached process-group spawn,
+ * tail-keep output with spill files, and SIGTERM→SIGKILL escalation. This layer
+ * reacts to an abort signal; the executor owns deadlines and classifies causes.
 * @module dsh-bash-local/run
 */

@@ -50,18 +34,9 @@ export const ENV_OVERRIDES = {
 export const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i

 /**
- * `process.env` minus credential-shaped vars, plus the model-friendly
- * overrides, plus any caller-supplied `extra` entries.
+ * Build a child environment by scrubbing credential-shaped ambient variables,
+ * applying model-friendly overrides, then merging trusted caller entries last.
 *
- * Layering matters: the scrub drops `process.env` credentials, then
- * `ENV_OVERRIDES` forces the model-friendly terminal vars, then `extra` is
- * merged LAST so an explicit caller entry wins even when its name matches the
- * scrub pattern (the scrub is the control that stops the HARNESS's ambient
- * credentials leaking into a spawned command; a caller that explicitly sets a
- * var named a value it already holds, not that ambient secret). `extra` is set
- * by in-process plugins (the hooks bridges), not the model — `dsh-tool-bash`
- * builds its request from named fields only and does not forward model input
- * here (see its README, § "The tool builds its request from named args only").
 * @param extra - caller-supplied entries merged last; an explicit entry wins even against the scrub and the overrides.
 * @returns the environment to hand to `spawn` for the child process.
 */
@@ -209,27 +184,6 @@ export class OutputCollector {
    writeSync(this.spillFd, chunk)
  }

-  // TODO(snapshot-scope): `snapshot()` has one internal caller (`finalize()` at
-  // the bottom of this file) and `totalBytes` is read only by a test. The live
-  // background-poll path goes through `readFrom()`, so inline snapshot() into
-  // finalize() and drop or privatize the totalBytes getter.
-  /**
-   * Read the collected tail without finalizing (the final-result snapshot).
-   * @returns the retained tail text, the truncation flag, and the spill path when one was created.
-   */
-  snapshot(): CollectedOutput {
-    return {
-      text: Buffer.concat(this.chunks).toString('utf8'),
-      truncated: this.dropped,
-      ...this.spillFile !== undefined ? { spillPath: this.spillFile } : {},
-    }
-  }
-
-  /** Total bytes ever pushed (including bytes dropped from memory). */
-  get totalBytes(): number {
-    return this.total
-  }
-
  /**
   * Incremental read in whole-stream byte coordinates: returns everything
   * pushed since `fromByte`. When `fromByte` has already slid out of the
@@ -262,26 +216,24 @@ export class OutputCollector {
      try {
        closeSync(this.spillFd)
      } catch {
-        // close can surface delayed writeback failures (for example EIO/ENOSPC)
-        // after writeSync appeared to succeed. Keep finalize total so runBash's
-        // close handler still resolves, but stop advertising a spill file that
-        // may be missing its tail.
+        // A delayed writeback failure makes the spill unreliable; keep finalize
+        // total but stop advertising that file.
        this.spillFile = undefined
      }
      this.spillFd = undefined
    }
-    return this.snapshot()
+    return {
+      text: Buffer.concat(this.chunks).toString('utf8'),
+      truncated: this.dropped,
+      ...this.spillFile !== undefined ? { spillPath: this.spillFile } : {},
+    }
  }
 }

 /**
- * Send `sig` to the process GROUP led by `pid` (requires the child to have
- * been spawned with `detached: true`). NEVER throws: kills race process exit
- * by design (ESRCH), and the other failure modes (EPERM from setuid
- * children, …) fire inside timer callbacks where a throw would crash the
- * host process — a kill that cannot be delivered is reported by the process
- * NOT dying, which callers already handle via escalation/timeouts. No-op for
- * non-positive pids (spawn never started a process).
+ * Send `sig` to a detached process group. Never throws: delivery races process
+ * exit and may run in a timer callback, so failures are contained and a
+ * non-positive pid is a no-op.
 * @param pid - the group leader's pid; non-positive means the spawn failed and the call is a no-op.
 * @param sig - the signal to deliver to the whole group.
 */
@@ -311,24 +263,13 @@ export interface RunningBash {
 }

 /**
- * Spawn `bash -c <command>` in its own process group and collect output.
- *
- * Outcome semantics: the returned promise REJECTS only for spawn-level
- * failures (bad cwd → ENOENT, missing binary, pre-aborted signal); every
- * runtime outcome — nonzero exit, timeout kill, abort kill, signal death —
- * RESOLVES with a {@link SpawnOutcome} describing what happened, so callers
- * shape one consistent report for the model.
- *
- * XXX(stateful-shell): per the agent-tool survey there are two proven
- * stateful designs worth revisiting — Claude Code persists ONLY cwd between
- * calls (captures `pwd -P` after each command), and Codex keeps whole PTY
- * exec sessions addressable via session ids + stdin writes. We deliberately
- * spawn a fresh non-login `bash -c` per call for determinism (no rc files,
- * no inherited shell state); revisit when real workflows demand it.
- * @param spec - the fully-resolved run (command, cwd, limits); no defaulting happens here.
- * @param internals - test-only knobs; omitted fields fall back to the private per-process spill dir.
- * @returns the live handle: pid, the two live collectors, the outcome promise, and `kill()`.
+ * Spawn one isolated `bash -c` process group and collect its output.
+ * Runtime exits resolve as {@link SpawnOutcome}; only spawn failures reject.
+ * @param spec - fully resolved command, cwd, limits, and cancellation.
+ * @param internals - test-only process and spill-directory overrides.
+ * @returns live process handle and outcome promise.
 */
+// XXX(stateful-shell): evaluate persistent cwd or PTY sessions when workflows require shell state.
 export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningBash {
  const spillDir = internals.spillDir ?? privateSpillDir()

@@ -336,16 +277,7 @@ export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningB
    throw new Error(`aborted before spawn: ${String(spec.signal.reason ?? 'aborted')}`)
  }

-  // stdin is a pipe ONLY when the caller supplied bytes; with none it is `ignore`
-  // (fd 0 → /dev/null) — the exact pre-seam default. This matters: a spawn pipe
-  // and /dev/null are NOT observationally identical (node's pipe is an AF_UNIX
-  // socket, so a command that probes stdin's type — `test -c /dev/stdin`, `stat
-  // /proc/self/fd/0` — sees a char device vs a socket), so the no-stdin path
-  // (every model-driven call) must keep /dev/null rather than regress to a socket.
-  // Two LITERAL `stdio` tuples (not one variable tuple): only a literal lets the
-  // typed `spawn` overload infer non-null stdout/stderr, which the
-  // `ChildProcessByStdio` annotation captures (stdin `Writable | null`; stdout/
-  // stderr the non-null `Readable` the collectors attach to without a cast).
+  // Keep absent stdin as /dev/null; literal tuples preserve non-null output types.
  const env = childEnv(spec.env)
  const child: ChildProcessByStdio<Writable | null, Readable, Readable> = spec.stdin !== undefined
    ? spawn('bash', ['-c', spec.command], { cwd: spec.cwd, env, stdio: ['pipe', 'pipe', 'pipe'], detached: true })
@@ -358,8 +290,7 @@ export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningB

  let graceTimer: NodeJS.Timeout | undefined

-  // pid is undefined when the spawn itself fails (bad cwd, missing binary);
-  // the 'error' handler rejects `done` and kills become no-ops via pid -1.
+  // Failed spawns use pid -1 so kill remains a no-op.
  const pid = child.pid ?? -1

  const kill = (): void => {
@@ -368,27 +299,11 @@ export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningB
    graceTimer = setTimeout(() => { killGroup(pid, 'SIGKILL') }, spec.graceMs)
  }

-  // runBash owns no timer: the executor's `run()` fuses timeout+cancel into one
-  // deadline signal (`@deepseek-ai/dsh-timeout`) and passes it here; we only
-  // listen and run the SIGTERM→grace→SIGKILL kill. Whether the abort was a
-  // timeout or an upstream cancel is classified by the executor from that
-  // signal, not tracked here.
+  // The executor owns timeout classification; this layer only reacts to abort.
  const onAbort = (): void => { kill() }
  spec.signal?.addEventListener('abort', onAbort, { once: true })

-  // Write stdin and close it, but ONLY when the caller supplied bytes — with no
-  // stdin, fd 0 is `ignore` (/dev/null) and `child.stdin` is null. The error
-  // handler must exist whenever we write: an unhandled 'error' on the stream
-  // would throw and crash the host. We swallow the error rather than reject
-  // `done`, and that is correct for ANY stdin-write error, not just the common
-  // one — the stdin write is BEST-EFFORT, while the command's authoritative
-  // outcome is its exit code + captured output, which the `close` handler reports
-  // regardless of whether the write landed. The expected case is EPIPE (the child
-  // exited without reading, so closing our end of a still-full pipe fails); a rare
-  // non-EPIPE pipe fault means the command ran with incomplete stdin, and it
-  // surfaces that itself through its own exit/output (e.g. a hook that gets
-  // truncated JSON errors out) — rejecting here would instead discard that real
-  // output and turn it into an opaque infrastructure error, which is worse.
+  // Stdin writes are best-effort; process exit and captured output remain authoritative.
  if (child.stdin !== null) {
    child.stdin.on('error', () => { /* stdin write is best-effort; outcome rides on exit/output. */ })
    child.stdin.end(spec.stdin)
@@ -396,8 +311,7 @@ export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningB

  const done = new Promise<SpawnOutcome>((resolve, reject) => {
    child.on('error', (error) => {
-      // Spawn-level failure (ENOENT cwd, EACCES, …): no close event with
-      // meaningful output follows; clean up and reject.
+      // No meaningful close outcome follows a spawn failure.
      cleanup()
      reject(error)
    })
--- a/packages/bash/bash-local/tests/executor.spec.ts
+++ b/packages/bash/bash-local/tests/executor.spec.ts
@@ -337,7 +337,7 @@ describe('LocalBashExecutor background tasks', () => {
  })
 })

-describe('review fixes: lifecycle hardening', () => {
+describe('executor cancellation, callback, and disposal contracts', () => {
  it('start honors a pre-aborted or later-aborted AbortSignal', async () => {
    const { bash } = await setup()
    const controller = new AbortController()
--- a/packages/bash/bash-local/tests/run.spec.ts
+++ b/packages/bash/bash-local/tests/run.spec.ts
@@ -2,8 +2,8 @@ import { mkdtempSync, readFileSync, statSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
-import { killGroup, OutputCollector, runBash } from '@deepseek-ai/dsh-bash-local'
-import type { RunningBash } from '@deepseek-ai/dsh-bash-local'
+import { killGroup, OutputCollector, runBash } from '../src/run.ts'
+import type { RunningBash } from '../src/run.ts'

 const { failNextClose } = vi.hoisted(() => ({ failNextClose: { value: false } }))
 vi.mock('node:fs', async (importOriginal) => {
@@ -49,7 +49,7 @@ async function waitGone(pid: number, timeoutMs = 5_000): Promise<void> {
 async function waitForStdout(running: RunningBash, expected: string, timeoutMs = 5_000): Promise<void> {
  const deadline = Date.now() + timeoutMs
  while (Date.now() < deadline) {
-    if (running.stdout.snapshot().text.includes(expected)) return
+    if (running.stdout.readFrom(0).text.includes(expected)) return
    await new Promise(resolve => setTimeout(resolve, 20))
  }
  throw new Error(`stdout did not include ${JSON.stringify(expected)} after ${timeoutMs}ms`)
@@ -189,12 +189,8 @@ describe('stdin and extra env (set by in-process plugins)', () => {
  })

  it('gives fd 0 the exact pre-seam type: /dev/null when no stdin, a pipe when supplied', async () => {
-    // The no-stdin path must stay observationally identical to the pre-seam
-    // `ignore` default: a command that probes stdin's file type sees a char
-    // device (/dev/null). Regressing to an always-open pipe would make fd 0 a
-    // socket (node's spawn pipe is an AF_UNIX socket, not a FIFO), flipping
-    // `test -c /dev/stdin` for every model-driven call. When bytes ARE supplied,
-    // fd 0 is that pipe (a socket), as it must be to carry them.
+    // With no bytes, fd 0 remains the pre-seam `ignore` default (/dev/null, a character device).
+    // Supplied bytes use Node's spawn pipe, which is an AF_UNIX socket rather than a FIFO.
    const none = await runBash(spec('test -c /dev/stdin && echo char || echo other')).done
    expect(none.stdout.text).toBe('char\n')
    const piped = await runBash(spec('test -S /dev/stdin && echo socket || echo other', { stdin: 'x' })).done
@@ -219,9 +215,8 @@ describe('stdin and extra env (set by in-process plugins)', () => {
  })

  it('does not crash or reject when the child ignores a large stdin (EPIPE)', async () => {
-    // The child exits immediately without reading; closing our end of a stdin
-    // pipe still holding ~1MiB triggers EPIPE on the write. The handler must
-    // swallow it: `done` resolves normally with the child's real exit.
+    // The child exits without reading, so closing a stdin pipe holding ~1 MiB triggers EPIPE.
+    // The handler swallows that write error and `done` reports the child's real exit.
    const big = 'x'.repeat(1024 * 1024)
    const result = await runBash(spec('exit 7', { stdin: big })).done
    expect(result.exitCode).toBe(7)
@@ -300,19 +295,11 @@ describe('OutputCollector', () => {
    expect(third.spillPath).toBeDefined()
  })

-  it('tracks totalBytes across drops', () => {
-    const collector = new OutputCollector(4, 'test', spillDir)
-    collector.push(Buffer.from('aaaa'))
-    collector.push(Buffer.from('bbbb'))
-    expect(collector.totalBytes).toBe(8)
-    expect(collector.finalize().text).toBe('bbbb')
-  })
-
  it('contains close failures and drops the spill path', () => {
    const collector = new OutputCollector(4, 'closefail', spillDir)
    collector.push(Buffer.from('aaaa'))
    collector.push(Buffer.from('bbbb'))
-    expect(collector.snapshot().spillPath).toBeDefined()
+    expect(collector.readFrom(0).spillPath).toBeDefined()

    failNextClose.value = true
    let out: ReturnType<typeof collector.finalize>
@@ -360,7 +347,7 @@ describe('abort edge cases', () => {
  })
 })

-describe('review fixes: env scrubbing and spill hardening', () => {
+describe('environment and spill-file hardening', () => {
  it('scrubs credential-shaped env vars from child processes', async () => {
    process.env.DSH_TEST_API_KEY = 'super-secret'
    process.env.DSH_TEST_TOKEN = 'also-secret'
--- a/packages/bash/bash-sandbox/README.md
+++ b/packages/bash/bash-sandbox/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-bash-sandbox

-Sandbox-consuming implementation of the [`@deepseek-ai/dsh-bash`](../bash/) executor seam. Load it **instead of** `@deepseek-ai/dsh-bash-local`, together with a [`ctx.sandbox`](../../sandbox/sandbox/) provider (e.g. [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)) — the model-facing tool layer (`dsh-tool-bash`) is untouched; that swap is exactly what the seams exist for.
+Sandbox-consuming implementation of the [`@deepseek-ai/dsh-bash`](../bash/) executor seam. Load it **instead of** `@deepseek-ai/dsh-bash-local`, together with a [`ctx.sandbox`](../../sandbox/sandbox/) provider (e.g. [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)) — no alternate tool plugin is needed; `dsh-tool-bash` detects the executor's `sandboxMode` capability and adds the escalation fields.

 Every command is confined by handing the provider the exact `['bash', '-c', command]` argv this executor is about to spawn and spawning the returned (wrapped) argv instead. WHICH platform runner confines it — and whether one is usable at all (fail closed with a structured `SANDBOX_UNAVAILABLE` error, never a silent unconfined run) — is the provider's concern; this package owns the bash side only.

@@ -14,7 +14,7 @@ Semantics:

 - **Denials are result facts.** A failed run whose stderr carries the selected backend's own denial dialect — the signatures the provider stamps on every wrap (EROFS text under bwrap, EACCES under Landlock, EPERM under Seatbelt) — is reported as `BashRunResult.sandbox.denied: true` (conservative classification, read from the collected stderr tail); every CONFINED run also carries the mode it executed under (`result.sandbox.mode`) and the provider's enforcement completeness (`result.sandbox.enforcement`: `full`, or `partial` on an older Landlock ABI).
 - **Runner failures are sandbox failures, never task failures.** A failed run matching the wrap's `runnerFailureSignatures` (the runner's own error prefix — also what the shell prints for a missing runner) means the sandbox itself broke and the command NEVER RAN; the check outranks denial classification because a runner's error text can contain denial words. The foreground path re-throws it as the structured fail-closed `SANDBOX_UNAVAILABLE` error, with the runner's first stderr line as the cause; a settled background task stamps `task.sandbox.runnerFailed` instead (no error channel remains after settle), which `bash_output` renders as its own marker.
- **Config-time default, per-call policy.** The DEFAULT mode is fixed by this entry's config for the executor's lifetime; `resolve()` stamps it onto every spec, and an explicit request-level `sandboxMode` override — set by the tool layer only for a call whose wider mode a human granted through `ctx.approval` ([the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)) — makes THAT call run, classify, and report under its own mode while every neighbor keeps the default (background facts are stamped per task at settle). The capability fact `ctx.bash.sandboxMode` reports the configured default so the tool layer advertises escalation only when this executor is mounted. The model learns of the sandbox only through result facts — the static bash tool description explains the denial marker; there is no current-mode statement in the system prompt.
+- **Config default, per-call override.** `resolve()` stamps the configured sandbox mode onto each spec unless an approved request supplies a wider mode. That override affects only its call or background task. `ctx.bash.sandboxMode` reports the default so the tool advertises escalation only when supported; results report the effective mode. The model learns standing mode only from tool/result facts, not a system-prompt announcement.
 - **File effects only.** Network and process visibility are deliberately not restricted — the mode vocabulary does not pretend to cover what the backend does not enforce.
 - Process mechanics (spawn, process-group kills, output collection/spill, background tasks, credential scrub) are inherited verbatim from [`dsh-bash-local`](../bash-local/); the runner ladder, probes, and the per-platform Landlock launcher packages live with [`dsh-sandbox-local`](../../sandbox/sandbox-local/).

@@ -30,4 +30,31 @@ Deny-only at the seam: a denial is a reported fact, and this executor never nego
    workspaceRoot: !!js process.cwd()
 ```

-The keyless consumer-integration proofs are `tests/bwrap.e2e.ts`, `tests/landlock.e2e.ts`, and `tests/seatbelt.e2e.ts` (the real provider + real runner driven through `ctx.bash`, world-verified, each self-skipping where its runner is absent); see [`examples/sandbox-acp-agent`](../../../examples/sandbox-acp-agent/) for the runnable demo.
+The keyless consumer-integration proofs are `tests/bwrap.e2e.ts`, `tests/landlock.e2e.ts`, and `tests/seatbelt.e2e.ts` (the real provider + real runner driven through `ctx.bash`, world-verified, each self-skipping where its runner is absent); see [the acp-agent example's default composition](../../../examples/acp-agent/) for the runnable demo.
+
+## Model Experience
+
+### Bash tool schema, indirectly
+
+**What the model sees**: The generated [`dsh-tool-bash` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash) are the baseline. By advertising a confining `sandboxMode`, this backend augments `bash` with `sandbox_permissions` using enum `workspace-write` | `danger-full-access` and with `justification`. The backend adds no prompt prose, and the session's effective mode remains unstated.
+
+**Token effect**: Small fixed schema increment on requests where `bash` is visible; mode switches add no context tokens.
+
+### Bash tool result, indirectly
+
+**What the model sees**: After ordinary bounded output, a denied call appends exactly `[sandbox: file access denied under <mode> mode]`. When escalation is available it next appends `[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]`. A settled background runner failure instead appends `[sandbox: the sandbox runner itself failed under <mode> mode — the command did not run; this is a sandbox problem, not a command failure]`.
+
+**Token effect**: Zero additional tokens on an unremarkable allowed run beyond ordinary output. Denial or failure adds the quoted conditional marker, retained until compaction.
+
+### Bash tool error, indirectly
+
+**What the model sees**: If no runner can enforce a confined mode, the foreground call propagates the [`SANDBOX_UNAVAILABLE` error owned by `dsh-sandbox`](../../sandbox/sandbox/README.md#confinement-error-indirectly). For an execution-time runner failure, this backend supplies the first stderr line as its detail.
+
+**Token effect**: Conditional error text is visible for that call and retained in history until compaction.
+
+## Known Limitations and Deferred Work
+
+- **Confinement covers file effects only** — network access and process visibility are unchanged, so the modes are not a general-purpose security sandbox.
+- **Denials are inferred from failed-command stderr** — backend signatures make the inference portable, but a matching application error can be classified as a denial and a denial omitted from the retained tail can be missed.
+- **A background runner failure has no immediate error channel** — it is recorded on the settled task and surfaces when the caller polls with `bash_output`.
+- **`danger-full-access` deliberately bypasses `ctx.sandbox`** — it is an explicit unconfined mode, not a wider sandbox profile.
--- a/packages/bash/bash-sandbox/package.json
+++ b/packages/bash/bash-sandbox/package.json
@@ -25,7 +25,7 @@
    "@deepseek-ai/dsh-bash": "^0.0.1",
    "@deepseek-ai/dsh-bash-local": "^0.0.1",
    "@deepseek-ai/dsh-sandbox": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  },
  "dependencies": {
    "schemastery": "^3.18.0"
@@ -36,6 +36,6 @@
    "@deepseek-ai/dsh-sandbox": "workspace:^",
    "@deepseek-ai/dsh-sandbox-local": "workspace:^",
    "node-addon-landlock-run": "0.0.0-test.0",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/bash/bash-sandbox/src/index.ts
+++ b/packages/bash/bash-sandbox/src/index.ts
@@ -1,43 +1,9 @@
 /**
- * `SandboxBashExecutor`: the sandbox-consuming implementation of the
- * `@deepseek-ai/dsh-bash` executor seam. Every spawned command is wrapped by
- * the `ctx.sandbox` provider (`@deepseek-ai/dsh-sandbox`) according to the
- * configured {@link SandboxMode}: the executor hands the provider the exact
- * `['bash', '-c', command]` argv it is about to spawn and spawns the wrapped
- * argv instead. WHICH platform runner confines it — and whether one is
- * usable at all (the provider fails CLOSED with a structured
- * `SANDBOX_UNAVAILABLE` error rather than passing the argv through) — is the
- * provider's concern (`@deepseek-ai/dsh-sandbox-local` first).
- *
- * Extends `LocalBashExecutor` so all process mechanics — spawn, process-group
- * kills, timeout escalation, output collection and spill files, background
- * tasks, the credential scrub — are the local implementation's, verbatim.
- * This package adds only the seam consumption and the result facts, which is
- * exactly the split the capability seam was designed for (a sandboxing
- * executor replaces `dsh-bash-local` without touching `dsh-tool-bash`, and
- * swapping the confinement backend never touches this package).
- *
- * A failed run whose stderr carries the selected backend's own denial
- * dialect (the signatures the provider stamps on every wrap) is classified
- * as a sandbox denial on `BashRunResult.sandbox`, and every confined result
- * also carries how completely the selected runner enforces the mode
- * (`sandbox.enforcement`, from the provider's wrap). A failure carrying the
- * backend's RUNNER-FAILURE signature instead means the sandbox itself broke
- * and the command never ran: the foreground path re-throws it as the
- * structured fail-closed `SANDBOX_UNAVAILABLE` error (late twin of the
- * provider's confine-time throw), a settled background task stamps
- * `sandbox.runnerFailed` — either way a broken sandbox can never read as a
- * failing command, and the command never slips through unconfined.
- *
- * Deny-only at the seam, escalation at the tool: a denial is a reported FACT
- * here, and the one-shot user-approved escalated retry of a denied action
- * (docs/rfc/implemented/feature/2026-07-06-sandbox.md) is driven by
- * `dsh-tool-bash` through `ctx.approval` — this executor's contribution is the
- * per-call `sandboxMode` override it honors in {@link resolve}: an escalated
- * call runs (and classifies, and reports) under ITS granted mode while every
- * neighboring call keeps its session's standing mode (or the configured
- * default when that session has no override).
- *
+ * Sandbox-consuming bash executor. It wraps the exact local bash argv through
+ * `ctx.sandbox`, inherits local process mechanics, and reports the selected
+ * mode, enforcement, and denial facts. Runner failure means the command never
+ * ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while settled background
+ * tasks carry `runnerFailed`. The tool owns approval and passes per-call modes.
 * @module @deepseek-ai/dsh-bash-sandbox
 */

@@ -79,24 +45,11 @@ export function shellQuote(text: string): string {
 }

 /**
- * Conservative sandbox-denial classifier: a run counts as denied only when it
- * FAILED (nonzero exit — a signal kill is not a denial) and its stderr
- * carries one of the SELECTED BACKEND's own denial signatures — the dialect
- * the provider stamps on every wrap (`ConfinedArgv.denialSignatures`:
- * `Read-only file system` under bwrap's EROFS mounts, `Permission denied`
- * under Landlock's EACCES, `Operation not permitted` under Seatbelt's
- * EPERM). Matching the backend's dialect rather than a cross-backend union
- * keeps the classifier from claiming denials the active backend never
- * produces (bare EPERM text under a Linux runner names non-file boundaries —
- * mount, kill, ptrace — that fail the same way unsandboxed). Text inference
- * is the fallback signal until a runner provides a structured one (which
- * wins once it exists); it errs toward NOT claiming a denial, and its known
- * residual imprecision is non-sandbox text in the active dialect (an ssh
- * auth failure reads as a denial under Landlock, a refused `kill` under
- * Seatbelt).
+ * Conservatively classify a nonzero, non-signal run using only the selected
+ * backend's denial signatures. Text inference may miss a denial or match
+ * unrelated stderr in that dialect; it never uses another backend's terms.
 * @param result - the settled foreground run to classify.
- * @param signatures - the active wrap's denial dialect, case-insensitive
- *   stderr substrings.
+ * @param signatures - the active wrap's denial dialect, case-insensitive stderr substrings.
 * @returns whether the run's failure reads as a sandbox denial.
 */
 export function classifyDenial(result: BashRunResult, signatures: readonly string[]): boolean {
@@ -104,17 +57,9 @@ export function classifyDenial(result: BashRunResult, signatures: readonly strin
 }

 /**
- * Runner-failure classifier: a failed run whose stderr carries the SELECTED
- * BACKEND's own runner-failure signature (`ConfinedArgv.
- * runnerFailureSignatures`: the runner's error prefix, which also matches
- * the shell's runner-not-found message) means the SANDBOX itself failed and
- * the command never ran. Checked BEFORE {@link classifyDenial} — a runner's
- * error text can contain denial words (an unopenable grant root reports
- * `Permission denied`) — and surfaced as the fail-closed
- * `SANDBOX_UNAVAILABLE` error on the foreground path, `sandbox.runnerFailed`
- * on a settled background task. Same conservative-text-inference stance and
- * residual imprecision as the denial classifier (a failing task that itself
- * prints the runner's prefix reads as a runner failure).
+ * Classify a nonzero run using the selected backend's runner-failure
+ * signatures. Callers check this before denial because runner diagnostics may
+ * contain denial words; the command did not run.
 * @param result - the settled foreground run to classify.
 * @param signatures - the active wrap's runner-failure signatures,
 *   case-insensitive stderr substrings.
@@ -137,15 +82,11 @@ function matchesSignature(exitCode: number | null, stderr: string, signatures: r
 }

 /**
- * Sandbox-consuming bash executor. Registers as `ctx.bash` (loading it
- * INSTEAD OF `dsh-bash-local`, together with a `ctx.sandbox` provider, is
- * the whole swap — the tool layer is untouched). Its configured mode is the
- * fallback exposed by {@link sandboxMode}; `dsh-tool-bash` folds a session's
- * durable `bash/sandbox-mode` override and stamps the effective mode onto each
- * request, while an approved escalation may stamp a strictly wider mode for
- * one call. The tool's per-agent prompt section states that same effective
- * mode, and each run's `result.sandbox` reports what actually executed plus
- * enforcement completeness.
+ * Registers as `ctx.bash` in place of the local executor and requires a
+ * `ctx.sandbox` provider; the tool layer is unchanged. The configured mode is
+ * the fallback, while a session override or approved one-shot escalation may
+ * select each call's mode. The prompt does not state the standing mode;
+ * `result.sandbox` reports the mode and enforcement actually used.
 */
 export class SandboxBashExecutor extends LocalBashExecutor {
  static inject = ['sandbox']
@@ -163,15 +104,9 @@ export class SandboxBashExecutor extends LocalBashExecutor {
  private readonly mode: SandboxMode
  private readonly workspaceRoot: string
  /**
-   * Per-task facts, keyed by task id from `start()` until the settle stamp
-   * consumes them: the mode the task runs under (per-call — an escalated task
-   * differs from its neighbors) plus its wrap facts. The seam returns facts
-   * PER WRAP — a provider may legally vary enforcement or dialect between
-   * calls — so overlapping background tasks must each classify against their
-   * OWN wrap; a single latest-wrap field would let a later `start()` clobber
-   * an earlier task's facts before it settles. A `danger-full-access` task
-   * has NO entry (nothing confined it), which is what the settle stamp keys
-   * off.
+   * Per-task mode and wrap facts retained until settlement. Overlapping tasks
+   * may use different modes or provider facts, so one latest-wrap field would
+   * misclassify earlier completions.
   */
  private readonly taskFacts = new Map<BashTaskId, {
    mode: ConfinedSandboxMode
@@ -215,11 +150,8 @@ export class SandboxBashExecutor extends LocalBashExecutor {
    }
    const confined = this.confine(spec.command, mode)
    const result = await super.run({ ...spec, command: confined.command })
-    // Runner failure outranks denial: the sandbox itself failed and the
-    // command NEVER RAN — surface the same structured fail-closed error a
-    // confine-time discovery throws (late detection, same outcome), with
-    // the runner's own first stderr line as the cause. Returning it as a
-    // task result would let a broken sandbox read as a failing command.
+    // Runner failure outranks denial because the command did not run. Throw the
+    // same fail-closed error as confine-time discovery with the first stderr line.
    if (classifyRunnerFailure(result, confined.runnerFailureSignatures)) {
      throw new SandboxUnavailableError(mode, result.stderr.text.trim().split('\n')[0])
    }
@@ -230,11 +162,8 @@ export class SandboxBashExecutor extends LocalBashExecutor {
    // Same stamped-by-resolve invariant as run().
    const mode = spec.sandboxMode as SandboxMode
    if (mode === 'danger-full-access') return super.start(spec)
-    // Sandbox facts are stamped at settle time by {@link notifyTaskDone}
-    // (denial classification runs against the settled task's collected
-    // stderr). The map entry lands synchronously after spawn, strictly
-    // before the earliest possible settle (a process exit reaches us no
-    // sooner than the next tick).
+    // Classification needs settled stderr. Store facts synchronously after
+    // spawn, before the earliest process completion can be observed.
    const confined = this.confine(spec.command, mode)
    const task = super.start({ ...spec, command: confined.command })
    const { enforcement, denialSignatures, runnerFailureSignatures } = confined
@@ -243,27 +172,16 @@ export class SandboxBashExecutor extends LocalBashExecutor {
  }

  /**
-   * Stamp the sandbox facts BEFORE completion listeners run: the base
-   * executor notifies from inside the task's settle path, so overriding the
-   * notification point is what makes `task.sandbox` visible to `onTaskDone`
-   * consumers and `done` awaiters alike. Each task classifies against the
-   * facts of ITS OWN wrap and reports ITS OWN mode (consumed from the
-   * per-task map here — settle is the entry's end of life): with per-call
-   * escalation, tasks under different modes settle side by side, so keying
-   * anything off the configured default would misreport them. A
-   * `danger-full-access` task has no map entry and carries no facts (nothing
-   * confined it); a signal-killed task (null exit code) is never a denial,
-   * mirroring the foreground classifier.
+   * Stamp per-task sandbox facts before completion listeners and `done` settle.
+   * Full-access tasks have no facts; signal deaths are not denials.
   */
  protected override notifyTaskDone(task: BashTask): void {
    const facts = this.taskFacts.get(task.id)
    if (facts !== undefined) {
      this.taskFacts.delete(task.id)
      const stderr = this.collectedStderr(task.id)
-      // Runner failure outranks denial (the command never ran; the runner's
-      // own error text can contain denial words). A settled task has no
-      // error channel left, so the fact IS the surface here — the foreground
-      // path throws instead.
+      // Runner failure outranks denial. Background settlement has no throw
+      // channel, so this fact is its counterpart to the foreground exception.
      const runnerFailed = matchesSignature(task.exitCode, stderr, facts.runnerFailureSignatures)
      task.sandbox = {
        mode: facts.mode,
--- a/packages/bash/bash-sandbox/tests/bwrap.e2e.ts
+++ b/packages/bash/bash-sandbox/tests/bwrap.e2e.ts
@@ -9,20 +9,13 @@ import { bwrapProfileArgs, LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'

 /**
- * KEYLESS consumer-integration proof under bwrap: the REAL
- * `LocalSandboxProvider` (nothing forced — bwrap is the ladder's first rung,
- * so a passing probe selects it) underneath the REAL `SandboxBashExecutor`,
- * driven through the executor's public run/start paths. Verifies the WORLD
- * (files exist or don't) plus the stamped result facts — in particular that
- * bwrap's EROFS denial text classifies as `denied: true` through the
- * wrap-carried dialect; the backend-only confinement proofs live with
- * `@deepseek-ai/dsh-sandbox-local`.
+ * Keyless integration of the real provider and executor through public run/start paths. With
+ * no rung forced, a passing bwrap probe selects the ladder's first rung. The tests check world
+ * effects and stamped facts, including EROFS classification through the wrap-carried dialect;
+ * backend-only confinement is covered by `@deepseek-ai/dsh-sandbox-local`.
 *
- * Self-skips wherever the functional probe fails — no `bwrap` on PATH, or a
- * host that denies unprivileged user namespaces.
- *
- * HOME-based dirs on purpose: bwrap's `/tmp` is an ephemeral mount, so only
- * paths outside it prove the workspace-root boundary.
+ * Skips when bwrap or unprivileged user namespaces are unavailable. HOME-based paths are
+ * intentional because bwrap replaces `/tmp`, which cannot prove the workspace-root boundary.
 */

 const probe = spawnSync('bwrap', [...bwrapProfileArgs({ mode: 'read-only', workspaceRoot: '/' }), '--', 'true'], { timeout: 5_000, stdio: 'ignore' })
--- a/packages/bash/bash-sandbox/tests/sandbox.spec.ts
+++ b/packages/bash/bash-sandbox/tests/sandbox.spec.ts
@@ -1,11 +1,8 @@
 /**
- * SandboxBashExecutor tests: the CONSUMER side of the sandbox seam. A fake
- * `ctx.sandbox` provider (injected as a real cordis service) makes wrapping,
- * policy hand-off, fail-closed propagation, classification, and fact
- * stamping all deterministic without any real runner; the real-provider
- * integration proof lives in `tests/landlock.e2e.ts`. Denials are produced
- * with plain unix permissions (a 0555 directory), which exercises the same
- * stderr signature the classifier keys on.
+ * Consumer-side `SandboxBashExecutor` tests. A fake Cordis sandbox service makes wrapping,
+ * policy hand-off, fail-closed propagation, classification, and fact stamping deterministic;
+ * real-provider integration lives in `tests/landlock.e2e.ts`. A mode-0555 directory supplies
+ * the Unix denial signature used by the classifier without requiring a real sandbox runner.
 */

 import { chmodSync, mkdirSync, mkdtempSync } from 'node:fs'
@@ -286,10 +283,9 @@ describe('background sandbox facts', () => {
  })

  it('overlapping background tasks keep their OWN wrap facts (per-task, not latest-wrap)', async () => {
-    // The seam returns facts PER WRAP — a legal provider may vary them
-    // between calls. The slow task settles AFTER the quick one started, so a
-    // latest-wrap field would classify its denial against the quick task's
-    // dialect (missing it) and stamp the wrong enforcement.
+    // Facts belong to each wrap and may vary between calls. The slow task settles after the
+    // quick task starts; a shared latest-wrap field would classify and stamp it with the wrong
+    // task's dialect and enforcement.
    const wraps: Array<Pick<ConfinedArgv, 'enforcement' | 'denialSignatures'>> = [
      { enforcement: 'partial', denialSignatures: ['permission denied'] },
      { enforcement: 'full', denialSignatures: ['read-only file system'] },
--- a/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts
+++ b/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts
@@ -9,16 +9,11 @@ import { LocalSandboxProvider, seatbeltProfileArgs } from '@deepseek-ai/dsh-sand
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'

 /**
- * KEYLESS consumer-integration proof on macOS: the REAL `LocalSandboxProvider`
- * (Linux rungs forced off, so `sandbox-exec`/Seatbelt confines) underneath
- * the REAL `SandboxBashExecutor`, driven through the executor's public
- * run/start paths. Verifies the WORLD (files exist or don't) plus the
- * stamped result facts — in particular that Seatbelt's EPERM denial text
- * classifies as `denied: true` through the wrap-carried dialect; the
- * backend-only confinement proofs live with `@deepseek-ai/dsh-sandbox-local`.
- *
- * Self-skips wherever the functional probe fails — every non-macOS host, or
- * a macOS whose `sandbox-exec` refuses the profile.
+ * Keyless macOS integration of the real provider and executor through public run/start paths.
+ * Linux rungs are forced off so Seatbelt is selected. The tests check world effects and stamped
+ * facts, including EPERM classification through the wrap-carried dialect; backend-only
+ * confinement is covered by `@deepseek-ai/dsh-sandbox-local`. Skips off macOS or when
+ * `sandbox-exec` rejects the profile.
 */

 const probe = spawnSync('sandbox-exec', [...seatbeltProfileArgs({ mode: 'read-only', workspaceRoot: '/' }), '--', 'true'], { timeout: 5_000, stdio: 'ignore' })
--- a/packages/bash/bash/README.md
+++ b/packages/bash/bash/README.md
@@ -11,7 +11,7 @@ This package is the interface quarter of the bash capability, split so each conc
 | `@deepseek-ai/dsh-bash-sandbox` | an implementation: `dsh-bash-local`'s mechanics with every spawn confined via [`ctx.sandbox`](../../sandbox/sandbox/), denials reported as result facts |
 | `@deepseek-ai/dsh-tool-bash` | the model-facing tool schemas over `ctx.bash` |

-The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool survey: pi hides execution behind a `BashOperations` interface (local shell / SSH / VM backends), Codex behind an exec-server protocol. `dsh-bash-sandbox` is exactly that swap in action — a sandboxing executor behind the same interface, tool schemas untouched; a containerized or remote executor slots in the same way.
+The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool survey: pi hides execution behind a `BashOperations` interface (local shell / SSH / VM backends), Codex behind an exec-server protocol. `dsh-bash-sandbox` is exactly that swap in action — a sandboxing executor behind the same interface; the consumer detects its `sandboxMode` capability and adds escalation fields without importing the implementation. A containerized or remote executor slots in the same way.

 ## Service API (`ctx.bash`)

@@ -32,6 +32,15 @@ Implementations subclass `BashExecutor`, implement the abstract methods, and cal

 `BashExecRequest` (command, workdir?, timeoutMs?, signal?, stdin?, env?, owner?, sandboxMode?) resolves to `BashExecSpec` (command, workdir, timeoutMs, signal?, stdin?, env?, owner, sandboxMode) before execution; `owner` and `sandboxMode` are optional on the request and **required-but-nullable** on the resolved spec, so a forgotten one is a visible `undefined` rather than a silently-absent property. `sandboxMode` is the explicit per-call sandbox-policy input: an escalation grant a human just issued ([the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md), which outranks) or the session's standing override ([the sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)); a sandboxing executor's `resolve()` stamps its configured default when the request carries none, and a non-sandboxing executor carries the field verbatim and confines nothing.

-The seam also owns the per-session mode override vocabulary (the sandbox RFC § Per-session mode switching): the log-only `'bash/sandbox-mode'` session event, the pure fold `effectiveSandboxMode(events)` (last event wins; `undefined` means "apply the executor default"), and THE write path `setSandboxMode(session, mode)` — the session log is the store, so an override survives restart by replay and two sessions can never see each other's mode. Writers must respect turn-enclosure: the ACP bridge anchors an idle switch at the next turn rather than appending between turns. The task id (`BashTaskId`) and the `owner` token (`OwnerToken`) are [branded](../../util/brand) — `OwnerToken` is a DISTINCT brand from `SessionId` (the seam never imports `dsh-session`; the `dsh-tool-bash` consumer is the single boundary that casts its `SessionId` into one). `run()` returns `BashRunResult` (exitCode, signal, timedOut, aborted, timeoutMs, stdout/stderr as `CollectedOutput`) and `start()`/`readOutput()` use `BashTask`/`BashTaskRead` for the background side. A sandboxing executor additionally stamps `sandbox` result facts on results and settled tasks (`BashSandboxInfo`: the mode it executed under, the conservative `denied` classification, and — for confined modes — the backend's `enforcement` completeness); the mode/enforcement vocabulary is owned by the [`dsh-sandbox`](../../sandbox/sandbox/) seam, and the facts are documented in [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md). See `src/types.ts` for the full contracts.
+The seam owns per-session sandbox overrides through the log-only `bash/sandbox-mode` event, `effectiveSandboxMode`, and `setSandboxMode`; writers preserve turn enclosure, and replay restores the last override. `BashTaskId` and `OwnerToken` are distinct brands. Foreground `run` returns exit, timeout, cancellation, output, and optional sandbox facts; background `start` and `readOutput` use task records. A sandboxing executor reports the executed mode, conservative denial classification, and enforcement completeness. See [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md) for full shapes.

 `stdin` and `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload on stdin and its `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` env. The model-facing `dsh-tool-bash` tool does not expose them as parameters — a model already has equivalent power through shell syntax (`FOO=bar cmd`, a heredoc), so they would be redundant tool params. This is not a security boundary: the implementation's credential scrub (not these fields) is what keeps the harness's ambient secrets out of a spawned command. They are plain optionals on the resolved spec (unlike `owner`'s required-but-nullable): a missing one means "none", the safe default. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
+
+## Model Experience
+
+Indirectly, through `dsh-tool-bash`, which turns executor output and sandbox facts into guidance and retained tool-result tokens.
+
+## Known Limitations and Deferred Work
+
+- **No interactive-input vocabulary** — `stdin` is written once at spawn and closed; the seam has no channel to feed a running task and no PTY session concept.
+- **Foreground timeouts are always executor-owned** — a caller-owned-deadline mode on the seam is explicitly deferred by [the tool-call timeout-policy RFC](../../../docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md).
--- a/packages/bash/bash/package.json
+++ b/packages/bash/bash/package.json
@@ -25,12 +25,12 @@
    "@deepseek-ai/dsh-brand": "^0.0.1",
    "@deepseek-ai/dsh-sandbox": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
    "@deepseek-ai/dsh-brand": "workspace:^",
    "@deepseek-ai/dsh-sandbox": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/bash/bash/src/index.ts
+++ b/packages/bash/bash/src/index.ts
@@ -1,16 +1,6 @@
 /**
- * The bash executor seam (`ctx.bash`): an abstract service defining WHAT a
- * bash backend does — run commands, manage background tasks — without saying
- * HOW. Implementations subclass {@link BashExecutor} and register themselves
- * as the `bash` service; `@deepseek-ai/dsh-bash-local` (local subprocesses)
- * is the first. Future implementations swap in sandboxes, containers, or
- * remote exec servers without touching the tool schemas that consume them
- * (`@deepseek-ai/dsh-tool-bash`).
- *
- * The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the
- * surveyed agents: pi hides execution behind a `BashOperations` interface
- * (local shell / SSH / VM backends), Codex behind an exec-server protocol.
- *
+ * The bash executor seam (`ctx.bash`): an abstract service defining what a bash backend does —
+ * run commands, manage background tasks — without saying how.
 * @module @deepseek-ai/dsh-bash
 */

@@ -39,25 +29,11 @@ declare module 'cordis' {
 }

 /**
- * Abstract bash execution service. Subclass, implement the abstract methods,
- * and load the subclass as a plugin — it registers as `ctx.bash` (one
- * implementation per context; loading a second throws, which is cordis'
- * standard duplicate-service behavior).
- *
- * Semantics every implementation must honor:
- * - {@link run} REJECTS only for infrastructure failures (unusable workdir,
- *   missing shell, pre-aborted signal). Nonzero exits, timeout kills, and
- *   abort kills RESOLVE with a descriptive {@link BashRunResult} — reporting
- *   a failed command is the tool layer's job, not an exception.
- * - {@link start} returns immediately; no timeout applies to background
- *   tasks (callers stop them via {@link kill} or the spec's AbortSignal).
- *   Completion must fire the {@link onTaskDone} listeners exactly once per
- *   task, and must NOT fire after the service is disposed.
- * - {@link readOutput} is incremental: consecutive reads never re-deliver
- *   output. Implementations bound their buffers; reads that lost data flag
- *   `lossy` and point at full-stream spill files when available.
- * - Disposal kills every running task and awaits their exit (no orphan
- *   processes survive `fiber.dispose()`).
+ * Registers one `ctx.bash` implementation. Runtime command failures resolve as
+ * {@link BashRunResult}; only infrastructure failures reject. Background starts
+ * return immediately without a timeout, report completion exactly once while
+ * live, and remain cancellable by signal or {@link kill}. Output reads are
+ * incremental and flag lost buffered data; disposal kills and awaits all tasks.
 */
 export abstract class BashExecutor extends Service {
  private listeners = new Set<BashTaskListener>()
@@ -74,14 +50,11 @@ export abstract class BashExecutor extends Service {
  }

  /**
-   * The sandbox mode this executor confines commands under BY DEFAULT, or
-   * `undefined` when it does not sandbox at all — the capability fact the
-   * tool and ACP layers read to advertise sandbox controls honestly. The
-   * getter proves a sandboxing executor is mounted and supplies its fallback
-   * mode; a session override may make the effective mode narrower or wider,
-   * so strict escalation widening is checked per call rather than encoded in
-   * this default-relative capability fact. The base class reports
-   * `undefined`; a sandboxing implementation overrides the getter.
+   * The sandbox mode this executor confines commands under BY DEFAULT, or `undefined` when it
+   * does not sandbox at all — the capability fact the tool and ACP layers read to advertise
+   * sandbox controls honestly.
+   * A session or call may override this default, so widening is evaluated per
+   * execution rather than encoded in this getter.
   * @returns the configured default mode of a sandboxing executor;
   *   `undefined` for an executor that never confines.
   */
@@ -90,12 +63,7 @@ export abstract class BashExecutor extends Service {
  }

  /**
-   * Resolve a caller's {@link BashExecRequest} into a fully-specified
-   * {@link BashExecSpec}, applying this implementation's config defaults and
-   * caps (working directory, default/max timeout). Consumers (tool layer)
-   * call this, then pass the result to {@link run}/{@link start} — keeping
-   * defaulting in the implementation that owns the config while the seam type
-   * stays explicit (no hidden `?? default` inside run/start).
+   * Apply implementation-owned defaults and caps to a request before execution.
   * @param request - the caller's request; omitted fields get this
   *   implementation's defaults, capped fields are clamped.
   * @returns the fully-specified spec to hand to {@link run}/{@link start}.
@@ -125,17 +93,10 @@ export abstract class BashExecutor extends Service {
  abstract get(id: BashTaskId): BashTask | undefined

  /**
-   * The opaque OWNER token recorded for a background task at {@link start}
-   * (from the {@link BashExecSpec}'s `owner`), or `undefined` for an unknown id
-   * OR a known-but-ownerless task. The executor stores and returns the token
-   * verbatim — it never interprets it; the access POLICY (who may read/kill a
-   * task) lives in the consumer (`@deepseek-ai/dsh-tool-bash`), which compares
-   * `ownerOf(id)` to the caller's token. Collapsing unknown-id and
-   * known-but-unowned into the same `undefined` is fine: the consumer's access
-   * gate treats `undefined` as "open", and a genuinely unknown id then fails
-   * loudly at the subsequent {@link readOutput}/{@link kill} ("unknown task").
-   * Storing ownership in the executor (disposed with ITS fiber) — not in the
-   * tool plugin — is what makes ownership survive a `tool-bash` HMR reload.
+   * The opaque OWNER token recorded for a background task at {@link start} (from the {@link
+   * BashExecSpec}'s `owner`), or `undefined` for an unknown id OR a known-but-ownerless task.
+   * The executor stores the token without interpreting policy; keeping it here
+   * lets ownership survive a consumer-plugin reload.
   * @param id - the background task id to look up ownership for.
   * @returns the token recorded at start, verbatim; undefined for an unknown
   *   id or a known-but-ownerless task.
--- a/packages/bash/bash/src/session-mode.ts
+++ b/packages/bash/bash/src/session-mode.ts
@@ -1,17 +1,9 @@
 /**
- * Per-session sandbox-mode override: the session log as the store. A runtime
- * switch (an ACP `session/set_config_option`, a test scenario) is recorded as
- * one `bash/sandbox-mode` event on the session it applies to;
- * `effective = fold(events) ?? the executor's configured default`, so an
- * override survives restart by replay, two sessions can never see each
- * other's state, and there is no external config store. The event is
- * log-only (the `approval/*` precedent): the model learns the mode from the
- * prompt section and the boundary notices in `@deepseek-ai/dsh-tool-bash`,
- * never from the event itself. EXECUTION honors the fold in the tool layer —
- * it stamps the effective mode onto each call's `BashExecRequest.sandboxMode`
- * (weakest-precedence: an escalation grant for the call outranks it) — the
- * executor itself stays a config-fixed default plus per-call overrides.
- *
+ * Per-session sandbox-mode override stored as log-only events. Folding the log
+ * isolates sessions and survives replay; the tool stamps the override onto
+ * each call unless an approved one-shot escalation outranks it, and the
+ * executor default applies when neither exists. The model receives neither the
+ * event nor a standing-mode notice; denial results name the effective mode.
 * @module dsh-bash/session-mode
 */

@@ -21,12 +13,9 @@ import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 declare module '@deepseek-ai/dsh-session' {
  interface SessionEventMap {
    /**
-     * The session's sandbox mode was switched — log-only (like `approval/*`;
-     * NOT a surface event, carries no `surfaceOp`): durable and replayable,
-     * never in the model transcript. The LAST such event is the session's
-     * override ({@link effectiveSandboxMode}); who asked for it is derivable
-     * from position (an event after the log's last `request/header*` was a
-     * runtime switch by the user; see the tool layer's narrator).
+     * Durable log-only sandbox-mode override; never a surface event or model
+     * message. Execution and ACP option reporting fold the latest event through
+     * {@link effectiveSandboxMode} without adding a prompt notice.
     */
    'bash/sandbox-mode': { mode: SandboxMode }
  }
@@ -37,9 +26,8 @@ export const SANDBOX_MODES: readonly SandboxMode[] = ['read-only', 'workspace-wr

 /**
 * The session's sandbox-mode override: the last `bash/sandbox-mode` event in
- * the log, or undefined when the session never switched (callers apply the
- * executor's configured default). The pure fold — resume needs no catch-up
- * machinery because replaying the log IS the state.
+ * the log, or undefined when the session never switched and callers should use
+ * the executor default. Replay needs no separate catch-up state.
 * @param events - session events in log order (other event types are skipped).
 * @returns the mode of the last switch event, or undefined without one.
 */
@@ -52,10 +40,9 @@ export function effectiveSandboxMode(events: readonly SessionEvent[]): SandboxMo
 }

 /**
- * THE write path for a session's sandbox-mode override: appends exactly one
- * `bash/sandbox-mode` event — the switch IS its event; nothing mutates mode
- * state out of band. Takes effect on the session's next bash call and next
- * prompt assembly (the consumers fold on every read).
+ * Append one `bash/sandbox-mode` event as the only override write path.
+ * Execution and ACP option reporting fold it on read; prompt assembly does not
+ * consume it.
 * @param session - the session the override belongs to.
 * @param mode - the mode every subsequent bash call in this session runs
 *   under (until the next switch).
--- a/packages/bash/bash/src/types.ts
+++ b/packages/bash/bash/src/types.ts
@@ -71,14 +71,8 @@ export interface BashSandboxInfo {
   */
  enforcement?: SandboxEnforcement
  /**
-   * True when the executor classifies this failure as the SANDBOX RUNNER
-   * itself failing (missing binary, refused profile, fail-closed refusal
-   * before exec) — the command NEVER RAN; this is a sandbox failure, not a
-   * task failure, and it outranks `denied` (a runner's own error text can
-   * contain denial words). Only ever stamped on settled BACKGROUND tasks: a
-   * foreground run surfaces the same condition as the thrown
-   * `SANDBOX_UNAVAILABLE` error instead (the foreground path has an error
-   * channel; a settled task's facts are its only channel).
+   * The sandbox runner failed before executing the command. Set only on settled
+   * background tasks; foreground runs throw `SANDBOX_UNAVAILABLE` instead.
   */
  runnerFailed?: boolean
 }
@@ -125,17 +119,9 @@ export interface BashExecRequest {
   */
  owner?: OwnerToken | undefined
  /**
-   * Explicit per-call sandbox-policy input, overriding the executor's
-   * configured default mode for THIS call. Never a silent default: a
-   * consumer sets it only from an explicit policy source — an
-   * `'allowed-once'` grant a human just issued through `ctx.approval` (the
-   * escalation flow in the sandbox RFC § Escalation, which outranks), or the
-   * session's standing override folded from its own `bash/sandbox-mode`
-   * events (the sandbox RFC § Per-session mode switching — the user's recorded per-session
-   * choice). A sandboxing executor confines THIS call under the given mode;
-   * a non-sandboxing executor carries the field and confines nothing (the
-   * tool layer stamps neither escalation nor overrides without a sandboxing
-   * executor — see {@link BashExecutor.sandboxMode}).
+   * Explicit per-call sandbox policy. The tool stamps a session override or a
+   * one-shot approved escalation, with the grant taking precedence. Sandboxing
+   * executors honor it for this call; non-sandboxing executors do not confine.
   */
  sandboxMode?: SandboxMode | undefined
 }
@@ -229,7 +215,6 @@ export type BashTaskStatus = 'running' | 'completed' | 'killed'
 /** A tracked background task handle. */
 export interface BashTask {
  readonly id: BashTaskId
-  readonly command: string
  status: BashTaskStatus
  /** Exit code once finished (null = killed by signal / still running). */
  exitCode: number | null
--- a/packages/bash/bash/tests/service.spec.ts
+++ b/packages/bash/bash/tests/service.spec.ts
@@ -34,7 +34,6 @@ class StubExecutor extends BashExecutor {
  start(spec: BashExecSpec): BashTask {
    const task: BashTask = {
      id: BashTaskId(`stub-${this.tasks.size + 1}`),
-      command: spec.command,
      status: 'running',
      exitCode: null,
      signal: null,
--- a/packages/bash/tool-bash/README.md
+++ b/packages/bash/tool-bash/README.md
@@ -1,10 +1,12 @@
 # @deepseek-ai/dsh-tool-bash

-The model-facing bash tools — `bash`, `bash_output`, `bash_kill` — registered over the `ctx.bash` executor seam (`@deepseek-ai/dsh-bash`). Pure schema + text shaping; every process concern lives behind the seam, so sandboxed or remote executor implementations swap in without changing what the model sees.
+The model-facing bash tools — `bash`, `bash_output`, `bash_kill` — registered over the `ctx.bash` executor seam (`@deepseek-ai/dsh-bash`). This package owns schema and text shaping while process concerns stay behind the seam. Executor facts can change rendered results, and a sandboxing executor activates the escalation fields, without moving those presentation rules into the backend.

 Requires a loaded executor implementation (e.g. `@deepseek-ai/dsh-bash-local`); the plugin stays pending until `ctx.bash` exists (`inject: ['tools', 'bash', 'systemPrompt']`).

-The plugin also contributes the `tool:bash` prompt section (order 105) — the cross-call habit the per-tool descriptions cannot carry: check the `[exit code: N]` marker on every result and investigate failures before moving on. Under a sandboxing executor it additionally contributes the per-agent `env:bash-sandbox` section (order 110) stating each session's EFFECTIVE mode, and the pre-step narrator — see [Per-session mode](#per-session-mode-switching-and-visibility).
+The package root exposes only the Cordis plugin contract (`name`, `inject`, `apply`); result rendering remains an implementation detail covered by same-package tests.
+
+The plugin also contributes the `tool:bash` prompt section (order 105) — the cross-call habit the per-tool descriptions cannot carry: check the `[exit code: N]` marker on every result and investigate failures before moving on. A sandboxing executor changes the `bash` schema and result markers but adds no mode statement or switch notice; see [Per-session mode](#per-session-mode-switching).

 ## Tools

@@ -22,7 +24,7 @@ The plugin also contributes the `tool:bash` prompt section (order 105) — the c

 `command`, `workdir`, and `timeoutMs` are resolved against the executor's config defaults via `ctx.bash.resolve()` before execution, so the executor seam (`BashExecSpec`) receives explicit `workdir`/`timeoutMs` values. The workdir default is applied in the tool layer (from the calling agent's `session.header.cwd`) BEFORE `resolve()` — the per-session cwd must come from `exec.agent`, since N sessions share one executor; only when no session cwd is available does the executor fall back to its own config / `process.cwd()`.

-Result text: stdout, then a `[stderr]` section, then status markers — `[sandbox: file access denied under <mode> mode]` when a sandboxing executor classified the failure as a policy denial (reported first so `[exit code: N]` stays the last line; the static description tells the model a denial is policy, not a command bug, and forbids retrying around it), `[timed out after Nms]` whenever the executor's timer fired (reported independently of how the process ended, so a command that traps SIGTERM and exits 0 still shows it), `[killed by signal: …]` for a signal death, `[exit code: N]` for a non-zero exit (reported, **not** `isError`: the model decides how to react), and `[output truncated; full output: <path>]` when the tail was kept and a safe spill file is available. If the executor knows output was dropped but cannot safely advertise a complete spill file, the path is reported as `(unavailable)`. Only infrastructure failures (spawn errors, aborts) surface as `isError` results.
+Result text contains stdout, an optional `[stderr]` section, then applicable sandbox-denial, timeout, signal, exit-code, and truncation markers. Timeout is reported independently of final exit status; nonzero exit remains a model-interpreted result rather than `isError`. Truncation links a safe complete spill file or reports it unavailable. Only infrastructure failures such as spawn errors and aborts produce `isError`.

 ### `bash_output`

@@ -34,26 +36,71 @@ Result text: stdout, then a `[stderr]` section, then status markers — `[sandbo

 ### Task ownership (cross-session isolation)

-The owning agent's session token (`session.header.id`) is stamped onto the task at spawn — passed to the executor via `resolve({ …, owner })` and stored ON THE TASK inside the executor (the `dsh-bash` `ownerOf(id)` seam), **not** in a plugin-local map. `bash_output`/`bash_kill` compare `ctx.bash.ownerOf(id)` to the caller's token (`session.header.id`) with `!== undefined` semantics and reject a task owned by a *different* session with `task <id> belongs to another session` (a task started with no agent — a non-loop caller — has no owner token and is open to anyone; a call with no `exec.agent` cannot access an owned task). Task ids are global and predictable, so under multi-session ACP this token check is the fence that stops one session's agent from reading or killing another session's background task. Because ownership lives on the task in the executor (disposed with the `dsh-bash` fiber), it **survives an independent `tool-bash` HMR reload** — closing the old plugin-local-map gap where a reload orphaned pre-reload tasks. (The `onTaskDone` listener is still effect-scoped to this plugin's `apply`, so a completion landing during the reload gap still drops its one notice — the pre-existing reload-gap drop — but the ownership fence itself is HMR-proof.)
+The executor stores the spawning session id as the task's owner. `bash_output` and `bash_kill` reject a caller with a different session id; agent-less tasks remain unowned, while agent-less calls cannot access owned tasks. Storing ownership on the task prevents predictable global ids from crossing ACP sessions and preserves the fence across tool-plugin reloads. Completion notices remain effect-scoped and may be missed during a reload gap.

 ## UI presentation

-These tools own how their calls render in a UI (an editor's tool-call card) via the `dsh-tools` `presentCall`/`presentResult` seam, each returning a `card`-tagged render intent — a UI never special-cases tool names. A FOREGROUND `bash` run declares a **terminal card**: `presentCall` returns `{ card: 'terminal', title, description?, cwd? }` — the **title** is the exact `command` ("ls -la src"), the model-written `description` rides along (rendered ABOVE the card), and `cwd` comes from the model `workdir` when given (absolute as-is, relative for the UI bridge to resolve against the session cwd; else left for the bridge to fill from the session cwd) — and `presentResult` returns `{ card: 'terminal', title?, output?, exitCode?, signal? }` carrying the raw output plus the parsed `exitCode`/`signal`, so a capable client (Zed) renders a terminal card with an exit-status pill. The result carries the raw `output`; the bridge DERIVES the ` ```console ` fenced fallback for a no-terminal-capability UI (the tool no longer encodes the fences itself), so the model-facing result text stays unfenced. A `run_in_background` call is NOT a terminal (it returns a task id immediately and never streams a terminal — poll with `bash_output`) and instead returns a **generic card** (`{ card: 'generic', title, kind: 'execute', rawInput: command, content: [description] }`); an `isError` result (spawn failure / abort) likewise returns a `generic` result view with no exit pill (there is no real process exit). `bash_output`/`bash_kill` return a `generic` card with a task-scoped title ("Read output from background task bash-3" / "Kill background task bash-3") and the task id as rawInput. These methods are pure/display-only (they also run on `session/load` replay), and a malformed/older logged arg shape falls back to a generic presentation rather than throwing. See `packages/core/tools` ("Tool-owned UI presentation") and `packages/ui/acp` ("Terminal card" / "Tool-call presentation").
+UI presentation is tool-owned through `presentCall` and `presentResult`. Foreground `bash` uses a terminal card whose title is the exact command and whose optional description is separate; cwd follows an explicit `workdir`—resolved by the bridge against the session when relative—or the session cwd. Its result carries raw output plus exit or signal data, and clients without terminal support receive a bridge-derived fenced console fallback. Background runs, spawn failures, `bash_output`, and `bash_kill` use generic cards. Presenters are pure and replay-safe; malformed older arguments fall back to generic rendering. See [`dsh-tools`](../../core/tools/) and [`dsh-acp`](../../ui/acp/) for card semantics.

 ## Background completion notices

-When a background task finishes, a short notice is injected into the owning agent's session (`agent.inject()`, source `{kind: 'plugin', plugin: 'tool-bash'}`). The owning agent is found by its session token: the listener reads `ctx.bash.ownerOf(task.id)` and scans `ctx.get('agents')?.list()` for an agent whose `session.header.id` matches (read via `ctx.get` — `onTaskDone` runs on the bash fiber, a foreign fiber, so the `ctx.agents` proxy would throw). If no live agent carries that token — e.g. the owning session disconnected and its agent was disposed while the task ran on — the notice is dropped cleanly. Injection is **durable context for the next model request, not a wake-up** — an idle agent stays idle until something sends a message. That's why the tool descriptions tell the model to poll with `bash_output`.
+When a task finishes, the plugin resolves its owner token to a live agent and injects a durable completion notice. If the owner no longer exists, the notice is dropped. Injection affects the next request but does not wake an idle agent, so the model must poll with `bash_output` when it needs completion promptly.

 ## The tool builds its request from named args only

-The `BashExecRequest` seam carries optional `stdin` and `env`, used by the hooks bridges to feed a hook command its JSON payload and `CLAUDE_*` env. This tool does **not** expose them as parameters: its request is built from `command`/`workdir`/`timeoutMs`/`signal`/`owner` only, so a model that includes `env` or `stdin` keys in its tool arguments has them ignored. This is not a trust boundary — a model already has equivalent power through shell syntax (`FOO=bar cmd`, a heredoc), and the real defense against leaking the harness's ambient secrets is `dsh-bash-local`'s credential scrub, which works regardless. A regression guard drives the real tool with those extra args and asserts the resulting request carries neither field — its job is to catch a future refactor that blindly spreads `...args` into the request (which would silently forward model input into the post-scrub `env` merge), not to defend a wall. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
+The seam supports trusted-plugin `stdin` and `env`, but the model-facing tool does not. It builds requests only from its declared arguments, signal, and owner; extra model keys are ignored. Shell syntax already provides equivalent command-level behavior, while the local executor's credential scrub protects ambient secrets. See the [stdin/env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).

 ## Permissions and escalation

 Commands run with the executor's full authority unless a sandboxing executor ([`dsh-bash-sandbox`](../bash-sandbox/)) confines them — the deny-only sandbox reports denials as result facts, rendered here as the denial marker; per-call allow/deny/ask policy is the `tools/pre-execute` waterfall (see docs/architecture.md).

-On top of a denial sits the escalation gate ([the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)): an escalating call (`sandbox_permissions` + `justification`) resolves [`ctx.approval`](../../ui/user-approval/README.md) BEFORE anything executes — `allowed-once` stamps the granted mode onto the bash request as the seam-level `sandboxMode` override (that one call runs, classifies, and reports under the wider mode; its neighbors keep the session's effective mode), while `rejected`/`cancelled`/`unavailable` and the no-service / no-agent paths each fail closed with their own error text and execute nothing. The seam is consumed opportunistically (`ctx.get('approval')`, the dsh-tools ask-routing pattern); the grant is consumed by the very call that asked, and nothing is stored. The static description teaches — and a denied result itself prompts, via the escalation-available marker appended exactly when the fields are advertised — the SAME-TURN flow: on a denial a wider mode would cure, retry the exact command once with `sandbox_permissions` (the narrowest mode that suffices) + `justification` immediately, without detouring through chat (the approval prompt IS the user's consent); never speculatively — an escalation is grounded in a real denial (up-front only when the session already denied the same access), a prompt-stated approvals-disabled policy turns the exception off entirely, and a rejected escalation is final for that command.
+Escalating bash calls resolve `ctx.approval` before execution. `allowed-once` applies the requested mode only to that call; rejection, cancellation, unavailability, or missing approval context executes nothing and returns a distinct error. On a real denial, the model may retry the same command once in the same turn with the narrowest sufficient mode and justification; the approval prompt itself is the consent step. Escalation is never speculative, and a disabled or rejected approval is final. The [sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md) owns the rationale.

 ## Per-session mode switching

-Under a sandboxing executor this plugin makes the session's standing mode override ([the sandbox RFC § Per-session mode switching](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md); the `bash/sandbox-mode` fold owned by [`dsh-bash`](../bash/README.md)) real at EXECUTION: every call is stamped `escalation grant > session override > undefined` onto `BashExecRequest.sandboxMode`; without either, the executor's `resolve()` applies its configured default. Nothing is stamped under a non-sandboxing executor (nothing would honor it) or for an agent-less caller (no session to fold). The prompt deliberately does NOT state the mode and a switch is not narrated: a standing declaration teaches the model to refuse preemptively, while the denial marker already names the mode the command ran under exactly when the boundary is hit — behavior, not belief, carries the state.
+For sandboxing executors, each call resolves mode as one-shot escalation, then session override, then executor default. Non-sandboxing and agent-less calls carry no session override. Neither the prompt nor a switch notice announces the standing mode; denial results report the effective mode when the boundary matters. See the [`dsh-bash` fold](../bash/README.md) and [sandbox switching contract](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md).
+
+## Model Experience
+
+### System prompt
+
+**What the model sees**: Every request in this plugin's registration scope contains the bash guidance below. A sandboxing executor adds no mode statement or switch notice. Scoped tool restrictions can hide the schemas without removing this independently registered section.
+
+**Token effect**: Small fixed input cost per request while the plugin is active, unchanged by sandbox mode or mode switches.
+
+#### Bash guidance
+
+```markdown
+Check the [exit code: N] marker on every bash result; investigate failures before moving on.
+```
+
+### Tool schemas
+
+**What the model sees**: The model sees the generated [`bash`, `bash_output`, and `bash_kill` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash). `sandbox_permissions` and `justification` augment `bash` only when the mounted executor advertises sandboxing. Agent-scoped tool restrictions can remove the definitions for that agent.
+
+**Token effect**: Fixed schema cost on every request where the tools are visible; sandbox support adds the escalation fields and its conditional description paragraph.
+
+### Foreground result
+
+**What the model sees**: The renderer emits the data-dependent stdout tail, then optional `[stderr]` and the stderr tail. With no output it emits exactly `(no output)`. Conditional lines are exactly `[output truncated; full output: <path-or-(unavailable)>]`, `[sandbox: file access denied under <mode> mode]`, `[timed out after <timeoutMs>ms]`, `[killed by signal: <signal>]`, and `[exit code: <exitCode>]`; the sandbox escalation and runner-failure lines are quoted in [`dsh-bash-sandbox`](../bash-sandbox/README.md).
+
+**Token effect**: Zero result tokens before a call. Output is bounded per stream, while each emitted line remains in history until compaction.
+
+### Background task context and results
+
+**What the model sees**: Start returns exactly `started background task <taskId>`. Completion injects exactly `background bash task <taskId> finished <status>. Read its output with bash_output.` Reads return only the data-dependent delta or `(no new output)`, optionally `[some output was dropped from memory; full output: <paths-or-(unavailable)>]`, then exactly one of `[status: running]`, `[status: killed]`, `[status: killed by <signal>]`, or `[status: completed, exit code: <exitCode>]`. Kill returns `killed background task <taskId>` or `task <taskId> had already finished`.
+
+**Token effect**: Start and status text is small; deltas are data-dependent. The completion notice and every tool result are retained until compaction, but polling does not repeat already-delivered output.
+
+### Tool errors
+
+**What the model sees**: Validation and policy failures are normalized as `Error: <message>`. This package's stable messages are `invalid command: expected a non-empty string`, `invalid description: expected a non-empty string`, `invalid timeoutMs: expected a positive number, got <value>`, `invalid escalation: sandbox_permissions requires a justification`, `invalid escalation: justification is only valid together with sandbox_permissions`, `invalid justification: expected a non-empty sentence`, `invalid task_id: expected a string, got <value>`, `task <taskId> belongs to another session`, `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`, `sandbox escalation to "<mode>" is not strictly wider than this call's current "<mode>" mode`, the approval-availability/rejection/cancellation variants, and `command aborted`.
+
+**Token effect**: Only the failing call adds these retained tokens; a rejected escalation does not add command output because the command does not run.
+
+## Known Limitations and Deferred Work
+
+- **Replay exit pills parse from result text** — output whose final line happens to be exactly `[exit code: N]` / `[killed by signal: …]` shows a wrong pill on session replay; a display-only known residual.
+- **The bash tools opt out of `timeout-policy` budgets** — `bash` keeps the executor-owned `BASH_TIMEOUT` path and `bash_output`/`bash_kill` declare no budget, per [the tool-call timeout-policy RFC](../../../docs/rfc/implemented/architecture/2026-07-07-tool-call-timeout-policy.md).
+- **Completion notices do not wake an idle agent** — they become durable context for the next request; a caller needing progress now must poll `bash_output` or send another message.
+- **Tasks started outside an agent have no ownership fence** — their predictable ids are readable and killable by any caller; only agent-started tasks carry a session owner token.
--- a/packages/bash/tool-bash/package.json
+++ b/packages/bash/tool-bash/package.json
@@ -29,7 +29,7 @@
    "@deepseek-ai/dsh-sandbox": "^0.0.1",
    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
    "@deepseek-ai/dsh-agent": "workspace:^",
@@ -44,6 +44,6 @@
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -1,57 +1,10 @@
 /**
- * The model-facing bash tools: `bash`, `bash_output`, `bash_kill`. Pure
- * schema + text shaping — every process concern lives behind the `ctx.bash`
- * executor seam (`@deepseek-ai/dsh-bash`), so sandbox/permission/remote
- * executor implementations swap in without touching what the model sees.
- *
- * Background notifications: when a background task completes, a short notice
- * is injected into the owning agent's session (`agent.inject()` — the
- * documented context seam). Injection is durable context for the NEXT model
- * request, not a wake-up: an idle agent stays idle until something sends a
- * message, which is why the tool descriptions tell the model to poll with
- * `bash_output`.
- *
- * Task ownership: a background task's OWNER is an opaque token — the owning
- * agent's `session.header.id` — passed to the executor at spawn
- * (`resolve({ …, owner })`) and stored ON THE TASK inside the executor
- * (`@deepseek-ai/dsh-bash`'s `ownerOf(id)` seam), NOT in a plugin-local map.
- * `bash_output`/`bash_kill` compare `ctx.bash.ownerOf(id)` to the caller's token
- * and reject a task owned by a DIFFERENT session (`owner !== undefined && owner
- * !== caller`); an unowned task (no token — started by a non-agent caller) is
- * open to anyone. Task ids are global and predictable (`bash-1`, …); under
- * multi-session ACP (RFC 011) this token check is the fence that stops one
- * session's agent from reading or killing another session's background task.
- *
- * Storing the token on the task in the EXECUTOR (disposed with the `dsh-bash`
- * fiber), rather than in this plugin, is what makes ownership survive a
- * `tool-bash` HMR reload — a reload that reset a plugin-local map would orphan
- * a task spawned before it. (The `onTaskDone` listener is still effect-scoped
- * to this plugin's `apply`, so a
- * completion landing during the reload gap still drops its one notice — the
- * pre-existing reload-gap drop — but the ownership fence itself is HMR-proof.)
- *
- * Commands run with the executor's full authority unless a sandboxing
- * executor (`@deepseek-ai/dsh-bash-sandbox`) confines them; per-call
- * allow/deny/ask policy is the `tools/pre-execute` waterfall — see
- * docs/architecture.md § Extension And Composition. Under a sandboxing
- * executor this plugin also advertises the ESCALATION surface
- * (`sandbox_permissions`/`justification` — the sandbox RFC § Escalation,
- * docs/rfc/implemented/feature/2026-07-06-sandbox.md): a command the
- * sandbox denied may be retried once under a strictly wider mode, resolved
- * through `ctx.approval` BEFORE anything executes and failing closed on every
- * unanswerable path. The fields exist only when the mounted executor reports
- * a confining default (`ctx.bash.sandboxMode`) — a lever is never advertised
- * that the composition cannot honor.
- *
- * Per-session mode switching (the sandbox RFC § Per-session mode switching): a session may carry a
- * standing sandbox-mode override — the `bash/sandbox-mode` event fold from
- * `@deepseek-ai/dsh-bash` — which this plugin makes real at EXECUTION: each
- * call is stamped `escalation grant > session override > executor default`.
- * The prompt deliberately does NOT state the mode and no switch is narrated:
- * the model learns the boundary from the denial marker (which names the mode
- * it ran under) exactly when it matters, instead of preemptively refusing
- * work a standing declaration would discourage.
- *
+ * Model-facing `bash`, `bash_output`, and `bash_kill` tools over the executor
+ * seam. Background tasks are fenced by owning session, completion injects a
+ * durable notice, and confining executors add one-shot approval-based escalation.
+ * Notices do not wake idle agents. Ownership is stored with the executor task so
+ * it survives this plugin's reload; per-call authority is escalation grant,
+ * session override, then executor default. See the package README for the tool contract.
 * @module @deepseek-ai/dsh-tool-bash
 */

@@ -68,20 +21,15 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-user-approval'
 import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { BashTaskId, OwnerToken, effectiveSandboxMode } from '@deepseek-ai/dsh-bash'
-import type { BashRunResult, BashTask, CollectedOutput } from '@deepseek-ai/dsh-bash'
+import type { BashTask } from '@deepseek-ai/dsh-bash'
+import { parseExitStatus, renderResult } from './render.ts'

 export const name = 'tool-bash'
 export const inject = ['tools', 'bash', 'systemPrompt']

 /**
- * Validate the constraints the SchemaSpec can't express. `defineTool` now
- * validates parsed args against the SchemaSpec before `execute` runs (the
- * arg-validation RFC), so type/required/enum checks are already done and `args`
- * is the validated `InferArgs` shape here. What remains are value constraints
- * the DSL has no vocabulary for: non-empty strings, a positive finite timeout,
- * and the escalation pairing (`sandbox_permissions` and `justification` travel
- * together — an approval prompt without a reason, or a reason driving nothing,
- * is a malformed ask).
+ * Validate value constraints absent from SchemaSpec: non-empty strings, a
+ * positive finite timeout, and paired escalation mode and justification.
 */
 function validateBashArgs(args: BashToolArgs): void {
  if (args.command.trim().length === 0) {
@@ -105,9 +53,7 @@ function validateBashArgs(args: BashToolArgs): void {
 }

 /**
- * Reject an empty `task_id`. Type and presence are guaranteed by the
- * SchemaSpec validation (the arg-validation RFC); only the non-empty constraint, which the
- * DSL can't express, is left to check here.
+ * Reject an empty `task_id`; SchemaSpec already validates type and presence.
 */
 function validateTaskId(value: string): BashTaskId {
  if (value.length === 0) {
@@ -117,10 +63,8 @@ function validateTaskId(value: string): BashTaskId {
 }

 /**
- * The bash tool's validated argument shape — the base parameters plus the two
- * escalation fields, which are ADVERTISED only when the mounted executor
- * reports a confining default mode (absent from the schema otherwise, so the
- * SchemaSpec validator rejects them before `execute` ever sees one).
+ * Validated bash arguments. Escalation fields are advertised only when the
+ * mounted executor reports a confining mode.
 */
 interface BashToolArgs {
  command: string
@@ -133,10 +77,8 @@ interface BashToolArgs {
 }

 /**
- * The strictly-wider table: what a call whose effective mode is the key may
- * escalate TO. Checked at EXECUTION, never baked into the schema — the
- * schema's enum is {@link ESCALATION_TARGETS}, because schemas are
- * registry-global while the effective mode is per-call truth.
+ * Strictly wider modes for each effective mode. Execution checks this table
+ * because the schema is global while the effective mode is per call.
 */
 const WIDER_MODES: Record<string, readonly SandboxMode[]> = {
  'read-only': ['workspace-write', 'danger-full-access'],
@@ -144,24 +86,16 @@ const WIDER_MODES: Record<string, readonly SandboxMode[]> = {
 }

 /**
- * The closed escalation-target vocabulary — every mode a call could ever
- * escalate TO (`read-only` is the floor; nothing escalates to it). Advertised
- * whenever the mounted executor confines: cutting the enum down to the modes
- * wider than the executor's DEFAULT would strand a session whose effective
- * mode sits below it (a `danger-full-access` default would advertise nothing
- * while a narrower-switched session stays confined with no lever).
+ * All possible escalation targets. Advertise the global set because a session
+ * override may be narrower than the executor default; execution rejects a
+ * target that is not wider for that call.
 */
 const ESCALATION_TARGETS: readonly SandboxMode[] = ['workspace-write', 'danger-full-access']

 /**
- * The bash tool's static description. The base text is byte-stable regardless
- * of composition (it is part of the pinned snapshot header); the escalation
- * teaching rides only when the mounted executor actually honors the fields —
- * it names the ONE sanctioned exception to the base text's "do not retry
- * another way" rule. Its deference clause ("If the session states approval
- * prompts are disabled…") points at the approval plugin's never-policy prompt
- * sentence by meaning, not by parsed wording — a rendezvous kept working by
- * that sentence continuing to open with the approvals-disabled claim.
+ * The bash tool's byte-stable base description. Escalation guidance is added
+ * only when the mounted executor can honor it, as the one exception to the
+ * ordinary no-retry guidance.
 */
 function bashDescription(escalationModes: readonly SandboxMode[]): string {
  const base = 'Execute a bash command (`bash -c`) and return its stdout/stderr. '
@@ -173,107 +107,22 @@ function bashDescription(escalationModes: readonly SandboxMode[]): string {
    + 'poll it with `bash_output` and stop it with `bash_kill`.'
  if (escalationModes.length === 0) return base
  return base + ' Attempting a command the sandbox may deny is safe and expected: run it and read the '
-    + 'marker rather than assuming the denial. When a command IS denied and a wider mode would let it '
-    + 'succeed, escalate immediately in the SAME turn — the ONE sanctioned exception to a denial: retry '
+    + 'marker rather than assuming the denial. When a command is denied and a wider mode would let it '
+    + 'succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry '
    + 'the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) '
    + 'plus a one-sentence `justification`. Do not detour through chat to ask permission first — the '
-    + 'approval prompt raised by that retry IS how the user consents. If the session states approval '
+    + 'approval prompt raised by that retry is how the user consents. If the session states approval '
    + 'prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. '
-    + 'Never escalate speculatively: ground the request in a real denial — normally the one THIS command '
+    + 'Never escalate speculatively: ground the request in a real denial — normally the one this command '
    + 'just hit; escalating up front is fine only when this session already denied the same access. '
-    + 'A rejected escalation is final for THAT command — stop and explain, never work around '
+    + 'A rejected escalation is final for that command — stop and explain, never work around '
    + 'it — but it does not forbid attempting or escalating other commands later.'
 }

-/** Append the truncation notice (with the full-output spill path) to a stream's text. */
-function streamText(output: CollectedOutput): string {
-  if (!output.truncated) return output.text
-  return `${output.text}\n[output truncated; full output: ${output.spillPath ?? '(unavailable)'}]`
-}
+// Pure tool-owned presentation used for both live events and replay.

 /**
- * Shape one finished run into the text the model sees: stdout, then a marked
- * stderr section, then exit-status markers. Non-zero exits are REPORTED, not
- * errored — the model decides how to react; only infrastructure failures
- * (spawn errors, aborts) surface as isError results.
- * @param result - the completed foreground run from the executor.
- * @param escalationModes - the escalation targets this composition advertises;
- *   non-empty adds the same-turn escalation hint after a denial marker
- *   (default `[]`: no hint).
- * @returns the model-facing text: output body (or `(no output)`), then any timeout/signal/exit markers, each on its own line.
- */
-export function renderResult(
-  result: BashRunResult,
-  escalationModes: readonly SandboxMode[] = [],
-): string {
-  const out = streamText(result.stdout)
-  const err = streamText(result.stderr)
-
-  let body = out
-  if (err.length > 0) {
-    // Single newline between sections (stdout usually ends with one already).
-    if (body.length > 0 && !body.endsWith('\n')) body += '\n'
-    body += `[stderr]\n${err}`
-  }
-  if (body.length === 0) body = '(no output)'
-
-  const markers: string[] = []
-  // The sandbox marker precedes the exit-status markers so `[exit code: N]`
-  // stays the LAST line (exitStatus() anchors its parse there). Denial is a
-  // reported fact like timeout: the model decides how to react.
-  if (result.sandbox?.denied) {
-    markers.push(`[sandbox: file access denied under ${result.sandbox.mode} mode]`)
-    // The same-turn nudge lives at the decision point: only when this
-    // composition advertises the fields (a lever is never hinted that the
-    // schema does not offer), and inside the sandbox marker family so the
-    // exit-code marker stays the last line.
-    if (escalationModes.length > 0) {
-      markers.push('[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]')
-    }
-  }
-  // Timeout is reported independently of how the process actually ended: a
-  // command can trap SIGTERM and exit 0 after our timer fired (e.g.
-  // `trap "exit 0" TERM; sleep 60`), giving timedOut:true / exitCode:0 /
-  // signal:null — the model must still see that the command was cut short.
-  if (result.timedOut) markers.push(`[timed out after ${result.timeoutMs}ms]`)
-  if (result.signal !== null) {
-    markers.push(`[killed by signal: ${result.signal}]`)
-  } else if (result.exitCode !== 0) {
-    markers.push(`[exit code: ${result.exitCode}]`)
-  }
-  if (markers.length === 0) return body
-
-  if (!body.endsWith('\n')) body += '\n'
-  return body + markers.join('\n')
-}
-
-// ---------------------------------------------------------------------------
-// UI presentation (tool-owned). These shape how a UI (e.g. the ACP bridge)
-// renders a bash call's pending and completed states. They are display-only and
-// pure — a UI may call them during live streaming AND a session-log replay.
-// ---------------------------------------------------------------------------
-
-/**
- * Pending-state presentation for a `bash` call. The TITLE is the exact `command`
- * — a `kind: 'execute'` card is rendered as a terminal whose header label IS the
- * title, and an execute-kind card HIDES `rawInput` (Zed: `should_show_raw_input
- * = !is_terminal_tool`), so the command must BE the title to be seen. This
- * mirrors the reference ACP adapters (claude-agent-acp, codex-acp), which both
- * use the bare command as an execute tool's title. The model-written
- * `description` (a readable summary) rides as a `content` text block shown ABOVE
- * the card. (Note: claude-agent-acp DROPS the description in terminal mode and
- * shows only the card; surfacing it as a content block is a deliberate
- * divergence here — we keep the human summary visible alongside the card.)
- * `rawInput` still carries the bare command for non-execute UIs that DO render it.
- *
- * `terminal` marks the call so a capable UI renders a TERMINAL card — but ONLY a
- * FOREGROUND run is a terminal: a `run_in_background` call returns a task id
- * immediately (it never streams a terminal; its output is polled via
- * `bash_output`), so it is NOT marked terminal and renders as an ordinary
- * execute card. For a foreground run the `terminal.cwd` (header) is the model
- * `workdir` when given — ABSOLUTE as-is, RELATIVE for the UI bridge to resolve
- * against the session cwd; when omitted the bridge fills the session workspace
- * cwd (this PURE presenter, args only, can't see it).
+ * Present foreground calls as terminals and background starts as generic cards.
 */
 type BashCallArgs = { command: string; description: string; workdir?: string; run_in_background?: boolean }

@@ -289,8 +138,7 @@ function presentBashCall(args: BashCallArgs): GenericCallView | TerminalCallView
      content: [{ type: 'text', text: args.description }],
    }
  }
-  // A foreground run IS a terminal: the command titles the card, the description
-  // renders above it, and the cwd (when the model gave a workdir) heads it.
+  // A foreground run is a terminal; an explicit workdir supplies its cwd.
  return {
    card: 'terminal',
    title: args.command,
@@ -300,26 +148,8 @@ function presentBashCall(args: BashCallArgs): GenericCallView | TerminalCallView
 }

 /**
- * Completed-state presentation for a `bash` call. Two parallel renderings of the
- * same output: `terminal.output` for a UI that shows a terminal card (the run's
- * stdout/stderr + status markers, exactly as the model sees them — the RAW text,
- * newlines preserved, since a terminal renderer relies on exact bytes), and a
- * fenced ```console `content` block as the fallback for a UI without terminal
- * support (the fences are a UI-only affordance, so they live here, not in the
- * model-facing result; the fenced body is trimmed of trailing blank lines for a
- * tidy block). A capable UI also gets an exit-status pill from `terminal.exitCode`
- * / `terminal.signal`, parsed from the status markers `renderResult` appended.
- *
- * Terminal output/exit is suppressed for results that are NOT a finished
- * foreground run: a `run_in_background` start (`isBackground` — the text is a
- * task-id ack, not a streamed run) and an `isError` result (a spawn failure or
- * abort — there is no real process exit to pill, and the body is an error
- * message, not `renderResult` output, so parsing it would be meaningless). Those
- * return a `generic` result whose content is the fenced ```console block. A
- * finished foreground run returns a `terminal` result carrying the RAW output
- * and the parsed exit status; the BRIDGE derives the fenced fallback from
- * `output` for a UI without terminal support, so the tool does not double-encode
- * it. A non-text result (unexpected for bash) falls through to `undefined`.
+ * Present completed foreground output as a terminal; background acknowledgements
+ * and execution errors use generic fenced output without an exit-status pill.
 */
 function presentBashResult(args: unknown, result: ToolResult): ToolResultView | undefined {
  const block = result.content.length === 1 ? result.content[0] : undefined
@@ -331,59 +161,19 @@ function presentBashResult(args: unknown, result: ToolResult): ToolResultView |
  if (isBackground || result.isError) {
    return { card: 'generic', content: [{ type: 'text', text: `\`\`\`console\n${raw.replace(/\n+$/, '')}\n\`\`\`` }] }
  }
-  // A finished foreground run: RAW output + parsed exit for the terminal card.
+  // A finished foreground run supplies raw output and parsed exit status.
  // The bridge derives the no-capability fenced fallback from `output`.
  return { card: 'terminal', output: raw, ...parseExitStatus(raw) }
 }

-/**
- * Recover the structured exit status from a rendered `renderResult` string — the
- * inverse of the status markers it appends. A `[killed by signal: SIG]` marker
- * yields `{signal}`; otherwise an `[exit code: N]` marker yields `{exitCode:N}`;
- * absent both we report `{exitCode:0}` (a clean run appends no marker — and a
- * trapped-timeout run that exits 0 also has none and is accurately exit 0).
- *
- * Why parse rendered text at all: `presentResult` is replay-safe and on a
- * `session/load` the ONLY thing persisted is this content text — the structured
- * `BashRunResult` is long gone — so unless the exit were added to the persisted
- * event schema (deliberately NOT done; see the terminal-rendering RFC), parsing
- * is the only channel. The match is anchored to a LEADING newline + end-of-string
- * because `renderResult` always inserts a `\n` before the marker (line ~124) onto
- * a non-empty body: a real marker is therefore always its own final line. That
- * defeats the common spoof (program output that simply ENDS in `[exit code: 5]`
- * with no trailing newline — a clean exit 0 — no longer reads as a failure).
- *
- * KNOWN RESIDUAL (inherent to the replay-only-sees-text design): a clean exit 0
- * whose body's FINAL line is itself exactly the marker text — `[exit code: N]`
- * or `[killed by signal: SIG]`, printed by the program with nothing after — is
- * still indistinguishable from a real marker and would show a wrong pill. This is
- * display-only (execution and the model-facing text are unaffected) and narrow;
- * the complete fix is to persist a structured exit on the result event, which the
- * RFC names as the escape hatch.
- */
-function parseExitStatus(text: string): { exitCode: number } | { signal: string } {
-  const signal = /\n\[killed by signal: ([^\]\n]+)\]$/.exec(text)
-  if (signal?.[1] !== undefined) return { signal: signal[1] }
-  const exit = /\n\[exit code: (\d+)\]$/.exec(text)
-  if (exit?.[1] !== undefined) return { exitCode: Number(exit[1]) }
-  return { exitCode: 0 }
-}
-
 /** Pending-state presentation for `bash_output`/`bash_kill` (background-task tools). */
 function presentTaskCall(verb: string, args: { task_id: string }): GenericCallView {
  return { card: 'generic', title: `${verb} background task ${args.task_id}`, kind: 'execute', rawInput: args.task_id }
 }

 /**
- * Resolve the working directory for a bash call. Precedence: an explicit model
- * `workdir` wins; otherwise default to the calling agent's session cwd
- * (`session.header.cwd`) so each ACP session's commands run in ITS workspace,
- * not the server's launch dir. A RELATIVE model `workdir` is resolved against
- * the session cwd (the tool tells the model to pass `workdir` instead of `cd`,
- * so a relative one should be relative to the session's root, not `process.cwd()`).
- * Returns `undefined` when neither is available (no agent / headerless session /
- * no session cwd) — the executor then applies its own config/`process.cwd()`
- * default, preserving today's non-ACP behavior.
+ * Resolve an explicit workdir first, making a relative one session-cwd-relative;
+ * otherwise use the session cwd and leave executor defaulting as the fallback.
 */
 function resolveWorkdir(modelWorkdir: string | undefined, exec: { agent?: Agent }): string | undefined {
  const sessionCwd = exec.agent?.session.header.cwd
@@ -404,9 +194,7 @@ function statusLine(task: BashTask): string {
 }

 export function apply(ctx: Context): void {
-  // The bash tools' cross-call HABIT, which the per-tool descriptions cannot
-  // carry (they describe one call each): the exit-code marker is only useful
-  // if the model actually checks it every time.
+  // Cross-call guidance belongs in the prompt rather than one tool description.
  ctx.systemPrompt.section({
    name: 'tool:bash',
    order: 105,
@@ -414,26 +202,15 @@ export function apply(ctx: Context): void {
  })

  /**
-   * The caller's owner TOKEN — the owning agent's `session.header.id`, or
-   * `undefined` for a non-agent caller. Read `session.header.id` (NOT
-   * `session.id`): every other subsystem keys off the header id (the ACP bridge,
-   * both persistence backends), and the sibling `resolveWorkdir` already reads
-   * `session.header.cwd`, so using `session.id` here would be the asymmetry smell
-   * the conventions flag. The two are equal in production, but the header is the
-   * canonical identity.
+   * Return the canonical session-header id used by ACP and persistence as the
+   * task owner, or undefined for a non-agent caller.
   */
  const callerToken = (exec: { agent?: Agent }): OwnerToken | undefined =>
    exec.agent ? OwnerToken(exec.agent.session.header.id) : undefined

  /**
-   * Authorize a `bash_output`/`bash_kill` call against the task's stored owner
-   * token. Rejects when the task HAS an owner and it differs from the caller's
-   * token — using `!== undefined` semantics, NOT truthiness, so an empty-string
-   * token is still a real owner (never treated as unowned). An unowned task
-   * (`ownerOf` returns `undefined`) is allowed; a truly unknown id is also
-   * `undefined` here and then fails loudly at the subsequent
-   * `readOutput`/`kill` ("unknown bash task"). The conservative no-agent caller
-   * (`callerToken` undefined) cannot match an owned task and is rejected.
+   * Reject access when a task has a different session owner. Unowned tasks are
+   * allowed; unknown ids still fail in the subsequent read or kill.
   */
  const assertTaskAccess = (taskId: BashTaskId, exec: { agent?: Agent }): void => {
    const owner = ctx.bash.ownerOf(taskId)
@@ -442,15 +219,8 @@ export function apply(ctx: Context): void {
    }
  }

-  // Background completion → inject a notice into the owning agent's session.
-  // Find the live agent by its session id token via the agent registry, read
-  // opportunistically with `ctx.get('agents')` (NOT `ctx.agents`/static inject):
-  // this listener runs from `task.done.then` on the bash fiber — a foreign
-  // fiber — where the `ctx.agents` property proxy would throw through the
-  // traceable shadow; `ctx.get(name)` is the topology-independent lookup. No
-  // registry mounted (`undefined`) → drop the notice. Match on
-  // `agent.session.header.id`, NOT the registry key: a config agent's id differs
-  // from its session id, and the owner token IS the session id.
+  // Completion runs on the bash fiber, so use topology-independent lookup and
+  // match the executor's stored session-owner token to a live agent.
  ctx.bash.onTaskDone((task) => {
    const ownerToken = ctx.bash.ownerOf(task.id)
    if (ownerToken === undefined) return
@@ -462,62 +232,38 @@ export function apply(ctx: Context): void {
        { source: { kind: 'plugin', plugin: 'tool-bash' } },
      )
    } catch (error: unknown) {
-      // The ONE expected failure: the agent was disposed between task
-      // completion and this injection (ReactLoopAgent.inject throws
-      // `agent "<id>" is disposed`). That race is benign — drop the notice.
-      // Anything else is a real bug and must surface, not be swallowed.
+      // The one expected failure: the agent was disposed between task completion and this
+      // injection (ReactLoopAgent.inject throws `agent "<id>" is disposed`).
      if (error instanceof Error && error.message.includes('is disposed')) return
      throw error
    }
  })

  // The escalation surface exists whenever the mounted executor confines.
-  // Its enum is the closed target vocabulary, deliberately NOT cut down by
-  // the configured default: a session may switch to a narrower effective mode
-  // while sharing this globally registered schema. Strict widening therefore
-  // belongs to the per-call check below. An executor swap restarts this fiber
-  // (static inject) and re-registers the schema.
+  // Advertise the closed target vocabulary globally, then enforce strict
+  // widening against each call's effective session mode.
  const defaultMode = ctx.bash.sandboxMode
  const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS

  /**
-   * The session's standing mode override for an ordinary (non-escalating)
-   * call: the `bash/sandbox-mode` fold of the calling agent's log, stamped
-   * onto the request so EXECUTION follows the same effective mode the prompt
-   * section states. Weakest precedence — an escalation grant (freshly
-   * approved for exactly this call) outranks it, and without either the
-   * executor's `resolve()` applies its configured default. Undefined for a
-   * non-sandboxing executor (nothing honors it) and for agent-less callers
-   * (no session to fold).
+   * Return the calling session's folded standing mode. Approval outranks this
+   * value and the executor default applies when it is absent; non-sandboxing
+   * and agent-less calls have no override.
   */
  const sessionOverride = (exec: ToolExecution): SandboxMode | undefined =>
    defaultMode === undefined || exec.agent === undefined ? undefined : effectiveSandboxMode(exec.agent.session.events)

  /**
-   * Resolve a sandbox-escalation request through `ctx.approval` BEFORE
-   * anything executes. Returns the granted mode to stamp onto the bash
-   * request; throws the distinct fail-closed text for every other path (no
-   * service composed, an agent-less execution, a rejection, a cancellation,
-   * an unanswerable ask) — the registry turns the throw into this call's
-   * isError result, and nothing has run. The seam is consumed
-   * opportunistically (`ctx.get`, the dsh-tools ask-routing pattern), so a
-   * deployment without it degrades per call, never at registration.
+   * Request one-shot escalation before execution. Missing approval context,
+   * rejection, cancellation, and unavailable answers throw without running the
+   * command; the optional seam is resolved per call through `ctx.get`.
   */
  const approveEscalation = async (mode: string, justification: string, exec: ToolExecution): Promise<SandboxMode> => {
-    // Schema validation only checks ADVERTISED keys, so an unadvertised
-    // `sandbox_permissions` (no sandboxing executor) still reaches execute — reject it here so a
-    // human is never prompted to "escalate" a sandbox that is not there. When
-    // the fields ARE advertised, the registry's SchemaSpec enum has already
-    // pinned `mode` to this ladder for every caller.
+    // Reject an unadvertised escalation before prompting for a nonexistent sandbox.
    if (escalationModes.length === 0) {
      throw new Error('sandbox_permissions is not available in this composition (no sandboxing executor to escalate)')
    }
-    // Strict widening is an EXECUTION check against the call's effective
-    // mode — session override ?? executor default, the same fold ordinary
-    // calls are stamped with — deliberately not a schema constraint (the
-    // enum is the closed target vocabulary; the effective mode is per-call
-    // truth). A non-widening request fails closed here and never prompts a
-    // human.
+    // Reject sandbox widening against the call's effective mode before requesting approval.
    const effectiveMode = (sessionOverride(exec) ?? defaultMode) as SandboxMode
    if (!(WIDER_MODES[effectiveMode] ?? []).includes(mode as SandboxMode)) {
      throw new Error(`sandbox escalation to "${mode}" is not strictly wider than this call's current "${effectiveMode}" mode`)
@@ -539,8 +285,7 @@ export function apply(ctx: Context): void {
      ...exec.signal ? { signal: exec.signal } : {},
    })
    switch (outcome) {
-      // The SchemaSpec enum already pinned `mode` to the closed target
-      // vocabulary; the per-call check above proved it is strictly wider.
+      // Schema validation pins the vocabulary; the per-call check proves widening.
      case 'allowed-once': return mode as SandboxMode
      case 'rejected': throw new Error(`the user rejected escalating this command to "${mode}"`)
      case 'cancelled': throw new Error(`approval for escalating to "${mode}" was cancelled`)
@@ -580,14 +325,8 @@ export function apply(ctx: Context): void {
    },
    async execute(args: BashToolArgs, exec) {
      validateBashArgs(args)
-      // `description` is display/logging metadata only (surfaced to UIs via
-      // the tool/call session event); it is intentionally NOT forwarded to
-      // ctx.bash and has no effect on execution.
-      // An escalating call resolves approval BEFORE anything executes; every
-      // non-grant outcome throws its distinct error text and runs nothing.
-      // (validateBashArgs pinned the pairing, so the double narrow is exact.)
-      // An ordinary call carries the session's standing override instead —
-      // grant > session override > executor default (see sessionOverride).
+      // `description` is display/logging metadata only. Escalation approval
+      // completes before execution; grant > session override > executor default.
      const sandboxMode = args.sandbox_permissions !== undefined && args.justification !== undefined
        ? await approveEscalation(args.sandbox_permissions, args.justification, exec)
        : sessionOverride(exec)
@@ -603,10 +342,7 @@ export function apply(ctx: Context): void {
        ...sandboxMode !== undefined ? { sandboxMode } : {},
      }
      if (args.run_in_background === true) {
-        // Stamp the owner token (the agent's session id) onto the spec so the
-        // executor stores it on the task — the isolation fence for bash_output/
-        // bash_kill. Foreground runs pass no owner (they finish inline; nothing
-        // to fence).
+        // Store the session owner on the task for bash_output/bash_kill isolation.
        const task = ctx.bash.start(ctx.bash.resolve({ ...request, owner: callerToken(exec) }))
        return [{ type: 'text', text: `started background task ${task.id}` }]
      }
@@ -640,15 +376,11 @@ export function apply(ctx: Context): void {
      }
      text += `\n${statusLine(read.task)}`
      if (read.task.sandbox?.runnerFailed) {
-        // The sandbox RUNNER itself failed — the command never ran. The
-        // foreground path surfaces this as the structured SANDBOX_UNAVAILABLE
-        // error; a settled task's read carries the marker instead.
+        // Background settlement carries the runner-failure fact that a
+        // foreground call exposes as SANDBOX_UNAVAILABLE.
        text += `\n[sandbox: the sandbox runner itself failed under ${read.task.sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`
      } else if (read.task.sandbox?.denied) {
-        // Mirrors the foreground result marker (and its same-turn escalation
-        // hint). Background denials are only classifiable once the task
-        // settles (the classifier needs the whole stderr), so the marker
-        // rides every read that sees the settled task.
+        // Mirrors the foreground result marker (and its same-turn escalation hint).
        text += `\n[sandbox: file access denied under ${read.task.sandbox.mode} mode]`
        if (escalationModes.length > 0) {
          text += '\n[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]'
--- a/packages/bash/tool-bash/src/render.ts
+++ b/packages/bash/tool-bash/src/render.ts
@@ -0,0 +1,92 @@
+/**
+ * Model-facing result rendering for the bash tool.
+ *
+ * @module @deepseek-ai/dsh-tool-bash/render
+ */
+
+import type { BashRunResult, CollectedOutput } from '@deepseek-ai/dsh-bash'
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+
+/** Append the truncation notice (with the full-output spill path) to a stream's text. */
+function streamText(output: CollectedOutput): string {
+  if (!output.truncated) return output.text
+  return `${output.text}\n[output truncated; full output: ${output.spillPath ?? '(unavailable)'}]`
+}
+
+/**
+ * Shape one finished run into the text the model sees: stdout, then a marked
+ * stderr section, then exit-status markers. Non-zero exits are REPORTED, not
+ * errored — the model decides how to react; only infrastructure failures
+ * (spawn errors, aborts) surface as isError results.
+ * @param result - the completed foreground run from the executor.
+ * @param escalationModes - the escalation targets this composition advertises;
+ *   non-empty adds the same-turn escalation hint after a denial marker
+ *   (default `[]`: no hint).
+ * @returns the model-facing text: output body (or `(no output)`), then any timeout/signal/exit markers, each on its own line.
+ */
+export function renderResult(
+  result: BashRunResult,
+  escalationModes: readonly SandboxMode[] = [],
+): string {
+  const out = streamText(result.stdout)
+  const err = streamText(result.stderr)
+
+  let body = out
+  if (err.length > 0) {
+    // Single newline between sections (stdout usually ends with one already).
+    if (body.length > 0 && !body.endsWith('\n')) body += '\n'
+    body += `[stderr]\n${err}`
+  }
+  if (body.length === 0) body = '(no output)'
+
+  const markers: string[] = []
+  // The sandbox marker precedes the exit-status markers so `[exit code: N]`
+  // stays the LAST line (exitStatus() anchors its parse there). Denial is a
+  // reported fact like timeout: the model decides how to react.
+  if (result.sandbox?.denied) {
+    markers.push(`[sandbox: file access denied under ${result.sandbox.mode} mode]`)
+    // The same-turn nudge lives at the decision point: only when this
+    // composition advertises the fields (a lever is never hinted that the
+    // schema does not offer), and inside the sandbox marker family so the
+    // exit-code marker stays the last line.
+    if (escalationModes.length > 0) {
+      markers.push('[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]')
+    }
+  }
+  // Timeout is reported independently of how the process actually ended: a
+  // command can trap SIGTERM and exit 0 after our timer fired (e.g.
+  // `trap "exit 0" TERM; sleep 60`), giving timedOut:true / exitCode:0 /
+  // signal:null — the model must still see that the command was cut short.
+  if (result.timedOut) markers.push(`[timed out after ${result.timeoutMs}ms]`)
+  if (result.signal !== null) {
+    markers.push(`[killed by signal: ${result.signal}]`)
+  } else if (result.exitCode !== 0) {
+    markers.push(`[exit code: ${result.exitCode}]`)
+  }
+  if (markers.length === 0) return body
+
+  if (!body.endsWith('\n')) body += '\n'
+  return body + markers.join('\n')
+}
+
+/**
+ * Recover the structured exit status from a rendered {@link renderResult}
+ * string — the inverse of the status markers it appends. A killed marker
+ * yields `signal`; otherwise a non-zero marker yields `exitCode`; absent both
+ * means a clean exit 0.
+ *
+ * Replay only retains the rendered content text, not the original
+ * `BashRunResult`, so terminal presentation must recover the exit pill here.
+ * Requiring a leading newline and the end of the string keeps ordinary output
+ * that merely ends with marker-like text from matching unless the final line
+ * is indistinguishable from a real marker.
+ * @param text - rendered model-facing bash result.
+ * @returns the recovered terminal exit code or signal.
+ */
+export function parseExitStatus(text: string): { exitCode: number } | { signal: string } {
+  const signal = /\n\[killed by signal: ([^\]\n]+)\]$/.exec(text)
+  if (signal?.[1] !== undefined) return { signal: signal[1] }
+  const exit = /\n\[exit code: (\d+)\]$/.exec(text)
+  if (exit?.[1] !== undefined) return { exitCode: Number(exit[1]) }
+  return { exitCode: 0 }
+}
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -19,7 +19,7 @@ import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
 import ApprovalService from '@deepseek-ai/dsh-user-approval'
 import type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
-import { renderResult } from '@deepseek-ai/dsh-tool-bash'
+import { renderResult } from '../src/render.ts'

 const spillDir = mkdtempSync(join(tmpdir(), 'dsh-tool-bash-spec-'))

@@ -56,12 +56,8 @@ async function setup() {
 */
 const fakeAgentDisposers = new Map<Context, (() => Promise<void> | void)[]>()
 function registerFakeAgent(ctx: Context, sessionId: string, inject: (...args: unknown[]) => void): Agent {
-  // The registry KEY (agent.id) is deliberately DIFFERENT from the session
-  // token (session.header.id) — a config agent has `agentId !== sessionId`. The
-  // owner token IS the session id, so the notice path must find the agent by
-  // `session.header.id`, NOT the registry key. Using distinct values here makes
-  // the test fail if a regression matched on the wrong field (a same-value fake
-  // would pass either way — the "hits the line but not the scenario" trap).
+  // A config agent has distinct registry (`agent.id`) and owner (`session.header.id`) tokens.
+  // Keeping them unequal makes notice lookup by the wrong field fail instead of passing by chance.
  const agent = { id: `agent-${sessionId}`, inject, session: { header: { version: 0, id: sessionId, createdAt: 0 } } } as unknown as Agent
  const dispose = ctx.agents.register(agent)
  const list = fakeAgentDisposers.get(ctx) ?? []
@@ -118,7 +114,6 @@ abstract class TestBashExecutor extends BashExecutor {
 class LossyReadBashExecutor extends TestBashExecutor {
  private readonly task: BashTask = {
    id: BashTaskId('bash-lossy'),
-    command: 'fake',
    status: 'running',
    exitCode: null,
    signal: null,
@@ -293,9 +288,17 @@ describe('bash tool', () => {

  it('contributes the exit-code habit as its prompt section (guidance the descriptions cannot carry)', async () => {
    const ctx = await setup()
+    ctx.systemPrompt.section({ name: 'test:before-bash', order: 104, text: 'before' })
+    ctx.systemPrompt.section({ name: 'test:after-bash', order: 106, text: 'after' })
    const assembly = await ctx.systemPrompt.assemble()
    const section = assembly.sections.find(s => s.name === 'tool:bash')
-    expect(section?.order).toBe(105)
+    expect(assembly.sections.map(s => s.name)).toEqual([
+      'harness:identity',
+      'deployment:persona',
+      'test:before-bash',
+      'tool:bash',
+      'test:after-bash',
+    ])
    expect(section?.text).toContain('[exit code: N]')
  })

@@ -418,9 +421,8 @@ describe('background tools', () => {
  it('injects a completion notice into the owning agent (found via the registry by session token)', async () => {
    const ctx = await setup()
    const inject = vi.fn()
-    // The notice path looks the agent up in ctx.agents by its session token, so
-    // the agent must be REGISTERED (not merely passed to execute). Mount a
-    // registry and register a fake whose session.header.id IS the owner token.
+    // Notices look up the agent in ctx.agents by session token, so passing it to execute is not
+    // enough: the fake must be registered with a matching `session.header.id`.
    const agent = registerFakeAgent(ctx, 'bg', inject)

    const started = await ctx.tools.execute({
@@ -483,11 +485,8 @@ describe('background tools', () => {
  })

  it('drops the notice cleanly when the owning agent is gone from the registry by completion', async () => {
-    // A bash task (owned by the host-scoped bash-local fiber) can OUTLIVE its
-    // per-session agent — e.g. the ACP session disconnects and its AgentHandle
-    // disposes while the background task is still running. The owner token is
-    // still on the task, but no live agent carries it anymore, so the registry
-    // lookup finds nothing and the notice is dropped (no throw).
+    // Host-scoped bash tasks can outlive a per-session agent after an ACP disconnect. The task
+    // retains its owner token, but with no matching live agent the notice is dropped without error.
    const ctx = await setup()
    const inject = vi.fn()
    const agent = registerFakeAgent(ctx, 'bg', inject)
@@ -517,11 +516,8 @@ describe('background task ownership (cross-session isolation)', () => {
  function callAs(ctx: Context, agent: import('@deepseek-ai/dsh-agent').Agent | undefined, name: string, args: unknown) {
    return ctx.tools.execute({ callId: CallId(`own-${++callCounter}`), name, arguments: args, ...agent ? { agent } : {} })
  }
-  // Ownership is by TOKEN (session.header.id), NOT agent object identity — so
-  // each agent needs a DISTINCT session id, else every fake yields the same
-  // token and the isolation tests pass for the wrong reason (all tasks owned by
-  // the same token). The impl reads `session.header.id`, so the fakes MUST carry
-  // it.
+  // Ownership uses `session.header.id`, not object identity. Distinct ids keep the isolation tests
+  // from passing accidentally because every fake produced the same owner token.
  const fakeAgent = (sessionId: string) =>
    ({ inject: () => undefined, session: { header: { version: 0, id: sessionId, createdAt: 0 } } }) as unknown as import('@deepseek-ai/dsh-agent').Agent

@@ -601,11 +597,8 @@ describe('background task ownership (cross-session isolation)', () => {
  })

  it('ownership SURVIVES an independent tool-bash HMR reload (token lives on the executor)', async () => {
-    // The owner token lives on the TASK inside the executor (dsh-bash fiber), NOT
-    // in a tool-bash plugin-local map. So reloading ONLY tool-bash (executor +
-    // task survive) preserves ownership. This is the regression guard: a
-    // plugin-local map would make B accessible after reload, and this test would
-    // catch it.
+    // The executor task owns the token, so reloading only tool-bash preserves ownership. A
+    // plugin-local map would lose it and incorrectly expose the task to agent B.
    const ctx = new Context()
    await ctx.plugin(SystemPrompt)
    await ctx.plugin(ToolRegistry)
@@ -824,11 +817,8 @@ describe('tool-owned UI presentation (presentCall / presentResult)', () => {
  it('bash presentResult: a clean exit-0 whose output ENDS in marker-like text is NOT read as a failure', async () => {
    const ctx = await setup()
    const args = { command: 'printf "[exit code: 5]"', description: 'print' }
-    // A successful command can print text that looks like a marker. renderResult
-    // for a clean exit 0 appends NOTHING (and no trailing newline), so the body's
-    // own tail is `[exit code: 5]`. The parse requires a LEADING newline before
-    // the marker (renderResult always inserts one before a REAL marker), so this
-    // no-trailing-newline body is NOT mistaken for a failure → exitCode 0.
+    // A successful command may print marker-like text. A clean result appends no marker or
+    // newline; parsing requires the leading newline emitted for real markers, so this stays exit 0.
    const out = ctx.tools.get('bash')!.presentResult!(args, { content: [{ type: 'text', text: '[exit code: 5]' }], isError: false })
    expect(out).toEqual({ card: 'terminal', output: '[exit code: 5]', exitCode: 0 })
    // Same for a fake signal marker with no leading newline.
@@ -891,26 +881,18 @@ describe('tool-owned UI presentation (presentCall / presentResult)', () => {

  it('presentCall validates softly: malformed args (missing required description) return undefined, never throw', async () => {
    const ctx = await setup()
-    // defineTool wraps presentCall to soft-validate against the schema and fall
-    // back to undefined (a generic UI presentation) rather than throwing on the
-    // display path — it may run on replay of arbitrary logged args. The
-    // ToolDefinition.presentCall takes `unknown`, so a malformed shape needs no cast.
+    // `defineTool` soft-validates replayed logged args before presentation. Invalid shapes return
+    // undefined for generic UI rendering rather than throwing; `presentCall` accepts `unknown`.
    expect(ctx.tools.get('bash')?.presentCall?.({ command: 'ls' })).toBeUndefined()
  })
 })

 describe('the model-facing bash tool builds its request from named args only (no {...args} forward)', () => {
  /**
-   * Records every {@link BashExecRequest} the consumer hands to `resolve()`, so a
-   * test can assert what the model-facing tool DID and DID NOT forward. The `bash`
-   * tool does not expose `stdin`/`env` as parameters (bash syntax already gives a
-   * model that power), so it must build its request from named args only and
-   * never spread unknown tool-call keys into it. This guard's job is to catch a
-   * future refactor that blindly forwards `...args` — which would silently thread
-   * model input into the post-scrub `env` merge — NOT to defend a trust boundary
-   * (the credential scrub in dsh-bash-local is the security control; see the
-   * bash-stdin-env RFC). Foreground `run()` returns a canned result; `start()` is
-   * unused here.
+   * Records requests passed to `resolve()` so tests can prove the model-facing tool forwards only
+   * named arguments. It intentionally exposes neither `stdin` nor `env`; this catches a future
+   * `...args` spread into the post-scrub env merge. The credential scrub remains the security
+   * boundary; see the bash stdin/env RFC. Foreground `run()` is canned and `start()` is unused.
   */
  class RecordingBashExecutor extends BashExecutor {
    readonly requests: BashExecRequest[] = []
@@ -953,12 +935,9 @@ describe('the model-facing bash tool builds its request from named args only (no

  it('does not forward env/stdin even when the model includes them as extra arguments', async () => {
    const { ctx, bash } = await setupRecording()
-    // Extra args: the model includes `env` and `stdin` keys hoping they reach the
-    // executor. The bash tool's schema ignores unknown keys, and execute() builds
-    // the request from only command/workdir/timeoutMs/signal — so the recorded
-    // request carries NEITHER. (Not a security wall — the model could set an env
-    // var or feed stdin via shell syntax anyway; this just keeps the request
-    // shape honest so a future `...args` spread can't silently forward input.)
+    // Unknown `env` and `stdin` keys are ignored by the schema and named request construction.
+    // This preserves the request shape; it is not a security boundary because shell syntax can
+    // already set environment variables or feed stdin.
    await ctx.tools.execute({
      callId: CallId('no-forward-1'),
      name: 'bash',
@@ -1062,7 +1041,6 @@ describe('sandbox rendering', () => {
    class FactsOnlyExecutor extends TestBashExecutor {
      private readonly task: BashTask = {
        id: BashTaskId('bash-facts'),
-        command: 'fake',
        status: 'completed',
        exitCode: 1,
        signal: null,
@@ -1438,11 +1416,9 @@ describe('per-session sandbox mode (the bash/sandbox-mode fold)', () => {
  })

  it('escalates relative to the session effective mode, not the executor default (narrower override)', async () => {
-    // The blocker scenario: a workspace-write default with a read-only
-    // override — the sensible escalation is workspace-write, which a
-    // default-relative ladder could not even express. The static target
-    // vocabulary advertises it and the execution check accepts it as
-    // strictly wider than the CALL's effective (overridden) mode.
+    // With a workspace-write default and read-only override, escalation must return to
+    // workspace-write. The static target vocabulary exposes it, and validation compares it with
+    // the call's effective override rather than a default-relative ladder.
    const ctx = await setupModal('workspace-write', { approval: true })
    ctx.on('approval/request', () => Promise.resolve<ApprovalOutcome>('allowed-once'))
    const seen: (string | undefined)[] = []
--- a/packages/code-runtime/code-runtime-worker/README.md
+++ b/packages/code-runtime/code-runtime-worker/README.md
@@ -23,10 +23,24 @@ Every field is validated (positive numbers) and defaulted; there are no other tu
 - **Type-strip host-side, in execution context** — the program is wrapped in an async-function shell, stripped with `node:module`'s `stripTypeScriptTypes` (erasable syntax only — `enum`/namespaces are rejected as a program `exception` and no worker spawns), and sliced back out byte-positioned; it then executes as the body of an `AsyncFunction`, so top-level `await`/`return` work.
 - **The port assumes a hostile peer** — model code can reach `parentPort` and forge traffic, so every inbound message is shape-validated and REBUILT before anything reads it (`null`, primitives, junk types, and malformed payloads drop without a throw; forged extra fields never ride along), the host answers each call id at most once, resolves binding names as OWN properties only (a forged `constructor` cannot walk a prototype chain), drops post-settlement replies, and converts a non-cloneable binding resolution into an error reply. Forged `log`/`done` messages cannot bypass the caps: one host-side ledger bounds everything that lands in `logs`, and the completion value is re-capped host-side. Worker-side namespaces are null-prototype with `defineProperty`, so `__proto__`-shaped binding names are ordinary keys.
 - **Two independent budgets, because the peer is hostile** — `computeMs` meters the worker's MEASURED busy time (`worker.performance.eventLoopUtilization()` polling): a hot loop cannot hide behind a pending decoy dispatch, and a program awaiting a slow tool accrues nothing. `maxWallMs` backstops what busy time cannot see (awaiting a promise nobody resolves). Both funnel into `worker.terminate()`, which ends hot synchronous loops too; heap overflow surfaces as the worker's OOM exit (`kind: 'worker-exit'`).
- **Logs stream eagerly** — console/stdout/stderr entries cross the port as they happen, so a timed-out or killed program still shows what it printed. ONE shared `maxLogBytes` ledger bounds everything: streamed entries, forged port traffic, and pipe bytes that bypass the patched streams (appended after), with the overflow marked in-band once.
+- **Logs stream eagerly** — console/stdout/stderr text crosses the port in emission order, so a timed-out or killed program still shows what it printed. ONE shared `maxLogBytes` ledger bounds everything: streamed text, forged port traffic, and pipe bytes that bypass the patched streams (appended after), with the overflow marked in-band once.
 - **Empty environment** — the worker gets `env: {}` and `execArgv: []`: no ambient credentials (stronger than the scrubbed-env rule for spawned commands) and no inherited loader flags.
 - **Dispose to quiescence** — teardown fails in-flight runs as `abort` and AWAITS each worker's exit before resolving.

 ## The worker entry, unbuilt and built

-`worker.ts` is deliberately erasable-only TypeScript with type-only cross-package imports: unbuilt (vitest/tsx), the host spawns `src/worker.ts` directly and Node's native type stripping loads it; built, the entry ships as the sibling CommonJS bundle `lib/worker.cjs` (its own tsdown entry). The CommonJS format is required because pkg's VFS Worker hook compiles filesystem-string entries as CommonJS. The host converts either entry URL to a filesystem string before constructing `Worker`, which works through both ordinary Node resolution and that pkg hook. The built path is pinned by `tests/built-lib.e2e.ts`, the real-load-path guard from [docs/testing.md](../../../docs/testing.md).
+Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. `tests/built-lib.e2e.ts` pins the real load path required by [docs/testing.md](../../../docs/testing.md).
+
+The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers are source-private implementation details.
+
+## Model Experience
+
+Indirectly, through Code Mode in [`dsh-tools`](../../core/tools/README.md), which renders this worker's capped printed or returned data and exact `[dsh-code-runtime-worker] log capture truncated at <maxLogBytes> bytes` and `… [truncated]` markers into a retained `run_code` result. Binding traffic and worker internals stay outside context.
+
+## Known Limitations and Deferred Work
+
+- **OS processes a program spawns survive termination** — `worker.terminate()` ends the thread only, weaker than bash-local's process-group kill; orphan cleanup is a deployment concern until a container backend exists.
+- **Type-strip rides Node's experimental `stripTypeScriptTypes` API** — the relied-on behavior is pinned by unit tests, with amaro/sucrase as named drop-in replacements if it shifts.
+- **`computeMs` expiry can overshoot by up to one poll interval** — busy time is sampled every 25 ms (an internal constant, deliberately not config).
+- **Programs get a five-method `console` shim** (`log`/`info`/`warn`/`error`/`debug`) — deliberately not Node's full console surface.
+- **A non-cloneable or oversize completion value does not cross as a value** — it arrives as a bounded, truncation-marked `util.inspect` rendering in `value`'s place.
--- a/packages/code-runtime/code-runtime-worker/package.json
+++ b/packages/code-runtime/code-runtime-worker/package.json
@@ -15,7 +15,6 @@
      "types": "./lib/types/worker.d.ts",
      "default": "./lib/worker.cjs"
    },
-    "./src/*": "./src/*",
    "./package.json": "./package.json"
  },
  "files": [
@@ -28,13 +27,13 @@
  "license": "BSD-3-Clause",
  "peerDependencies": {
    "@deepseek-ai/dsh-code-runtime": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  },
  "dependencies": {
    "schemastery": "^3.18.0"
  },
  "devDependencies": {
    "@deepseek-ai/dsh-code-runtime": "workspace:^",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
+++ b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
@@ -1,18 +1,12 @@
 /**
- * Worker-side execution logic, written as plain functions over an injected
- * port so the unit suite can run every line IN-PROCESS against a fake port
- * (a real worker thread is a separate V8 isolate the coverage provider
- * cannot observe). The real worker entry (`worker.ts`) is a thin
- * self-executing glue file over {@link runWorkerMain}, excluded from
- * coverage the same way `bin.ts` entrypoints are, and exercised end-to-end
- * by the integration tests that spawn real workers.
- *
+ * Worker-side execution logic, written as plain functions over an injected port so the unit
+ * suite can run every line IN-PROCESS against a fake port (a real worker thread is a separate
+ * V8 isolate the coverage provider cannot observe).
 * @module @deepseek-ai/dsh-code-runtime-worker/src/bootstrap
 */

 import { inspect } from 'node:util'
 import { serialize } from 'node:v8'
-import type { CodeLogEntry } from '@deepseek-ai/dsh-code-runtime'
 import { logTruncationMarker } from './protocol.ts'
 import type { DoneMessage, ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts'

@@ -33,12 +27,12 @@ export interface PatchableStream {
 }

 /**
- * Ordered log capture under one shared byte budget, delivered to a sink as
- * each entry lands (the real sink streams entries over the port eagerly, so
+ * Ordered text capture under one shared byte budget, delivered to a sink as
+ * each item lands (the real sink streams text over the port eagerly, so
 * captured output survives a mid-run termination). Once the budget is
- * exhausted it emits exactly one in-band marker entry (on the `stderr`
- * diagnostics channel) and silently drops everything after — the cap is a
- * blast-radius bound, so "how much was lost" intentionally stays unmeasured.
+ * exhausted it emits exactly one in-band marker and silently drops everything
+ * after. The cap is a blast-radius bound, so "how much was lost" intentionally
+ * stays unmeasured.
 */
 export class LogBuffer {
  private remaining: number
@@ -47,28 +41,28 @@ export class LogBuffer {
  // under Node's native strip-only mode, which rejects non-erasable syntax —
  // and parameter properties are non-erasable.
  private readonly maxBytes: number
-  private readonly sink: (entry: CodeLogEntry) => void
+  private readonly sink: (text: string) => void

-  constructor(maxBytes: number, sink: (entry: CodeLogEntry) => void) {
+  constructor(maxBytes: number, sink: (text: string) => void) {
    this.maxBytes = maxBytes
    this.sink = sink
    this.remaining = maxBytes
  }

  /**
-   * Emit one entry to the sink, charging its text against the budget (drops + marks once exhausted).
-   * @param entry - the log entry to deliver.
+   * Emit text to the sink, charging it against the budget (drops + marks once exhausted).
+   * @param text - the captured text to deliver.
   */
-  push(entry: CodeLogEntry): void {
+  push(text: string): void {
    if (this.truncated) return
-    const cost = Buffer.byteLength(entry.text, 'utf8')
+    const cost = Buffer.byteLength(text, 'utf8')
    if (cost > this.remaining) {
      this.truncated = true
-      this.sink({ source: 'stderr', text: logTruncationMarker(this.maxBytes) })
+      this.sink(logTruncationMarker(this.maxBytes))
      return
    }
    this.remaining -= cost
-    this.sink(entry)
+    this.sink(text)
  }
 }

@@ -89,32 +83,30 @@ export function makeConsoleShim(logs: LogBuffer): Record<(typeof CONSOLE_LEVELS)
    args.map(arg => typeof arg === 'string' ? arg : inspect(arg, INSPECT_OPTIONS)).join(' ')
  const shim = Object.create(null) as Record<(typeof CONSOLE_LEVELS)[number], (...args: unknown[]) => void>
  for (const level of CONSOLE_LEVELS) {
-    shim[level] = (...args: unknown[]) => { logs.push({ source: 'console', level, text: render(args) }) }
+    shim[level] = (...args: unknown[]) => { logs.push(render(args)) }
  }
  return shim
 }

 /**
 * Redirect a stream's `write` into the log buffer (the program-visible
- * `process.stdout`/`process.stderr` in the real worker), so raw writes land
- * in emission order alongside console output instead of racing down a pipe.
- * The shim keeps Node's `write(chunk[, encoding][, callback])` contract: the
- * callback fires asynchronously once the chunk is admitted (a program
- * awaiting flush completion must complete, not sit until the wall timeout),
- * even for writes the exhausted budget drops.
+ * `process.stdout`/`process.stderr` in the real worker), so raw writes land in emission order
+ * alongside console output instead of racing down a pipe. It preserves Node's optional callback
+ * contract: the callback runs asynchronously after admission, even when the log budget drops
+ * the write.
+ *
 * @param logs - the buffer captured writes are pushed into.
 * @param stream - the stream whose `write` slot is patched.
- * @param source - the log source the captured writes are attributed to.
 * @returns the restore function (the in-process tests un-patch; the real
 *   worker never needs to).
 */
-export function captureStreamWrites(logs: LogBuffer, stream: PatchableStream, source: 'stdout' | 'stderr'): () => void {
+export function captureStreamWrites(logs: LogBuffer, stream: PatchableStream): () => void {
  // The slot's VALUE is stored for restore and reassigned — never invoked
  // detached, so the unbound-method concern does not apply.
  // eslint-disable-next-line @typescript-eslint/unbound-method
  const original = stream.write
  stream.write = (chunk: unknown, ...rest: unknown[]): boolean => {
-    logs.push({ source, text: typeof chunk === 'string' ? chunk : String(chunk) })
+    logs.push(typeof chunk === 'string' ? chunk : String(chunk))
    // Node's optional-encoding shape: the callback is whichever of the next
    // two positions holds a function (a non-function there is the encoding).
    const callback = [rest[0], rest[1]].find(
@@ -152,16 +144,12 @@ export function truncateUtf8Bytes(text: string, maxBytes: number): string {
 }

 /**
- * Prepare the program's completion value for the done message: a value whose
- * MEASURED cross-boundary size fits `maxValueBytes` crosses raw — exact
- * bytes for a string, the structured-clone wire size (`v8.serialize`) for
- * everything else, so a huge container whose BOUNDED inspect rendering
- * happens to be small cannot smuggle itself past the cap. Anything else
- * (non-cloneable, or oversized) is REPLACED by its bounded `util.inspect`
- * rendering, byte-truncated ({@link truncateUtf8Bytes}) with an in-band
- * marker — the seam contract's "a non-transferable value is replaced by a
- * string rendering", extended to oversized ones so a huge return cannot
- * flood the host.
+ * Prepare the program's completion value for the done message: a value whose MEASURED
+ * cross-boundary size fits `maxValueBytes` crosses raw — exact bytes for a string, the
+ * structured-clone wire size (`v8.serialize`) for everything else, so a huge container whose
+ * bounded inspect rendering happens to be small cannot smuggle itself past the cap. Oversized
+ * or non-cloneable values are replaced by a bounded string rendering with an in-band marker.
+ *
 * @param value - the program's completion value.
 * @param maxValueBytes - the byte cap for the value.
 * @returns the done-message fragment: `{}` for `undefined`, else `{ value }`.
@@ -215,13 +203,11 @@ export function wireReplies(port: BootstrapPort, pending: Map<number, PendingCal
 }

 /**
- * Build the binding namespace objects the program sees: one null-prototype
- * global per namespace, each declared name an own enumerable async function
- * that bridges over the port (`__proto__`/`constructor`/`toString` are
- * ordinary keys, never prototype collisions). A non-cloneable argument
- * rejects that one call with a descriptive error; the host's reply (`ok`
- * false) rejects it likewise, so a failed tool call surfaces in the program
- * as an ordinary promise rejection.
+ * Build the binding namespace objects the program sees: one null-prototype global per
+ * namespace, each declared name an own enumerable async function that bridges over the port
+ * (`__proto__`/`constructor`/`toString` are ordinary keys, never prototype collisions).
+ * Non-cloneable arguments and host failure replies reject only the corresponding call.
+ *
 * @param data - the boot payload's namespace declarations (globals + names).
 * @param port - the port binding calls are posted to.
 * @param pending - the id-keyed map each posted call parks its handles in.
@@ -256,26 +242,21 @@ export function makeNamespaces(
 }

 /**
- * Run one program to settlement and post the {@link DoneMessage}: wires the
- * reply handler, materializes the namespaces and console shim, compiles the
- * type-stripped body as an async function (top-level `await`/`return`
- * work), and reports a thrown program error as the done message's `error`
- * field. Exactly one done message is ever posted.
- * @param port - the message port to the host (the real `parentPort`, or the tests' fake).
+ * Run one strict async-function body, allowing top-level `await` and `return`, and post exactly
+ * one terminal {@link DoneMessage}; a thrown program error becomes its `error` field.
+ * @param port - host message port or test double.
 * @param data - the boot payload the host sent.
- * @param streams - the stream objects whose `write` is captured (the real
- *   `process.stdout`/`process.stderr` in the worker; fakes in tests).
- * @returns resolves after the done message is posted (the tests await it;
- *   the real entry lets the worker exit naturally).
+ * @param streams - stdout/stderr objects captured as program logs.
+ * @returns after posting the done message.
 */
 export async function runWorkerMain(
  port: BootstrapPort,
  data: WorkerBootData,
  streams: { stdout: PatchableStream; stderr: PatchableStream },
 ): Promise<void> {
-  const logs = new LogBuffer(data.maxLogBytes, (entry) => { port.postMessage({ type: 'log', entry }) })
-  captureStreamWrites(logs, streams.stdout, 'stdout')
-  captureStreamWrites(logs, streams.stderr, 'stderr')
+  const logs = new LogBuffer(data.maxLogBytes, (text) => { port.postMessage({ type: 'log', text }) })
+  captureStreamWrites(logs, streams.stdout)
+  captureStreamWrites(logs, streams.stderr)

  const pending = new Map<number, PendingCall>()
  wireReplies(port, pending)
--- a/packages/code-runtime/code-runtime-worker/src/index.ts
+++ b/packages/code-runtime/code-runtime-worker/src/index.ts
@@ -1,14 +1,8 @@
 /**
- * Worker-thread implementation of the code-execution seam: one fresh Node
- * worker per run, executing the model's TypeScript after a host-side
- * type-strip, with bindings bridged over the message port. Containment, not
- * a security boundary (bash-equivalent trust — see the Code Mode RFC's
- * trust-posture section): the worker gets an EMPTY environment, a heap cap,
- * and two independent budgets — `computeMs` metered on the worker's
- * measured event-loop busy time (a hot loop cannot hide behind a pending
- * binding call) and a never-pausing `maxWallMs` ceiling — all funneling
- * into `worker.terminate()`, which ends hot synchronous loops too.
- *
+ * Worker-thread code runtime: a fresh worker runs each host-type-stripped TypeScript program
+ * and bridges bindings over its message port. This is containment, not a security boundary:
+ * model code has bash-equivalent trust despite an empty environment, a heap cap, measured
+ * event-loop busy-time and wall-time budgets, and termination that also stops synchronous loops.
 * @module @deepseek-ai/dsh-code-runtime-worker
 */

@@ -18,14 +12,11 @@ import { fileURLToPath } from 'node:url'
 import { Context } from 'cordis'
 import z from 'schemastery'
 import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
-import type { CodeBindingFunction, CodeLogEntry, CodeRunFailure, CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtime'
+import type { CodeBindingFunction, CodeRunFailure, CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtime'
 import { prepareValue, truncateUtf8Bytes } from './bootstrap.ts'
 import { logTruncationMarker } from './protocol.ts'
 import type { ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts'

-export type { BootstrapPort, PatchableStream } from './bootstrap.ts'
-export type { CallMessage, DoneMessage, ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts'
-
 /** Plugin config: every execution cap, changeable from `cordis.yml` (no hardcoded tunables). */
 export interface Config {
  /**
@@ -118,10 +109,6 @@ function messageOf(error: unknown): string {
  return error instanceof Error ? error.message : String(error)
 }

-/** The log sources / console levels the seam vocabulary admits, as runtime sets for inbound-message validation. */
-const LOG_SOURCES = new Set<string>(['console', 'stdout', 'stderr'])
-const LOG_LEVELS = new Set<string>(['log', 'info', 'warn', 'error', 'debug'])
-
 /**
 * Runtime shape gate for inbound port traffic. The peer runs MODEL CODE and
 * can post anything — `null`, primitives, objects with poisoned fields — so
@@ -140,20 +127,8 @@ function parseWorkerMessage(raw: unknown): WorkerToHost | undefined {
      return { type: 'call', id: m.id, global: m.global, name: m.name, args: m.args }
    }
    case 'log': {
-      const entry = m.entry
-      if (typeof entry !== 'object' || entry === null) return undefined
-      const e = entry as Record<string, unknown>
-      if (typeof e.text !== 'string') return undefined
-      if (typeof e.source !== 'string' || !LOG_SOURCES.has(e.source)) return undefined
-      if (e.level !== undefined && (typeof e.level !== 'string' || !LOG_LEVELS.has(e.level))) return undefined
-      return {
-        type: 'log',
-        entry: {
-          source: e.source as CodeLogEntry['source'],
-          ...e.level !== undefined ? { level: e.level as Exclude<CodeLogEntry['level'], undefined> } : {},
-          text: e.text,
-        },
-      }
+      if (typeof m.text !== 'string') return undefined
+      return { type: 'log', text: m.text }
    }
    case 'done': {
      if (m.error === undefined) return { type: 'done', ...m.value !== undefined ? { value: m.value } : {} }
@@ -282,11 +257,9 @@ export class WorkerCodeRuntime extends CodeRuntime {
      // Model code gets NO ambient environment — stronger than the scrubbed
      // env the defensive-patterns rule requires for spawned commands.
      env: {},
-      // Hermetic flags too: without this the worker inherits the host
-      // process's execArgv (a test runner's or tsx's loader hooks), which a
-      // bare isolate with an empty environment cannot satisfy. The entry
-      // needs nothing beyond native type stripping, on this repo's whole
-      // Node range.
+      // Hermetic flags too: without this the worker inherits the host process's execArgv (a
+      // test runner's or tsx's loader hooks), which a bare isolate with an empty environment
+      // cannot satisfy.
      execArgv: [],
      resourceLimits: { maxOldGenerationSizeMb: this.config.maxOldGenerationSizeMb },
      // Backstop capture: the bootstrap patches JS-level writes into its own
@@ -299,43 +272,36 @@ export class WorkerCodeRuntime extends CodeRuntime {
    return new Promise<CodeRunResult>((resolve) => {
      let settled = false
      const answered = new Set<number>()
-      const logs: CodeLogEntry[] = []
-      const strayLogs: CodeLogEntry[] = []
+      const logs: string[] = []
+      const strayLogs: string[] = []

-      // ONE host-side ledger for everything that lands in `logs`/`strayLogs`,
-      // whatever the path: honest port entries, FORGED port entries (model
-      // code posting `log` messages directly, bypassing the worker-side
-      // LogBuffer), and stray pipe bytes. On the first overflow it emits the
-      // same in-band marker the worker's LogBuffer would and drops the rest,
-      // so the documented cap is one shared `maxLogBytes` however it is hit.
+      // One host-side budget covers normal, forged, and stray-pipe log entries. The first
+      // overflow emits the shared in-band marker and drops everything after it.
      let logBudget = this.config.maxLogBytes
      let logsTruncated = false
-      const admit = (entry: CodeLogEntry, sink: CodeLogEntry[]): void => {
+      const admit = (text: string, sink: string[]): void => {
        if (logsTruncated) return
-        const cost = Buffer.byteLength(entry.text, 'utf8')
+        const cost = Buffer.byteLength(text, 'utf8')
        if (cost > logBudget) {
          logsTruncated = true
-          sink.push({ source: 'stderr', text: logTruncationMarker(this.config.maxLogBytes) })
+          sink.push(logTruncationMarker(this.config.maxLogBytes))
          return
        }
        logBudget -= cost
-        sink.push(entry)
+        sink.push(text)
      }

      // No settled guard: `finish` snapshots the arrays when it resolves, so
      // a chunk flushing after settlement mutates only the discarded buffers,
      // and the ledger bounds that growth until the pipes close.
-      const captureStray = (source: 'stdout' | 'stderr') => (chunk: Buffer) => {
-        admit({ source, text: chunk.toString('utf8') }, strayLogs)
+      const captureStray = (chunk: Buffer): void => {
+        admit(chunk.toString('utf8'), strayLogs)
      }
-      worker.stdout.on('data', captureStray('stdout'))
-      worker.stderr.on('data', captureStray('stderr'))
+      worker.stdout.on('data', captureStray)
+      worker.stderr.on('data', captureStray)

-      // Settlement: exactly one outcome wins; every path funnels through
-      // here, cleans up the timers/listeners, terminates the worker, and
-      // resolves only after the worker actually exited (quiescence). Logs
-      // streamed eagerly before the settlement are kept — a timed-out or
-      // killed program still shows the model what it printed.
+      // Exactly one outcome wins. Every path cleans up, terminates, and awaits the worker;
+      // logs captured before timeout, abort, or failure remain in the result.
      let finishResolve!: () => void
      const finished = new Promise<void>((done) => { finishResolve = done })
      const finish = (result: Omit<CodeRunResult, 'logs'>): void => {
@@ -353,11 +319,8 @@ export class WorkerCodeRuntime extends CodeRuntime {

      const onDone = (message: WorkerToHost): void => {
        if (message.type !== 'done') return
-        // Re-cap the completion value HOST-side: the honest path already
-        // capped it in the worker (prepareValue there), but a forged done
-        // message bypasses the bootstrap entirely — without this, model code
-        // could flood the host past maxValueBytes. Honest values pass
-        // unchanged (see VALUE_RENDER_SLACK); the error text is bounded too.
+        // Re-cap forged completion traffic at the hostile boundary. Honest worker-capped values
+        // pass unchanged via VALUE_RENDER_SLACK; error text is bounded too.
        finish({
          ...prepareValue(message.value, this.config.maxValueBytes + VALUE_RENDER_SLACK),
          ...message.error ? { error: { kind: 'exception' as const, message: truncateUtf8Bytes(message.error.message, this.config.maxValueBytes) } } : {},
@@ -404,7 +367,7 @@ export class WorkerCodeRuntime extends CodeRuntime {
        // this listener would crash the host process. Junk drops silently.
        const message = parseWorkerMessage(raw)
        if (!message) return
-        if (message.type === 'log' && !settled) admit(message.entry, logs)
+        if (message.type === 'log' && !settled) admit(message.text, logs)
        onCall(message)
        onDone(message)
      })
--- a/packages/code-runtime/code-runtime-worker/src/protocol.ts
+++ b/packages/code-runtime/code-runtime-worker/src/protocol.ts
@@ -1,16 +1,10 @@
 /**
- * Wire protocol between the host runtime and the worker bootstrap. Everything
- * crossing the message port is structured-clone-plain and versionless — both
- * ends ship in this package, always at the same version. The host treats
- * inbound traffic as HOSTILE (the worker runs model code, which can reach
- * `parentPort` via `import('node:worker_threads')` and forge any of these
- * shapes); the worker treats inbound traffic as trusted.
- *
+ * Versionless, structured-clone wire protocol between co-shipped host and worker code. The host
+ * treats inbound traffic as hostile because model code can forge `parentPort` messages; the
+ * worker trusts host replies.
 * @module @deepseek-ai/dsh-code-runtime-worker/src/protocol
 */

-import type { CodeLogEntry } from '@deepseek-ai/dsh-code-runtime'
-
 /** What the host hands the worker at spawn, via `workerData`. */
 export interface WorkerBootData {
  /** The type-stripped (plain JS) program body. */
@@ -24,7 +18,7 @@ export interface WorkerBootData {
 }

 /** Worker → host: one bridged binding call. */
-export interface CallMessage {
+interface CallMessage {
  type: 'call'
  /** Worker-issued correlation id; the host answers each id at most once and ignores duplicates. */
  id: number
@@ -36,10 +30,10 @@ export interface CallMessage {
  args: unknown
 }

-/** Worker → host: one captured log entry, streamed eagerly so output survives a mid-run termination (timeout, abort, OOM). */
-export interface LogMessage {
+/** Worker → host: captured text, streamed eagerly so output survives a mid-run termination (timeout, abort, OOM). */
+interface LogMessage {
  type: 'log'
-  entry: CodeLogEntry
+  text: string
 }

 /**
--- a/packages/code-runtime/code-runtime-worker/src/worker.ts
+++ b/packages/code-runtime/code-runtime-worker/src/worker.ts
@@ -1,12 +1,6 @@
 /**
- * The worker-thread entrypoint: self-executing glue over
- * `bootstrap.ts`'s {@link runWorkerMain}, kept to the spawn wiring alone.
- * Like `bin.ts` CLI entrypoints, this file executes only inside a spawned
- * worker isolate — a place the coverage provider cannot observe — so it is
- * excluded from the coverage gate while every line of actual logic lives in
- * `bootstrap.ts`, unit-tested in-process; the real spawn path is pinned by
- * the integration tests that run genuine workers.
- *
+ * Spawn-only worker entrypoint over {@link runWorkerMain}. Executable logic stays in
+ * `bootstrap.ts` for in-process coverage; real-worker tests cover this glue.
 * @module @deepseek-ai/dsh-code-runtime-worker/src/worker
 */

--- a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
@@ -1,9 +1,8 @@
 import { describe, expect, it } from 'vitest'
 import { EventEmitter } from 'node:events'
-import { LogBuffer, makeConsoleShim, makeNamespaces, captureStreamWrites, prepareValue, runWorkerMain, truncateUtf8Bytes, wireReplies } from '@deepseek-ai/dsh-code-runtime-worker/src/bootstrap.ts'
-import type { BootstrapPort, PatchableStream, PendingCall } from '@deepseek-ai/dsh-code-runtime-worker/src/bootstrap.ts'
-import type { ReplyMessage, WorkerToHost } from '@deepseek-ai/dsh-code-runtime-worker/src/protocol.ts'
-import type { CodeLogEntry } from '@deepseek-ai/dsh-code-runtime'
+import { LogBuffer, makeConsoleShim, makeNamespaces, captureStreamWrites, prepareValue, runWorkerMain, truncateUtf8Bytes, wireReplies } from '../src/bootstrap.ts'
+import type { BootstrapPort, PatchableStream, PendingCall } from '../src/bootstrap.ts'
+import type { ReplyMessage, WorkerToHost } from '../src/protocol.ts'

 /**
 * An in-process stand-in for the worker's parentPort: the test plays the
@@ -31,8 +30,8 @@ class FakePort implements BootstrapPort {
    this.emitter.emit('message', message)
  }

-  logs(): CodeLogEntry[] {
-    return this.sent.filter(message => message.type === 'log').map(message => message.entry)
+  logs(): string[] {
+    return this.sent.filter(message => message.type === 'log').map(message => message.text)
  }

  done(): WorkerToHost | undefined {
@@ -48,12 +47,12 @@ const BOOT = { maxLogBytes: 65_536, maxValueBytes: 32_768 }

 describe('LogBuffer', () => {
  it('streams entries to the sink until the byte budget, then emits one marker and drops the rest', () => {
-    const seen: CodeLogEntry[] = []
-    const buffer = new LogBuffer(10, entry => seen.push(entry))
-    buffer.push({ source: 'console', level: 'log', text: '12345' })
-    buffer.push({ source: 'console', level: 'log', text: '123456' })
-    buffer.push({ source: 'console', level: 'log', text: 'dropped' })
-    expect(seen.map(entry => entry.text)).toEqual([
+    const seen: string[] = []
+    const buffer = new LogBuffer(10, text => seen.push(text))
+    buffer.push('12345')
+    buffer.push('123456')
+    buffer.push('dropped')
+    expect(seen).toEqual([
      '12345',
      '[dsh-code-runtime-worker] log capture truncated at 10 bytes',
    ])
@@ -61,40 +60,37 @@ describe('LogBuffer', () => {
 })

 describe('makeConsoleShim', () => {
-  it('captures the five levels and renders non-strings inspect-style', () => {
-    const seen: CodeLogEntry[] = []
-    const shim = makeConsoleShim(new LogBuffer(1_000, entry => seen.push(entry)))
+  it('captures the five methods and renders non-strings inspect-style', () => {
+    const seen: string[] = []
+    const shim = makeConsoleShim(new LogBuffer(1_000, text => seen.push(text)))
    shim.log('plain', { a: 1 })
    shim.info('i')
    shim.warn('w')
    shim.error('e')
    shim.debug('d')
-    expect(seen.map(entry => entry.level)).toEqual(['log', 'info', 'warn', 'error', 'debug'])
-    expect(seen[0]?.text).toBe('plain { a: 1 }')
-    expect(seen.every(entry => entry.source === 'console')).toBe(true)
+    expect(seen).toEqual(['plain { a: 1 }', 'i', 'w', 'e', 'd'])
  })
 })

 describe('captureStreamWrites', () => {
  it('redirects writes into the buffer and restores on request', () => {
-    const seen: CodeLogEntry[] = []
-    const buffer = new LogBuffer(1_000, entry => seen.push(entry))
+    const seen: string[] = []
+    const buffer = new LogBuffer(1_000, text => seen.push(text))
    let underlying = ''
    const stream: PatchableStream = { write: (chunk: unknown) => { underlying += String(chunk); return true } }
-    const restore = captureStreamWrites(buffer, stream, 'stdout')
+    const restore = captureStreamWrites(buffer, stream)
    stream.write('captured', 'utf8')
    stream.write(Buffer.from('bytes'))
    restore()
    stream.write('after')
-    expect(seen.map(entry => entry.text)).toEqual(['captured', 'bytes'])
-    expect(seen[0]).toMatchObject({ source: 'stdout' })
+    expect(seen).toEqual(['captured', 'bytes'])
    expect(underlying).toBe('after')
  })

  it('invokes the write callback asynchronously, in both optional-encoding shapes', async () => {
    const buffer = new LogBuffer(1_000, () => {})
    const stream: PatchableStream = { write: () => true }
-    captureStreamWrites(buffer, stream, 'stdout')
+    captureStreamWrites(buffer, stream)
    const calls: (Error | null | undefined)[] = []
    stream.write('two-arg', (error?: Error | null) => calls.push(error))
    stream.write('three-arg', 'utf8', (error?: Error | null) => calls.push(error))
@@ -107,7 +103,7 @@ describe('captureStreamWrites', () => {
  it('still fires the callback for a write the exhausted budget drops', async () => {
    const buffer = new LogBuffer(4, () => {})
    const stream: PatchableStream = { write: () => true }
-    captureStreamWrites(buffer, stream, 'stdout')
+    captureStreamWrites(buffer, stream)
    stream.write('this write overflows the budget and is dropped')
    await new Promise<void>(resolve => stream.write('also dropped', resolve))
  })
@@ -210,7 +206,7 @@ describe('runWorkerMain', () => {
      code: 'const doubled = await tools.double({ n: 21 }); console.log("got", doubled); return { doubled };',
      namespaces: [{ global: 'tools', names: ['double'] }],
    }, fakeStreams())
-    expect(port.logs()).toEqual([{ source: 'console', level: 'log', text: 'got 42' }])
+    expect(port.logs()).toEqual(['got 42'])
    expect(port.done()).toEqual({ type: 'done', value: { doubled: 42 } })
  })

@@ -268,6 +264,6 @@ describe('runWorkerMain', () => {
    // The patch stays installed for the worker's lifetime; writes during the
    // program landed in order. Here the program wrote nothing via streams, so
    // only the post-run write above went through the patched slot.
-    expect(port.logs().at(-1)).toMatchObject({ source: 'stdout' })
+    expect(port.logs().at(-1)).toBe('never seen — already restored? no: patch persists in worker')
  })
 })
--- a/packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts
@@ -5,19 +5,10 @@ import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'

 /**
- * BUILT-ARTIFACT smoke for the published package (the real-load-path guard
- * from docs/testing.md): the unit suite runs `src/` under vitest, where the
- * worker entry resolves to `src/worker.ts` — a consumer runs `lib/index.js`
- * under plain `node`, where it must resolve the sibling `lib/worker.cjs`
- * bundle instead. This spawns plain `node` (NOT tsx) from inside the package
- * directory and imports the package BY NAME, so resolution flows through the
- * real `exports` map exactly as it would from a downstream install; the
- * program exercises the type-strip, the worker spawn, the binding bridge,
- * and log capture end-to-end through the built bundles.
- *
- * It build-gates: SKIPS when the built artifacts are absent (suite run
- * without `pnpm run build`); CI runs it after the build step. KEYLESS — no
- * model is involved.
+ * Keyless built-artifact smoke: plain Node imports the package by name through its exports map,
+ * then exercises type stripping, sibling `worker.cjs` loading, bindings, and logs. Unit tests use
+ * `src/worker.ts`; this pins the downstream `lib/index.js` path. It skips when `lib/` is absent,
+ * and CI runs it after the build.
 */

 const pkgDir = fileURLToPath(new URL('..', import.meta.url))
@@ -47,9 +38,9 @@ describe.skipIf(!built)('built lib real load path (plain node)', () => {

    expect(exitCode, `stderr:\n${stderr}`).toBe(0)
    const lastLine = stdout.trim().split('\n').at(-1) ?? ''
-    const result = JSON.parse(lastLine) as { value?: unknown; logs: { source: string; level?: string; text: string }[]; error?: unknown }
+    const result = JSON.parse(lastLine) as { value?: unknown; logs: string[]; error?: unknown }
    expect(result.error).toBeUndefined()
    expect(result.value).toBe(42)
-    expect(result.logs).toContainEqual({ source: 'console', level: 'log', text: 'halfway 42' })
+    expect(result.logs).toContain('halfway 42')
  })
 })
--- a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
@@ -28,7 +28,7 @@ describe('WorkerCodeRuntime — programs and bindings (real workers)', () => {
    expect(runtime.isolation).toBe('worker-thread')
  })

-  it('runs TypeScript (erasable syntax), captures console/stdout in order, returns the value', async () => {
+  it('runs TypeScript (erasable syntax), captures output in order, returns the value', async () => {
    const { runtime } = await setup()
    const result = await runtime.run({
      program: `
@@ -43,12 +43,7 @@ describe('WorkerCodeRuntime — programs and bindings (real workers)', () => {
    })
    expect(result.error).toBeUndefined()
    expect(result.value).toBe(3)
-    expect(result.logs.map(entry => [entry.source, entry.level ?? null])).toEqual([
-      ['console', 'log'],
-      ['stdout', null],
-      ['console', 'warn'],
-    ])
-    expect(result.logs[0]?.text).toBe('point { x: 1, y: 2 }')
+    expect(result.logs).toEqual(['point { x: 1, y: 2 }', 'raw-out\n', 'careful'])
  })

  it('bridges binding calls both ways and rejects the program-side call on a host rejection', async () => {
@@ -115,7 +110,7 @@ describe('WorkerCodeRuntime — programs and bindings (real workers)', () => {
      bindings: [],
    })
    expect(result.error?.kind).toBe('exception')
-    expect(result.logs.map(entry => entry.text)).toContain('before')
+    expect(result.logs).toContain('before')
  })
 })

@@ -210,8 +205,8 @@ describe('WorkerCodeRuntime — budgets and containment (real workers)', () => {
      program: 'for (let i = 0; i < 1000; i++) console.log("spam line", i); return 1',
      bindings: [],
    })
-    expect(result.logs.at(-1)?.text).toContain('truncated at 300 bytes')
-    const total = result.logs.reduce((sum, entry) => sum + Buffer.byteLength(entry.text, 'utf8'), 0)
+    expect(result.logs.at(-1)).toContain('truncated at 300 bytes')
+    const total = result.logs.reduce((sum, text) => sum + Buffer.byteLength(text, 'utf8'), 0)
    expect(total).toBeLessThan(1_000)
  })

@@ -241,7 +236,7 @@ describe('WorkerCodeRuntime — budgets and containment (real workers)', () => {
    })
    expect(result.error).toBeUndefined()
    expect(result.value).toBe('done')
-    expect(result.logs).toContainEqual({ source: 'stdout', text: 'flushed' })
+    expect(result.logs).toContain('flushed')
  })

  it('caps a huge container whose bounded rendering is small (wire size, not rendering, is what counts)', async () => {
@@ -255,10 +250,8 @@ describe('WorkerCodeRuntime — budgets and containment (real workers)', () => {
  it('captures pipe writes that bypass the patched write slot as stray logs, capped by the same budget', async () => {
    const { runtime } = await setup({ maxLogBytes: 4 })
    const result = await runtime.run({
-      // The bootstrap patches the stream instance's own `write`; going
-      // through the prototype's slot reaches the real pipe underneath, so
-      // the bytes arrive host-side as stray data. The pauses keep the two
-      // writes in separate pipe chunks and let them land before settlement.
+      // The prototype write bypasses the patched instance and reaches the real pipe. Pauses keep
+      // writes in separate chunks and let both reach the host before settlement.
      program: `
        const write = (text) => Object.getPrototypeOf(process.stdout).write.call(process.stdout, text);
        write('abcd');
@@ -270,8 +263,8 @@ describe('WorkerCodeRuntime — budgets and containment (real workers)', () => {
      bindings: [],
    })
    expect(result.error).toBeUndefined()
-    expect(result.logs).toContainEqual({ source: 'stdout', text: 'abcd' })
-    expect(result.logs.map(entry => entry.text)).not.toContain('ef')
+    expect(result.logs).toContain('abcd')
+    expect(result.logs).not.toContain('ef')
  }, 15_000)
 })

@@ -306,11 +299,9 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => {
          { type: 'call', id: 1e9, global: 7, name: 'real', args: {} },
          { type: 'call', id: 1e9, global: 'tools', name: 7, args: {} },
          { type: 'log' },
-          { type: 'log', entry: null },
-          { type: 'log', entry: { source: 'stdout', text: 7 } },
-          { type: 'log', entry: { source: 'nope', text: 'x' } },
-          { type: 'log', entry: { source: 'console', level: 'nope', text: 'x' } },
-          { type: 'log', entry: { source: 'console', level: 7, text: 'x' } },
+          { type: 'log', text: null },
+          { type: 'log', text: 7 },
+          { type: 'log', text: {} },
          { type: 'done', error: 5 },
          { type: 'done', error: { message: 5 } },
        ]) parentPort.postMessage(junk);
@@ -331,7 +322,7 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => {
      // code and an unbounded result.
      program: `
        const { parentPort } = await import('node:worker_threads');
-        for (let i = 0; i < 50; i++) parentPort.postMessage({ type: 'log', entry: { source: 'stdout', text: 'F'.repeat(100), forged: true } });
+        for (let i = 0; i < 50; i++) parentPort.postMessage({ type: 'log', text: 'F'.repeat(100), forged: true });
        parentPort.postMessage({ type: 'done', value: 'V'.repeat(100000) });
        for (;;) {}
      `,
@@ -343,10 +334,9 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => {
    expect(value.endsWith('… [truncated]')).toBe(true)
    expect(value.length).toBeLessThan(120)
    const marker = '[dsh-code-runtime-worker] log capture truncated at 200 bytes'
-    const total = result.logs.reduce((sum, entry) => sum + Buffer.byteLength(entry.text, 'utf8'), 0)
+    const total = result.logs.reduce((sum, text) => sum + Buffer.byteLength(text, 'utf8'), 0)
    expect(total).toBeLessThanOrEqual(200 + Buffer.byteLength(marker, 'utf8'))
-    expect(result.logs.at(-1)?.text).toBe(marker)
-    expect(result.logs.every(entry => !('forged' in entry))).toBe(true)
+    expect(result.logs.at(-1)).toBe(marker)
  })

  it('accepts a forged done carrying both value and error (self-sabotage, contained)', async () => {
--- a/packages/code-runtime/code-runtime-worker/tsdown.config.ts
+++ b/packages/code-runtime/code-runtime-worker/tsdown.config.ts
@@ -1,17 +1,9 @@
 import { defineConfig } from 'tsdown'

 /**
- * Package-shape override (see the root tsdown.config.ts): besides the
- * default lib/index.js bundle, the worker BOOTSTRAP ships as its own
- * sibling CommonJS entry — `new Worker(fileURLToPath(new URL('./worker.cjs', import.meta.url)))`
- * loads it as a file, so it cannot be part of the index bundle. pkg's VFS
- * Worker hook compiles string-path entries as CommonJS, so an ESM worker is
- * not viable inside the executable. TWO
- * single-entry builds, not one two-entry build: a multi-entry build emits
- * the shared bootstrap module as a `lib/bootstrap-*.js` chunk both bundles
- * import, which the package.json `files` whitelist (deliberately exact)
- * would omit from the packed artifact — each single-entry build inlines its
- * own bootstrap copy instead, keeping every shipped file self-contained.
+ * Build the index and worker as separate single-entry bundles. The sibling `worker.cjs` is loaded
+ * by file and must be CommonJS for pkg's VFS Worker hook. A multi-entry build emits an unlisted
+ * shared chunk omitted by the package's exact `files` whitelist; separate builds inline it.
 */
 export default defineConfig([
  {
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -16,4 +16,14 @@ Semantics every implementation must honor (contract details in the class JSDoc):

 ## 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.
+`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?`, ordered capped `logs: string[]`, and the `error?` (`CodeRunFailure`: `kind` + model-feedable `message`). See `src/types.ts` for the full contracts.
+
+## Model Experience
+
+Indirectly, through Code Mode in `dsh-tools`, which exposes `run_code` and returns program logs, values, or failures as retained tool-result tokens.
+
+## Known Limitations and Deferred Work
+
+- **`run()` is one-shot** — `logs` arrive only on the resolved `CodeRunResult`; the seam exposes no streaming-log or progress surface for a live program's output.
+- **A persistent REPL-style kernel is recorded future work** — the no-state-between-runs contract stands until a persistent-kernel backend brings its own logging story ([Code Mode RFC](../../../docs/rfc/implemented/feature/2026-06-15-code-mode.md)).
+- **Only the worker-thread backend ships** — `'process'`/`'container'` are declared well-known `isolation` values with no implementation; a hard security boundary awaits a container backend.
--- a/packages/code-runtime/code-runtime/package.json
+++ b/packages/code-runtime/code-runtime/package.json
@@ -22,9 +22,9 @@
  ],
  "license": "BSD-3-Clause",
  "peerDependencies": {
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/code-runtime/code-runtime/src/index.ts
+++ b/packages/code-runtime/code-runtime/src/index.ts
@@ -1,18 +1,6 @@
 /**
- * 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/implemented/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.
- *
+ * Code-execution seam for running one model-written program against host async bindings.
+ * Runtimes know nothing about tools or sessions; consumers own those concerns.
 * @module @deepseek-ai/dsh-code-runtime
 */

@@ -22,7 +10,6 @@ import type { CodeRunRequest, CodeRunResult } from './types.ts'
 export type {
  CodeBindingFunction,
  CodeBindingNamespace,
-  CodeLogEntry,
  CodeRunFailure,
  CodeRunRequest,
  CodeRunResult,
@@ -35,26 +22,10 @@ declare module 'cordis' {
 }

 /**
- * 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()`).
+ * Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate
+ * failures resolve in {@link CodeRunResult}; only seam misuse rejects. Implementations bridge
+ * structured-cloneable bindings while treating programs as hostile peers, isolate runs from
+ * one another, and terminate and await in-flight runs during disposal.
 */
 export abstract class CodeRuntime extends Service {
  /**
--- a/packages/code-runtime/code-runtime/src/types.ts
+++ b/packages/code-runtime/code-runtime/src/types.ts
@@ -54,20 +54,6 @@ export interface CodeRunRequest {
  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
@@ -98,8 +84,8 @@ export interface CodeRunResult {
   * or value-less run leaves this absent.
   */
  value?: unknown
-  /** Everything the program emitted, in order (capped by the implementation). */
-  logs: CodeLogEntry[]
+  /** Text the program emitted, in order (capped by the implementation). */
+  logs: string[]
  /** Present iff the run failed; see {@link CodeRunFailure} for the taxonomy. */
  error?: CodeRunFailure
 }
--- a/packages/code-runtime/code-runtime/tests/service.spec.ts
+++ b/packages/code-runtime/code-runtime/tests/service.spec.ts
@@ -55,7 +55,7 @@ describe('CodeRuntime service seam', () => {
  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' }],
+      logs: ['boom'],
      error: { kind: 'exception', message: 'boom' },
    }
    const result = await runtime.run({ program: 'throw new Error("boom")', bindings: [] })
--- a/packages/compact/compact-basic/README.md
+++ b/packages/compact/compact-basic/README.md
@@ -6,16 +6,15 @@ This is the implementation tier of the compaction capability — see the [interf

 ## What it owns

-The abstract contract states only WHAT compaction does; this backend owns every HOW decision:
+This backend owns the compaction policy:

- **Token estimation** — `estimateContentTokens()`: chars divided by the `charsPerToken` config (default 4) with per-block structural overhead (`text`/`reasoning` = `ceil(len/charsPerToken) + 4`, `tool-call` from name + arguments, `tool-result` recursive, unknown blocks via JSON length). The pressure gate estimates the NEXT request via `estimatePressure()`: the session prefix (the `agent/session-prefix` product — composed by the loop BEFORE the pre-step seam and handed through it, so the gate counts the prefix this instance will actually send in front of the history, never a stale logged one) + the derived history + the system prompt.
- **Retention policy** — `compactIfNeeded()` walks the surface nodes tail→head summing per-node token estimates, and retains the smallest tail-run of WHOLE units (a closed step, or a single no-step node such as a pre-step `user/message` or inter-step `steering/message`) whose total reaches `retainTokens`; everything older is compacted. Retention is **turn-agnostic** — turn boundaries play no role, so a single runaway turn that alone exceeds the window compacts its OWN early closed steps rather than being retained verbatim (the failure mode that motivated dropping turn-protection: a tool-heavy turn must stay compactable or the harness dies exactly when compaction is needed). The only structural guard is **tool-pairing balance**: the compacted region's edges are balanced cuts on the surface (no unanswered tool-call crosses either edge), so it never splits a step's `assistant/message` tool-calls from their `tool/result`s. When the only compactable content left is an un-splittable open tail step, it declines (returns `null`) and retries once an older step closes. **Single-unit overflow is out of scope, by design**: if one retained unit (a single closed step, or a large pasted `user/message`) ALONE exceeds the budget, compaction cannot help and the call may go out over-budget — bounding an individual unit's size is a separate concern. `compactRegion()` enforces tool-pairing balance strictly, throwing on a boundary that would split a step. `dsh-session` exports `isToolPairingBalanced` for the check.
- **Dynamic convergence** — no static summary-length config pretends to bound what the model will write. If framing/estimator/system overhead leaves the compacted surface above threshold, `compactIfNeeded()` re-compacts the head checkpoint up to `compactionRetries` extra times; if it still cannot get below threshold, it throws. A summary whose estimated stored size is not smaller than the shadowed content fails closed before it mutates the surface.
- **Summarization** — `summarize()`: a `GenerateOptions` request assembled via `BlockAssembler` with a fixed system prompt that asks for a structured checkpoint (Primary Request and Intent · Key Technical Concepts · Files and Code · Errors and Fixes · Pending Tasks · Current Work · Next Step · Critical Context), every section mandatory, exact paths/commands/identifiers preserved. The request is a direct one-shot `ctx.llm.stream()` call — NOT a loop step, so it does not run `agent/request` (that seam shapes the loop's conversation requests); the model comes from `summarizationModel` falling back to the agent's own, and per-call routing happens at `llm/stream` like any other direct call. `maxTokens` is the provider-side generation cap; only text blocks from the model's reply are kept before the checkpoint is stored (reasoning is dropped so private chain-of-thought never leaks into the durable summary, and a stray `tool-call` is dropped so the synthesized `user/message` summary cannot land an orphaned call with no matching `tool-result`). The compacted region is flattened to a plain-text transcript first: text and reasoning contribute their text, and every non-text block (tool-call, tool-result, plugin-added types) contributes a type-tagged placeholder (`[tool-call: name(args)]`, `[tool-result: …]`, …) so the summarizer is told what existed rather than silently dropping it.
- **Checkpoint framing** — the raw summary is not landed directly. `compactRegion()` wraps it in a checkpoint preamble (so a resuming model reads it as a checkpoint, not a fresh user request, and builds on the captured context rather than restating it) plus `<compacted-summary>…</compacted-summary>` tags. Because region compaction can be invoked manually, a surface may hold several checkpoints, so the framing does not claim everything after it is recent or verbatim. The tags make a prior checkpoint detectable in the transcript on the next compaction cycle: the summarization prompt then instructs the model to merge it in place (preserve still-true facts, drop stale ones) rather than re-summarize it verbatim — a cheap incremental merge that needs no extra log/event machinery. The unframed summary stays on the `compact/summary` provenance event.
- **Surface mutation** — `compactRegion()` appends the `compact/start` → `compact/summary` → `compact/end` log records and the single `user/message` replace node carrying the framed summary (see the interface README).
- **Auto-compaction** — an `agent/pre-step` listener delegates to `compactIfNeeded()` before every step (not just a turn's first — a tool-heavy turn grows the surface mid-turn, so a runaway turn still compacts, and per-step firing is the only moment to rescue it before overflow). `agent/pre-step` is a serial (awaited, in-order) surface-mutation checkpoint that fires after `turn/start` and BEFORE the step opens (`step/start`) and its request history is derived, so compaction mutates the surface — with its log-only `compact/*` records landing cleanly outside any step — and the loop derives once from the result: no double-derive, and the listener cannot see (or need to rewrite) an already-assembled `messages` array. The listener owns no threshold logic of its own (the single token-pressure check lives in `compactIfNeeded()`); because Cordis `serial` bails early on non-void return values, the listener returns `void` and does not use the dispatcher's bail channel as a veto surface.
- **Failure handling** — the `compact/start … compact/end` bracket is a log-recorded lock: it makes a crash mid-summarization a detectable orphan (a `compact/start` with no `compact/end`), records provenance, and prevents a concurrent compaction. Two failure paths: a **crash** (the loop dies mid-summarization) leaves a dangling `compact/start` that is inert — `compact/*` events are log-only, the surface replacement never landed, so the full history derives fine and generic turn-repair closes the turn; a **recoverable** failure (summarization throws but the loop survives) appends `compact/end` with its `error` field set, leaving the surface untouched so the call proceeds with full history. Core session repair stays compaction-agnostic by design — it never learns about `compact/*`.
+- **Estimation** — a configurable characters-per-token heuristic counts the current session prefix supplied to pre-step, derived history, and system prompt, matching the next request rather than stale logged prefix state.
+- **Retention** — compact the oldest whole surface units while preserving a recent tail and balanced tool-call/result cuts. Turn boundaries do not protect old steps inside a runaway turn. An open indivisible tail declines until it closes; a single unit larger than the budget remains out of scope.
+- **Convergence** — retry head-checkpoint compaction up to `compactionRetries`; reject a summary that does not shrink its source, and throw if retries cannot return below threshold.
+- **Summarization** — a direct `llm/stream` call uses the configured model and cap without running the loop-only `agent/request` seam. The input transcript preserves non-text blocks as tagged placeholders; only returned text enters the checkpoint, excluding reasoning and tool calls that would leak private reasoning or create an orphaned call.
+- **Framing** — the replacement user message marks established checkpoint context with `<compacted-summary>` tags. The raw summary remains on the provenance event, and later automatic cycles merge the prior checkpoint.
+- **Lifecycle** — `compactRegion()` records its start, summary, replacement, and end. The serial `agent/pre-step` listener checks pressure before every step, outside an open step, so a tool-heavy turn remains compactable and the loop derives history once after mutation.
+- **Failure handling** — an unmatched `compact/start` is an inert crash marker because no replacement landed. Recoverable failure records an error end and leaves the surface unchanged.

 `estimateContentTokens()` and `summarize()` are overridable hooks: a tokenizer-based or template-based backend can subclass `BasicCompactService` and override just those, reusing the retention walk and surface plumbing. `summarize()` returns the summary blocks together with the call envelope it actually used (`{ summary, model, maxTokens? }`) — the caller logs that envelope on the `compact/summary` provenance event, so an overriding backend reports its own envelope honestly.

@@ -56,3 +55,75 @@ export function apply(ctx: Context): void {
 ```

 Loading the plugin registers `ctx.compact`. With `auto: true` (the default) it compacts automatically under token pressure; a consumer (a future `/compact` tool) can also call `ctx.compact.compactIfNeeded(...)` or `ctx.compact.compactRegion(...)` directly.
+
+## Model Experience
+
+### Conversation history
+
+**What the model sees**: Before a step whose estimated envelope and history exceed the threshold, the conversation model receives the checkpoint preamble below, a blank line, `<compacted-summary>`, the data-dependent summary, and `</compacted-summary>`. This one checkpoint replaces the selected older range and is followed by the retained recent units.
+
+**Token effect**: The replacement reduces future input history rather than appending a second copy. The summary remains until a later compaction replaces it; one oversized indivisible unit can still exceed the budget.
+
+#### Conversation checkpoint preamble
+
+```markdown
+This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.
+```
+
+### Auxiliary summarizer user message
+
+**What the model sees**: The summarization model receives exactly `Summarize this conversation history:` followed by a blank line, the data-dependent [`renderTranscript()`](../compact/README.md) output, another blank line, and `Summary:`. The conversation model never sees this private request or its reasoning; only returned text is stored.
+
+**Token effect**: This is a separate model call with data-dependent input and `maxTokens`-capped output. Convergence retries can pay this cost more than once.
+
+### Auxiliary summarizer system prompt
+
+**What the model sees**: The summarization model receives the checkpoint-writing instruction below.
+
+**Token effect**: Fixed auxiliary input cost plus the data-dependent transcript on every summarization attempt.
+
+#### Auxiliary summarizer system prompt
+
+```markdown
+You are a compaction engine for an AI coding assistant. Condense the conversation transcript into a structured checkpoint that lets another model resume the work with no loss of essential context.
+
+Output EXACTLY the Markdown structure below: keep every section, in order. Use terse bullets, not prose paragraphs. Write "(none)" for an empty section — never drop a section.
+
+## Primary Request and Intent
+- [the user's original and evolving goals; quote verbatim where the exact wording matters]
+
+## Key Technical Concepts
+- [technologies, frameworks, patterns, and conventions in play]
+
+## Files and Code
+- [exact path: why it matters, key changes or snippets]
+
+## Errors and Fixes
+- [error: how it was resolved, plus any related user feedback]
+
+## Pending Tasks
+- [explicitly requested work not yet completed]
+
+## Current Work
+- [precisely what was in progress at this checkpoint]
+
+## Next Step
+- [the single next action, directly in line with the most recent request, or "(none)"]
+
+## Critical Context
+- [decisions and their rationale, constraints, user preferences, open questions, data needed to continue]
+
+Rules:
+- Preserve exact file paths, commands, error strings, identifiers, and function signatures.
+- Capture user feedback and explicit instructions faithfully, especially corrections.
+- Do NOT mention this summarization process or that the context was compacted.
+- If the transcript already contains a <compacted-summary> block, it is a PRIOR checkpoint. Do not copy it forward verbatim: preserve still-true facts, drop stale ones, and merge newer information into a single consolidated summary under the same structure.
+```
+
+## Known Limitations and Deferred Work
+
+- **Token estimation is the chars/`charsPerToken` heuristic** — a marked TODO schedules replacing it with an exact count (a real tokenizer, or provider `usage` fed back) so thresholds track the model's actual budget.
+- **`estimatePressure()` does not count the request's `tools` field** — pressure is underestimated by the size of the serialized tool schemas the request also carries.
+- **`compactRegion` requires an open turn** — a manual call on a fully-closed session throws ("no open turn") rather than compacting.
+- **Summarization failure fails closed with full, over-budget history** — including truncation at the summarization `maxTokens`, which hidden reasoning tokens can consume; the auto path logs a warning and proceeds.
+- **The summarization call has no transcript-snapshot coverage** — `dsh-llm-replay` derives calls from `assistant/chunk` events, so this chunk-less direct `ctx.llm.stream()` call cannot replay (named deferred replay infrastructure in [the seam RFC](../../../docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md)).
--- a/packages/compact/compact-basic/package.json
+++ b/packages/compact/compact-basic/package.json
@@ -26,7 +26,7 @@
    "@deepseek-ai/dsh-compact": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
    "@deepseek-ai/dsh-agent": "workspace:^",
@@ -37,6 +37,6 @@
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/compact/compact-basic/src/index.ts
+++ b/packages/compact/compact-basic/src/index.ts
@@ -1,31 +1,8 @@
 /**
- * `BasicCompactService`: the first implementation of the
- * `@deepseek-ai/dsh-compact` seam. It owns the entire compaction strategy:
- *
- * - **Token estimation** — chars/`charsPerToken` heuristic (config, default 4)
- *   with per-block structural overhead.
- * - **Retention policy** — walk surface nodes tail→head, keep recent nodes up
- *   to a token budget, compact everything older. The cutoff is snapped forward
- *   to the next balanced tool-pairing boundary so a compacted region never
- *   splits a step's tool-call/result pair (an open tail step is never crossed —
- *   compaction declines and retries once it closes).
- * - **Summarization** — a direct one-shot `ctx.llm.stream()` call assembled
- *   via `BlockAssembler` with a fixed condense-the-history system prompt;
- *   NOT a loop step, so `agent/request` never fires — interception happens
- *   at `llm/stream` like any other direct call.
- * - **Surface mutation** — a single `user/message` replace node carries the
- *   summary; `compact/*` events are log-only lock + provenance records.
- * - **Auto-compaction** — an `agent/pre-step` listener delegates to
- *   {@link BasicCompactService.compactIfNeeded} before EVERY step (so a
- *   tool-heavy turn that grows the surface mid-turn still compacts); it owns the
- *   sole token-pressure check.
- *
- * A different backend (real tokenizer, template summarizer, turn-count
- * retention) either subclasses this and overrides the {@link
- * BasicCompactService.estimateContentTokens} / {@link
- * BasicCompactService.summarize} hooks, or implements the abstract
- * {@link CompactService} from scratch.
- *
+ * Basic compaction backend. It estimates request pressure, retains a recent
+ * tool-balanced surface tail, summarizes the older head through a one-shot model
+ * call, and replaces that head with one checkpoint. Auto-compaction runs before
+ * every step so a growing turn can compact its earlier closed steps.
 * @module @deepseek-ai/dsh-compact-basic
 */

@@ -54,15 +31,8 @@ const SUMMARY_OPEN_TAG = '<compacted-summary>'
 const SUMMARY_CLOSE_TAG = '</compacted-summary>'

 /**
- * The summarization system prompt: instructs the model to condense the
- * conversation into a fixed, fully-populated structure rather than freeform
- * bullets. The fixed structure guarantees coverage of the things a resuming
- * model needs (original intent, pending work, the next step, critical context)
- * and is stable across compaction cycles, so a prior checkpoint can be merged
- * in place. The final rule keys off {@link SUMMARY_OPEN_TAG}: when the
- * transcript already contains a prior checkpoint, the model consolidates rather
- * than re-summarizing it verbatim (a cheap incremental-merge that needs no
- * extra log/event machinery — the tag travels on the summary surface node).
+ * Fixed summary structure for resumable checkpoints. A tagged prior checkpoint
+ * is merged with newer history instead of copied forward verbatim.
 */
 const SUMMARIZE_SYSTEM_PROMPT = [
  'You are a compaction engine for an AI coding assistant. Condense the conversation transcript into a structured checkpoint that lets another model resume the work with no loss of essential context.',
@@ -100,29 +70,13 @@ const SUMMARIZE_SYSTEM_PROMPT = [
  `- If the transcript already contains a ${SUMMARY_OPEN_TAG} block, it is a PRIOR checkpoint. Do not copy it forward verbatim: preserve still-true facts, drop stale ones, and merge newer information into a single consolidated summary under the same structure.`,
 ].join('\n')

-/**
- * Framing prepended to the landed summary so a resuming model reads it as a
- * checkpoint rather than a fresh user request, and continues the task from it.
- * It summarizes an earlier span of the conversation; the messages that follow
- * are the continuation. Because region compaction can be invoked manually, a
- * surface may hold several checkpoints, so the framing does NOT claim that
- * everything after it is recent or verbatim — only that the captured context
- * should be built on, not restated.
- */
+/** Framing that makes a landed summary established context rather than a new request. */
 const CHECKPOINT_PREAMBLE =
  'This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.'

 /**
- * Map a terminal `FinishReason` to the error a SUMMARIZATION must throw, or
- * `undefined` for an acceptable finish. `FinishReason` is merge-extensible.
- *
- * Compaction fails CLOSED on a truncated summary: `error`, `aborted`, AND
- * `max-tokens` all raise. Unlike an ordinary agent turn — where `max-tokens` is
- * a normal "the model hit its budget" outcome the loop keeps — a summary cut off
- * at the token cap is an INCOMPLETE checkpoint, and committing it would shadow
- * (discard) the real history it summarizes. Raising here keeps the original
- * surface intact (the caller appends `compact/end` with the error and the auto
- * path proceeds with full history). `stop`/future kinds are accepted.
+ * Map a terminal summary failure to an error. A max-token finish is rejected
+ * because committing an incomplete checkpoint would shadow the full history.
 */
 function finishError(finish: FinishReason): Error | undefined {
  switch (finish.kind) {
@@ -164,25 +118,8 @@ export class BasicCompactService extends CompactService {
    this.config = resolveConfig(config)

    if (this.config.auto) {
-      // Auto-compaction: delegate to compactIfNeeded before EVERY step. This is
-      // LOAD-BEARING for runaway-turn survival: a tool-heavy ReAct turn appends
-      // an assistant/message and a tool/result per step, so the surface (and the
-      // derived token count) grows WITHIN a turn. The only moment to rescue a
-      // turn that alone approaches the window is the next step's pre-step
-      // checkpoint; gating to a turn's first step would let a runaway turn
-      // overflow before the next turn's check. The listener owns NO threshold
-      // logic — compactIfNeeded is the single place that decides whether to
-      // compact, and its in-progress lock serializes concurrent attempts.
-      //
-      // It runs on `agent/pre-step` (a serial surface-mutation checkpoint fired
-      // AFTER turn/start but BEFORE step/start), NOT `agent/request`: compaction
-      // mutates the session surface, and the loop derives the request `messages`
-      // AFTER this fires — so a single derive already reflects the compaction,
-      // with no double-derive and no need to rewrite an already-assembled
-      // `messages` array. Firing pre-step (outside any open step) keeps the
-      // log-only `compact/*` records and the replacement node cleanly outside a
-      // step, so a crash mid-compaction leaves an inert orphan the turn-repair
-      // closes — never a half-open step.
+      // Check before every step so a single growing turn can compact earlier closed steps.
+      // This serial pre-step seam mutates the surface outside the pending step.
      ctx.on('agent/pre-step', async (agent: Agent, _turn: number, _step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal) => {
        try {
          const result = await this.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)
@@ -289,27 +226,9 @@ export class BasicCompactService extends CompactService {
  }

  /**
-   * Summarize conversation text into content blocks via `ctx.llm.stream()`
-   * assembled through a `BlockAssembler`. A direct one-shot model call, NOT a
-   * loop step: it does not run the `agent/request` waterfall (that seam shapes
-   * the loop's conversation requests); per-call
-   * interception happens at `llm/stream` like any other direct call. The model
-   * comes from `BasicCompactConfig.summarizationModel`, falling back to the
-   * agent's own model.
-   * Override in a subclass for a template or remote summarizer.
-   *
-   * Honors the adapter failure contract: an adapter may report a model failure
-   * by throwing from `stream()` (propagated here) OR by ending the stream with
-   * a `finish {kind:'error'|'aborted'}` chunk — the latter is re-thrown so a
-   * provider error never yields an empty summary.
-   *
-   * Forwards `signal` into `GenerateOptions.signal` so an abort/dispose tears
-   * down the in-flight summarization rather than orphaning the model call.
-   *
-   * Returns the summary blocks TOGETHER with the call envelope it actually
-   * used (`model`, `maxTokens`) — the caller logs the envelope on the
-   * `compact/summary` provenance event, so an overriding subclass (template
-   * or remote summarizer) reports its own envelope honestly.
+   * Summarize through a direct one-shot `ctx.llm.stream()` call, not an agent
+   * step or `agent/request` dispatch. Failure finishes and truncated summaries
+   * reject; the signal is forwarded and only text reaches the checkpoint.
   *
   * @param text - plain-text rendering of the conversation region to condense.
   * @param agent - supplies the fallback model and the session id stamped on
@@ -359,42 +278,10 @@ export class BasicCompactService extends CompactService {
  // ---- Core API (implements the abstract contract) ----

  /**
-   * The sole token-pressure gate: estimate the NEXT request's pressure — the
-   * session prefix + the surface-derived history + the system prompt
-   * ({@link estimatePressure}) — and if it exceeds the threshold
-   * (`contextWindow * thresholdRatio`), compact
-   * the oldest surface nodes outside the `retainTokens` budget. The auto-
-   * compaction listener delegates here rather than pre-checking, so this is the
-   * only place the decision lives. The prefix counts because every request
-   * carries it in front of the history (`EpochHeader.messagePrefix`) even
-   * though it is not derived history — omitting it would under-estimate by
-   * exactly the prefix and let a deployment at the window edge skip
-   * compaction, then ship an over-window request. The loop composes the
-   * prefix BEFORE the pre-step seam and hands it through, so the gate sees
-   * this instance's actual prefix (never a previous instance's logged one —
-   * a resumed/forked instance whose contributor grew is gated on the grown
-   * value from its very first step). Compaction itself can only
-   * shrink HISTORY: a prefix that alone approaches the window is a
-   * configuration error no compactor fixes.
-   *
-   * Retention is a UNIFORM tail→head walk over the whole surface — turn
-   * boundaries play NO role. Walking node-by-node from the tail and summing
-   * token estimates, once the retained total reaches `retainTokens` the cutoff
-   * is rounded to a balanced tool-pairing boundary: if the cut before the
-   * retained node is unbalanced (an unanswered tool-call sits before it — i.e.
-   * it is mid-step), the walk continues head-ward until the cut is balanced so
-   * the whole step is retained (never splitting a step's tool-calls from their
-   * results); if it stopped on a free node (a node belonging to no step), that
-   * cut is already balanced. This always rounds toward retaining MORE (retained
-   * ≥ `retainTokens`) and is boundary-safe by construction — no separate snap
-   * pass.
-   *
-   * The compacted range is always anchored at the surface HEAD (`nodes[0]`):
-   * auto-compaction re-consolidates any prior head checkpoint into one fresh
-   * checkpoint. Declines (`null`) when nothing is over threshold, when the whole
-   * surface fits the retain budget, or when no balanced cutoff exists in the
-   * compactable range (its only content is an open tail step — retry once it
-   * closes).
+   * The sole pressure gate: count the next request's prefix, derived history,
+   * and system prompt. Above threshold, retain a recent tool-balanced tail and
+   * compact the head, reconsolidating any prior automatic checkpoint. Returns
+   * `null` when no safe or necessary range exists.
   */
  override async compactIfNeeded(
    agent: Agent,
@@ -450,13 +337,7 @@ export class BasicCompactService extends CompactService {
    agent: Agent,
    signal?: AbortSignal,
  ): Promise<CompactionResult> {
-    // Resolve the range by surface POSITION, not numeric seq interval. A prior
-    // replace lands a fresh high-seq summary node AT the shadowed range's
-    // position, so the surface order (head→tail) no longer tracks seq order —
-    // `[newSummarySeq, olderRetainedSeq, …]` is normal. Indexing into the
-    // ordered node list and slicing it is the only correct way to read a range;
-    // a `node.seq >= start && node.seq <= end` interval test would mis-collect
-    // nodes (and `start > end` would falsely reject) once that happens.
+    // Resolve by surface position: a newer replacement seq may occupy an older slot.
    const nodes = session.surface.nodes
    const startIdx = nodes.findIndex(n => n.seq === start)
    const endIdx = nodes.findIndex(n => n.seq === end)
@@ -466,14 +347,7 @@ export class BasicCompactService extends CompactService {
      throw new Error(`compactRegion: start seq ${start} (position ${startIdx}) is after end seq ${end} (position ${endIdx}) on the surface`)
    }

-    // The region must never split a step's assistant-message tool-calls from
-    // their tool/results (which would orphan one side and produce a transcript
-    // every provider rejects). A region is safe iff BOTH its edges are balanced
-    // cuts: the cut before `start`, and the cut after `end`. A node that belongs
-    // to no step (pre-step user message, inter-step steering, injection context)
-    // is a balanced (free) boundary; an `end` inside an open (unclosed) tail step
-    // leaves the cut after it unbalanced (the open tool-call has no result yet),
-    // so it is rejected. See dsh-session's tool-pairing balance check.
+    // Both range edges must preserve assistant tool-call/result pairing.
    const events = session.events
    if (!isToolPairingBalanced(nodes, events, start)) {
      throw new Error(`compactRegion: start seq ${start} is not a balanced boundary (would split a step's tool-call/result pair)`)
@@ -490,13 +364,8 @@ export class BasicCompactService extends CompactService {
      throw new Error('compaction already in progress')
    }

-    // Compaction's events (compact/* and the replacement user/message) must be
-    // turn-enclosed: the session-log contract rejects any plugin event appended
-    // outside an open turn. Auto-compaction satisfies this — it runs on the
-    // `agent/pre-step` seam, after `turn/start` and before `step/start`, so
-    // strictly inside the open turn (but outside any step). A manual call on a
-    // fully-closed session has no turn to enclose the events, so reject rather
-    // than emit an un-enclosed run.
+    // Compaction's events (compact/* and the replacement user/message) must be turn-enclosed:
+    // the session-log contract rejects any plugin event appended outside an open turn.
    const openTurn = this._openTurn(session)
    if (openTurn === null) {
      throw new Error('compactRegion: no open turn — compaction events must be enclosed in a turn')
@@ -537,13 +406,8 @@ export class BasicCompactService extends CompactService {
        ...maxTokens !== undefined ? { maxTokens } : {},
      })

-      // --- Surface replacement ---
-      // The user/message directly shadows all compacted surface nodes with a
-      // single replace op. It is the ONLY surface event in the compaction
-      // sequence — compact/start, compact/summary, and compact/end are log-only
-      // (surfaceOp is rejected by the compiler for non-SurfaceEventType).
-      // The landed content is FRAMED (checkpoint preamble + tag-wrapped summary);
-      // the compact/summary provenance event above holds the raw model output.
+      // --- Surface replacement --- The user/message directly shadows all compacted surface
+      // nodes with a single replace op.
      session.append('user/message', {
        content: framedSummary,
        source: { kind: 'plugin', plugin: 'compact' },
@@ -597,17 +461,8 @@ export class BasicCompactService extends CompactService {
  }

  /**
-   * Whether a compaction is currently in progress for `session` — an unmatched
-   * `compact/start` (no later `compact/end`) WITHIN the current turn.
-   *
-   * The scan is scoped to the current turn: walking back from the tail it stops
-   * at the first `turn/end` (the boundary closing the prior turn). A
-   * `compact/start` left orphaned by a crash mid-compaction lives in a turn that
-   * persistence repair then closes with a synthetic `turn/end`; scoping here so
-   * that a stale orphan from a PAST turn cannot wedge compaction forever (it sits
-   * before the nearest `turn/end`, so the scan never reaches it). An in-progress
-   * compaction's `compact/start` is always in the still-open current turn,
-   * before any `turn/end`, so it is still detected.
+   * Whether a compaction is currently in progress for `session` — an unmatched `compact/start`
+   * (no later `compact/end`) WITHIN the current turn.
   */
  private _isCompactionInProgress(session: Session): boolean {
    const events = session.events
@@ -650,14 +505,10 @@ export class BasicCompactService extends CompactService {
    // The whole surface fits the retain budget — nothing to compact.
    if (keepFromIdx === 0) return null

-    // Round the cutoff to a tool-pairing boundary: if the cut before
-    // `nodes[keepFromIdx]` is unbalanced (an unanswered tool-call sits before
-    // it — i.e. it is mid-step), extend the retained side head-ward until the
-    // cut is balanced, so the compacted range ends without splitting an
-    // assistant↔result pair. A node that belongs to no step is already a
-    // balanced (free) boundary. Decline if no balanced cut exists at or below
-    // `keepFromIdx` (the compactable range is only an un-splittable open tail
-    // step — retry once it closes).
+    // Round the cutoff to a tool-pairing boundary: if the cut before `nodes[keepFromIdx]` is
+    // unbalanced (an unanswered tool-call sits before it — i.e. it is mid-step), extend the
+    // retained side head-ward until the cut is balanced, so the compacted range ends without
+    // splitting an assistant↔result pair.
    while (keepFromIdx > 0) {
      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
      if (isToolPairingBalanced(nodes, events, nodes[keepFromIdx]!.seq)) break
@@ -673,17 +524,7 @@ export class BasicCompactService extends CompactService {
    return { start: firstSeq, end: cutoffSeq }
  }

-  /**
-   * Keep ONLY text blocks from the model-produced summary before storing it.
-   *
-   * The summary lands on the surface as a synthesized `user/message` (see
-   * {@link _frameSummary}), so the only block type that is both useful and safe
-   * there is `text`. A model assistant message can otherwise carry `reasoning`
-   * (private chain-of-thought, must not leak into the durable checkpoint) and
-   * `tool-call` blocks — and a surviving `tool-call` in a user message would be
-   * an orphaned call with no matching `tool-result`, exactly the tool-pairing
-   * breakage compaction works to avoid. Filtering to text drops both.
-   */
+  /** Keep only text; checkpoints cannot contain reasoning or orphan tool calls. */
  private _textOnly(blocks: readonly ContentBlock[]): ContentBlock[] {
    return blocks.filter((block): block is Extract<ContentBlock, { type: 'text' }> => block.type === 'text')
  }
--- a/packages/compact/compact-basic/src/types.ts
+++ b/packages/compact/compact-basic/src/types.ts
@@ -48,13 +48,6 @@ export type ResolvedConfig = Required<BasicCompactConfig>
 /**
 * Default `auto`/`charsPerToken` when unset and reject nonsensical numeric knobs.
 *
- * Convergence is not a static config invariant: provider generation caps can be
- * spent on hidden or surfaced reasoning tokens, and the model may emit a summary
- * of unpredictable size. The backend instead enforces convergence dynamically:
- * each committed summary must be smaller than the content it shadows, and
- * `compactIfNeeded` may re-compact up to `compactionRetries` extra times before
- * throwing if the surface still exceeds the threshold.
- *
 * @param config - the raw, unresolved backend config.
 * @returns the validated config with `auto` and `charsPerToken` defaulted.
 */
--- a/packages/compact/compact-basic/tests/compact-basic.spec.ts
+++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts
@@ -82,15 +82,7 @@ function createTestService(overrides: Partial<BasicCompactConfig> = {}): TestCom
  return new TestCompactService(new Context(), cfg({ auto: false, ...overrides }))
 }

-/**
- * Build a multi-turn session with surface markers (simulating real agent-loop
- * output). Compaction always runs inside an OPEN turn (the loop fires the
- * `agent/pre-step` seam after a turn's start and before a step's start), so by
- * default the session is left with a trailing open turn: turns `1..turns`
- * close, then one more `turn/start` opens with no matching `turn/end`. Pass
- * `{ leaveOpen: false }` for a fully-closed session (e.g. to assert that manual
- * compaction is rejected when no turn is open).
- */
+/** Build closed turns plus an open compaction turn unless `leaveOpen` is false. */
 function multiTurnSession(turns: number, messagesPerTurn: number = 2, opts: { leaveOpen?: boolean } = {}): Session {
  const leaveOpen = opts.leaveOpen ?? true
  const s = new Session(SessionId('test'))
@@ -211,12 +203,8 @@ function expectNoOrphanToolResults(messages: Message[]): void {

 describe('BasicCompactService step-alignment (never split a tool-call/result pair)', () => {
  it('compactIfNeeded rounds the retained boundary head-ward to keep a whole step (no orphaned tool-result)', async () => {
-    // 3 turns, each one step = { assistant(tool-call), tool/result }. Surface
-    // (9 nodes): user1, asst1, res1, user2, asst2, res2, user3, asst3, res3 —
-    // 10/20/10 tokens. The tail→head walk retains by whole units; the compacted
-    // region always ends on a step boundary, so no step's tool-call is split
-    // from its result. retainTokens=55 keeps the recent tail; the older steps
-    // compact intact.
+    // Retain the recent tail while the older assistant/result pairs compact as
+    // whole units; no boundary may orphan a result.
    const svc = createTestService({ contextWindow: 280, thresholdRatio: 0.5, retainTokens: 55 })
    const session = toolTurnSession(3)

@@ -231,12 +219,8 @@ describe('BasicCompactService step-alignment (never split a tool-call/result pai
  })

  it('compactIfNeeded returns null when the only compactable region is an un-splittable single step', async () => {
-    // The surface is exactly ONE step: [assistant(tool-call), tool/result]. Over
-    // threshold (by the derived role overhead), the tail→head walk stops with the
-    // retained boundary at the tool/result — which is NOT a step-aligned start (its
-    // issuing assistant precedes it in the same step). Rounding head-ward to find a
-    // clean boundary reaches index 0, so there is no step-aligned cutoff in the
-    // compactable range: compactIfNeeded declines rather than splitting the step.
+    // The only candidate cut is inside one assistant/result pair; with no safe
+    // compactable prefix, decline rather than split it.
    const s = new Session(SessionId('one-step'))
    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    s.append('step/start', { turn: 1, step: 1 })
@@ -605,27 +589,16 @@ describe('BasicCompactService.compactIfNeeded', () => {
  })

  it('returns null when the whole surface fits the retain budget (over threshold by role/system overhead)', async () => {
-    // threshold = floor(480*0.1) = 48. The 4 surface nodes weigh 10 each (raw 40
-    // for the retention walk), but the derived estimate adds 4 role tokens per
-    // message → 56 ≥ 48, so the threshold check passes and the walk runs. The
-    // walk accumulates all 40 < retainTokens (45) without crossing the budget,
-    // so keepFromIdx reaches 0 and compaction declines.
+    // Role overhead pushes the request above its 48-token threshold, but the
+    // raw four-node retention walk remains below retainTokens=45, so all fit.
    const svc = createTestService({ contextWindow: 480, thresholdRatio: 0.1, retainTokens: 45 })
    const session = multiTurnSession(2, 1)
    expect(await compactIfNeeded(svc, session, '', 'm', SIGNAL)).toBeNull()
  })

  it('compacts a runaway turn: its early CLOSED steps summarize while recent steps stay verbatim', async () => {
-    // The REGRESSION that motivated dropping turn-protection. A single in-flight
-    // (open) turn has grown past the threshold on its own: several CLOSED steps,
-    // each [assistant(tool-call), tool/result]. Retention is turn-agnostic, so
-    // the turn's OWN early closed steps are eligible — they compact while the
-    // recent tail stays verbatim, and the harness survives.
-    //
-    // On the OLD layer-2 code this test FAILS: the entire open turn was retained
-    // verbatim (protectedIdx = first open-turn node = 0), so compactIfNeeded
-    // returned null and shadowedSeqs would be empty — the runaway turn could
-    // never compact and the next model call would overflow the window.
+    // Completed early steps of the open turn remain eligible; protecting the
+    // whole turn would make a runaway turn impossible to compact.
    const svc = createTestService({ contextWindow: 800, thresholdRatio: 0.1, retainTokens: 25 })
    const s = new Session(SessionId('runaway'))
    // ONE open turn with 5 closed steps; each step is [asst(tool-call), result].
@@ -665,12 +638,7 @@ describe('BasicCompactService.compactIfNeeded', () => {
  })

  it('compacts again after a prior summary node heads the surface (the summary stays eligible)', async () => {
-    // After the first compaction lands a replacement summary node at the head,
-    // a second compaction (still over threshold) re-consolidates it with newer
-    // context — head-anchoring means the prior checkpoint is always re-included,
-    // never stranded. retainTokens=25 leaves a couple of retained nodes after
-    // the first compaction (so the surface is [summary, …retained], not just
-    // [summary]).
+    // Head-anchored recompaction must include the previous summary and retained context.
    const svc = createTestService({ contextWindow: 800, thresholdRatio: 0.1, retainTokens: 25 })
    const s = multiTurnSession(4, 1) // turns 1-4 closed, turn 5 open (no surface yet)

@@ -776,10 +744,8 @@ describe('BasicCompactService blocking (compaction in progress)', () => {
  })

  it('is not wedged by an orphaned compact/start from a prior (now-closed) turn', async () => {
-    // A crash mid-compaction left a compact/start with no compact/end; the turn
-    // it lived in was later closed (persistence repair appends turn/end). A
-    // whole-log scan would treat that stale start as an active lock forever. The
-    // scan is scoped to the current turn, so a NEW turn compacts normally.
+    // An orphaned start in a closed repaired turn is stale; only the current
+    // turn participates in the in-progress lock.
    const svc = createTestService()
    const s = new Session(SessionId('stale-lock'))
    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
@@ -860,11 +826,8 @@ describe('BasicCompactService HMR safety', () => {
  })

  it('disposing the plugin fiber unregisters ctx.compact', async () => {
-    // Mount through the real plugin fiber (the Loader path), then dispose it and
-    // confirm the service registration is torn down. LlmService is mounted first
-    // so the service's `inject: ['llm']` resolves and the fiber activates. (The
-    // sibling-fiber ctx.llm resolution this same setup also exercises is covered
-    // under the "llm inject (real plugin-load path)" suite.)
+    // Mount through the real plugin fiber (the Loader path), then dispose it and confirm the
+    // service registration is torn down.
    const ctx = new Context()
    await ctx.plugin(LlmService)
    const fiber = await ctx.plugin(BasicCompactService, cfg({ auto: false }))
@@ -1259,11 +1222,8 @@ describe('BasicCompactService auto-compaction (agent/pre-step listener)', () =>

  it('summarization is interceptable at llm/stream (model routing for direct calls)', async () => {
    const { ctx, adapter } = await ctxWithModel('ROUTED SUMMARY', 'routed-model')
-    // The summarize call is a direct one-shot model call, not a loop step: it
-    // does not run agent/request (that seam shapes the loop's conversation
-    // requests). llm/stream is its interception surface, and a hand-built
-    // request is not frozen, so mutate-then-next model routing works — the
-    // adapter resolves AFTER the waterfall, so the rewrite picks the adapter.
+    // One-shot summaries bypass agent/request but remain mutable at llm/stream;
+    // adapter selection happens after the waterfall rewrite.
    ctx.on('llm/stream', (options, next) => {
      options.model = 'routed-model'
      return next()
@@ -1517,19 +1477,13 @@ describe('BasicCompactService edge cases', () => {
    const svc = createTestService()
    const s = new Session(SessionId('empties'))
    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    // Step 1: an empty-text user, an empty-reasoning assistant with NO tool-call
-    // (balanced: nothing to answer), and empty context/steering — all extract to
-    // nothing and are skipped.
    s.append('step/start', { turn: 1, step: 1 })
    s.append('user/message', { content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'reasoning', text: '' }] }, { surfaceOp: 'append' })
    s.append('context/message', { content: [], source: { kind: 'user' } }, { surfaceOp: 'append' })
    s.append('steering/message', { turn: 1, content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
    s.append('step/end', { turn: 1, step: 1 })
-    // Step 2: a tool exchange whose tool/result has empty content → empty
-    // extraction → skipped. The assistant carries the matching tool-call so the
-    // surface stays tool-pairing balanced; its text extracts to the tool-call
-    // placeholder (the one surviving line).
+    // Keep the log pairing-valid while the empty result covers the final message kind.
    s.append('step/start', { turn: 1, step: 2 })
    s.append('assistant/message', {
      turn: 1, step: 2,
@@ -1543,10 +1497,6 @@ describe('BasicCompactService edge cases', () => {

    const nodes = s.surface.nodes
    await compactRegion(svc, s, nodes[0]!.seq, nodes[nodes.length - 1]!.seq, 'm')
-    // Every empty-content message (user text, empty reasoning, empty-content
-    // tool/result, empty context, empty steering) extracted to nothing and was
-    // skipped — the only surviving line is the assistant's tool-call (which a
-    // balanced surface requires to answer the tool/result).
    expect(svc.summarizeCalls[0]!.text).toBe('Assistant: [tool-call: bash({})]')
  })

@@ -1594,40 +1544,26 @@ describe('BasicCompactService edge cases', () => {

 describe('BasicCompactService positional range (surface seqs are not monotonic after a replace)', () => {
  it('compacts a second region after the first replace lands a high-seq summary at the head position', async () => {
-    // A replace inserts the new summary node (a high seq) AT the shadowed
-    // range's surface position, so the surface becomes
-    // [highSeqSummary, …olderRetainedLowerSeqs]. A second compaction over a
-    // range whose start node has a HIGHER seq than its end node must still
-    // succeed — the range is positional, not a numeric seq interval.
+    // Replacement makes surface seqs non-monotonic. The next region is a
+    // positional span even when startSeq > endSeq.
    const svc = createTestService({ auto: false })
    const session = multiTurnSession(4, 1)

-    // First compaction: shadow the two oldest surface nodes.
+    // A replacement puts its high-seq summary at the surface head.
    const nodes0 = session.surface.nodes
    const first = await compactRegion(svc, session, nodes0[0]!.seq, nodes0[1]!.seq, 'm')

-    // The summary node now sits at the head with a seq HIGHER than the
-    // retained older nodes that follow it — the non-monotonic surface. (The
-    // head is the user/message replace node, appended after the compact/summary
-    // provenance event, so its seq is at least first.summarySeq.)
    const nodes1 = session.surface.nodes
    expect(nodes1[0]!.seq).toBeGreaterThanOrEqual(first.summarySeq)
    expect(nodes1[0]!.seq).toBeGreaterThan(nodes1[1]!.seq)

-    // Second compaction: shadow [summary(head) … turn-2's step end]. The start
-    // seq (the head summary node) is GREATER than the end seq (an older retained
-    // node), so the range is a SURFACE-POSITION span, not a numeric seq interval.
-    // The end must land on a step boundary (turn-2's assistant message closes
-    // its step).
    const startSeq = nodes1[0]!.seq
    const endSeq = nodes1[2]!.seq
    expect(startSeq).toBeGreaterThan(endSeq)
    const second = await compactRegion(svc, session, startSeq, endSeq, 'm')

-    // Exactly the three nodes at surface positions [0..2] are shadowed, in
-    // surface order — the positional slice, regardless of their seq values.
+    // Selection follows surface positions, not sequence-number order.
    expect(second.shadowedSeqs).toEqual([nodes1[0]!.seq, nodes1[1]!.seq, nodes1[2]!.seq])
-    // The surface still derives cleanly: a new head replace node + the rest.
    const finalNodes = session.surface.nodes
    expect(finalNodes[0]!.seq).toBeGreaterThanOrEqual(second.summarySeq)
    expect(session.deriveMessages().length).toBe(finalNodes.length)
@@ -1637,20 +1573,15 @@ describe('BasicCompactService positional range (surface seqs are not monotonic a
    const svc = createTestService({ auto: false })
    const session = multiTurnSession(3, 1)

-    // First compaction shadows the oldest two surface nodes, landing a high-seq
-    // summary node at the head.
+    // Put a high-seq summary at the head; log order would place retained older nodes first.
    const n0 = session.surface.nodes
    await compactRegion(svc, session, n0[0]!.seq, n0[1]!.seq, 'm')

-    // Second compaction spans [head summary … turn-2's step end]. The head's seq
-    // is higher than the older retained nodes' seqs, so a log-seq-order walk
-    // would emit the older messages BEFORE the checkpoint.
    const n1 = session.surface.nodes
    svc.summarizeCalls = []
    await compactRegion(svc, session, n1[0]!.seq, n1[2]!.seq, 'm')

-    // The extracted transcript follows surface order: the checkpoint (head)
-    // first, then the older retained messages — matching deriveMessages().
+    // Extraction must match surface and `deriveMessages()` order.
    const { text } = svc.summarizeCalls[0]!
    const checkpointIdx = text.indexOf('compacted-summary')
    const olderIdx = text.indexOf('turn 2 user')
@@ -1661,10 +1592,8 @@ describe('BasicCompactService positional range (surface seqs are not monotonic a

 describe('BasicCompactService llm inject (real plugin-load path)', () => {
  it('declares llm in static inject so a sibling fiber can resolve ctx.llm', () => {
-    // summarize() reads ctx.llm; the inject lets the cordis ctx proxy resolve a
-    // sibling LlmService when this service is mounted as its own plugin fiber.
-    // Asserting the declaration (and exercising the real mount below) guards the
-    // resolution that root-ctx unit tests cannot, since they share one fiber.
+    // summarize() reads ctx.llm; the inject lets the cordis ctx proxy resolve a sibling
+    // LlmService when this service is mounted as its own plugin fiber.
    expect(BasicCompactService.inject).toContain('llm')
  })

--- a/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts
+++ b/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts
@@ -14,24 +14,10 @@ import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
 import type { SurfaceEvent } from '@deepseek-ai/dsh-session'

 /**
- * CBR-001 regression: a compaction checkpoint that the REAL loop lands is a
- * free surface boundary (it carries no tool-call/result pair), so it must be a
- * valid region edge on BOTH sides. A surface-anchored balance check sees that;
- * the abandoned log-position scan did not.
- *
- * The loop fires the compaction seam mid-flight, so the landed checkpoint
- * `user/message{replace}` sits at a HIGH log seq positioned beside the current
- * step even though its SURFACE position is the head. A log-position forward scan
- * from the checkpoint reaches the step's own later `assistant/message` and
- * wrongly reports the checkpoint as mid-step — refusing it as a region end. A
- * SECOND compaction that re-summarizes just that head checkpoint (region end ==
- * checkpoint) therefore throws and is swallowed, so the surface never
- * re-consolidates.
- *
- * This drives a real auto-compaction through the agent-loop and asserts the
- * landed checkpoint balances on both sides AND that re-compacting it (end ==
- * checkpoint) succeeds. RED on the log-position predicates; GREEN once alignment
- * is decided from surface tool-pairing balance.
+ * CBR-001 regression through the real loop. A replacement checkpoint has a high
+ * log seq at the surface head and carries no tool pair, so both adjacent cuts
+ * must be safe and re-compacting that checkpoint alone must succeed. This pins
+ * surface-position semantics rather than raw-log scanning.
 */

 const TOKENS_PER_BLOCK = 10
@@ -132,14 +118,8 @@ describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', ()
      )
      expect(checkpoints.length).toBeGreaterThan(0)

-      // The loop fired compaction mid-flight, so each landed checkpoint sits at a
-      // high log seq beside the step it landed in, even though its SURFACE
-      // position is the head of the range it shadowed. A checkpoint carries no
-      // tool-call/result pair (only summarized prose), so every checkpoint still
-      // on the surface must be a balanced cut on BOTH sides — the cut before it
-      // (region START) and the cut after it (region END). The abandoned
-      // log-position scan reported the END as mis-aligned because the forward log
-      // scan reached the neighbouring step's assistant/message.
+      // High log position does not make a text-only checkpoint mid-step; both
+      // its start and end cuts are balanced in surface order.
      const nodes = agent.session.surface.nodes
      for (const cp of checkpoints) {
        const node = nodes.find(n => n.seq === cp.seq)
--- a/packages/compact/compact/README.md
+++ b/packages/compact/compact/README.md
@@ -7,7 +7,7 @@ This package is the interface tier of the compaction capability, split so each c
 | Package | Role |
 |---|---|
 | `@deepseek-ai/dsh-compact` (this) | the interface: abstract service + `compact/*` events + `CompactionResult` + the shared transcript renderer (`renderTranscript`/`renderContentBlocks`) |
-| `@deepseek-ai/dsh-compact-basic` (deferred) | a backend: chars-per-token estimation (`charsPerToken`, default 4) + token-budget retention + `llm.stream()` summarization |
+| `@deepseek-ai/dsh-compact-basic` | a backend: chars-per-token estimation (`charsPerToken`, default 4) + token-budget retention + `llm.stream()` summarization |
 | `@deepseek-ai/dsh-tool-compact` (deferred) | the model-facing `/compact` tool over `ctx.compact` |

 Unlike the bash seam, this interface depends on `@deepseek-ai/dsh-session` and `@deepseek-ai/dsh-llm` — the contract's verbs are defined over a `Session` and its output is the `ContentBlock` vocabulary, so they cannot be expressed without naming those packages. That deviation from the "interface depends only on cordis" guidance is intentional and recorded in the [compaction capability-seam RFC](../../../docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md).
@@ -48,3 +48,24 @@ The `compact/*` events extend `SessionEventMap` (merge-extensible) via declarati
 ## Implementing a backend

 Subclass `CompactService`, implement `compactIfNeeded` and `compactRegion`, and load the subclass as a plugin — it registers as `ctx.compact`. A tokenizer-, template-, or model-backed implementation can live as a sibling package without changing callers.
+
+## Model Experience
+
+### Conversation history, when a backend is invoked
+
+**What the model sees**: A successful implementation replaces an older surface range with one user-role summary checkpoint; the raw events stay logged but stop appearing in derived model messages. The seam itself performs no rewrite.
+
+**Token effect**: Zero direct tokens from this interface. A backend trades many retained history tokens for one summary and leaves the recent tail unchanged.
+
+### Transcript supplied to a compaction consumer
+
+**What the model sees**: `renderTranscript()` joins entries with one blank line and renders them exactly as `User: <content>`, `Assistant: <content>`, `Tool result (call <callId>): <content>`, `Tool error (call <callId>): <content>`, `[Context: <content>]`, or `[Steering: <content>]`. Non-text blocks render exactly as `[reasoning: <text>]`, `[tool-call: <name>(<arguments>)]`, `[tool-result: <content>]`, `[tool-result]`, or `[<block-type>]`.
+
+**Token effect**: Data-dependent input tokens are paid only by the auxiliary model or consumer that requests this transcript; the conversation model does not receive a duplicate transcript.
+
+## Known Limitations and Deferred Work
+
+- **No model-facing consumer tier yet** — `@deepseek-ai/dsh-tool-compact` (the `/compact` tool) is deferred; compaction is reachable only via direct `ctx.compact` calls or a backend's auto listener.
+- **Single-unit overflow is out of contract** — one retained unit (a closed step or a large pasted `user/message`) alone exceeding the budget cannot be compacted; the call may go out over-budget.
+- **A session prefix that alone approaches the window is a configuration error no backend fixes** — compaction shrinks derived history, never the prefix.
+- **Request context injected by downstream `agent/request` listeners sits outside pressure accounting** — `compactIfNeeded` counts prefix, derived history, and system prompt only.
--- a/packages/compact/compact/package.json
+++ b/packages/compact/compact/package.json
@@ -24,11 +24,11 @@
  "peerDependencies": {
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/compact/compact/src/index.ts
+++ b/packages/compact/compact/src/index.ts
@@ -1,23 +1,9 @@
 /**
- * The compaction service seam (`ctx.compact`): an abstract service defining
- * WHAT compaction does — decide when to compact, summarize a range of
- * conversation history into a single surface node — without saying HOW.
- *
- * Implementations subclass {@link CompactService}, implement
- * {@link CompactService.compactIfNeeded} and {@link CompactService.compactRegion},
- * and load as a plugin — registering as `ctx.compact` (one implementation per
- * context). A tokenizer-, template-, or model-backed implementation can live
- * as a sibling package; callers stay on the same `ctx.compact` seam without
- * touching consumers.
- *
- * The split follows the capability-seams RFC — interface (this) /
- * implementation (deferred) / consumer (a `/compact` tool, deferred) — modeled
- * on the bash trio. Unlike `dsh-bash`, this interface necessarily
- * depends on `dsh-session` and `dsh-llm`: the contract's verbs are defined over
- * a `Session` and its output is the `ContentBlock` vocabulary. That deviation
- * from the "interface depends only on cordis" guidance is intentional and
- * recorded in the [compaction capability-seam RFC](../../../../docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md).
- *
+ * Compaction service seam (`ctx.compact`): implementations decide when to
+ * compact and replace a history range with one summary node by subclassing
+ * {@link CompactService}. This interface necessarily depends on session and LLM
+ * vocabulary; the rationale is in the
+ * [compaction RFC](../../../../docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md).
 * @module @deepseek-ai/dsh-compact
 */

@@ -42,25 +28,10 @@ declare module 'cordis' {
 }

 /**
- * Abstract compaction service. Subclass implement the two abstract methods,
- * and load the subclass as a plugin — it registers as `ctx.compact` (one
- * implementation per context; loading a second throws, which is cordis'
- * standard duplicate-service behavior).
- *
- * Both core methods are abstract: the contract states WHAT compaction does,
- * while the entire strategy — token estimation, retention policy, event
- * sequencing, summarization — is a HOW decision owned by the implementation.
- *
- * Implementations MUST honor:
- * - **Surface contract**: a successful compaction shadows the compacted surface
- *   nodes with a SINGLE replacement node carrying the summary. Because
- *   `SurfaceEventType` is a closed union, that node is a `user/message` with
- *   `surfaceOp: { op:'replace', start, end }`; the `compact/*` events are
- *   log-only (lock + provenance).
- * - **Blocking**: no compaction begins while another is in progress for the
- *   same session. The recommended mechanism is the log-recorded lock — append
- *   `compact/start` before the slow work and `compact/end` after (even on
- *   failure) — so the lock is visible to replay and crash recovery.
+ * Abstract compaction service. Implementations own token estimation, retention,
+ * and summarization, but a successful run must replace the selected surface span
+ * with one summary node and prevent concurrent compaction of the same session.
+ * Load one implementation per context as `ctx.compact`.
 */
 export abstract class CompactService extends Service {
  constructor(ctx: Context) {
@@ -69,43 +40,17 @@ export abstract class CompactService extends Service {

  /**
   * Check token pressure and compact if the conversation is too large.
-   *
-   * Estimates the NEXT request's size — the session prefix, the
-   * surface-derived history, and the system prompt — and if it exceeds the
-   * backend's threshold, compacts an older range
-   * via {@link compactRegion}, keeping recent context intact. Returns `null`
-   * when no compaction is needed.
-   *
-   * Scope and guarantees a backend MUST honor:
-   * - **Compaction acts on surface-derived history only**, but the ESTIMATE
-   *   counts everything the request carries: the loop composes the session
-   *   prefix before the pre-step seam fires and hands it here, so the gate
-   *   sees the prefix this instance will actually send (`EpochHeader.messagePrefix`
-   *   — request-only, never derived history). Non-surface context injected
-   *   downstream (into the request `messages` by a later listener) is out of
-   *   this accounting by construction.
-   * - **Head-anchored, best-effort.** Auto-compaction consolidates from the
-   *   surface HEAD up to a balanced tool-pairing cutoff, so a prior head
-   *   checkpoint is
-   *   re-summarized into one fresh checkpoint (the surface holds at most one
-   *   auto-generated checkpoint, always at the head). It is best-effort over
-   *   CLOSED steps: when the only compactable content left is an un-splittable
-   *   open tail step, it declines (`null`) and retries once that step closes.
-   * - **Single-unit overflow is out of scope.** If a single retained unit (one
-   *   closed step, or a large free node such as a pasted `user/message`) ALONE
-   *   exceeds the budget, compaction cannot help and the call may go out
-   *   over-budget. Bounding an individual unit's size is a separate concern —
-   *   as is a session prefix that alone approaches the window (a
-   *   configuration error no compactor fixes: compaction cannot shrink the
-   *   prefix).
+   * Estimate the next request, including its session prefix, derived history,
+   * and system prompt. Above threshold, compact a head-anchored range ending at
+   * a balanced tool boundary and reconsolidate any prior automatic checkpoint.
+   * Return `null` when no compaction is needed or an open tail leaves no safe
+   * cutoff. A single oversized retained unit or prefix cannot be repaired here.
   *
   * @param agent - agent context owning the session surface and model options.
   * @param fullSystemPrompt - assembled system prompt, counted toward the estimate.
-   * @param sessionPrefix - the instance's composed session prefix, counted toward the estimate.
-   * @param signal - cancellation signal. A backend summarizing via
-   *   `ctx.llm.stream()` MUST forward this into the call's `GenerateOptions.signal`
-   *   so an abort/dispose tears down the in-flight summarization rather than
-   *   leaving an orphaned model call running past the cancellation.
+   * @param sessionPrefix - the instance's composed session prefix, counted toward the
+   *   estimate.
+   * @param signal - cancellation signal; model-backed implementations must forward it.
   * @returns the compaction result, or `null` if no compaction was needed.
   */
  abstract compactIfNeeded(
@@ -117,36 +62,19 @@ export abstract class CompactService extends Service {

  /**
   * Forcibly compact a range of surface nodes into a single summary node.
+   * `start` and `end` name an inclusive span by surface position, not numeric seq
+   * order; replacements can make visible seqs non-monotonic. Both edges must be
+   * balanced so assistant tool calls remain paired with their results. A model-
+   * backed implementation forwards cancellation and rejects active, missing,
+   * reversed, or unbalanced ranges.
   *
-   * `start` and `end` are inclusive seqs of surface nodes to shadow; the backend
-   * summarizes their content and appends a replacement surface node. Used by the
-   * (future) `/compact` tool and internally by {@link compactIfNeeded}.
-   *
-   * The region MUST NOT split a step's `assistant/message` tool-calls from their
-   * `tool/result`s, leaving the rehydrated transcript with a dangling tool-call
-   * or an orphaned tool-result that every provider rejects. A region is safe iff
-   * both its edges are balanced cuts on the surface: the cut before `start` and
-   * the cut after `end` each have no unanswered tool-call before them. A node
-   * that belongs to no step (a pre-step user message, inter-step steering, or an
-   * injection context message) is a balanced (free) boundary; an `end` inside an
-   * open (unclosed) tail step is invalid — its tool-calls have no results yet.
-   * `dsh-session` exports `isToolPairingBalanced` for this check.
-   *
-   * @param session - the session whose surface is mutated.
-   * @param start - inclusive seq of the first surface node to compact.
-   * @param end - inclusive seq of the last surface node to compact.
-   * @param agent - agent context used by router-aware summarizers.
-   * @param signal - optional cancellation signal. A backend that summarizes via
-   *   `ctx.llm.stream()` MUST forward this into the call's `GenerateOptions.signal`
-   *   so an abort/dispose tears down the in-flight summarization rather than
-   *   leaving an orphaned model call running past the cancellation.
-   * @throws if compaction is already in progress, if `start`/`end` are not
-   *   valid surface nodes, if `start` is positioned after `end` on the surface
-   *   (the range is a surface-POSITION span, not a numeric seq interval — a
-   *   prior replace can leave the surface non-monotonic in seq order), or if
-   *   either boundary is not a balanced tool-pairing cut (would split a step's
-   *   tool-call/result pair).
-   * @returns what the compaction did (the replaced range and its summary node).
+   * @param session - session to mutate.
+   * @param start - first surface seq, inclusive.
+   * @param end - last surface seq, inclusive.
+   * @param agent - summarizer context.
+   * @param signal - optional cancellation; model-backed implementations must forward it.
+   * @throws when compaction is active or the range is missing, reversed, or unbalanced.
+   * @returns the replaced range and summary.
   */
  abstract compactRegion(
    session: Session,
--- a/packages/compact/compact/src/render.ts
+++ b/packages/compact/compact/src/render.ts
@@ -1,16 +1,6 @@
 /**
- * Plain-text transcript rendering over session events: the shared projection
- * used wherever a compaction-class consumer needs "what a model once saw" as
- * readable text — a summarizer's input, or a recall tool's output.
- *
- * Extracted from the basic backend's private helpers so the summarize path and
- * the recall read path render one span identically (two renderers would drift,
- * and a recall reader would then see a different transcript than the one the
- * summary was written from). Both functions are pure over their arguments: no
- * session access beyond the provided events, no clock, no randomness — a
- * rendered span is a pure function of the log, so replay reproduces it
- * byte-identically.
- *
+ * Pure shared transcript projection for summarization and recall, so both
+ * render the same log span byte-for-byte under replay.
 * @module @deepseek-ai/dsh-compact/render
 */

@@ -18,14 +8,9 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'

 /**
- * Render content blocks to a single plain-text string. Text and reasoning
- * contribute their text (reasoning wrapped as `[reasoning: …]`); every other
- * block type contributes a type-tagged placeholder (`[tool-call: name(args)]`,
- * `[tool-result: …]`, …) so the reader is told what non-text content existed
- * rather than silently losing it. A `tool-result` block recurses into its
- * nested content (`[tool-result: <inner rendering>]`), falling back to a bare
- * `[tool-result]` when the nested content renders to nothing. Blocks join
- * with newlines; empty-text blocks contribute nothing.
+ * Render text directly, reasoning as a tagged span, and every other block as a
+ * type-tagged placeholder. Tool results recurse into nested content; empty
+ * blocks contribute nothing and rendered blocks join with newlines.
 *
 * @param blocks - the content blocks to render.
 * @returns the newline-joined plain-text rendering; empty string when nothing renders.
@@ -59,17 +44,9 @@ export function renderContentBlocks(blocks: readonly ContentBlock[]): string {
 }

 /**
- * Render a set of surface-node seqs as a `User:`/`Assistant:`/`Tool result:`
- * transcript. Walks `seqs` in the order given — callers pass surface order
- * (e.g. a `compactRegion` slice of the surface-node list), which after a
- * `replace` is NOT ascending log-seq order (a high-seq summary node can sit at
- * the head of the surface before older retained lower-seq nodes); a log-order
- * scan would render the transcript out of order.
- *
- * Only the five surface (message-producing) event types render; a seq naming
- * any other event type contributes nothing. `SessionEventMap` is
- * merge-extensible, so unknown types are simply non-message events with no
- * renderable text.
+ * Render message-producing events as a role-labeled transcript. `seqs` are
+ * walked in caller-supplied surface order, which may differ from numeric log
+ * order after replacement; non-surface and unknown merged events are skipped.
 *
 * @param events - the session log the seqs index into (`session.events`).
 * @param seqs - the surface-node seqs to render, in surface order.
--- a/packages/compact/compact/src/types.ts
+++ b/packages/compact/compact/src/types.ts
@@ -1,17 +1,9 @@
 /**
 * Compaction vocabulary: the result type and the `compact/*` session events.
- *
- * Extends {@link SessionEventMap} with `compact/*` event types via declaration
- * merging. {@link SurfaceEventType} is deliberately NOT extended — `compact/*`
- * events are log-only markers (lock + provenance); only the five
- * surface-eligible types can carry `surfaceOp`. The actual surface mutation is
- * performed by a separate `user/message` event carrying the summary (see the
- * [compaction capability-seam RFC](../../../../docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md)).
- *
- * Configuration lives in the backend, not here: the contract states WHAT
- * compaction produces, while every tunable (context window, thresholds,
- * retention budget) is a HOW decision owned by the implementation.
- *
+ * Those declaration-merged events are log-only lock/provenance markers, not
+ * surface events; a separate replacement `user/message` carries the summary.
+ * Backend packages own configuration and retention policy; see
+ * `docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md`.
 * @module @deepseek-ai/dsh-compact/types
 */

--- a/packages/context/README.md
+++ b/packages/context/README.md
@@ -0,0 +1,7 @@
+# context/ — optional request context
+
+Opt-in plugins that add bounded model-visible request context without defining a tool or service. The default `dsh-agent-core` bundle excludes them.
+
+| Package | Role | ctx key |
+|---|---|---|
+| `time-context/` | Current time and elapsed-time system-prompt context | (none) |
--- a/packages/context/time-context/README.md
+++ b/packages/context/time-context/README.md
@@ -0,0 +1,43 @@
+# @deepseek-ai/dsh-time-context
+
+Opt-in dynamic system-prompt context with the current zoned time and elapsed time since the latest model-visible message before the turn. `dsh-agent-core` and shipped examples do not mount it. Decision record: [the time-context RFC](../../../docs/rfc/implemented/feature/2026-07-14-time-context-plugin.md).
+
+## Config
+
+```yaml
+- id: time-context
+  name: '@deepseek-ai/dsh-time-context'
+  config:
+    timeZone: Asia/Shanghai   # optional IANA override; omit for the process zone
+    refreshIntervalMs: 60000  # default; 0 refreshes on every step
+```
+
+When `timeZone` is omitted, the plugin resolves the Node process's system zone once at plugin load. Node honors `TZ`; without that override, the host or container supplies the zone. An explicit `timeZone` must be an IANA identifier and is validated at plugin load. `refreshIntervalMs` must be a non-negative safe integer. Every turn's first request refreshes; later steps reuse the reading until its age reaches the interval. `0` refreshes every step. Refresh occurs only during request assembly and creates no timer work.
+
+## Message baseline
+
+The duration starts at the latest user, assistant, tool-result, context, or steering message before the current `turn/start`. Every refresh in the turn retains that baseline, so the current prompt does not collapse the interval to approximately zero. The first turn reports that no earlier message exists. The durable clock source is session-event append time, not client send time.
+
+The loop records the dynamic section in `request/header` / `request/header-delta`. Requests therefore remain reconstructable, carry one timing block, and retain no earlier readings in conversation history.
+
+## Model Experience
+
+### Temporal system prompt
+
+**What the model sees**: Every request in an active turn includes the two lines below. `<timestamp>` is an ISO-shaped local timestamp with numeric offset and IANA zone; `<duration-or-unavailable>` is compact whole-second units or the first-turn fallback.
+
+**Token effect**: Fixed two-line cost per request. A refresh replaces the request-header section; prior readings do not accumulate.
+
+#### Temporal context section
+
+```markdown
+Current time: <timestamp>
+Time since previous message: <duration-or-unavailable>.
+```
+
+## Known Limitations and Deferred Work
+
+- **Request-bound refresh only** — no clock update is emitted while the agent is waiting inside a model call or tool; the next assembled step refreshes once the configured interval has elapsed.
+- **Whole-second display** — timestamps and durations omit sub-second precision even when `refreshIntervalMs` is below 1,000.
+- **Session-event baseline** — elapsed time starts from the durable append timestamp, not a client transport's original send timestamp.
+- **Process-local default zone** — omission uses the Node process's `TZ`, host, or container zone captured at plugin load, not a remote user's zone; configure an explicit IANA zone when those differ.
--- a/packages/context/time-context/package.json
+++ b/packages/context/time-context/package.json
@@ -0,0 +1,41 @@
+{
+  "name": "@deepseek-ai/dsh-time-context",
+  "description": "Opt-in system-prompt context with the current time and elapsed time since the previous message",
+  "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-system-prompt": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "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.7"
+  }
+}
--- a/packages/context/time-context/src/index.ts
+++ b/packages/context/time-context/src/index.ts
@@ -0,0 +1,183 @@
+/**
+ * Opt-in request-time clock context. Active turns receive the current zoned
+ * time and elapsed time since the preceding model-visible message. The loop
+ * logs each rendered value as request-header state rather than conversation
+ * history.
+ *
+ * @module @deepseek-ai/dsh-time-context
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { AssembleContext } from '@deepseek-ai/dsh-system-prompt'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'time-context'
+
+/** The system-prompt registry that owns the dynamic request section. */
+export const inject = ['systemPrompt']
+
+/** Request-time clock formatting and refresh policy. Invalid values fail plugin load. */
+export interface Config {
+  /** IANA time zone used for the rendered timestamp. Omit to resolve the Node process's system zone at plugin load. */
+  timeZone?: string
+  /** Maximum age of a reading within one turn, in milliseconds (default 60,000; `0` refreshes every step). */
+  refreshIntervalMs?: number
+}
+
+/** Schemastery validation and defaults for {@link Config}. */
+export const Config: z<Config> = z.object({
+  timeZone: z.string(),
+  refreshIntervalMs: z.number().default(60_000),
+})
+
+interface OpenTurn {
+  turn: number
+  startSeq: number
+}
+
+/** Cached text and the fixed inter-turn baseline used by one agent's open turn. */
+interface RenderState {
+  turn: number
+  renderedAt: number
+  previousMessageTime: number | undefined
+  text: string
+}
+
+type TimestampPart = 'day' | 'hour' | 'minute' | 'month' | 'second' | 'timeZoneName' | 'year'
+
+function openTurn(agent: Agent): OpenTurn | undefined {
+  for (const event of [...agent.session.events].reverse()) {
+    switch (event.type) {
+      case 'turn/end':
+        return undefined
+      case 'turn/start':
+        return { turn: event.data.turn, startSeq: event.seq }
+      default:
+        // Merge-extensible session events: only turn boundaries matter here.
+        break
+    }
+  }
+  return undefined
+}
+
+/** Find the latest model-visible timestamp strictly before one turn boundary. */
+function previousMessageTime(agent: Agent, turnStartSeq: number): number | undefined {
+  for (const event of [...agent.session.events].reverse()) {
+    if (event.seq >= turnStartSeq) continue
+    switch (event.type) {
+      case 'user/message':
+      case 'assistant/message':
+      case 'tool/result':
+      case 'context/message':
+      case 'steering/message':
+        return event.time
+      default:
+        // Merge-extensible session events: non-surface records are not messages.
+        break
+    }
+  }
+  return undefined
+}
+
+/** Format an epoch millisecond value as an ISO-shaped timestamp with offset and IANA zone. */
+function formatTimestamp(now: number, formatter: Intl.DateTimeFormat, timeZone: string): string {
+  const parts = Object.fromEntries(
+    formatter.formatToParts(now).map(part => [part.type, part.value]),
+  ) as Record<TimestampPart, string>
+  const offset = parts.timeZoneName.replace(/^GMT$/, 'GMT+00:00').slice(3)
+  return `${parts['year']}-${parts['month']}-${parts['day']}T${parts['hour']}:${parts['minute']}:${parts['second']}${offset}[${timeZone}]`
+}
+
+/** Format a non-negative elapsed millisecond count as compact whole-second units. */
+function formatDuration(elapsedMs: number): string {
+  let seconds = Math.floor(Math.max(0, elapsedMs) / 1000)
+  const days = Math.floor(seconds / 86_400)
+  seconds %= 86_400
+  const hours = Math.floor(seconds / 3600)
+  seconds %= 3600
+  const minutes = Math.floor(seconds / 60)
+  seconds %= 60
+  const parts: string[] = []
+  if (days > 0) parts.push(`${days}d`)
+  if (hours > 0) parts.push(`${hours}h`)
+  if (minutes > 0) parts.push(`${minutes}m`)
+  parts.push(`${seconds}s`)
+  return parts.join(' ')
+}
+
+function renderText(
+  now: number,
+  previous: number | undefined,
+  formatter: Intl.DateTimeFormat,
+  timeZone: string,
+): string {
+  const elapsed = previous === undefined
+    ? 'unavailable (no earlier message in this session)'
+    : formatDuration(now - previous)
+  return `Current time: ${formatTimestamp(now, formatter, timeZone)}\nTime since previous message: ${elapsed}.`
+}
+
+/**
+ * Register the request-time clock section for the lifetime of `ctx`.
+ * @param ctx - plugin context; the section registration is disposed with it.
+ * @param config - validated time zone and intra-turn refresh interval.
+ * @throws when the time zone or refresh interval is invalid.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const timeZone = config.timeZone
+  const refreshIntervalMs = config.refreshIntervalMs as number
+  if (!Number.isSafeInteger(refreshIntervalMs) || refreshIntervalMs < 0) {
+    throw new Error(`time-context: refreshIntervalMs must be a non-negative safe integer, got ${refreshIntervalMs}`)
+  }
+
+  let formatter: Intl.DateTimeFormat
+  try {
+    formatter = new Intl.DateTimeFormat('en-US', {
+      ...(timeZone === undefined ? {} : { timeZone }),
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      hourCycle: 'h23',
+      timeZoneName: 'longOffset',
+    })
+  } catch (error: unknown) {
+    const message = timeZone === undefined
+      ? 'time-context: failed to resolve the system time zone'
+      : `time-context: invalid IANA timeZone ${JSON.stringify(timeZone)}`
+    throw new Error(message, { cause: error })
+  }
+  const resolvedTimeZone = formatter.resolvedOptions().timeZone
+  const states = new WeakMap<Agent, RenderState>()
+
+  ctx.systemPrompt.section({
+    name: 'context:time',
+    order: 10,
+    text(context: AssembleContext): string {
+      const agent = context.agent
+      if (agent === undefined) return ''
+      const currentTurn = openTurn(agent)
+      if (currentTurn === undefined) return ''
+
+      const now = Date.now()
+      const prior = states.get(agent)
+      if (prior !== undefined
+        && prior.turn === currentTurn.turn
+        && now >= prior.renderedAt
+        && now - prior.renderedAt < refreshIntervalMs) {
+        return prior.text
+      }
+
+      const previous = prior?.turn === currentTurn.turn
+        ? prior.previousMessageTime
+        : previousMessageTime(agent, currentTurn.startSeq)
+      const text = renderText(now, previous, formatter, resolvedTimeZone)
+      states.set(agent, { turn: currentTurn.turn, renderedAt: now, previousMessageTime: previous, text })
+      return text
+    },
+  })
+}
--- a/packages/context/time-context/tests/fixtures/cordis.yml
+++ b/packages/context/time-context/tests/fixtures/cordis.yml
@@ -0,0 +1,17 @@
+# Test-only composition: keep time-context opt-in while exercising its real Loader/app path.
+- id: mock-llm
+  name: '../../../../../examples/echo-agent/src/mock-llm.ts'
+
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+
+- id: time-context
+  name: '@deepseek-ai/dsh-time-context'
+
+- id: stdio-agent
+  name: '@deepseek-ai/dsh-stdio-agent'
+  config:
+    model: mock-echo
+    persona: 'Test the time-context plugin.'
+    welcome: 'time-context e2e ready.'
+    persistenceRoot: './.sessions'
--- a/packages/context/time-context/tests/time-context.e2e.ts
+++ b/packages/context/time-context/tests/time-context.e2e.ts
@@ -0,0 +1,115 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import { foldRequestHeader, type SessionEvent } from '@deepseek-ai/dsh-session'
+
+const binScript = fileURLToPath(new URL('../../../ui/stdio-agent/src/bin.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('./fixtures/cordis.yml', import.meta.url))
+const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
+const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
+const PROCESS_TIMEOUT_MS = 30_000
+const TEST_TIMEOUT_MS = PROCESS_TIMEOUT_MS + 15_000
+const FIRST_REPLY = 'You said: "first". Try "echo <something>" to see a tool call.'
+
+let child: ChildProcessWithoutNullStreams | undefined
+let workdir: string | undefined
+
+afterEach(async () => {
+  if (child !== undefined && child.exitCode === null) child.kill('SIGKILL')
+  child = undefined
+  if (workdir !== undefined) await rm(workdir, { recursive: true, force: true })
+  workdir = undefined
+})
+
+async function jsonlFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+  const paths = await Promise.all(entries.map(async (entry) => {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) return jsonlFiles(path)
+    return entry.isFile() && entry.name.endsWith('.jsonl') ? [path] : []
+  }))
+  return paths.flat()
+}
+
+async function runTwoTurns(): Promise<{ stdout: string; stderr: string }> {
+  workdir = await mkdtemp(join(tmpdir(), 'time-context-e2e-'))
+  const cwd = workdir
+  return new Promise((resolve, reject) => {
+    const proc = spawn(
+      process.execPath,
+      ['--expose-internals', '--import', tsxLoader, binScript, configPath],
+      {
+        cwd,
+        env: {
+          ...process.env,
+          TZ: 'Asia/Shanghai',
+          TSX_TSCONFIG_PATH: repoTsconfig,
+          DSH_HOME: join(cwd, '.dsh'),
+          DSH_AGENTS_HOME: join(cwd, '.agents'),
+        },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      },
+    )
+    child = proc
+    let stdout = ''
+    let stderr = ''
+    let sentSecond = false
+    proc.stdout.setEncoding('utf8')
+    proc.stdout.on('data', (chunk: string) => {
+      stdout += chunk
+      if (!sentSecond && stdout.includes(`${FIRST_REPLY}\n> `)) {
+        sentSecond = true
+        proc.stdin.end('second\n')
+      }
+    })
+    proc.stderr.setEncoding('utf8')
+    proc.stderr.on('data', (chunk: string) => { stderr += chunk })
+
+    const timer = setTimeout(() => {
+      proc.kill('SIGKILL')
+      reject(new Error(`time-context e2e did not exit within ${PROCESS_TIMEOUT_MS / 1_000}s. stdout:\n${stdout}\nstderr:\n${stderr}`))
+    }, PROCESS_TIMEOUT_MS)
+
+    proc.on('exit', (code) => {
+      clearTimeout(timer)
+      if (code === 0) resolve({ stdout, stderr })
+      else reject(new Error(`time-context e2e exited ${code}. stdout:\n${stdout}\nstderr:\n${stderr}`))
+    })
+    proc.on('error', (error) => { clearTimeout(timer); reject(error) })
+    proc.stdin.write('first\n')
+  })
+}
+
+describe('time-context through a real cordis.yml and stdio process', () => {
+  it('uses the process zone and persists both first-turn and elapsed-time request context', async () => {
+    const { stdout, stderr } = await runTwoTurns()
+    expect(stderr).not.toContain('UNHANDLED')
+    expect(stdout).toContain('time-context e2e ready.')
+    expect(stdout).toContain(FIRST_REPLY)
+    expect(stdout).toContain('You said: "second".')
+
+    const logs = await jsonlFiles(join(workdir as string, '.sessions'))
+    expect(logs).toHaveLength(1)
+    const lines = (await readFile(logs[0] as string, 'utf8')).trimEnd().split('\n')
+    const events = lines.slice(1).map(line => JSON.parse(line) as SessionEvent)
+    expect(events.filter(event => event.type === 'turn/end')).toHaveLength(2)
+
+    const firstHeader = events.find(event => event.type === 'request/header')
+    if (firstHeader?.type !== 'request/header') throw new Error('missing initial request/header event')
+    expect(firstHeader.data.header.system).toMatch(
+      /Current time: \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+08:00\[Asia\/Shanghai\]/,
+    )
+    expect(firstHeader.data.header.system).toContain(
+      'Time since previous message: unavailable (no earlier message in this session).',
+    )
+
+    const finalSystem = foldRequestHeader(events)?.system
+    expect(finalSystem).toContain('[Asia/Shanghai]')
+    expect(finalSystem).toMatch(
+      /Time since previous message: (?:\d+d )?(?:\d+h )?(?:\d+m )?\d+s\./,
+    )
+  }, TEST_TIMEOUT_MS)
+})
--- a/packages/context/time-context/tests/time-context.spec.ts
+++ b/packages/context/time-context/tests/time-context.spec.ts
@@ -0,0 +1,371 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import LlmService, { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import SessionStore, { Session, SessionId, foldRequestHeader } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import * as timeContext from '@deepseek-ai/dsh-time-context'
+import type { Config } from '@deepseek-ai/dsh-time-context'
+
+const BASE = Date.parse('2026-07-14T00:00:00.000Z')
+const ORIGINAL_TIME_ZONE = process.env['TZ']
+
+beforeEach(() => {
+  process.env['TZ'] = 'UTC'
+  vi.useFakeTimers()
+  vi.setSystemTime(BASE)
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.useRealTimers()
+  if (ORIGINAL_TIME_ZONE === undefined) delete process.env['TZ']
+  else process.env['TZ'] = ORIGINAL_TIME_ZONE
+})
+
+async function mount(config: Config = {}) {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  const fiber = await ctx.plugin(timeContext, config)
+  return { ctx, fiber }
+}
+
+function sessionAgent(session: Session, id = 'agent'): Agent {
+  return { id: AgentId(id), session } as unknown as Agent
+}
+
+async function sectionText(ctx: Context, agent?: Agent): Promise<string | undefined> {
+  const assembly = await ctx.systemPrompt.assemble(agent === undefined ? {} : { agent })
+  return assembly.sections.find(section => section.name === 'context:time')?.text
+}
+
+function openMessageTurn(session: Session, turn: number): void {
+  session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } })
+  session.append('user/message', {
+    content: [{ type: 'text', text: `turn ${turn}` }],
+    source: { kind: 'user' },
+  }, { surfaceOp: 'append' })
+}
+
+function textResponse(text: string): StreamChunk[] {
+  return [
+    { type: 'block-start', index: 0, blockType: 'text' },
+    { type: 'block-end', index: 0, block: { type: 'text', text } },
+    { type: 'finish', reason: { kind: 'stop' } },
+  ]
+}
+
+function toolCallResponse(): StreamChunk[] {
+  return [
+    { type: 'block-start', index: 0, blockType: 'tool-call' },
+    {
+      type: 'block-end',
+      index: 0,
+      block: { type: 'tool-call', id: CallId('tick-1'), name: 'tick', arguments: '{}' },
+    },
+    { type: 'finish', reason: { kind: 'tool-calls' } },
+  ]
+}
+
+class ScriptedAdapter extends LlmAdapter {
+  readonly requests: GenerateOptions[] = []
+
+  constructor(private readonly script: StreamChunk[][]) {
+    super()
+  }
+
+  override async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    this.requests.push(options)
+    const chunks = this.script.shift()
+    if (chunks === undefined) throw new Error('ScriptedAdapter: script exhausted')
+    for (const chunk of chunks) yield chunk
+  }
+}
+
+async function loopHarness(adapter: ScriptedAdapter, 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(timeContext, config)
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return ctx
+}
+
+describe('temporal section rendering', () => {
+  it('renders the first turn in UTC with the explicit no-previous-message fallback', async () => {
+    const { ctx } = await mount()
+    const session = new Session(SessionId('first'))
+    openMessageTurn(session, 1)
+
+    expect(await sectionText(ctx, sessionAgent(session))).toBe(
+      'Current time: 2026-07-14T00:00:00+00:00[UTC]\n'
+      + 'Time since previous message: unavailable (no earlier message in this session).',
+    )
+  })
+
+  it('renders a non-UTC numeric offset and all compact duration units', async () => {
+    const { ctx } = await mount({ timeZone: 'Asia/Shanghai' })
+    const session = new Session(SessionId('offset'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      content: [{ type: 'text', text: 'previous' }],
+    }, { surfaceOp: 'append' })
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    vi.setSystemTime(BASE + 90_061_000)
+    openMessageTurn(session, 2)
+
+    expect(await sectionText(ctx, sessionAgent(session))).toBe(
+      'Current time: 2026-07-15T09:01:01+08:00[Asia/Shanghai]\n'
+      + 'Time since previous message: 1d 1h 1m 1s.',
+    )
+  })
+
+  it('clamps a backward wall-clock adjustment to a zero duration', async () => {
+    const { ctx } = await mount()
+    const session = new Session(SessionId('backward-duration'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      content: [{ type: 'text', text: 'future by adjusted clock' }],
+    }, { surfaceOp: 'append' })
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    vi.setSystemTime(BASE - 5_000)
+    openMessageTurn(session, 2)
+
+    expect(await sectionText(ctx, sessionAgent(session))).toContain('Time since previous message: 0s.')
+  })
+
+  const previousMessageCases = [
+    ['user/message', (session: Session): void => {
+      session.append('user/message', { content: [{ type: 'text', text: 'u' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    }],
+    ['assistant/message', (session: Session): void => {
+      session.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'a' }] }, { surfaceOp: 'append' })
+    }],
+    ['tool/result', (session: Session): void => {
+      session.append('tool/result', {
+        turn: 1,
+        step: 1,
+        callId: CallId('previous'),
+        content: [{ type: 'text', text: 'r' }],
+        isError: false,
+      }, { surfaceOp: 'append' })
+    }],
+    ['context/message', (session: Session): void => {
+      session.append('context/message', {
+        content: [{ type: 'text', text: 'c' }],
+        source: { kind: 'plugin', plugin: 'test' },
+      }, { surfaceOp: 'append' })
+    }],
+    ['steering/message', (session: Session): void => {
+      session.append('steering/message', {
+        turn: 1,
+        content: [{ type: 'text', text: 's' }],
+        source: { kind: 'user' },
+      }, { surfaceOp: 'append' })
+    }],
+  ] as const
+
+  it.each(previousMessageCases)('uses a prior %s as the duration baseline', async (_name, appendPrevious) => {
+    const { ctx } = await mount()
+    const session = new Session(SessionId(`previous-${_name}`))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    appendPrevious(session)
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    vi.setSystemTime(BASE + 5_000)
+    openMessageTurn(session, 2)
+
+    expect(await sectionText(ctx, sessionAgent(session))).toContain('Time since previous message: 5s.')
+  })
+
+  it('contributes empty text without an active agent turn', async () => {
+    const { ctx } = await mount()
+    expect(await sectionText(ctx)).toBe('')
+
+    const empty = sessionAgent(new Session(SessionId('empty')))
+    expect(await sectionText(ctx, empty)).toBe('')
+
+    const closedSession = new Session(SessionId('closed'))
+    openMessageTurn(closedSession, 1)
+    closedSession.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    expect(await sectionText(ctx, sessionAgent(closedSession))).toBe('')
+  })
+})
+
+describe('refresh policy', () => {
+  it('reuses within the interval, refreshes at expiry, and refreshes after a backward clock jump', async () => {
+    const { ctx } = await mount({ refreshIntervalMs: 60_000 })
+    const session = new Session(SessionId('interval'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session, 1)
+
+    const first = await sectionText(ctx, agent)
+    vi.setSystemTime(BASE + 30_000)
+    expect(await sectionText(ctx, agent)).toBe(first)
+    vi.setSystemTime(BASE + 60_000)
+    const expired = await sectionText(ctx, agent)
+    expect(expired).toContain('2026-07-14T00:01:00+00:00[UTC]')
+    vi.setSystemTime(BASE + 59_000)
+    expect(await sectionText(ctx, agent)).toContain('2026-07-14T00:00:59+00:00[UTC]')
+  })
+
+  it('refreshes every assembly when refreshIntervalMs is zero', async () => {
+    const { ctx } = await mount({ refreshIntervalMs: 0 })
+    const session = new Session(SessionId('every-step'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session, 1)
+    const first = await sectionText(ctx, agent)
+    vi.setSystemTime(BASE + 1_000)
+    expect(await sectionText(ctx, agent)).not.toBe(first)
+  })
+
+  it('always refreshes for a new turn and keeps the preceding message baseline', async () => {
+    const { ctx } = await mount({ refreshIntervalMs: 60_000 })
+    const session = new Session(SessionId('turn-refresh'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session, 1)
+    const first = await sectionText(ctx, agent)
+    vi.setSystemTime(BASE + 1_000)
+    session.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      content: [{ type: 'text', text: 'done' }],
+    }, { surfaceOp: 'append' })
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    vi.setSystemTime(BASE + 2_000)
+    openMessageTurn(session, 2)
+
+    const second = await sectionText(ctx, agent)
+    expect(second).not.toBe(first)
+    expect(second).toContain('Time since previous message: 1s.')
+  })
+
+  it('keeps refresh caches independent per agent', async () => {
+    const { ctx } = await mount({ refreshIntervalMs: 60_000 })
+    const sessionA = new Session(SessionId('agent-a'))
+    const sessionB = new Session(SessionId('agent-b'))
+    const agentA = sessionAgent(sessionA, 'a')
+    const agentB = sessionAgent(sessionB, 'b')
+    openMessageTurn(sessionA, 1)
+    openMessageTurn(sessionB, 1)
+    const aFirst = await sectionText(ctx, agentA)
+    vi.setSystemTime(BASE + 30_000)
+    const bFirst = await sectionText(ctx, agentB)
+    vi.setSystemTime(BASE + 40_000)
+
+    expect(await sectionText(ctx, agentA)).toBe(aFirst)
+    expect(bFirst).toContain('2026-07-14T00:00:30+00:00[UTC]')
+  })
+})
+
+describe('configuration and lifecycle', () => {
+  it('defaults to the process system zone and retains the zone resolved at plugin load', async () => {
+    process.env['TZ'] = 'Asia/Shanghai'
+    const { ctx } = await mount()
+    process.env['TZ'] = 'America/New_York'
+    const session = new Session(SessionId('system-zone'))
+    openMessageTurn(session, 1)
+
+    expect(await sectionText(ctx, sessionAgent(session))).toContain(
+      'Current time: 2026-07-14T08:00:00+08:00[Asia/Shanghai]',
+    )
+  })
+
+  it('fails loud for negative, fractional, unsafe, and invalid-zone config', async () => {
+    for (const refreshIntervalMs of [-1, 1.5, Number.MAX_SAFE_INTEGER + 1]) {
+      const ctx = new Context()
+      await ctx.plugin(SystemPrompt)
+      await expect(ctx.plugin(timeContext, { refreshIntervalMs })).rejects.toThrow(/non-negative safe integer/)
+    }
+
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await expect(ctx.plugin(timeContext, { timeZone: 'Not/A_Real_Zone' })).rejects.toThrow(/invalid IANA timeZone/)
+  })
+
+  it('fails loud when the process system zone cannot be resolved', async () => {
+    vi.spyOn(Intl, 'DateTimeFormat').mockImplementationOnce(() => {
+      throw new RangeError('system zone unavailable')
+    })
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+
+    await expect(ctx.plugin(timeContext, {})).rejects.toThrow(/failed to resolve the system time zone/)
+  })
+
+  it('removes its section when the plugin fiber disposes', async () => {
+    const { ctx, fiber } = await mount()
+    const session = new Session(SessionId('dispose'))
+    const agent = sessionAgent(session)
+    openMessageTurn(session, 1)
+    expect(await sectionText(ctx, agent)).toContain('Current time:')
+
+    await fiber.dispose()
+    expect(await sectionText(ctx, agent)).toBeUndefined()
+  })
+})
+
+describe('real agent-loop request logging', () => {
+  it('refreshes a long turn in the system prompt and records the header delta without context history', async () => {
+    const adapter = new ScriptedAdapter([toolCallResponse(), textResponse('done'), textResponse('next turn')])
+    const ctx = await loopHarness(adapter, { refreshIntervalMs: 60_000 })
+    ctx.tools.register(defineTool({
+      name: 'tick',
+      description: 'advance fake time',
+      parameters: {},
+      async execute() {
+        vi.setSystemTime(BASE + 61_000)
+        return [{ type: 'text' as const, text: 'advanced' }]
+      },
+    }))
+    const agent = ctx.agentLoop.create(AgentId('loop'), { model: 'mock' })
+
+    agent.send([{ type: 'text', text: 'start' }])
+    await agent.whenIdle()
+    expect(adapter.requests).toHaveLength(2)
+    expect(adapter.requests[0]!.system).toContain('2026-07-14T00:00:00+00:00[UTC]')
+    expect(adapter.requests[1]!.system).toContain('2026-07-14T00:01:01+00:00[UTC]')
+    expect(agent.session.events.some(event => event.type === 'context/message')).toBe(false)
+    expect(agent.session.events.filter(event => event.type === 'request/header-delta')).toHaveLength(1)
+    expect(foldRequestHeader(agent.session.events)?.system).toBe(adapter.requests[1]!.system)
+
+    vi.setSystemTime(BASE + 361_000)
+    agent.send([{ type: 'text', text: 'again' }])
+    await agent.whenIdle()
+    expect(adapter.requests[2]!.system).toContain('Time since previous message: 5m 0s.')
+    await ctx.fiber.dispose()
+  })
+})
+
+describe('real Loader export path', () => {
+  it('keeps the namespace metadata and boots through unwrapExports', async () => {
+    expect('default' in timeContext).toBe(false)
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(timeContext) as Record<string, unknown>
+    expect(unwrapped).toBe(timeContext)
+    expect(unwrapped.name).toBe('time-context')
+    expect(unwrapped.inject).toEqual(['systemPrompt'])
+    expect(unwrapped.Config).toBeDefined()
+    expect(typeof unwrapped.apply).toBe('function')
+
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    const plugin = loader.unwrapExports(timeContext) as Parameters<Context['plugin']>[0]
+    await ctx.plugin(plugin)
+    const session = new Session(SessionId('loader'))
+    openMessageTurn(session, 1)
+    expect(await sectionText(ctx, sessionAgent(session))).toContain('Current time:')
+  })
+})
--- a/packages/context/time-context/tsconfig.json
+++ b/packages/context/time-context/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../core/system-prompt" },
+    { "path": "../../core/agent" }
+  ]
+}
--- a/packages/cordis/tool-cordis/README.md
+++ b/packages/cordis/tool-cordis/README.md
@@ -12,7 +12,7 @@ Exact model-facing schemas: [the generated tool catalog](../../../docs/tool-cata

 ## Trust stance

-The sandbox isolates the global context only — it is not a security boundary. No Node API is provided: `require`, the timers, and `fetch` are callable traps that throw a redirect to the cordis alternative (`ctx.fs` / `ctx.web` / `ctx.bash` / `inject: ['timer']` + `ctx.setTimeout`); `process` and `Buffer` are `undefined`; `globalThis` writes stay inside. These traps steer honest code onto the cordis services; they do not contain a mount that goes looking — the host-realm helpers on the sandbox global (`harness`, `console`, `btoa`) are reachable functions, so mount code can reach the host realm and Node through one of them, which is fine because `ctx` is fully privileged anyway. The `ctx` a mounted plugin's `apply` receives is a whitelist façade — register tools, observe events, provide/consume services, use timers; framework internals (`ctx.root`, `ctx.fiber`, `ctx.extend`, `ctx.plugin`, …) are withheld — but the capabilities it does expose reach the real runtime, so load this plugin as deliberately as you would grant a bash tool.
+The sandbox isolates globals but is not a security boundary. Node globals are absent or redirect to Cordis services such as `ctx.fs`, `ctx.web`, and `ctx.bash`, and writes to `globalThis` stay local, but host-realm helpers make escape possible. Mounted plugins receive a façade without framework internals, yet its allowed services affect the live runtime. Treat this toolset like bash access; see the [design and trust stance](../../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).

 ## Config

@@ -31,3 +31,29 @@ All three tools render `generic` cards (`read` / `execute` / `delete`); `cordis_
 ## Export shape

 Namespace plugin: named exports `name` / `inject` / `Config` / `apply`, no default export ([docs/postmortem/0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)).
+
+## Model Experience
+
+### Tool schemas
+
+**What the model sees**: The conversation model sees the generated [`cordis_inspect`, `cordis_mount`, and `cordis_unmount` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-cordis) whenever this plugin is visible.
+
+**Token effect**: Fixed schema cost on every request in that tool view.
+
+### Tool-call history and results
+
+**What the model sees**: Inspect joins selected sections exactly as `## <section>` then a newline and the data-dependent body, with one blank line between sections. Mount returns `mounted <id> (plugin "<name>", state: <state>)`, optionally inserting ` — waiting for service(s): <names> (activates when provided)` before the closing parenthesis. Unmount returns `unmounted <id> (plugin "<name>")`; an unknown id becomes `Error: no dynamic plugin with id "<id>" (list mounts with cordis_inspect what:"dynamic")`. The submitted mount program remains in the assistant tool-call history.
+
+**Token effect**: Inspect output and mount code are data-dependent and resent until compaction; lifecycle acknowledgements are small.
+
+### Later requests after a mount
+
+**What the model sees**: A mounted plugin may register tools, prompt contributions, or listeners that change later requests for the scopes it targets; unmount removes those contributions after quiescence.
+
+**Token effect**: Indirect token impact equals the mounted plugin's contributions and lasts only for the mount lifetime.
+
+## Known Limitations and Deferred Work
+
+- **The sandbox is containment for honest code, not a security boundary** — host-realm helpers on the sandbox global are reachable, so mount code can reach Node; load this plugin as deliberately as you would grant a bash tool (see § Trust stance).
+- **The `ctx` façade exposes no `effect()`** — mount code cannot register a bespoke disposer; `on`/`provide`/`tools.register` cover every mount seen so far, and a guarded `effect` waits on a real need (`FIXME(sandbox-effect)`).
+- **`vmTimeoutMs` bounds only synchronous evaluation** — an async mount body escapes it; there is no async budget on mount code.
--- a/packages/cordis/tool-cordis/package.json
+++ b/packages/cordis/tool-cordis/package.json
@@ -24,7 +24,7 @@
  "peerDependencies": {
    "@deepseek-ai/dsh-scope": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  },
  "dependencies": {
    "schemastery": "^3.18.0"
@@ -37,8 +37,8 @@
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
-    "@cordisjs/plugin-loader": "^1.0.0-rc.4",
-    "cordis": "^4.0.0-rc.6",
+    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
+    "cordis": "^4.0.0-rc.7",
    "@cordisjs/plugin-timer": "workspace:^"
  }
 }
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -77,14 +77,14 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
  },
  {
    key: 'approval',
-    summary: 'The `ctx.approval` service: dispatches ApprovalRequests to the `approval/request` waterfall and audits every ask/outcome pair to the requesting agent\'s session log.',
+    summary: 'Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session.',
    methods: [
      'async request(req: ApprovalRequest): Promise<ApprovalOutcome>',
    ],
  },
  {
    key: 'bash',
-    summary: 'Abstract bash execution service.',
+    summary: 'Registers one `ctx.bash` implementation.',
    methods: [
      'abstract resolve(request: BashExecRequest): BashExecSpec',
      'abstract run(spec: BashExecSpec): Promise<BashRunResult>',
@@ -99,7 +99,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
  },
  {
    key: 'codeRuntime',
-    summary: 'Abstract code-execution service.',
+    summary: 'Registers one `ctx.codeRuntime` implementation.',
    methods: [
      'abstract run(request: CodeRunRequest): Promise<CodeRunResult>',
    ],
@@ -114,7 +114,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
  },
  {
    key: 'fs',
-    summary: 'Abstract filesystem provider service.',
+    summary: 'Abstract filesystem provider.',
    methods: [
      'abstract resolve(path: string, opts?: { cwd?: string }): Promise<FsTarget>',
      'abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>',
@@ -134,6 +134,16 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
      'stream(options: GenerateOptions): AsyncIterable<StreamChunk>',
    ],
  },
+  {
+    key: 'permission',
+    summary: 'Owns the deployment\'s permission presets and their write path.',
+    methods: [
+      'current(events: readonly SessionEvent[]): string',
+      'resolve(name: string): PresetSpec',
+      'optionOf(name: string): PresetOption',
+      'set(session: Session, name: string): void',
+    ],
+  },
  {
    key: 'sandbox',
    summary: 'Abstract process-sandbox service.',
@@ -143,7 +153,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
  },
  {
    key: 'sessionPersistence',
-    summary: 'Abstract durable session-persistence service.',
+    summary: 'Durable append-only session storage.',
    methods: [
      'abstract create(meta: SessionHeader): Promise<void>',
      'abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>',
@@ -207,7 +217,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
  },
  {
    key: 'systemPrompt',
-    summary: 'Registry service (`ctx.systemPrompt`): plugins contribute ordered text sections, tool-schema providers, and named prompt variables; the agent loop calls `assemble(context)` once per step.',
+    summary: 'Registry service for the prompt inputs assembled before each model step.',
    methods: [
      'section(section: PromptSection): () => void',
      'tools(provider: (context: AssembleContext) => ToolProviderResult): () => void',
@@ -217,7 +227,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
  },
  {
    key: 'tools',
-    summary: 'Tool registry (`ctx.tools`): tool plugins register definitions; the agent loop executes calls through the `tools/pre-execute` → guards → `tools/execute` → `tools/post-execute` → `tools/result` pipeline.',
+    summary: 'Tool registry and execution pipeline.',
    methods: [
      'register(definition: ToolDefinition): () => void',
      'restrict(filter: ToolRestriction): () => void',
@@ -241,13 +251,13 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
    methods: [
      'registerSearchProvider(provider: WebSearchProvider): () => void',
      'registerFetchProvider(provider: WebFetchProvider): () => void',
-      'async search(request: WebSearchRequest, exec?: WebExecContext): Promise<WebSearchResult>',
-      'async fetch(request: WebFetchRequest, exec?: WebExecContext): Promise<WebFetchResult>',
+      'async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>',
+      'async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>',
    ],
  },
  {
    key: 'workflows',
-    summary: 'Abstract workflow execution service.',
+    summary: 'Workflow execution seam.',
    methods: [
      'abstract start(request: WorkflowStartRequest): WorkflowRun',
    ],
@@ -260,13 +270,13 @@ export const EVENT_API: readonly EventApiEntry[] = [
    name: 'agent/created',
    mode: 'emit',
    signature: '\'agent/created\'(this: Scoped<Agent>, agent: Agent): void',
-    summary: 'An agent\'s fully composed scoped world was published in the AgentRegistry.',
+    summary: 'A fully configured agent and live session were published.',
  },
  {
    name: 'agent/disposed',
    mode: 'emit',
    signature: '\'agent/disposed\'(this: Scoped<Agent>, agent: Agent): void',
-    summary: 'An agent was removed from the registry.',
+    summary: 'An agent left the registry; AgentLoop emits this after driver quiescence but before session detachment and scoped-registration unwind.',
  },
  {
    name: 'agent/error',
@@ -278,37 +288,37 @@ export const EVENT_API: readonly EventApiEntry[] = [
    name: 'agent/pre-step',
    mode: 'serial',
    signature: '\'agent/pre-step\'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise<void> | void',
-    summary: 'Awaited pre-step surface-mutation checkpoint, fired once per step AFTER `turn/start` (and after the prior step closed) but BEFORE this step\'s `step/start` — so anything a listener appends lands OUTSIDE the step, between `turn/start`/`step/end` and the upcoming `step/start`.',
+    summary: 'Awaited serial checkpoint for session-surface mutation after prompt assembly and before `step/start`; appends land outside the pending step.',
  },
  {
    name: 'agent/prompt-submit',
    mode: 'waterfall',
    signature: '\'agent/prompt-submit\'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise<PromptDecision>): Promise<PromptDecision>',
-    summary: 'Waterfall: decide what happens to ONE drained queued message before it becomes a `user/message` — allow (optionally rewriting the prompt bytes or attaching `additionalContext`) or block it.',
+    summary: 'Allow, rewrite, or block one drained prompt before it becomes a user message.',
  },
  {
    name: 'agent/queued',
    mode: 'emit',
    signature: '\'agent/queued\'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], info: { source: MessageSource; steering: boolean }): void',
-    summary: 'A message entered the agent\'s inbox (queued or steering).',
+    summary: 'Detached, frozen content entered the agent\'s inbox.',
  },
  {
    name: 'agent/request',
    mode: 'waterfall',
    signature: '\'agent/request\'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>',
-    summary: 'Waterfall: shape the step\'s call configuration — model switching, sampling overrides — by returning a replacement LlmCallConfig (the frozen seed is the config the loop would otherwise use).',
+    summary: 'Replace the frozen call configuration.',
  },
  {
    name: 'agent/session-prefix',
    mode: 'waterfall',
    signature: '\'agent/session-prefix\'(this: Scoped<Agent>, agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise<Message[]>): Promise<Message[]>',
-    summary: 'Waterfall: compose the SESSION PREFIX — request-only messages placed in front of the ENTIRE derived history (directly after the provider\'s system slot) on every request this loop instance sends.',
+    summary: 'Compose request-only messages placed before derived history.',
  },
  {
    name: 'agent/session-start',
    mode: 'emit',
    signature: '\'agent/session-start\'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void',
-    summary: 'The agent\'s session lifecycle began, fired once before its first turn.',
+    summary: 'The session lifecycle began, once before the first turn.',
  },
  {
    name: 'agent/status',
@@ -326,37 +336,37 @@ export const EVENT_API: readonly EventApiEntry[] = [
    name: 'agent/turn-continuation',
    mode: 'waterfall',
    signature: '\'agent/turn-continuation\'(this: Scoped<Agent>, agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise<ContinuationDecision>): Promise<ContinuationDecision>',
-    summary: 'Waterfall: override the turn-continuation decision via a typed ContinuationDecision.',
+    summary: 'Override whether the turn continues.',
  },
  {
    name: 'agent/turn-stop',
    mode: 'serial',
    signature: '\'agent/turn-stop\'(this: Scoped<Agent>, agent: Agent, turn: number): ContinuationStop | undefined',
-    summary: 'Serial terminal-stop checkpoint after the ordinary `agent/turn-continuation` waterfall, any `continue.reason`, and the pending-steering continuation override have been folded.',
+    summary: 'Monotonic terminal-stop checkpoint after continuation and steering are folded; a stop remains authoritative through turn close and flush: steering queued in that window is discarded, while ordinary sends survive.',
  },
  {
    name: 'approval/request',
    mode: 'waterfall',
    signature: '\'approval/request\'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>',
-    summary: 'Waterfall asking the composed answerers to decide one approval request.',
+    summary: 'Ask composed answerers for one decision.',
  },
  {
    name: 'fs/edit-intent',
    mode: 'waterfall',
    signature: '\'fs/edit-intent\'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>',
-    summary: 'Single-slot decision: produce the optional version guard for the next FileSystem.editText.',
+    summary: 'Single-slot decision for the next FileSystem.editText.',
  },
  {
    name: 'fs/observed',
    mode: 'emit',
    signature: '\'fs/observed\'(target: FsTarget, version: FsVersion, actor: object | undefined): void',
-    summary: 'Record that an actor observed a target at a version, after a successful read/write/edit.',
+    summary: 'Record a successful observation.',
  },
  {
    name: 'fs/write-intent',
    mode: 'waterfall',
    signature: '\'fs/write-intent\'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>',
-    summary: 'Single-slot decision: produce the write intent for the next FileSystem.writeText.',
+    summary: 'Single-slot decision for the next FileSystem.writeText.',
  },
  {
    name: 'llm/stream',
@@ -368,37 +378,25 @@ export const EVENT_API: readonly EventApiEntry[] = [
    name: 'session/created',
    mode: 'emit',
    signature: '\'session/created\'(this: Scoped<Session>, session: Session): void',
-    summary: 'A session was created in the store.',
+    summary: 'Creation announcement during session publication.',
  },
  {
    name: 'session/disposed',
    mode: 'emit',
    signature: '\'session/disposed\'(this: Scoped<Session>, session: Session): void',
-    summary: 'A previously announced session left the store.',
+    summary: 'Emitted once when an announced session leaves the store, including publication rollback, but never for an entry whose creation announcement did not begin.',
  },
  {
    name: 'session/event',
    mode: 'emit',
    signature: '\'session/event\'(this: Scoped<Session>, session: Session, event: SessionEvent): void',
-    summary: 'An event was appended to a session log (sync, fire-and-forget).',
+    summary: 'Post-commit, fire-and-forget append feed.',
  },
  {
    name: 'session/flush',
    mode: 'parallel',
    signature: '\'session/flush\'(this: Scoped<Session>, session: Session): Promise<void> | void',
-    summary: 'Awaited durability checkpoint.',
-  },
-  {
-    name: 'skill/provider-added',
-    mode: 'emit',
-    signature: '\'skill/provider-added\'(provider: SkillProvider): void',
-    summary: 'A skill provider became resolvable in the `ctx.skills` registry.',
-  },
-  {
-    name: 'skill/provider-removed',
-    mode: 'emit',
-    signature: '\'skill/provider-removed\'(name: string): void',
-    summary: 'A skill provider left the registry because its plugin fiber was disposed.',
+    summary: 'Awaited parallel durability checkpoint: every listener runs and the caller awaits all of them, with no waterfall veto.',
  },
  {
    name: 'subagent/end',
@@ -428,13 +426,13 @@ export const EVENT_API: readonly EventApiEntry[] = [
    name: 'system-prompt/assemble',
    mode: 'waterfall',
    signature: '\'system-prompt/assemble\'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>',
-    summary: 'Waterfall around prompt assembly — mutate or extend the PromptAssembly (sections + tools + variables) before it is rendered.',
+    summary: 'Expert waterfall over the assembled sections, tools, and variables.',
  },
  {
    name: 'system-prompt/change',
    mode: 'emit',
    signature: '\'system-prompt/change\'(): void',
-    summary: 'A section, tool provider, or variable provider was registered or unregistered (the assembly inputs changed — possibly for one scope only).',
+    summary: 'Emitted when any prompt provider changes.',
  },
  {
    name: 'tools/change',
@@ -446,25 +444,25 @@ export const EVENT_API: readonly EventApiEntry[] = [
    name: 'tools/execute',
    mode: 'waterfall',
    signature: '\'tools/execute\'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>',
-    summary: 'Around-dispatch waterfall wrapping the registry\'s core tool dispatch, between the `tools/pre-execute` gate and the `tools/post-execute` seam.',
+    summary: 'Around-dispatch waterfall for timeout, retry, or metrics.',
  },
  {
    name: 'tools/post-execute',
    mode: 'waterfall',
    signature: '\'tools/post-execute\'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>',
-    summary: 'Waterfall AFTER a tool runs — where hook plugins inspect the result and accept it (optionally REPLACING the model-facing content, and/or attaching `additionalContext` for the next request) or block it with corrective `feedback` (Claude Code\'s `PostToolUse`).',
+    summary: 'Accept, replace, enrich, or block a normalized dispatch result.',
  },
  {
    name: 'tools/pre-execute',
    mode: 'waterfall',
    signature: '\'tools/pre-execute\'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>',
-    summary: 'Waterfall BEFORE a tool runs — the gate where sandbox, permission, and hook plugins allow or deny a call (Claude Code\'s `PreToolUse`).',
+    summary: 'Allow, deny, or ask before dispatch.',
  },
  {
    name: 'tools/result',
    mode: 'emit',
    signature: '\'tools/result\'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined',
-    summary: 'Synchronous notification of the authoritative FINAL tool outcome, after the complete pre/execute/post pipeline, final lossless-JSON validation, and outer error normalization.',
+    summary: 'Observe the frozen, lossless-JSON final outcome.',
  },
  {
    name: 'workflow/agent-end',
@@ -534,6 +532,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'ApprovalOutcome',
    declaration: 'export type ApprovalOutcome = \'allowed-once\' | \'rejected\' | \'cancelled\' | \'unavailable\';',
  },
+  {
+    name: 'ApprovalPolicy',
+    declaration: 'export type ApprovalPolicy = \'ask\' | \'never\';',
+  },
  {
    name: 'ApprovalRequest',
    declaration: 'export interface ApprovalRequest {\n    readonly agent: Agent;\n    readonly toolName: string;\n    readonly callId?: CallId;\n    readonly reason?: string;\n    readonly signal?: AbortSignal;\n}',
@@ -564,7 +566,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'AssembledSection',
-    declaration: 'export interface AssembledSection {\n    name: string;\n    order: number;\n    text: string;\n}',
+    declaration: 'export interface AssembledSection {\n    name: string;\n    text: string;\n}',
  },
  {
    name: 'BashExecRequest',
@@ -584,7 +586,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'BashTask',
-    declaration: 'export interface BashTask {\n    readonly id: BashTaskId;\n    readonly command: string;\n    status: BashTaskStatus;\n    exitCode: number | null;\n    signal: NodeJS.Signals | null;\n    readonly done: Promise<void>;\n    sandbox?: BashSandboxInfo;\n}',
+    declaration: 'export interface BashTask {\n    readonly id: BashTaskId;\n    status: BashTaskStatus;\n    exitCode: number | null;\n    signal: NodeJS.Signals | null;\n    readonly done: Promise<void>;\n    sandbox?: BashSandboxInfo;\n}',
  },
  {
    name: 'BashTaskId',
@@ -618,10 +620,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'CodeBindingNamespace',
    declaration: 'export interface CodeBindingNamespace {\n    global: string;\n    functions: Record<string, CodeBindingFunction>;\n}',
  },
-  {
-    name: 'CodeLogEntry',
-    declaration: 'export interface CodeLogEntry {\n    source: \'console\' | \'stdout\' | \'stderr\';\n    level?: \'log\' | \'info\' | \'warn\' | \'error\' | \'debug\';\n    text: string;\n}',
-  },
  {
    name: 'CodeRunFailure',
    declaration: 'export interface CodeRunFailure {\n    kind: \'exception\' | \'timeout\' | \'abort\' | \'worker-exit\';\n    message: string;\n}',
@@ -632,7 +630,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'CodeRunResult',
-    declaration: 'export interface CodeRunResult {\n    value?: unknown;\n    logs: CodeLogEntry[];\n    error?: CodeRunFailure;\n}',
+    declaration: 'export interface CodeRunResult {\n    value?: unknown;\n    logs: string[];\n    error?: CodeRunFailure;\n}',
  },
  {
    name: 'CollectedOutput',
@@ -762,6 +760,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'OwnerToken',
    declaration: 'export type OwnerToken = Branded<\'OwnerToken\'>;',
  },
+  {
+    name: 'PresetOption',
+    declaration: 'export interface PresetOption {\n    value: string;\n    name: string;\n    description?: string;\n}',
+  },
+  {
+    name: 'PresetSpec',
+    declaration: 'export interface PresetSpec {\n    sandbox: SandboxMode;\n    approval: ApprovalPolicy;\n    name?: string;\n    description?: string;\n}',
+  },
  {
    name: 'PromptAssembly',
    declaration: 'export interface PromptAssembly {\n    sections: AssembledSection[];\n    tools: ToolSchema[];\n    variables: Record<string, string | undefined>;\n}',
@@ -1040,7 +1046,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'ToolExecutionResult',
-    declaration: 'export interface ToolExecutionResult {\n    callId: CallId;\n    content: ContentBlock[];\n    isError: boolean;\n    error?: ToolErrorInfo;\n    additionalContext?: HookContext;\n    meta?: unknown;\n}',
+    declaration: 'export interface ToolExecutionResult {\n    content: ContentBlock[];\n    isError: boolean;\n    error?: ToolErrorInfo;\n    additionalContext?: HookContext;\n    meta?: unknown;\n}',
  },
  {
    name: 'ToolExecutionToken',
@@ -1094,33 +1100,25 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'UserInteractionProvider',
    declaration: 'export interface UserInteractionProvider {\n    ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>;\n}',
  },
-  {
-    name: 'WebExecContext',
-    declaration: 'export interface WebExecContext {\n    readonly signal?: AbortSignal;\n}',
-  },
  {
    name: 'WebFetchBody',
    declaration: 'export type WebFetchBody = {\n    readonly kind: \'html\';\n    readonly content: string;\n} | {\n    readonly kind: \'text\';\n    readonly content: string;\n};',
  },
  {
    name: 'WebFetchProvider',
-    declaration: 'export interface WebFetchProvider {\n    readonly id: string;\n    status(): WebProviderStatus;\n    fetch(request: WebFetchRequest, exec?: WebExecContext): Promise<WebFetchResult>;\n}',
+    declaration: 'export interface WebFetchProvider {\n    readonly id: string;\n    available(): boolean;\n    fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;\n}',
  },
  {
    name: 'WebFetchRequest',
-    declaration: 'export interface WebFetchRequest {\n    readonly url: string;\n    readonly timeoutMs?: number;\n}',
+    declaration: 'export interface WebFetchRequest {\n    readonly url: string;\n}',
  },
  {
    name: 'WebFetchResult',
-    declaration: 'export interface WebFetchResult {\n    readonly providerId: string;\n    readonly url: string;\n    readonly statusCode: number;\n    readonly body: WebFetchBody;\n    readonly truncated: boolean;\n}',
-  },
-  {
-    name: 'WebProviderStatus',
-    declaration: 'export type WebProviderStatus = {\n    readonly available: true;\n} | {\n    readonly available: false;\n    readonly reason: \'missing-credential\' | \'misconfigured\';\n};',
+    declaration: 'export interface WebFetchResult {\n    readonly url: string;\n    readonly statusCode: number;\n    readonly body: WebFetchBody;\n    readonly truncated: boolean;\n}',
  },
  {
    name: 'WebSearchProvider',
-    declaration: 'export interface WebSearchProvider {\n    readonly id: string;\n    status(): WebProviderStatus;\n    search(request: WebSearchRequest, exec?: WebExecContext): Promise<WebSearchResult>;\n}',
+    declaration: 'export interface WebSearchProvider {\n    readonly id: string;\n    available(): boolean;\n    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;\n}',
  },
  {
    name: 'WebSearchRequest',
@@ -1128,7 +1126,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'WebSearchResult',
-    declaration: 'export interface WebSearchResult {\n    readonly providerId: string;\n    readonly query: string;\n    readonly content?: string;\n    readonly sources: readonly WebSearchSource[];\n    readonly truncated: boolean;\n}',
+    declaration: 'export interface WebSearchResult {\n    readonly content?: string;\n    readonly sources: readonly WebSearchSource[];\n    readonly truncated: boolean;\n}',
  },
  {
    name: 'WebSearchSource',
--- a/packages/cordis/tool-cordis/src/fiber-state.ts
+++ b/packages/cordis/tool-cordis/src/fiber-state.ts
@@ -1,15 +1,7 @@
 /**
- * Runtime mirror of the cordis `FiberState` const enum plus human-readable
- * labels, shared by the mount lifecycle (state reporting) and the inspect
- * renderers (plugin-list and mount-table labels).
- *
- * Cordis exposes `FiberState` as a `const enum`: there is no runtime object for
- * Node's type-stripping runner to import, so the members are mirrored here as
- * values — each typed (via the type-only import) as the cordis enum member it
- * mirrors, so enum-typed reads like `fiber.state` compare against them under a
- * shared enum type. Source of truth: vendor/cordis/src/fiber.ts (pinned; drift
- * only happens through a deliberate vendor sync).
- *
+ * Runtime mirror and labels for Cordis's `FiberState` const enum. A const enum has no runtime
+ * object to import, so these values mirror the pinned vendored definition while retaining its
+ * type.
 * @module @deepseek-ai/dsh-tool-cordis/fiber-state
 */

--- a/packages/cordis/tool-cordis/src/guard.ts
+++ b/packages/cordis/tool-cordis/src/guard.ts
@@ -1,50 +1,14 @@
 /**
- * The registration boundary between sandboxed mount code and the real runtime:
- * SchemaSpec normalization + validation with teaching errors, the
- * marker-guarded `harness.defineTool` / `harness.registerTool` pair, the
- * SANDBOX CONTEXT FAÇADE a mounted plugin's `apply` receives in place of the
- * real `ctx`, and the plugin-shape helpers the mount lifecycle narrows sandbox
- * return values with.
- *
- * The façade is a WHITELIST, not a pass-through proxy. Mount code needs to do
- * exactly four things — register a tool, listen to an event, provide a service,
- * call an injected service (timers included) — so the façade exposes only those
- * verbs and the injected services, each object-valued service individually
- * wrapped (a primitive provided value passes through as-is — see
- * {@link sandboxContext}). Every framework plumbing member (`root`, `parent`, `scope`, `fiber`, `reflect`, `registry`,
- * `events`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) is
- * DENIED with a teaching error rather than passed through. This closes an
- * entire escape class at once: a pass-through proxy that only special-cased
- * `ctx.tools` still handed back the raw context through `ctx.root`,
- * `ctx.extend()`, or a service instance's `.ctx`, and mount code could then
- * `ctx.root.tools.register({…})` to bypass the marker check and host-realm
- * normalization — a raw vm-realm result then errors a real agent turn at the
- * session-log plainness check. The whitelist has no such hole: there is no
- * context-valued member to reach, and any injected-service method that returns
- * a `Context` is rejected (harness services never do — see {@link denyContext}).
- *
- * Two realm facts drive the tool path. Objects built inside the vm carry the vm
- * realm's `Object.prototype`, and the session log's append-time plainness check
- * (`dsh-session`'s `isJsonValue`, a prototype-identity comparison) rejects
- * foreign-realm data — so every dynamic tool's `execute` return is JSON
- * round-tripped into the host realm and shape-checked against the two
- * `ToolExecuteReturn` forms before it reaches the registry (the registry
- * trusts the shape blindly — it spreads `result.content`, so an unvalidated
- * `{ content: 'ok' }` would enter the session log as `['o','k']` and silently
- * corrupt the next model request), and the schema itself is rebuilt as fresh
- * host-realm objects. And a malformed tool
- * schema must fail at REGISTRATION, not when a later request assembles it — so
- * dynamic tool registration accepts only definitions produced by the sandbox's
- * `harness.defineTool`, which normalizes `parameters` up front.
- *
- * Normalize, don't lecture, where the input has exactly one meaning: models
- * write the JSON-Schema dialect by strong prior (the `{ type: 'object',
- * properties, required: […] }` wrapper, `type: 'integer'`, `required: false`),
- * and each rejection costs a model turn — so those convert to the SchemaSpec
- * DSL silently, and only genuinely meaningless input (an unknown type, a
- * non-boolean `required`) is rejected, with the error enumerating the valid
- * vocabulary.
+ * The registration boundary between sandboxed mount code and the real runtime: SchemaSpec
+ * normalization + validation with teaching errors, the marker-guarded `harness.defineTool` /
+ * `harness.registerTool` pair, the SANDBOX CONTEXT FAÇADE a mounted plugin's `apply` receives
+ * in place of the real `ctx`, and the plugin-shape helpers the mount lifecycle narrows sandbox
+ * return values with. The façade is a whitelist of lifecycle-safe verbs and declared services;
+ * framework internals and context-valued service returns are denied.
 *
+ * VM-realm schemas are rebuilt as host objects, and tool results are JSON-round-tripped and
+ * shape-checked before session logging. Common JSON-Schema spellings are normalized when they
+ * have one meaning; invalid vocabulary fails during registration with a teaching error.
 * @module @deepseek-ai/dsh-tool-cordis/guard
 */

@@ -102,7 +66,7 @@ function normalizeSchemaProp(value: unknown, path: string, forceRequired = false
  }
  // On an object property a JSON-Schema-style `required` ARRAY names required
  // children (handled by the nested unwrap below); everywhere else `required`
-  // must be a boolean, and `false` simply reads as optional.
+  // must be a boolean, and `false` means optional.
  const nestedRequiredArray = type === 'object' && Array.isArray(value.required)
  if (value.required !== undefined && typeof value.required !== 'boolean' && !nestedRequiredArray) {
    throw new Error(`harness.defineTool ${path}.required must be a boolean when present`)
@@ -195,14 +159,11 @@ function assertExecuteReturn(value: unknown): ToolExecuteReturn {
 }

 /**
- * The `harness.defineTool` handed into the sandbox: the real DSL, with
- * `parameters` normalized into a fresh host-realm SchemaSpec (JSON-Schema
- * wrapper unwrapped, `integer` mapped, `required: false` dropped) and the
- * tool's `execute` return normalized into the host realm via a JSON round-trip
- * (see the module doc). The round-trip projects the return onto exactly what
- * the log would durably store, and {@link assertExecuteReturn} then vets that
- * projection — so a non-JSON-serializable OR wrong-shape return surfaces as
- * that one call's teaching error instead of poisoning the turn.
+ * The `harness.defineTool` handed into the sandbox: the real DSL, with `parameters` normalized
+ * into a fresh host-realm SchemaSpec (JSON-Schema wrapper unwrapped, `integer` mapped,
+ * `required: false` dropped) and the tool's `execute` return normalized into the host realm
+ * via a JSON round-trip. Non-JSON or wrong-shape output fails that call instead of poisoning
+ * the session log.
 * @param options - the standard `defineTool` options; `parameters` may be the SchemaSpec DSL or a JSON-Schema-style wrapper.
 * @returns the marker-tagged definition `harness.registerTool` (and the guarded `ctx.tools.register`) accepts.
 */
@@ -236,15 +197,9 @@ export function sandboxRegisterTool(ctx: Context, tool: unknown): () => void {
 }

 /**
- * The verbs a mounted plugin may reach through the sandbox `ctx` façade,
- * beyond its injected services. `on`/`once` observe events, `provide` exposes
- * a service to other mounts, and the timer helpers schedule work — each a
- * fiber effect that unwinds on unmount. Everything else on a real cordis `ctx`
- * is framework plumbing and is denied. Forwarded LAZILY: the timer helpers are
- * mixin accessors that throw `without inject` when read on a plugin that did
- * not inject `timer`, so the façade reads `ctx[verb]` only at call time — the
- * plugin that never touches a timer never trips that, and one that does gets
- * cordis's own inject error at the call site.
+ * The verbs a mounted plugin may reach through the sandbox `ctx` façade, beyond its injected
+ * services. `on`/`once` observe events, `provide` exposes a service to other mounts, and the
+ * timer helpers schedule work — each a fiber effect that unwinds on unmount.
 */
 const CTX_VERBS = new Set(['on', 'once', 'provide', 'timeout', 'interval', 'setTimeout', 'setInterval', 'throttle', 'debounce'])

@@ -258,11 +213,7 @@ const CTX_VERBS = new Set(['on', 'once', 'provide', 'timeout', 'interval', 'setT
 * name/description/parameters view as `schemas()`, and nothing invocable.
 */
 function sandboxTools(ctx: Context): Record<string, unknown> {
-  // Reads resolve through the MOUNT's own scope (`scopeOf(ctx)`), mirroring
-  // where the façade's `register` lands its writes (the calling context's
-  // layer): mount code always sees the tools its own world sees — the global
-  // view for today's global mounts, its agent's view if a mount ever runs
-  // under an agent scope.
+  // Resolve reads and writes through the mount's own scope.
  return {
    register: (tool: unknown): (() => void) => sandboxRegisterTool(ctx, tool),
    schemas: () => ctx.tools.schemas(scopeOf(ctx)),
@@ -320,15 +271,8 @@ function declaredInjects(ctx: Context): Set<string> {
 }

 /**
- * The sandbox context façade handed to a mounted plugin's `apply` in place of
- * the real `ctx`. A whitelist (see the module doc): the registration/eventing
- * verbs, the timer helpers, a guarded `tools`, and injected services resolved
- * through a guarded `get` / property access. A service is reachable only if the
- * plugin DECLARED it in `inject` — an undeclared service is denied even when a
- * global provider exists, so cordis's activation/unload semantics (park the
- * mount when a declared provider goes away) actually bind. Every
- * framework-plumbing member is denied with a teaching error; there is no
- * context-valued member to reach.
+ * Whitelist context for mounted plugins: lifecycle-safe verbs, guarded tools, and only declared
+ * injected services. Framework plumbing is denied, and service methods cannot return a Context.
 */
 function sandboxContext(ctx: Context): Context {
  const tools = sandboxTools(ctx)
@@ -348,16 +292,8 @@ function sandboxContext(ctx: Context): Context {
      + 'Framework internals (root, fiber, registry, extend, plugin, …) are withheld by design.',
    )
  }
-  // Read a service for either access path (property or `get`). `tools` is the
-  // façade's own surface. An UNDECLARED name is denied with the teaching
-  // error; a DECLARED one resolves to the guarded service. A declared inject
-  // is required in cordis (the fiber only activates once every declared
-  // service is live), so at `apply`/`execute` time `ctx.get(name)` is present
-  // for a declared name — no undefined case to handle here. `provide()`
-  // accepts ANY value though (cross-mount composition advertises
-  // `ctx.provide('name', value)`), so a primitive or null value passes
-  // through unwrapped: Proxy throws on a non-object target, and only an
-  // object can carry a method that hands back a Context.
+  // Read a service for either access path (property or `get`). `tools` is the façade's own
+  // surface.
  const readService = (name: string): unknown => {
    if (name === 'tools') return tools
    if (!declared.has(name)) return denyRead(name)
@@ -408,20 +344,11 @@ export function isPlugin(value: unknown): value is Plugin {
 }

 /**
- * Wrap a plugin so its `apply` receives the sandbox context façade instead of
- * the real `ctx` (see {@link sandboxContext} and the module doc). Both
- * function-form and object-form plugins go through the same wrap; the plugin's
- * own `inject` declaration is preserved (cordis reads it from the plugin
- * object, and pending/active gating happens on the real fiber before `apply`
- * runs), so cross-mount provide/inject works unmodified.
- *
- * `ctx.effect(customCleanup)` is deliberately absent from the façade for now —
- * `on` / `provide` / `tools.register` cover every mount seen so far, and each
- * is already a fiber effect. FIXME(sandbox-effect): expose a guarded `effect`
- * once a real mount needs a bespoke disposer.
+ * Wrap a plugin so `apply` receives the sandbox context while preserving injection metadata.
 * @param plugin - the plugin the mount code returned.
 * @returns an equivalent plugin whose `apply` sees the sandbox context façade.
 */
+// FIXME(sandbox-effect): expose guarded custom effects when a mount needs bespoke cleanup.
 export function guardedPlugin(plugin: Plugin): Plugin {
  if (typeof plugin === 'function') {
    const functionPlugin = plugin as (ctx: Context, config?: unknown) => unknown
--- a/packages/cordis/tool-cordis/src/index.ts
+++ b/packages/cordis/tool-cordis/src/index.ts
@@ -1,37 +1,9 @@
 /**
- * The self-referential cordis toolset: three model-facing tools that let the
- * agent inspect and MODIFY the live cordis runtime it is running inside.
- *
- * - `cordis_inspect` — read-only: provided services, the flat plugin list
- *   with lifecycle states, registered tools, the dynamic mounts, and the
- *   catalog-backed `api` / `events` references.
- * - `cordis_mount` — evaluate model-written code in a `node:vm` sandbox; the
- *   code returns a cordis plugin, which is mounted as a child of a dedicated
- *   `cordis-dynamic` group fiber and tracked under an id (`dyn-1`, `dyn-2`, …).
- * - `cordis_unmount` — dispose one dynamic mount by id, awaiting quiescence.
- *
- * Everything the model's plugin registers (listeners via `ctx.on`, tools via
- * `harness.registerTool`, services via `ctx.provide`) is an effect on the
- * dynamic fiber, so unmounting — or disposing this plugin itself (HMR) — cleans
- * it all up through the ordinary cordis lifecycle. The group fiber exists
- * exactly so the dynamic mounts form ONE subtree, disposed as a unit with
- * this plugin. Design home:
- * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md.
- *
- * The vm sandbox guards against ACCIDENTAL global pollution only, and the `ctx`
- * a mounted plugin's `apply` receives is a WHITELIST façade (register a tool,
- * observe events, provide/consume services, use timers — framework internals
- * withheld; see the guard module). Neither is a security boundary: the verbs
- * the façade DOES expose reach the real runtime unsandboxed (a mounted tool can
- * shell out through `ctx.bash`), so a deployment loads this plugin as
- * deliberately as it grants a bash tool. Design home:
- * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md.
- *
- * 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` and drop `inject`, crashing at load
- * (see docs/postmortem/0001).
- *
+ * Self-referential runtime tools: inspect live services/plugins/tools, mount a returned plugin
+ * under an owned dynamic fiber, and unmount it to quiescence. Registrations are fiber effects,
+ * so plugin disposal removes the entire dynamic subtree. The VM and context façade prevent
+ * accidental misuse, not hostile code: an allowed service such as `ctx.bash` reaches the real
+ * runtime. Named exports preserve loader injection metadata.
 * @module @deepseek-ai/dsh-tool-cordis
 */

@@ -75,9 +47,7 @@ type ResolvedConfig = Required<Config>
 */
 export function apply(ctx: Context, config: Config): void {
  const { vmTimeoutMs } = config as ResolvedConfig
-  // The one group fiber every dynamic mount hangs under. Mounted here (a child
-  // of this plugin's fiber) so disposing tool-cordis cascades over the whole
-  // dynamic subtree — the ordinary parent→child fiber lifecycle, nothing extra.
+  // The one group fiber every dynamic mount hangs under.
  const group = ctx.plugin({ name: 'cordis-dynamic', apply: () => {} })

  const mounts = new Map<string, DynamicMount>()
--- a/packages/cordis/tool-cordis/src/inspect.ts
+++ b/packages/cordis/tool-cordis/src/inspect.ts
@@ -1,11 +1,7 @@
 /**
- * Read-only renderers over the live runtime for `cordis_inspect`: the service
- * list, the flat plugin list, the registered tools, the dynamic-mount
- * table (with per-mount provides/waits), and the catalog-backed `api` /
- * `events` sections. Every renderer is a pure function of the runtime handles
- * it receives — no session state, no clock — so inspect output is exactly the
- * runtime it describes.
- *
+ * Read-only renderers over the live runtime for `cordis_inspect`: the service list, the flat
+ * plugin list, the registered tools, the dynamic-mount table (with per-mount provides/waits),
+ * and the catalog-backed `api` / `events` sections.
 * @module @deepseek-ai/dsh-tool-cordis/inspect
 */

@@ -131,16 +127,13 @@ function typeClosure(seeds: string[], types: readonly TypeApiEntry[]): TypeApiEn
 }

 /**
- * The `api` section: the generated service catalog intersected with the LIVE
- * runtime — catalogued live services render summary + method signatures, live
- * services without a catalog entry (e.g. ones another mount provides) render
- * name + owning fiber, catalog services that are not running are listed
- * tersely, the type shapes the live signatures reference follow, and the
- * inherited `ctx` surface closes the section.
+ * Render the generated catalog against the live runtime: live catalogued services with methods,
+ * uncatalogued live services with owners, absent loadable services, referenced type shapes, and
+ * inherited Context APIs.
 * @param ctx - the runtime to intersect the catalog with.
- * @param api - the service catalog (the generated one by default; injectable for tests).
- * @param inherited - the inherited `ctx` surface lines (generated by default; injectable for tests).
- * @param types - the type-shape catalog (generated by default; injectable for tests).
+ * @param api - generated service entries, replaceable in tests.
+ * @param inherited - inherited `ctx` entries, replaceable in tests.
+ * @param types - public type shapes, replaceable in tests.
 * @returns the section lines.
 */
 export function describeApi(
--- a/packages/cordis/tool-cordis/src/mount.ts
+++ b/packages/cordis/tool-cordis/src/mount.ts
@@ -21,11 +21,8 @@ export interface DynamicMount {
 }

 /**
- * Mount a plugin under the group fiber and settle it. The group fiber loads
- * asynchronously right after the owning plugin's `apply`, so it is awaited
- * before hanging a child off its context. The child fiber's `await()` settles
- * its lifecycle work and rethrows a startup error (e.g. a throwing `apply`);
- * on error the fiber is disposed first — a failed mount never lingers.
+ * Await the group, mount and settle one guarded child, and dispose it before rethrowing any
+ * startup failure so a failed mount never lingers. A valid unresolved inject may remain pending.
 * @param group - the `cordis-dynamic` group fiber every mount hangs under.
 * @param plugin - the plugin the sandbox returned; wrapped with the registration guard before mounting.
 * @returns the settled child fiber (possibly pending on unsatisfied `inject`).
--- a/packages/cordis/tool-cordis/src/sandbox.ts
+++ b/packages/cordis/tool-cordis/src/sandbox.ts
@@ -1,20 +1,10 @@
 /**
- * The `node:vm` sandbox `cordis_mount` code evaluates in: a fresh realm whose
- * globals are a tagged write-through console, the `harness` registration
- * helpers, the encoding primitives a bare vm context lacks, and callable traps
- * over the Node APIs the sandbox deliberately withholds. Capability access is
- * routed through cordis services, never Node built-ins: filesystem work goes
- * through `ctx.fs`, network through `ctx.web`, processes through `ctx.bash`,
- * timers through the `ctx.timer` helpers (fiber effects, unwound on unmount)
- * — so a well-behaved mount stays inspectable and disposable. That routing is
- * STEERING toward the cordis services, not containment: the sandbox guards
- * against ACCIDENTAL global pollution, and it is not a security boundary. The
- * host-realm helpers on the sandbox global (`harness`, `console`, `btoa`) are
- * reachable functions, so a mount that goes looking — e.g. through such a
- * helper's `.constructor` — can still reach the host realm; that is accepted,
- * because the `ctx` a mounted plugin's `apply` later receives is the real,
- * fully privileged runtime handle, and that is the point of the toolset.
- *
+ * The `node:vm` sandbox `cordis_mount` code evaluates in: a fresh realm whose globals are a
+ * tagged write-through console, the `harness` registration helpers, the encoding primitives a
+ * bare vm context lacks, and callable traps over the Node APIs the sandbox deliberately
+ * withholds. Traps steer filesystem, network, process, and timer work to `ctx.fs`, `ctx.web`,
+ * `ctx.bash`, and Cordis timers. This keeps cooperative mounts inspectable and disposable but
+ * is not containment: host-realm helper functions remain an escape route.
 * @module @deepseek-ai/dsh-tool-cordis/sandbox
 */

@@ -35,17 +25,8 @@ function taggedConsole(id: string): Record<'log' | 'info' | 'warn' | 'error' | '
 }

 /**
- * Per-sandbox prelude: give the vm realm's own constructors a
- * `Symbol.hasInstance` that checks BOTH realms. Model code runs against a
- * fresh vm realm, but most objects it touches are HOST-realm (the `args` a
- * tool's `execute` receives, event payloads a listener observes, service
- * return values), so a plain `x instanceof Array` / `instanceof Object` in
- * sandbox code would silently be false. The patch replaces each vm
- * constructor's own `[Symbol.hasInstance]` with "ordinary check against the
- * vm constructor OR the host counterpart" — the ordinary algorithm is a pure
- * prototype-chain walk, so calling it with the host constructor as receiver
- * needs no host-side change. ONLY vm-realm globals are modified; host
- * intrinsics are passed in as values and never touched.
+ * Patch only VM constructors so `instanceof` accepts both VM values and host values passed as
+ * arguments, events, or service results; host intrinsics remain untouched.
 */
 const DUAL_REALM_INSTANCEOF_PRELUDE = `
 (hostIntrinsics) => {
@@ -156,13 +137,10 @@ export function syntaxErrorContext(error: Error): string {
 }

 /**
- * Evaluate mount code as the body of an async function inside the sandbox.
- * `vmTimeoutMs` only bounds the SYNCHRONOUS portion; an async body escapes it
- * — acceptable under the module's trust stance. A parse failure is answered
- * with the offending line + caret and a teaching hint: TypeScript syntax on
- * the failing line gets the remove-annotations fix, anything else gets the
- * function-body/bracket-balance reminder (models habitually close the returned
- * plugin object with `});` as if it were a callback argument).
+ * Evaluate mount code as the body of an async function inside the sandbox. `vmTimeoutMs` only
+ * bounds the SYNCHRONOUS portion; an async body escapes it — acceptable under the module's
+ * trust stance. Parse errors include the offending line and a TypeScript-removal or bracket-
+ * balance hint.
 * @param sandbox - the contextified object from {@link createSandbox}.
 * @param code - the model-written function body; must `return` a plugin.
 * @param id - the mount id, used as the vm filename (`cordis-mount-<id>.js`).
--- a/packages/cordis/tool-cordis/tests/mount.spec.ts
+++ b/packages/cordis/tool-cordis/tests/mount.spec.ts
@@ -48,12 +48,7 @@ describe('cordis_mount', () => {
  })

  it('normalizes a self-made tool\'s result into the host realm, so the session log accepts it', async () => {
-    // The model's execute builds its content blocks INSIDE the vm, where
-    // Object.prototype is a different object — dsh-session's isJsonValue (the
-    // gate every `tool/result` append runs through) compares prototype
-    // IDENTITY, so a raw foreign-realm result would error the whole turn the
-    // first time the self-made tool runs. harness.defineTool round-trips the
-    // return into host-realm JSON before it reaches the registry.
+    // VM-realm objects fail the session prototype-identity check; normalize them into host JSON.
    const ctx = await setup()
    await call(ctx, 'cordis_mount', { code: REVERSE_TOOL_CODE })
    const reversed = await call(ctx, 'reverse_text', { text: 'harness' })
@@ -94,11 +89,8 @@ describe('cordis_mount', () => {
    ['object-form blocks missing the type tag', 'return { content: [{ text: \'hi\' }] }', '{"content":[{"text":"hi"}]}'],
    ['undefined — a forgotten return', 'return undefined', 'undefined'],
  ])('rejects an execute return of %s as that one call\'s teaching error', async (_label, returnStatement, preview) => {
-    // The failure this prevents: the registry trusts the return shape
-    // (postExecute spreads result.content), so an unvalidated { content: 'ok' }
-    // would enter the session log as ['o','k'] and silently corrupt the next
-    // model request. The shape check turns it into THIS call's error instead —
-    // one well-formed text block the log and the model can digest.
+    // The registry spreads result.content, so { content: 'ok' } would become ['o','k']; reject
+    // it as this call's error before it corrupts the next request.
    const ctx = await setup()
    await call(ctx, 'cordis_mount', {
      code: `
@@ -150,10 +142,8 @@ describe('cordis_mount', () => {
  })

  it('accepts a JSON-Schema-style parameters wrapper and normalizes it to the DSL', async () => {
-    // The dialect models write by strong prior: the { type:'object',
-    // properties, required: […] } wrapper, `type: 'integer'`, and
-    // `required: false`. All of it has exactly one meaning — normalize instead
-    // of burning a model turn on a lecture.
+    // These common JSON-Schema spellings each have one DSL meaning, so normalize rather than
+    // consume another model turn with a rejection.
    const ctx = await setup()
    const result = await call(ctx, 'cordis_mount', {
      code: `
@@ -535,10 +525,9 @@ describe('cordis_mount', () => {
  })

  it('makes instanceof inside the sandbox see BOTH realms (patched vm constructors, host untouched)', async () => {
-    // The args a tool's execute receives are HOST-realm objects; without the
-    // dual-realm Symbol.hasInstance prelude, `args.items instanceof Array` in
-    // sandbox code is silently false. The patch lives on the vm realm's own
-    // constructors only — the host realm's must stay pristine.
+    // The args a tool's execute receives are HOST-realm objects; without the dual-realm
+    // Symbol.hasInstance prelude, `args.items instanceof Array` in sandbox code is silently
+    // false.
    const ctx = await setup()
    await call(ctx, 'cordis_mount', {
      code: `
--- a/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts
+++ b/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts
@@ -2,13 +2,10 @@ import { describe, expect, it } from 'vitest'
 import { call, setup, text } from './helpers.ts'

 /**
- * The sandbox context façade is a whitelist, not a pass-through proxy: mount
- * code reaches only the registration/eventing verbs, the timer helpers, a
- * guarded `tools`, and its injected services. Every framework-plumbing member
- * that could hand back an UNGUARDED context — through which a plugin could
- * `ctx.<escape>.tools.register({…})` to bypass the marker check and host-realm
- * normalization — is denied. These are the regression guards for that escape
- * class (the review finding on the original pass-through proxy).
+ * The sandbox context façade is a whitelist, not a pass-through proxy. Mounted code reaches only
+ * registration/eventing verbs, timer helpers, guarded tools, and injected services. Framework
+ * members that expose an unguarded context are denied because they could bypass marker checks and
+ * host-realm normalization; these tests pin that escape class.
 */

 /** Mount a plugin whose `apply` touches one framework member, and report the error text. */
@@ -77,10 +74,8 @@ describe('sandbox context façade — escape surface is closed', () => {

  it('denies a service whose method returns a Context (the .ctx escape), registering nothing', async () => {
    // A cordis Service instance carries `.ctx` (a real Context), so
-    // `ctx.systemPrompt.ctx.root.tools.register(…)` would be a fresh unguarded
-    // handle. The service wrapper's return-value guard rejects any Context on
-    // the way back to sandbox code, so the escape never lands. (`systemPrompt`
-    // is in the setup harness, so the plugin activates and its apply runs.)
+    // `ctx.systemPrompt.ctx.root.tools.register(…)` would escape the façade; service-return
+    // guards reject that Context before the registration lands.
    const ctx = await setup()
    const result = await call(ctx, 'cordis_mount', {
      code: `
@@ -104,10 +99,8 @@ describe('sandbox context façade — escape surface is closed', () => {
  })

  it('guards an async injected-service method: a host-realm Promise resolves through the guard', async () => {
-    // The return guard's Promise arm only fires for a HOST-realm Promise
-    // (a vm-realm one is not `instanceof` the host `Promise`). Provide a
-    // host-realm service from the test, then inject + await it from a mount:
-    // the resolved value is non-Context data and passes through.
+    // The return guard's Promise arm only fires for a HOST-realm Promise (a vm-realm one is not
+    // `instanceof` the host `Promise`).
    const ctx = await setup()
    ctx.plugin({
      name: 'host-async-svc',
@@ -194,11 +187,8 @@ describe('sandbox context façade — inject gate on services', () => {
  })

  it('a cross-mount consumer must declare the provider — the undeclared path is refused, not left as a zombie tool', async () => {
-    // The finding's scenario: a consumer registers a tool built on a provider's
-    // service WITHOUT declaring inject. cordis would then never park the
-    // consumer when the provider unmounts, leaving a tool that fails only at
-    // execution. The gate refuses the undeclared access up front, so the
-    // dependency is always visible to cordis.
+    // Without declared inject, Cordis cannot park the consumer when its provider unmounts. The
+    // façade refuses access up front instead of leaving a zombie tool.
    const ctx = await setup()
    await call(ctx, 'cordis_mount', {
      code: 'return { name: \'greeter-provider\', apply(ctx) { ctx.provide(\'greeter\', { greet: (n) => \'hi \' + n }) } }',
@@ -231,11 +221,9 @@ describe('sandbox context façade — inject gate on services', () => {

 describe('sandbox tools façade — get is a read-only schema view', () => {
  it('ctx.tools.get returns a schema, not the live ToolDefinition with execute', async () => {
-    // The finding: returning the raw ToolDefinition hands mount code the
-    // tool's execute function, letting it bypass ToolRegistry.execute (and its
-    // pre/post hooks). get now returns the same name/description/parameters
-    // view as schemas(), with no execute. Asserted via a self-made tool that
-    // reports the shape it saw — world-checked, not self-reported.
+    // The finding: returning the raw ToolDefinition hands mount code the tool's execute
+    // function, letting it bypass ToolRegistry.execute (and its pre/post hooks). get now
+    // returns the same name/description/parameters view as schemas(), with no execute.
    const ctx = await setup()
    await call(ctx, 'cordis_mount', {
      code: `
--- a/packages/core/agent-core/README.md
+++ b/packages/core/agent-core/README.md
@@ -2,7 +2,7 @@

 The **default executor-less, UI-less agent spine** as ONE Cordis bundle plugin. It loads the fixed set of services every harness agent needs, including the local skill provider, and forwards the loop's `agents` list as its own config — so an app package composes a working agent by adding only a front door and the swappable backends.

-This is the package to read to see **the whole plugin tree at once** — the teaching role the inlined `echo-agent` `cordis.yml` used to play before the spine moved behind this bundle.
+Read this package for the whole plugin tree and its composition order.

 ## The tree it loads

@@ -17,7 +17,7 @@ This is the package to read to see **the whole plugin tree at once** — the tea
@deepseek-ai/dsh-skill            skill provider registry
@deepseek-ai/dsh-skill-local      local filesystem skill provider
@deepseek-ai/dsh-agent            agent registry + agent/* event vocabulary
-@deepseek-ai/dsh-invariants       dev-mode event-contract assertions
+@deepseek-ai/dsh-invariants       runtime event-contract assertions
@deepseek-ai/dsh-tool-bash        the model-facing bash/bash_output/bash_kill schemas
@deepseek-ai/dsh-tool-skill       session-prefix skill catalog + model-facing loader schema
@deepseek-ai/dsh-agent-loop       THE concrete loop (gets the forwarded `agents`)
@@ -47,4 +47,13 @@ The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loo

 ## Why a code bundle, not a shared YAML include

-A YAML include can dedupe the config, but it cannot OWN a `bin`, and it can only *describe* the front-door coupling in a comment and trust each leaf to obey. Moving the spine into a package, and the front-door cluster into the app packages, means the default leaf for an ACP server has no logger entry to copy wrong — "the ACP app never logs to stdout" stops being a prose warning a leaf must remember and becomes the app package's default shape (a leaf can still add a sibling logger, so the rule stays documented — but it has nothing to get wrong by default). Services register in the root store keyed by their isolate symbol, so a child loaded here is visible to the bundle's siblings (the leaf's adapter and executor) exactly as a nested `plugin-include` subtree's services were — cordis gates every read on `inject`, never on load order.
+A YAML include can deduplicate config but cannot own a bin or provide front-door defaults. App packages make stdout-safe ACP wiring the default, though a leaf can still add an unsafe logger. Bundle children register services in the root isolate-keyed store, so injected leaf siblings see them without load-order coupling.
+
+## Model Experience
+
+Indirectly, through `dsh-system-prompt`, `dsh-tool-skill`, `dsh-tool-bash`, and `dsh-tools`, which this bundle mounts without adding model-bound wrapper content.
+
+## Known Limitations and Deferred Work
+
+- **The spine set is fixed in code** — `apply()` mounts every child unconditionally (including `tool-bash`); no config excludes or replaces one, so swapping the loop or dropping a spine member means composing a different bundle.
+- **`dsh-invariants` mounts unconditionally** — this bundle has no toggle, so every composition using it pays the dev-mode relational assertions; Session's always-on validation and freezing are separate.
--- a/packages/core/agent-core/package.json
+++ b/packages/core/agent-core/package.json
@@ -34,7 +34,7 @@
    "@deepseek-ai/dsh-tool-bash": "^0.0.1",
    "@deepseek-ai/dsh-tool-skill": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
    "@cordisjs/plugin-timer": "workspace:^",
@@ -49,7 +49,7 @@
    "@deepseek-ai/dsh-tool-bash": "workspace:^",
    "@deepseek-ai/dsh-tool-skill": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  },
  "dependencies": {
    "schemastery": "^3.18.0"
--- a/packages/core/agent-core/src/index.ts
+++ b/packages/core/agent-core/src/index.ts
@@ -1,47 +1,9 @@
 /**
- * The default executor-less, UI-less agent spine as ONE bundle plugin.
- *
- * Loads the fixed set of services every harness agent needs — `timer`, the LLM
- * service, the session store, system-prompt assembly, the tool registry, the
- * skill registry plus local skill provider, the agent registry, the dev-mode
- * invariants, the model-facing `bash` and `skill` tool schemas, and the concrete `agent-loop` — and forwards the loop's `agents`
- * list as its OWN config (default `[]`), so each app supplies its own
- * pre-created agents.
- *
- * It is deliberately NOT the whole app: the swappable choices stay OUTSIDE the
- * bundle, picked by whatever loads it.
- *  - the LLM ADAPTER (`llm-deepseek`/`llm-pi-ai`/`llm-replay`) — the bundle
- *    ships the abstract `llm` service + `tool-bash` consumer schema; the leaf
- *    registers a concrete adapter on `ctx.llm`.
- *  - the bash EXECUTOR (`bash-local` or a sandboxed impl) — the bundle ships
- *    the `bash` tool consumer; the leaf provides `ctx.bash`.
- *  - the PRESENTATION (stdio UI / ACP bridge / a logger) and the per-app infra
- *    (a console logger, `hmr`) — these are the coupled "front-door cluster" the
- *    app packages ({@link @deepseek-ai/dsh-stdio-agent},
- *    {@link @deepseek-ai/dsh-acp-agent}) bake in, NOT the shared spine.
- *  - additional SKILL PROVIDERS; the bundle ships the local filesystem provider
- *    because local skills are default agent behavior, while embedded or remote
- *    providers remain deployment choices.
- *
- * This is the interface/implementation/consumer seam at the composition level:
- * the bundle owns the shared spine, the leaf owns the backends, the app package
- * owns the front door. `timer` is in the spine (common to every front door — it
- * writes nothing to stdout); the console logger is NOT (it writes to stdout,
- * which the ACP bridge reserves for its JSON-RPC channel).
- *
- * Services register in the root store keyed by their isolate symbol, so a child
- * loaded here via `ctx.plugin(...)` is visible to the bundle's SIBLINGS (the
- * leaf's adapter and executor) exactly as a nested `plugin-include` subtree's
- * services were before this bundle existed — cordis gates every read on
- * `inject`, never on load order, so the fixed child set resolves regardless of
- * which entry loads first.
- *
- * Plugin export shape: named `name`/`Config`/`apply`, NO default export — the
- * cordis Loader's `unwrapExports` does `exports.default ?? exports`, so a stray
- * default would collapse the module to the bare `apply` function and drop the
- * `Config` schema (see docs/postmortem/0001). The keyless Loader-path smokes in
- * the app packages guard this end-to-end.
- *
+ * Default executor-less, UI-less agent spine. It bundles the common services,
+ * concrete loop, local skill provider, and model-facing bash/skill consumers;
+ * deployments still choose the LLM adapter, bash executor, and presentation.
+ * The plugin intentionally exposes named exports only because Loader default
+ * unwrapping would discard its `Config` schema (see docs/postmortem/0001).
 * @module @deepseek-ai/dsh-agent-core
 */

@@ -73,16 +35,13 @@ export interface SkillConfig {
 }

 /**
- * Bundle config: each field forwarded verbatim to the child that owns it —
- * `agents` to the agent loop (an app that pre-creates no agents, like the ACP
- * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
- * plugin (the deployment's persona section and the explicit model-facing tool
- * order), the `tools` object to the tool registry (its presentation `mode`),
- * and `skills` to the skill registry/local provider/tool consumer. Every field
- * is optional INPUT here because each owner's schema supplies the default;
- * the schema is the INTERSECTION of the owners' own schemas (with registry
- * schemas nested under their bundle keys), so validation and defaulting can
- * never drift from them.
+ * Bundle config: each field forwarded verbatim to the child that owns it — `agents` to the
+ * agent loop (an app that pre-creates no agents, like the ACP bridge, omits it),
+ * `persona` and `toolOrder` to the system-prompt plugin (the deployment's persona section and
+ * the explicit model-facing tool order), the `tools` object to the tool registry (its
+ * presentation `mode`), and `skills` to the skill registry/local provider/tool consumer.
+ * The schema intersects the owners' schemas, which supply defaults for every
+ * optional input and keep validation from drifting.
 */
 export interface Config {
  /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
@@ -124,12 +83,7 @@ export function apply(ctx: Context, config: Config): void {
  ctx.plugin(Timer)
  ctx.plugin(LlmService)
  ctx.plugin(SessionStore)
-  // The forwarded fields are validated + defaulted by this bundle's intersected
-  // schema before apply runs, so the ?? fallbacks only narrow the
-  // optional-input TYPES — they mirror the owners' schema defaults, never
-  // introduce different ones. toolOrder has no owner-supplied default value —
-  // ABSENT means "lexicographic order" — so it is forwarded conditionally
-  // rather than via ??.
+  // Owner schemas resolve defaults; forward toolOrder only when explicitly set.
  ctx.plugin(SystemPrompt, {
    persona: config.persona ?? '',
    ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
--- a/packages/core/agent-core/tests/agent-core.spec.ts
+++ b/packages/core/agent-core/tests/agent-core.spec.ts
@@ -187,15 +187,8 @@ describe('dsh-agent-core bundle', () => {
  })

  it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/Config/apply', () => {
-    // Postmortem 0001 guard: a stray `export default apply` makes the Loader's
-    // `unwrapExports` (`exports.default ?? exports`) collapse the module to the
-    // bare `apply` function, DROPPING the named `name`/`Config`. This package has
-    // no `inject` export (it mounts children that carry their own), so that
-    // collapse would NOT crash at load — the plugin would boot but silently lose
-    // its config schema. This bundle is also never Loader-unwrapped by any smoke
-    // (the apps import it directly; the mount test namespace-mounts it), so this
-    // is its ONLY export-shape guard. Assert directly AND through the real
-    // `unwrapExports` so adding `export default` to src/index.ts fails here.
+    // A default export would make `unwrapExports` collapse this inject-less namespace and silently
+    // drop `name`/`Config`. Apps import the bundle directly, so this is its Loader-shape guard.
    expect('default' in agentCore).toBe(false)
    expect(typeof agentCore.apply).toBe('function')

--- a/packages/core/agent-core/tests/gen-config-catalog.spec.ts
+++ b/packages/core/agent-core/tests/gen-config-catalog.spec.ts
@@ -1,18 +1,5 @@
 /**
 * Negative-path tests for the config catalog generator (`scripts/gen-config-catalog.ts`).
- *
- * The generated catalog is frozen by a regenerate-and-diff freshness gate, so
- * the freshness half is exercised by `pnpm run verify-config-catalog` in CI.
- * What a freshness diff CANNOT prove is that the generator REJECTS malformed
- * source the way it promises to — an unclassifiable package, an undocumented
- * config field, a schema key the config type does not declare, or a referenced
- * type name that resolves nowhere. These tests drive `collectConfigCatalog()`
- * against synthetic fixture packages to prove each guard fires (and that
- * well-formed packages classify and extract correctly), mirroring the
- * negative tests for gen-cordis-catalog. The spec lives in this package
- * because agent-core is the config-composition plugin (its schema is the
- * intersection of its children's), the shape the generator's cross-package
- * folding exists for.
 */

 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -1,6 +1,6 @@
 # dsh-agent-loop

-THE concrete agent plugin: `ReactLoopAgent` and the loop driver. Implements the `Agent` interface and drives the session/turn/step lifecycle.
+Concrete `ReactLoopAgent` implementation and loop driver.

 This is the only package in the harness that contains concrete loop logic. Everything else is an abstract service or a plugin against extension seams — new behavior goes into plugins, not here.

@@ -8,18 +8,16 @@ This is the only package in the harness that contains concrete loop logic. Every

 ### Public API

-Creation and resume are one rollback-covered transaction: construct a private session, concrete agent, and scoped context; await optional setup; enter both registries; announce `session/created` then `agent/created`; emit `agent/session-start`; and only then start the driver. Setup receives the full scoped `Context` as trusted same-process composition code and must not drive the unpublished agent. Ordinary typed identity and option inputs are borrowed under their readonly contract, while seed events and session metadata are validated and snapshotted because they cross the durable session boundary. An optional `AbortSignal` cancels only load/setup/publication and is detached before the returned handle becomes visible.
+Creation and resume use one caller-owned transaction: compose while unpublished, enter both registries, announce lifecycle edges, then start the driver. Failure rolls back private resources; caller, handle, and provider teardown share one quiescence boundary. The interface contract and ownership order live in [`dsh-agent`](../agent/README.md) and the [agent-scope runtime RFC](../../../docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md).

-The caller fiber and the AgentLoop provider are co-owners. `AgentFactory.createAgent(ownerCtx, options)` and `resume(ownerCtx, options)` receive caller ownership explicitly, while the factory keeps its own dependency context for `sessions`/`llm`/`tools`/`systemPrompt`; this lets a caller inject only `agents` without shrinking the new agent's service surface. Caller unload, handle disposal, or provider unload converge on one memoized quiescence boundary. Provider shutdown waits both resource teardown and the public create/resume wrapper that observed deactivation, so no continuation can publish after dependencies disappear.
+Caller-chosen ids arbitrate only at final registry entry, so concurrent contenders may prepare but every loser rolls back. Entry-bound detach capabilities cannot remove a later same-id replacement. Teardown stops and drains—including idle-injection flushes—before detaching agent, session, and scope; ids become reusable at detach.

-IDs are caller-chosen and assumed globally unique; accidental UUID collisions are outside the supported model. Two concurrent operations with the same agent or session id may both prepare, but the final `enter()` calls arbitrate publication and every loser rolls its private resources back. Each detach is bound to the exact entered object, so a stale disposer cannot remove a later same-id replacement. A detach requested during a synchronous creation notification waits for that dispatch to unwind, preserving created/disposed pairing. Teardown runs stop and drain (including outstanding idle-injection flushes) → detach agent → detach session → unwind scope; IDs become reusable at detach even if private scope cleanup is still finishing. Ordinary non-vetoing `agent/*` notifications go through `agentEvents(ctx, agent)`, per-step assembly goes through `assembleContextFor(agent)`, and turn-end durability checkpoints go through `ctx.sessions.flush(session)`.
-
- `ctx.agentLoop.create(id: string, options?: AgentOptions, meta?: { cwd?: string }): ReactLoopAgent` — synchronous no-setup create, used directly by programs and by `cordis.yml`-configured agents. It creates a fresh per-run session id `${id}-session-<uuid>` with optional metadata; the uuid avoids colliding with a prior durable log. Each call is a new session (a deliberate demo simplification — a real resume-or-create policy is a TODO). Disposed with the calling fiber.
+- `ctx.agentLoop.create(id, options?, meta?)` synchronously creates a caller-fiber-owned agent with a fresh generated session id and optional cwd. Each call starts a new session rather than applying resume-or-create policy.

 `AgentLoop` also implements the `AgentFactory` seam and registers itself via `ctx.agents.setFactory(this)`, so plugins create/resume agents through `ctx.agents` (the interface):

- `ctx.agents.create({ agentId, sessionId, meta?, seed?, agentOptions?, setup?, signal? }): Promise<AgentHandle>` — programmatic create on a caller-supplied `sessionId`, NOT `${id}-session`. It awaits the unpublished setup transaction before returning; `meta` carries cwd/lineage/seed-boundary metadata and `seed` reconstructs a forked child prefix after the session boundary validates and snapshots the durable values. `signal` applies only until this promise settles. The resolved [`AgentHandle`](../agent/README.md) owns exact teardown.
- `ctx.agents.resume({ agentId, resumeSessionId, agentOptions?, setup?, signal? }): Promise<AgentHandle>` — load a persisted session via `ctx.sessionPersistence` ([session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md)), reconstruct its history, then await setup against a fresh unpublished agent scope before rollback-covered publication. The live session id is the resumed id; turn numbering and derived history continue from the loaded log. Requires a session-persistence backend (NOT hard-injected — non-persistent demos still work; `resume` rejects with a clear error when persistence is absent). `signal` is creation-only. Returns an `AgentHandle`.
+- `ctx.agents.create({ agentId, sessionId, meta?, seed?, agentOptions?, setup?, signal? })` validates and snapshots durable seed and metadata, awaits optional composition while unpublished, creates on the supplied session id, and returns an owned [`AgentHandle`](../agent/README.md). Its signal applies only until publication.
+- `ctx.agents.resume({ agentId, resumeSessionId, agentOptions?, setup?, signal? })` loads through optional [session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md), continues stored history and turn numbering under the resumed session id, and follows the same unpublished setup and creation-only cancellation boundary. It rejects when no persistence backend is mounted.

 The config-driven `ctx.agentLoop.create()` path keeps its agent owned by the loop fiber (it discards the handle). For a programmatic agent, the handle holder is the only consumer-facing teardown capability; AgentLoop provider unload is the independent structural teardown edge, not another handle exposed to application code.

@@ -40,7 +38,7 @@ interface Config {
 }
 ```

-Agents listed in config are auto-created at startup. `cwd` applies only to fresh config-created sessions; `resumeSessionId` keeps the persisted session header. Config agents have no per-agent persona field: they use `dsh-system-prompt`'s deployment default, while programmatic factory callers can register an agent-scoped `deployment:persona` shadow in `setup`. The plugin registers the built-in `model`/`cwd` prompt variables on `ctx.systemPrompt`, resolved per step from `assembleContextFor(agent)` — the helper couples the typed agent with its matching scope selector. These are runtime facts of the agents THIS loop drives, unlike the `harness:identity` and default `deployment:persona` sections, which live on `dsh-system-prompt` so they survive a swapped loop plugin.
+Configured agents start automatically. `cwd` applies only to fresh sessions; `resumeSessionId` retains persisted metadata. They use the deployment persona. Programmatic setup can shadow it per agent. This plugin supplies the per-agent `model` and `cwd` prompt variables; harness identity and deployment persona belong to `dsh-system-prompt`.

 ### Exported concrete class

@@ -50,55 +48,11 @@ Agents listed in config are auto-created at startup. `cwd` applies only to fresh

 ### Loop lifecycle (`loop.ts`)

-The internal loop driver runs one agent for its whole lifetime:
+The driver owns one agent for its lifetime. It records turn, step, request, stream, and tool boundaries in the session log; live extension events coordinate policy around those durable facts. The [architecture turn flow](../../../docs/architecture.md#turn-flow) and generated [event catalog](../../../docs/cordis-catalog/events.md) are the authoritative sequence and signatures.

-```
-create agent → emit agent/session-start(source)   ⟵ once, before turn 1
-forever:
-  wait for queued messages (idle)
-  TURN (error-contained):
-    'turn/start'
-    each queued: waterfall agent/prompt-submit → allow (→ session('user/message'),
-      inject additionalContext) | block (→ session('prompt/blocked'), drop)
-    if every prompt blocked: 'turn/end'(rejected), no step  ⟵ zero-step turn
-    STEP loop:
-      drain steering
-      assembly = await systemPrompt.assemble(assembleContextFor(agent))
-                                                ⟵ renderPrompt(assembly) IS the full prompt
-      prefix ??= waterfall agent/session-prefix   ⟵ once per instance (first step): frozen
-                                                session prefix; on the header, never history
-      await serial agent/pre-step(…, prefix)  ⟵ surface mutation (compaction) outside the step;
-                                                pressure gates see the prefix the request carries
-      boundary = session.deriveMessages()   ⟵ reconstruction boundary: same sync frame,
-      session('step/start')                     strictly before step/start
-      config = waterfall agent/request       ⟵ frozen seed; return a replacement to switch
-      session('request/header'[-delta])      ⟵ the header event this request owes the log
-      stream llm.stream(freeze({header..., messages: prefix+boundary})) → session('assistant/chunk')
-      message = waterfall agent/step-result
-      session('assistant/message')
-      each tool-call: session('tool/call')
-        → tools.execute() [pre waterfall → monotonic guards → around dispatch → post waterfall → final notification]
-        → session('tool/result')
-      append buffered post-execute additionalContext as session('context/message')(s)
-      drain steering → session('steering/message')
-      cont = waterfall agent/turn-continuation → ContinuationDecision
-        ({action:'continue', reason?} records reason as next-step steering)
-      pending steering can override an ordinary stop
-      terminal = serial agent/turn-stop → ContinuationStop | undefined
-        (after ordinary decision/reason/steering folding)
-      if terminal stop, or ordinary action==stop with no pending steering: break
-    session('turn/end')
-    await session/flush
-    terminal turn: discard steering added before/during close and flush; keep ordinary queued sends
-    ordinary turn: re-enqueue leftover steering as queued
-  idle unless more queued
-```
+Plugin failure ends the current turn, not the loop. Cancellation clears pending work and aborts the current step without leaking to the next prompt. Terminal continuation stops remain authoritative through turn close and durability flush.

-Error containment: a throwing plugin ends the **turn**, never the loop. A throwing `agent/turn-stop` policy likewise fails the turn closed. A successful terminal stop stays authoritative through `turn/end` and `session/flush`, preventing their listeners from resurrecting steering through the late fallback. Dispose mid-turn emits `agent/status('disposed')` and ends with reason `disposed`. A step that hits the model's output-token ceiling makes the turn end `max-tokens` (the rule: any `max-tokens` step in the turn surfaces as `max-tokens`; `disposed`/`aborted`/`error` still take precedence) — distinct from a clean `completed` stop.
-
-Cancellation: `agent.cancel()` is the single public stop primitive — it clears the queued + steering FIFOs, aborts the in-flight step, and drives a turn-scoped marker the driver checks at every point a turn could start or continue (right after the idle wait, after the `running` flip, before each step, and at the continuation gate) so a turn about to start is dropped. A cancelled turn ends `aborted`; a queued-but-not-started prompt never runs and cannot be batched into the cancelled turn. The marker is reset once per loop iteration, so a cancel governs exactly one turn and never leaks onto a later prompt. (The loop still aborts its own per-step `AbortController` directly on disposal and from `cancel()`; that controller is loop-internal, not a public verb.)
-
-### What is NOT here
+### What belongs to plugins

 Everything that goes beyond "call the model, run the tools, repeat" belongs to plugins listening on the event taxonomy:
 - Hooks and policy: the relevant `agent/*` checkpoints plus the guarded `tools/pre-execute` → `tools/execute` → `tools/post-execute` → `tools/result` pipeline; exact signatures and modes live in the [generated event catalog](../../../docs/cordis-catalog/events.md)
@@ -107,3 +61,24 @@ Everything that goes beyond "call the model, run the tools, repeat" belongs to p
 - Sub-agents: implemented outside the loop as `ctx.subagents` providers; in-process providers use `ctx.agents.create()` and owned `AgentHandle` teardown, while child streaming/progress and background/poll collection remain deferred.
 - Persistence: `session/event` + `session/flush`
 - UI: `session/event` (assistant token stream, boundaries, tool activity) + `agent/*` control events (`agent/status`, `agent/created`/`agent/disposed`)
+
+## Model Experience
+
+### Complete conversation request
+
+**What the model sees**: For each step, the loop sends the rendered per-agent system prompt, visible tool schemas, the frozen session prefix, and the session's derived messages. It supplies `model` and `cwd` variable values but no additional fixed prose.
+
+**Token effect**: System text, schemas, and prefix are paid again on every step. Per-agent scoping chooses the initial contributions, while the authoritative assembly waterfall can alter the final request and makes its listener responsible for protocol coherence.
+
+### Retained message history
+
+**What the model sees**: Accepted user messages, assistant messages, tool calls and results, injected context, and steering are logged and sent on later steps. Raw stream chunks, lifecycle boundaries, and other log-only events are excluded.
+
+**Token effect**: Input grows with every surface message until a compaction replacement shadows older nodes; a multi-step tool turn resends the accumulated prefix and history each step.
+
+## Known Limitations and Deferred Work
+
+- **Tool calls within a step execute sequentially** — parallel execution waits on concurrency-safety metadata in the tool contract (see `dsh-tools`).
+- **No resume-or-create policy on the config path** — config-driven `create()` starts a fresh `${id}-session-<uuid>` every run (`TODO(demo)`), and a config `resumeSessionId` whose resume fails logs a warning and creates no agent.
+- **Config agents have no per-agent persona field or setup hook** — they use the deployment persona; scoped persona/tool composition is available only through the programmatic `ctx.agents.create()` / `resume()` factory options.
+- **No built-in turn budget** — the default continuation is `continue` whenever a step had tool calls or steering; bounding a runaway turn requires an `agent/turn-continuation` force-stop plugin.
--- a/packages/core/agent-loop/package.json
+++ b/packages/core/agent-loop/package.json
@@ -28,7 +28,7 @@
    "@deepseek-ai/dsh-session-persistence": "^0.0.1",
    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  },
  "dependencies": {
    "schemastery": "^3.18.0"
@@ -43,6 +43,6 @@
    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/core/agent-loop/src/agent.ts
+++ b/packages/core/agent-loop/src/agent.ts
@@ -48,10 +48,8 @@ export interface PreparedReactLoopAgent {
 }

 /**
- * Construct one concrete agent together with unforgeable, instance-bound
- * lifecycle controls. The package surface deliberately exposes neither source
- * subpaths nor this helper: setup code may identify the concrete class, but it
- * cannot publish or start the factory's unpublished instance.
+ * Construct an unpublished concrete agent with instance-bound lifecycle
+ * controls. Only those paired controls can publish or start this instance.
 * @param ctx - the agent-loop service context used for driving and events.
 * @param id - the concrete agent identity.
 * @param options - loop options for the agent.
@@ -131,16 +129,7 @@ export class ReactLoopAgent implements Agent {
   * leave it set to wrongly drop a later prompt.
   */
  private cancelRequested = false
-  /**
-   * The resolved reason for the pending {@link cancel} (`reason ?? 'cancelled'`),
-   * read by the driver loop's marker branches so a turn dropped in a
-   * marker-only window (pre-step / continuation, where no `AbortController`
-   * carries the reason) ends with the SAME `{kind:'aborted', reason}` the
-   * mid-step abort path produces from `abort.signal.reason`. Without this the
-   * caller's `cancel(reason)` would be silently replaced by the literal
-   * 'cancelled' whenever the cancel landed outside a running step — making the
-   * logged reason race-dependent and the public `reason?` param half-effective.
-   */
+  /** Pending cancellation reason, preserved even outside an active step signal. */
  private cancelReason = 'cancelled'
  private disposed: Promise<void>
  private resolveDisposed!: () => void
@@ -179,11 +168,7 @@ export class ReactLoopAgent implements Agent {
  private setStatus(status: AgentStatus): void {
    if (this._status === status || this._status === 'disposed') return
    this._status = status
-    // Release quiescence waiters on a transition OUT of running BEFORE emitting
-    // (the disposer handles the disposed transition separately). Settling first
-    // means a throwing `agent/status` subscriber cannot starve a `whenIdle()`
-    // waiter (docs/defensive-patterns.md "contain callback exceptions" — a lifecycle await must
-    // not hang on one bad listener).
+    // Settle first so a throwing status listener cannot starve quiescence waiters.
    if (status !== 'running') this.settleIdleWaiters()
    agentEvents(this.loopCtx, this).emit('agent/status', status)
  }
@@ -269,18 +254,8 @@ export class ReactLoopAgent implements Agent {
      // Decide the durability checkpoint from the log: an accepted one-shot
      // turn must be flushed even when its message append was the failing step.
      const turnRecorded = this.session.events.some(e => e.type === 'turn/start' && e.data.turn === turn)
-      // Checkpoint the one-shot turn for durability, exactly as the loop does at
-      // every turn/end. The loop is NOT running (we are idle), so nothing else
-      // will flush this turn. Fire-and-forget with error containment: inject()
-      // is synchronous, and a persistence backend failing must not throw into
-      // the caller (e.g. a tool-bash task-done callback). Disposal still drains
-      // independently, so a slow flush is safe. The task is tracked until it
-      // settles: driver disposal awaits every pending idle-injection checkpoint
-      // before unregistering the agent or detaching the session. A flush failure
-      // is reported via agent/error (step 0 — the idle-injection convention,
-      // there is no real step) AND the logger, mirroring the loop's post-turn/end
-      // flush path so plugins monitoring agent/error see idle-injection
-      // persistence failures too. A throwing agent/error listener is contained.
+      // Keep inject() synchronous: report checkpoint failures live instead of
+      // rejecting the caller, and track the task so disposal still drains it.
      if (turnRecorded) {
        // Through the store's flush (the carrier owner), never a raw parallel.
        const flush = this.loopCtx.sessions.flush(this.session).catch((error: unknown) => {
@@ -290,10 +265,7 @@ export class ReactLoopAgent implements Agent {
          agentEvents(this.loopCtx, this).emit('agent/error', turn, 0, err)
        })
        this.pendingIdleFlushes.add(flush)
-        // Attach the same retirement callback to both settlement arms so even a
-        // logger failure in the catch above cannot become an unhandled rejection.
-        // Teardown uses allSettled for the same reason: a reporting failure must
-        // not strand ownership.
+        // Retire on either settlement path.
        const retire = (): void => { this.pendingIdleFlushes.delete(flush) }
        void flush.then(retire, retire)
      }
@@ -301,15 +273,7 @@ export class ReactLoopAgent implements Agent {
  }

  cancel(reason?: string): void {
-    // Arm-gate: only mark a cancellation when there is actually work to cancel —
-    // a running turn, an in-flight step, or queued/steering work. An idle cancel
-    // with nothing pending is a true no-op; arming the marker then would wrongly
-    // drop the NEXT legitimate prompt (the marker is consumed only at the loop's
-    // turn-decision points, which an idle parked loop does not reach until woken
-    // by a real send()). Note the gate canNOT be `status === 'running'` alone:
-    // the pre-step window (a send() queued but the loop not yet flipped to
-    // running) has status `idle` with `hasQueued` true, and the marker exists
-    // precisely to cover it.
+    // Arm only for current work; an idle marker would cancel the next prompt.
    if (this._status === 'running' || this.currentAbort !== undefined || this.#inbox.hasQueued || this.#inbox.hasSteering) {
      this.cancelRequested = true
      // Capture the resolved reason for the marker-only windows (pre-step /
@@ -329,29 +293,14 @@ export class ReactLoopAgent implements Agent {
  }

  /**
-   * Resolve once the agent has reached quiescence after settling out of
-   * `running`. If it is already disposed, awaits {@link done} (the loop-exit
-   * promise) — `agent/status('disposed')` fires in the disposer BEFORE the
-   * driver loop has unwound, so it is NOT itself a quiescence signal. If it is
-   * idle AND has no queued work, resolves immediately. Otherwise queues an
-   * internal waiter (see {@link idleWaiters}) released on the next
-   * running→idle/disposed transition, resolving on `idle` directly (the turn
-   * fully ended) or chaining {@link done} on `disposed` (wait for the loop to
-   * actually exit). Implements the {@link Agent.whenIdle} contract: a non-owner
-   * quiescence-observation hook, distinct from teardown (a lifecycle owner stops
-   * and unregisters via `AgentHandle.dispose()`, whose driver boundary awaits
-   * both {@link done} and outstanding idle-injection flushes, not through this).
+   * Resolve immediately when idle with no queued work, on the next quiescent
+   * idle transition otherwise, or after driver exit when already disposed.
+   * This observes quiescence; it does not own teardown.
   */
  whenIdle(): Promise<void> {
    if (this._status === 'disposed') return this.done
    if (this._status !== 'running' && !this.#inbox.hasQueued) return Promise.resolve()
-    // Register an internal waiter (resolved by settleIdleWaiters on the next
-    // running→idle/disposed transition), NOT an effect-scoped `ctx.on` listener:
-    // a concurrent fiber disposal runs this agent's listener disposers, which
-    // could remove a `ctx.on` waiter before the `disposed` transition fires and
-    // hang the promise. On disposal the disposer settles the waiter AND we chain
-    // `done` here for true loop-exit quiescence (status flips to disposed before
-    // the loop unwinds); a plain idle transition resolves directly.
+    // Agent-owned waiters survive concurrent fiber disposal.
    return new Promise<void>((resolve) => {
      this.idleWaiters.push(() => {
        resolve(this._status === 'disposed' ? this.done : undefined)
@@ -387,12 +336,7 @@ export class ReactLoopAgent implements Agent {
      isCancelled: () => this.cancelRequested,
      cancelReason: () => this.cancelReason,
      clearCancel: () => { this.cancelRequested = false },
-      // Settle whenIdle() waiters WITHOUT a status transition — the pre-step
-      // cancel-skip path drops the about-to-run turn and re-parks without ever
-      // flipping running→idle, so a waiter registered in the pre-step window
-      // (status idle, hasQueued was true) would otherwise hang. This emits no
-      // agent/status, so an ACP agent/status listener never sees a spurious idle
-      // that would resolve a freshly-queued prompt as cancelled.
+      // Pre-step cancellation re-parks without emitting a status transition.
      settleIdle: () => { this.settleIdleWaiters() },
    })
  }
@@ -432,11 +376,8 @@ export class ReactLoopAgent implements Agent {
    // cleanup. The normal loop contains turn failures itself; allSettled is the
    // final lifecycle backstop for anything outside those boundaries.
    await Promise.allSettled([this.done])
-    // No new inject() can start after the synchronous disposed transition.
-    // Loop because settled tasks retire themselves in promise reactions that
-    // may run beside this continuation; either the set is empty or this waits
-    // the exact remaining quiescence boundary. allSettled keeps a failure in
-    // error reporting from skipping registry/session/scope disposers.
+    // Repeat because settled flushes retire in adjacent promise reactions;
+    // allSettled keeps reporting failures from skipping ownership teardown.
    while (this.pendingIdleFlushes.size > 0) {
      await Promise.allSettled([...this.pendingIdleFlushes])
    }
--- a/packages/core/agent-loop/src/index.ts
+++ b/packages/core/agent-loop/src/index.ts
@@ -74,12 +74,9 @@ function signalAbortError(id: AgentId, signal: AbortSignal): Error {
 }

 /**
- * One create/resume transaction from caller ownership through unpublished
- * setup, rollback-covered publication, and final quiescent teardown.
- *
- * The class deliberately owns the state machine in one place. Registries only
- * arbitrate identity at their final `enter()` calls; before that point every
- * resource is private to this transaction.
+ * Caller-owned create/resume transaction through rollback-covered publication
+ * and quiescent teardown. Resources remain private until the final registry
+ * entry arbitrates identity.
 */
 class AgentCreationTransaction {
  private active = true
--- a/packages/core/agent-loop/src/loop.ts
+++ b/packages/core/agent-loop/src/loop.ts
@@ -1,9 +1,7 @@
 /**
- * The agent loop driver: one `runLoop()` invocation drives one agent for its
- * whole lifetime. Error-contained at the turn level — a throwing plugin ends
- * the turn, never kills the loop. See the JSDoc on `runLoop()` for the full
- * lifecycle pseudo-code.
- *
+ * Drives one agent across queued durable turns. Turn failures are contained so
+ * later work can run; the session log, not this driver, owns conversation state.
+ * See docs/rfc/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md.
 * @module dsh-agent-loop/loop
 */

@@ -25,33 +23,12 @@ import type { Inbox } from './inbox.ts'
 /** An Error with an optional machine-readable code (e.g., from LlmError or a throwing plugin). */
 type CodedError = Error & { code?: string }

-/**
- * Normalize an arbitrary thrown value into a coded Error. A real Error passes
- * through (its `code`, if any, is preserved by {@link errorData}); a non-Error
- * throw is wrapped in a {@link HarnessError} with code `UNKNOWN` and the
- * original value chained as `cause`, so a bad throw still carries a routable
- * code instead of degrading to a bare message.
- */
+/** Normalize thrown values while preserving an existing error code. */
 function toError(error: unknown): CodedError {
  return error instanceof Error ? error : new HarnessError(String(error), 'UNKNOWN', { cause: error })
 }

-/**
- * Map a model-call {@link FinishReason} to the step error it should raise, or
- * `undefined` when the step completed normally.
- *
- * Adapters report provider/transport failures one of two sanctioned ways (see
- * the StreamChunk contract in dsh-llm): throw from `stream()` (handled by the
- * caller's try/catch), OR end the stream with a finish-error/aborted chunk
- * (the only option for adapters that can't throw mid-stream, e.g.
- * library-backed ones). This translates the latter into a thrown step error
- * so the turn ends error/aborted (the failure recorded on `turn/end.reason`),
- * never as a normal `completed` assistant message.
- *
- * `FinishReason` is merge-extensible (plugins/adapters can add `kind`s), so
- * the switch handles the known terminal-failure kinds and treats every other
- * kind — `stop`, `tool-calls`, `max-tokens`, future additions — as success.
- */
+/** Convert terminal failure finishes into step errors; unknown extensible finishes remain successful. */
 function finishError(finish: FinishReason): CodedError | undefined {
  switch (finish.kind) {
    case 'error': {
@@ -78,19 +55,7 @@ function errorData(err: CodedError): { message: string; code?: string } {
  return { message: err.message, ...typeof err.code === 'string' ? { code: err.code } : {} }
 }

-/**
- * The turn-end contribution of a step's *successful* finish, or `undefined`
- * when the step finished ordinarily (a plain `completed`).
- *
- * {@link finishError} has already converted `error`/`aborted` finishes into
- * thrown step errors, so the finishes that reach here are `stop`,
- * `tool-calls`, `max-tokens`, or a future merge-extensible kind. Only
- * `max-tokens` carries forward as a distinct {@link TurnEndReason}: a step that
- * hit the output-token ceiling ended the turn cut-short rather than by the
- * model's choice. `stop`/`tool-calls`/unknown kinds contribute nothing beyond
- * the default `completed`. {@link runTurn} applies this with the rule "any
- * `max-tokens` step in the turn makes the turn end `max-tokens`".
- */
+/** Map a successful max-token finish onto the turn reason; other successful finishes add nothing. */
 function stepFinishReason(finish: FinishReason): TurnEndReason | undefined {
  switch (finish.kind) {
    case 'max-tokens':
@@ -103,11 +68,7 @@ function stepFinishReason(finish: FinishReason): TurnEndReason | undefined {
  }
 }

-/**
- * Ambient handles the loop driver receives from the agent. Decouples the
- * pure function `runLoop` from the mutable ReactLoopAgent fields, making the
- * loop testable without a real agent.
- */
+/** Mutable agent controls supplied to the loop driver. */
 export interface LoopHandle {
  /** Native-private agent inbox handed to the driver only at internal startup. */
  readonly inbox: Inbox
@@ -116,122 +77,37 @@ export interface LoopHandle {
  /** Resolves when the agent is disposed — unblocks the idle wait. */
  disposed: Promise<void>
  isDisposed(): boolean
-  /**
-   * Whether a `cancel()` is pending for the current turn. The driver checks this
-   * at every decision point where a turn could start or continue (right after
-   * the idle wait, after the `running` flip, before each step, and at the
-   * continuation gate) and drops the about-to-run / continuing turn. Reset once
-   * per loop iteration via {@link clearCancel} after the turn returns, so the
-   * marker governs exactly one cancellation and never leaks to a later prompt.
-   */
+  /** Whether cancellation is pending for the current loop iteration. */
  isCancelled(): boolean
-  /**
-   * The resolved reason for the pending cancel (`reason ?? 'cancelled'`), read
-   * by the marker branches (pre-step / continuation) so a turn dropped where no
-   * `AbortController` carries the reason still records the caller's
-   * `cancel(reason)` value — matching the mid-step abort path. Only meaningful
-   * when {@link isCancelled} is true.
-   */
+  /** Resolved pending-cancellation reason; meaningful only while {@link isCancelled} is true. */
  cancelReason(): string
  /** Clear the cancel marker (called once per iteration after the turn returns). */
  clearCancel(): void
-  /**
-   * Settle pending `whenIdle()` waiters WITHOUT a status transition. Used by the
-   * pre-step cancel-skip path: it drops the about-to-run turn and re-parks at the
-   * idle wait, so no `running→idle` transition fires to settle a `whenIdle()`
-   * waiter that was registered in the pre-step window — this settles it directly
-   * (it emits no `agent/status`, so an ACP `agent/status` listener never sees a
-   * spurious idle that would resolve a freshly-queued prompt as cancelled).
-   */
+  /** Settle idle waiters when pre-running cancellation skips a turn, without emitting `agent/status`. */
  settleIdle(): void
 }

 /**
- * The agent loop. One invocation drives one agent for its whole lifetime:
- *
- * ```
- * create agent → emit agent/session-start(source)    ⟵ once, before turn 1
- * forever:
- *   wait for queued messages (idle)
- *   TURN (error-contained — a throwing plugin ends the turn, never the loop):
- *     'turn/start'; each queued msg: waterfall agent/prompt-submit    ⟵ durable turn boundary (no agent/* mirror)
- *       allow → session('user/message'…) (+ inject additionalContext) | block → drop
- *     every prompt blocked → 'turn/end'(rejected), 0 steps
- *     STEP loop:
- *       drain steering → session('steering/message')  ⟵ catches late steering
- *       assembly = ctx.systemPrompt.assemble(assembleContextFor(agent)) ⟵ waterfall system-prompt/assemble
- *                                                        (scope-filtered; scoped sections/tools join); renderPrompt
- *                                                        (persona section + {{variables}}) IS the full prompt
- *       prefix ??= waterfall agent/session-prefix    ⟵ once per loop instance (first step): frozen
- *                                                        session prefix; logged on the header, never
- *                                                        session history (scope-filtered, fused dispatch)
- *       await events.serial('agent/pre-step', …, prefix) ⟵ surface mutation (compaction) OUTSIDE the step;
- *                                                        pressure gates see the prefix the request carries
- *       boundary = session.deriveMessages()           ⟵ the reconstruction boundary: snapshot in the
- *       session('step/start')                            same sync frame, strictly before step/start
- *       config = waterfall agent/request(config)      ⟵ frozen seed; a returned replacement switches
- *       session('request/header'|'request/header-delta')  ⟵ the header event this request owes the
- *                                                        log (initial/resume anchor, delta, fallback)
- *       req = freeze({header..., messages: prefix+boundary, sessionId, signal})
- *       stream ctx.llm.stream(req)                    ⟵ waterfall llm/stream (raw chunks, frozen req)
- *         session('assistant/chunk')
- *       msg = waterfall agent/step-result             ⟵ BEFORE the log append, so the
- *       session('assistant/message' {content, usage?})   session records what actually ran
- *       each tool-call in msg (sequential, abort-checked):
- *         session('tool/call'); ctx.tools.execute()   ⟵ tools/pre-execute (allow/deny/ask)
- *                                                        → dispatch → tools/post-execute
- *         session('tool/result')
- *       append buffered post-execute additionalContext → session('context/message')(s)
- *       drain steering → session('steering/message')
- *       session('step/end')                           ⟵ durable step boundary (no agent/* mirror)
- *       cont = waterfall agent/turn-continuation       ⟵ ContinuationDecision; default
- *         {action: hadToolCalls||steered ? 'continue':'stop'}; a continue.reason is
- *         recorded as next-step steering
- *       if action==stop && steering arrived (step/end/continuation listeners): continue anyway
- *       terminal = serial agent/turn-stop              ⟵ stop or abstain; after all ordinary
- *                                                        continuation and steering folding
- *       if terminal: discard pending steering and break
- *       if action==stop: break
- *     session('turn/end')                             ⟵ durable turn boundary (no agent/* mirror)
- *     await ctx.sessions.flush(session)               ⟵ durability checkpoint (store-owned carrier)
- *     re-enqueue leftover steering as queued          ⟵ steering is never stranded
- *   idle (emit agent/status) unless more queued
- * ```
+ * Drive queued batches as durable turns until disposal. Plugin failures end the
+ * current turn without terminating the driver.
 * @param ctx - the plugin context the loop reaches events (agent/…, session/flush) and services (systemPrompt, llm, tools) through.
 * @param agent - the agent this invocation drives for its whole lifetime (its inbox, session, and options).
 * @param handle - the bridge to the agent's mutable state: status/abort setters plus the disposal and cancel-marker reads.
 */
 export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopHandle): Promise<void> {
-  // Per-instance transmission bookkeeping: whether THIS loop instance has
-  // anchored the log's header fold yet (its first request logs a
-  // 'initial'/'resume' request/header snapshot). Everything else the request
-  // needs is read from the session log itself — the loop holds no
-  // conversation state (the reconstructability RFC).
+  // Per-instance prefix and request-header state; conversation history remains in the session log.
  const transmission = createTransmissionLog()

  const { session } = agent
-  // The fused agent-subject dispatcher: every agent/* dispatch below carries
-  // the agent's scope (an `agent.ctx` listener hears only this agent) with
-  // the subject injected — one spelling, checked by the dev invariants.
+  // Fused subject and scope carrier for every agent event below.
  const events = agentEvents(ctx, agent)

  while (!handle.isDisposed()) {
    await handle.inbox.waitForQueued(handle.disposed)
    if (handle.isDisposed()) break

-    // Pre-step cancel (window 1): a `cancel()` landed after a `send()` woke the
-    // idle wait but before we flip to `running`. The cancelled queued/steering
-    // work is already cleared by `cancel()`. Clear the marker, then:
-    //   - if NOTHING new is queued, drop the about-to-run turn and re-park,
-    //     settling any `whenIdle()` waiter DIRECTLY (no running→idle transition
-    //     fires here to settle it) and WITHOUT emitting `agent/status` (an ACP
-    //     listener must not see a spurious idle that resolves a freshly-queued
-    //     prompt as cancelled);
-    //   - if a NEW prompt was queued AFTER the cancel (a send() that raced in
-    //     before the loop resumed), the marker was for the cancelled work only —
-    //     fall through and run the new prompt's turn. Do NOT settle waiters here:
-    //     a whenIdle() waiter must wait for that new turn's running→idle, not
-    //     resolve before it runs (the quiescence contract).
+    // Cancellation between wake and `running` skips only the cancelled work;
+    // a replacement prompt still runs and owns the eventual idle transition.
    if (handle.isCancelled()) {
      handle.clearCancel()
      if (!handle.inbox.hasQueued) {
@@ -242,18 +118,8 @@ export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopH

    handle.setStatus('running')

-    // Pre-step cancel (window 2): `setStatus('running')` emits `agent/status`
-    // SYNCHRONOUSLY, so a `running` listener can `cancel()` in the gap between the
-    // check above and `runTurn`. Mirror window 1: clear the marker, then
-    //   - if NOTHING new is queued, drop the about-to-run turn and transition
-    //     back to `idle` (`running` was already emitted, so a real idle
-    //     transition balances the status AND settles `whenIdle()` waiters);
-    //   - if a NEW prompt was queued AFTER the cancel (a `running` listener that
-    //     cancels then sends), the marker was for the cancelled work only — fall
-    //     through and run the new prompt's turn (status is already `running`), so
-    //     a `whenIdle()` waiter resolves on THAT turn's running→idle, not before
-    //     it runs. Settling here would resolve quiescence while the replacement
-    //     is still queued and unrun (the same early-resolve race window 1 fixes).
+    // A synchronous `running` listener can cancel before `runTurn`; balance the
+    // status only when no replacement prompt was queued by that listener.
    if (handle.isCancelled()) {
      handle.clearCancel()
      if (!handle.inbox.hasQueued) {
@@ -262,24 +128,13 @@ export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopH
      }
    }

-    // Re-derive the turn number from the log each iteration (do NOT keep a local
-    // counter): an idle `agent.inject()` can append its own one-shot turn while
-    // the loop waits above, so the next real turn must continue from whatever
-    // turn number is actually last in the log — a stale counter would collide.
+    // Idle injection can add a turn, so derive the next number from the log.
    const turn = lastTurnNumber(session) + 1
    let terminalStopped = false
    try {
      terminalStopped = await runTurn(ctx, events, agent, handle, turn, transmission)
    } catch (error: unknown) {
-      // Backstop: runTurn rethrows only a PRE-turn throw (the invariant guard
-      // before turn/start) — no turn/start was appended, so no turn is open and
-      // none is owed. A session `error` here would land outside any turn (after
-      // the previous turn/end), where the persistence backend drops it as a
-      // crash tail (the turn-enclosure RFC). Report via agent/error + the logger only; the
-      // driver survives and moves on.
-      // Acceptance and internal dispatch validation can reject before
-      // turn/start commits. Report that supported pre-turn failure without
-      // inventing a turn/end for a turn that never opened.
+      // Pre-turn failure has no durable boundary to close; report it without appending outside a turn.
      const err = toError(error)
      ctx.logger.warn(`agent "${agent.id}": turn ${turn} failed before it started: ${err.message}`)
      try {
@@ -287,21 +142,10 @@ export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopH
      } catch { /* contained: a throwing agent/error listener must not kill the driver */ }
    }

-    // Reset the cancel marker UNCONDITIONALLY here, after the turn returns and
-    // before the next iteration's idle wait. NOT gated on the idle transition
-    // below: a `send()` that lands during the cancelled turn's flush window makes
-    // `hasQueued` true at the `setStatus('idle')` guard, so an idle-gated reset
-    // would never fire and the stale marker would wrongly drop that next prompt's
-    // turn. Resetting per iteration scopes the marker to exactly the turn that was
-    // cancelled.
+    // Reset per iteration, including when a prompt arrives during the flush window.
    handle.clearCancel()

-    // Steering that arrived too late to join an ordinary turn (turn-end
-    // listeners, flush) becomes queued input so it is never stranded. A
-    // terminal-stop owner is the deliberate exception: discard the steering
-    // again after the close + flush window so terminal policy cannot be undone
-    // after its in-turn drain. Ordinary queued sends live in a separate FIFO and
-    // remain untouched.
+    // Late steering becomes queued input unless terminal policy stopped the turn.
    for (const message of handle.inbox.drainSteering()) {
      if (!terminalStopped) handle.inbox.enqueue(message)
    }
@@ -315,10 +159,7 @@ async function runTurn(
 ): Promise<boolean> {
  const { session } = agent

-  // --- Pre-turn. A throw here (the invariant guard) is owed NO turn/end —
-  // turn/start has not been appended — so it propagates to runLoop's backstop
-  // untouched. The queued messages are drained here but appended AFTER
-  // turn/start (below), so every event in the log lives inside a turn.
+  // Drain before opening the turn, but append only after `turn/start`.
  const queued = handle.inbox.drainQueued()
  const first = queued[0]
  /* v8 ignore next 3 -- invariant guard: runLoop only calls runTurn when hasQueued */
@@ -331,28 +172,17 @@ async function runTurn(
  let errorReported = false
  let terminalStopped = false

-  // Close the open step exactly once (idempotent via stepOpen). Post-commit
-  // session/event observers are contained by Session; a pre-commit validator
-  // failure still escapes so the outer recovery path may retry the boundary or
-  // fail loudly without pretending an uncommitted step/end exists.
+  // Close the committed step once; pre-commit validation failure still escapes.
  const closeStep = (): void => {
    if (!stepOpen) return
    session.append('step/end', { turn, step })
    stepOpen = false
  }

-  // Record a step/turn failure exactly once: set the error reason (carrying the
-  // failing `step` — the durable failure lives entirely on turn/end.reason, there
-  // is no separate session error event) and emit agent/error (contained — trap: a
-  // throwing agent/error listener must not re-escape and strand the turn).
-  // Disposal and abort set `reason` directly without calling this (they are not
-  // failures).
+  // Record the durable turn failure once and contain the live error notification.
  const failTurn = (err: CodedError): void => {
    if (errorReported) return
    errorReported = true
-    // The turn is still open here. Post-commit observers cannot escape append,
-    // and a pre-commit turn/end veto leaves no closing boundary to overwrite.
-    // Set the reason that the next successful closeTurn will append.
    reason = { kind: 'error', step, ...errorData(err) }
    try {
      events.emit('agent/error', turn, step, err)
@@ -362,9 +192,7 @@ async function runTurn(
    }
  }

-  // Close the turn. Post-commit observer failures are contained by Session;
-  // pre-commit validation failures escape to recovery instead of being mistaken
-  // for a committed boundary. Turn boundaries are durable session events only.
+  // Pre-commit validation failure escapes rather than masquerading as a committed boundary.
  const closeTurn = (): void => {
    session.append('turn/end', { turn, reason })
  }
@@ -414,11 +242,7 @@ async function runTurn(
    }

    while (true) {
-      // A fully-blocked batch (every prompt vetoed by prompt-submit) opens a
-      // zero-step turn that ends `rejected`: break BEFORE the first step so the
-      // boundary stays balanced (turn/start → turn/end) and the block is a
-      // durable in-turn fact. `anyAllowed` never changes inside the loop, so this
-      // only ever fires on the first iteration.
+      // A fully blocked batch closes its zero-step turn as rejected.
      if (!anyAllowed) {
        reason = { kind: 'rejected', reason: lastBlockReason }
        break
@@ -437,48 +261,20 @@ async function runTurn(
      const abort = new AbortController()
      handle.setAbort(abort)

-      // Assemble the system prompt for this step. Done HERE (before step/start)
-      // because the pre-step seam needs it: compaction measures token pressure
-      // against the system prompt (it counts toward the budget). runStep reuses
-      // this same assembly for the request, so the prompt is assembled once per
-      // step. renderPrompt IS the full prompt — the persona is the order-0
-      // section (owned by dsh-system-prompt) and `{{variable}}`
-      // interpolation happens in the render, so there is no separate join.
+      // Assemble once before pre-step so pressure checks and the request share the same prompt.
      const assembly = await ctx.systemPrompt.assemble(assembleContextFor(agent))
      const fullSystemPrompt = renderPrompt(assembly)

-      // Interruption landing after assembly: dispose() or cancel() in a
-      // turn-start listener (or a listener whose promise resolved before the
-      // await above) arms either handle.isDisposed() or handle.isCancelled().
-      // The Abort was created first, so any concurrent abort also lands on it.
-      // Drop the about-to-start step WITHOUT running the seam — no step is open
-      // yet, so end the turn accordingly (disposed wins for an unambiguous
-      // reason).
+      // Cancellation or disposal during assembly ends the turn before any step opens.
      if (handle.isCancelled() || handle.isDisposed()) {
        handle.setAbort(undefined)
        reason = handle.isDisposed() ? { kind: 'disposed' } : { kind: 'aborted', reason: handle.cancelReason() }
        break
      }

-      // Compose the session prefix ONCE per loop instance, lazily before the
-      // instance's first pre-step: request-only messages placed in front of
-      // the ENTIRE derived history on every request this instance sends. It
-      // MUST precede the pre-step seam so compaction gates on THIS instance's
-      // prefix — reading a previous instance's logged prefix would let a
-      // resumed/forked instance whose contributor grew skip compaction and
-      // ship an over-window first request. The result is deep-cloned
-      // (decoupled from listener-held references), deep-frozen, and cached on
-      // the transmission bookkeeping, so reuse is structural — the prefix
-      // cannot change mid-session and the provider prefix cache holds by
-      // construction (resume = a new instance = a recompose, anchored by its
-      // 'resume' snapshot). The prefix is not session history — the header
-      // event in runStep is its only durable record
-      // (EpochHeader.messagePrefix). The frozen empty seed serves both the
-      // listener chain and the no-listener fallback: a contribution is a
-      // RETURNED extension of `await next()`, never an in-place push. This
-      // runs OUTSIDE the step, before the boundary snapshot: a composing
-      // listener's session append lands before the boundary and joins the
-      // CURRENT request.
+      // Compose the request-only prefix once per loop instance before pressure
+      // checks. It precedes all derived history and is recorded only in the
+      // request header, not as session history.
      if (transmission.sessionPrefix === undefined) {
        const emptyPrefix: Message[] = deepFreeze([])
        const composed = await events.waterfall(
@@ -486,16 +282,7 @@ async function runTurn(
          () => Promise.resolve(emptyPrefix),
        )

-        // Interruption landing during prefix composition: mirror the assembly
-        // window above — drop the about-to-start step without running the
-        // seam, and DISCARD the composition instead of caching it. An
-        // abort-aware listener may have returned a degraded fallback under
-        // the firing signal; committing it would ship a prefix no request
-        // ever used (and no header ever logged) on this instance's next real
-        // request. The next turn recomposes under a live signal — the cache
-        // only ever holds a fully composed prefix. The cache-hit path needs
-        // no such check: nothing awaits between the assembly check above and
-        // the pre-step seam.
+        // Never cache an interrupted composition; the next turn recomposes it.
        if (handle.isCancelled() || handle.isDisposed()) {
          handle.setAbort(undefined)
          reason = handle.isDisposed() ? { kind: 'disposed' } : { kind: 'aborted', reason: handle.cancelReason() }
@@ -504,19 +291,7 @@ async function runTurn(
        transmission.sessionPrefix = deepFreeze(structuredClone(composed))
      }

-      // Pre-step surface-mutation checkpoint (compaction), fired OUTSIDE the
-      // step: after `turn/start` (and the prior step's close) but before
-      // `step/start`, so a compaction's log-only `compact/*` records and its
-      // replacement node land cleanly outside any step (honest structure that
-      // crash-safety relies on — a dangling `compact/start` sits before the
-      // synthetic `turn/end` repair appends). Serial (awaited, in order, no
-      // veto): each listener completes its surface mutation before the next, so
-      // concurrent listeners cannot interleave their `session.append`s. A
-      // throwing listener escapes to the outer catch, which closes the (not-yet-
-      // open) step as a no-op and ends the turn via failTurn — a broken
-      // pre-step plugin ends the turn, not the loop. The composed session
-      // prefix rides along so token-pressure listeners count everything the
-      // request will actually carry.
+      // Await surface mutations outside the step; pressure checks receive the pending prefix.
      await events.serial('agent/pre-step', turn, step, fullSystemPrompt, transmission.sessionPrefix, abort.signal)

      // Interruption landing during the pre-step seam: do not open an empty step.
@@ -526,16 +301,8 @@ async function runTurn(
        break
      }

-      // The reconstruction boundary (the reconstructability RFC): the request's
-      // messages are snapshotted HERE, in the same synchronous frame as the
-      // step/start append directly below — so the snapshot is exactly the
-      // derivation over the log prefix strictly before step/start's seq.
-      // Anything appended later by the request-window inject seam or a
-      // concurrent task lands after the boundary and joins the NEXT request.
-      // session/event itself is observe-only: append reentrancy is rejected
-      // until the current callback list drains. An external reconstructor
-      // recovers these exact messages by folding the surface over
-      // events[0..stepStartSeq).
+      // Snapshot the exact log prefix before step/start: the reconstruction
+      // boundary. Appends after this synchronous snapshot join the next request.
      const boundaryMessages = session.deriveMessages()

      session.append('step/start', { turn, step })
@@ -582,13 +349,7 @@ async function runTurn(
        break
      }

-      // The successful step's finish reason carries forward: a `max-tokens`
-      // step makes the whole turn end `max-tokens` (the ACP RFC's rule "any
-      // max-tokens step surfaces as max-tokens"). `stepFinishReason` returns
-      // `max-tokens` or `undefined`, so a later ordinary step never resets a
-      // max-tokens turn back to completed, and a never-truncated turn keeps the
-      // default `completed`. The disposal/abort/error branches above and the
-      // continuation-window disposal check below override this — they win.
+      // Preserve max-token completion unless a later disposal, abort, or error wins.
      const stepReason = stepFinishReason(stepOutcome.finish)
      if (stepReason) reason = stepReason

@@ -610,24 +371,16 @@ async function runTurn(
        break
      }

-      // A forced `continue` may carry model-facing context: record it as
-      // next-STEP steering (the steering channel), so the continued turn's next
-      // iteration drains it before its request — the typed twin of the /goal
-      // step/end-steer pattern.
+      // A continuation reason becomes next-step steering.
      if (decision.action === 'continue' && decision.reason) {
        handle.inbox.steer({ content: decision.reason.content, source: decision.reason.source })
      }
      let shouldContinue = decision.action === 'continue'

-      // Steering from step/end session-event or continuation listeners (the
-      // /goal pattern) demands the model see it — it overrides a stop decision;
-      // the next iteration's drain records it.
+      // Pending steering overrides an ordinary stop.
      if (!shouldContinue && handle.inbox.hasSteering) shouldContinue = true

-      // Terminal policy runs only AFTER the extensible continuation waterfall,
-      // its optional reason, and late steering have all been folded. Unlike the
-      // waterfall, this serial seam is monotonic: the first stop bail wins, and
-      // no later listener or steering override can resurrect the turn.
+      // Terminal policy is monotonic and runs after ordinary continuation folding.
      let terminalStop = false
      try {
        const stop = await events.serial('agent/turn-stop', turn)
@@ -640,19 +393,12 @@ async function runTurn(
      }
      if (terminalStop) {
        terminalStopped = true
-        // A continuation reason or listener may have queued steering before the
-        // terminal checkpoint. Discard only steering (never ordinary queued
-        // prompts) so it cannot become a next step or be re-enqueued as a fresh
-        // turn by runLoop's late-steering fallback.
+        // Terminal stop discards steering but preserves ordinary queued prompts.
        handle.inbox.drainSteering()
        shouldContinue = false
      }

-      // A cancel that landed during the continuation window — after the step's
-      // AbortController was cleared (setAbort(undefined)) but before the next
-      // step starts — has no controller to observe it, so the turn-scoped marker
-      // ends the turn here. cancel() also cleared the steering FIFO, so the
-      // override above did not re-arm continuation.
+      // The marker catches cancellation after the step controller was cleared.
      if (handle.isCancelled()) {
        reason = { kind: 'aborted', reason: handle.cancelReason() }
        break
@@ -668,19 +414,11 @@ async function runTurn(
    // Normal / inline-error loop exit: close the turn.
    closeTurn()
  } catch (error: unknown) {
-    // Decide whether this turn opened from the LOG, not a speculative flag. A
-    // pre-commit validator or acceptance failure leaves no turn/start and owes
-    // no turn/end, so it propagates to runLoop's backstop. Once turn/start is
-    // present, this path balances any committed step and records the failure.
+    // Close only a turn whose start committed to the log.
    const turnStartLogged = session.events.some(e => e.type === 'turn/start' && e.data.turn === turn)
    if (!turnStartLogged) throw error
    closeStep()
-    // Choose the close reason. Disposal wins only if no error was already
-    // reported: a turn disposed mid-step sets reason=disposed in the step-error
-    // branch (without reporting an error), so preserve disposed rather than
-    // overwrite it. Otherwise a mid-step throw on a live agent is a real
-    // failure → failTurn. (errorReported is mutated only inside the failTurn
-    // closure, which the analyzer can't follow, hence the inline lint-disable.)
+    // Preserve an established disposal reason; otherwise report the failure.
    if (handle.isDisposed() && !errorReported) { // eslint-disable-line @typescript-eslint/no-unnecessary-condition
      reason = { kind: 'disposed' }
    } else {
@@ -689,19 +427,11 @@ async function runTurn(
    closeTurn()
  }

-  // Durability checkpoint: persistence plugins drain write-behind buffers.
-  // A failing persistence plugin is reported but doesn't kill the agent.
-  // Through the store's flush (the carrier owner), never a raw parallel.
+  // Flush through the store-owned durability checkpoint without killing the driver on failure.
  try {
    await ctx.sessions.flush(session)
  } catch (error: unknown) {
-    // The turn is already closed (turn/end appended above) and flush must run
-    // AFTER turn/end to be a checkpoint — so there is no in-turn position left
-    // for a session `error` event. Appending one here would land it after the
-    // last turn/end, where the persistence backend treats it as a crash tail
-    // and drops it on resume (the turn-enclosure RFC: every event is turn-enclosed). Report
-    // the failure via agent/error + the logger only; persistence keeps the
-    // buffered events for the next flush/dispose, so nothing is lost.
+    // The turn is closed, so report the failed flush live rather than append outside a turn.
    const err = toError(error)
    ctx.logger.warn(`agent "${agent.id}": session/flush failed at turn ${turn}: ${err.message}`)
    try {
@@ -722,13 +452,12 @@ function drainSteering(agent: ReactLoopAgent, inbox: Inbox, turn: number): boole
  return messages.length > 0
 }

-/** One step: build the request from the boundary snapshot + the step's
- * header → compose the session prefix if this instance has none yet → log
- * the header event the request owes → stream model → record → execute
- * tools. The caller assembles the
- * system prompt, fires the `agent/pre-step` seam, snapshots the derivation,
- * and opens the step BEFORE calling this, so `boundaryMessages` is exactly
- * the surface prefix at step/start and already reflects any compaction. */
+/**
+ * Run one committed step: transform call config, log the request header, build
+ * the request from the cached prefix plus the step-boundary snapshot, stream and
+ * record the response, then execute tools. The caller has already assembled the
+ * prompt, run `agent/pre-step`, snapshotted history, and opened the step.
+ */
 async function runStep(
  ctx: Context,
  events: AgentEventDispatch,
@@ -743,40 +472,23 @@ async function runStep(
 ): Promise<{ hadToolCalls: boolean; finish: FinishReason }> {
  const { session, options } = agent

-  // Seed the call config: the first request of THIS loop instance seeds from
-  // current AgentOptions — explicit options always win over the logged
-  // baseline, which is what keeps fork model-overrides and resume-time
-  // reconfiguration correct. Later steps seed from the log's folded header,
-  // which by then is exactly what this instance last logged.
-  // One deep-cloned, frozen seed serves BOTH the listener chain and the
-  // no-listener fallback: structuredClone decouples it from the session's
-  // cached header fold (a raw reference would let a delegating listener
-  // mutate the fold in place and silently skip the delta log), and the freeze
-  // makes in-place shaping unrepresentable — a switch is a RETURNED
-  // replacement, which the header event below records.
+  // Seed the first request from agent options and later requests from the logged header;
+  // detach and freeze so listeners must return an attributable replacement.
  const seedConfig: LlmCallConfig = deepFreeze(structuredClone(transmission.loggedHeader
    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- loggedHeader ⟹ a snapshot is in the log
    ? session.requestHeader()!.config
    : { model: options.model ?? '' }))

-  // Shape the call config: listeners return a replacement to switch model or
-  // sampling (the seed is frozen — content shaping is not expressible here;
-  // model-visible content flows through the log channels). The header event
-  // below records whatever the request ACTUALLY uses, so a listener's switch
-  // is a logged, reconstructable fact, never silent drift.
+  // Listener replacements are recorded in the request header before dispatch.
  const config = await events.waterfall('agent/request', turn, step, seedConfig, () => Promise.resolve(seedConfig))
  if (!config.model) {
    throw new Error(`agent "${agent.id}" has no model: set AgentOptions.model or supply one via the agent/request waterfall`)
  }

-  // The session prefix was composed (once per instance) before this step's
-  // pre-step seam — the caller guarantees it, so the cache is always set here.
  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- runTurn composes the prefix before every runStep call
  const sessionPrefix = transmission.sessionPrefix!

-  // The request header (the log's request/header* vocabulary): canonical form,
-  // recorded before dispatch so the log always explains the request —
-  // including the session prefix, which no other event carries.
+  // Record the canonical header, including the otherwise-unlogged prefix, before dispatch.
  const header = canonicalHeader({
    config,
    ...system ? { system } : {},
@@ -785,11 +497,7 @@ async function runStep(
  })
  recordRequestHeader(session, transmission, header)

-  // Build and freeze: the request is a pure function of (boundary snapshot,
-  // logged header) — llm/stream listeners and adapters read it, mutation
-  // throws. sessionId + frozen is the loop-built marker the dev invariant
-  // keys on. Message order: header.messagePrefix, then the boundary
-  // snapshot — the reconstruction equation the invariant recomputes.
+  // Freeze the logged header plus boundary snapshot; the prefix precedes derived history.
  const request: GenerateOptions = deepFreeze({
    model: header.config.model,
    messages: [...header.messagePrefix ?? [], ...boundaryMessages],
@@ -813,26 +521,16 @@ async function runStep(
    assembler.push(chunk)
  }

-  // Adapters report provider/transport failures one of two sanctioned ways
-  // (see the StreamChunk contract in dsh-llm): throw from stream() — already
-  // handled by the caller's try/catch — OR end the stream with a
-  // finish-error/aborted chunk. finishError() maps the latter to the step
-  // error to raise (turn ends error/aborted, not a normal completed message).
+  // Normalize failure finish chunks into the same path as thrown stream errors.
  const stepError = finishError(assembler.finish)
  if (stepError) throw stepError

  if (assembler.finish.kind === 'max-tokens') {
    let message: Message = withoutToolCalls(assembler.message())
    message = withoutToolCalls(await events.waterfall('agent/step-result', turn, step, message, () => Promise.resolve(message)))
-    // Fire the assistant/message when there is content OR usage: a max-tokens
-    // step can be cut off with empty content but still carry token accounting,
-    // and assistant/message is the only host for usage (there is no standalone
-    // usage event). An empty-content assistant/message is skipped by
-    // deriveMessages(), so hosting usage on it never injects a spurious assistant
-    // turn into derived history.
+    // Preserve usage even when max-token truncation produced no content.
    if (message.content.length > 0 || assembler.usage) {
-      // A max-tokens finish is itself a streamed `finish` chunk, so chunkSeqs is
-      // never empty here — pass the provenance unconditionally.
+      // The finish chunk guarantees non-empty provenance here.
      session.append(
        'assistant/message',
        { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) },
@@ -842,20 +540,11 @@ async function runStep(
    return { hadToolCalls: false, finish: assembler.finish }
  }

-  // The step-result waterfall runs BEFORE the session append so the log (the
-  // source of truth for derived history and replay) records the message that
-  // tool dispatch actually uses.
+  // Record the post-waterfall message that tool dispatch uses.
  let message: Message = assembler.message()
  message = await events.waterfall('agent/step-result', turn, step, message, () => Promise.resolve(message))

-  // Same content-or-usage guard as the max-tokens branch: a step that finishes
-  // with neither assembled content nor usage (e.g. a bare `stop` finish that
-  // streamed nothing) records no assistant/message — an empty-content message
-  // exists only to host usage, and deriveMessages() skips it either way, so
-  // appending one with no usage would be a pure trace-only row.
-  //
-  // sourceEventSeqs records the assistant/chunk provenance, but is omitted when
-  // no chunks streamed (the surface invariant rejects an empty sourceEventSeqs).
+  // Empty messages exist only to carry usage; omit empty provenance.
  if (message.content.length > 0 || assembler.usage) {
    session.append(
      'assistant/message',
@@ -864,15 +553,9 @@ async function runStep(
    )
  }

-  // --- Tool execution (sequential; parallel execution is a TODO) ---
-  // ToolRegistry.execute converts tool failures (including aborts) into
-  // isError results, so abort is re-checked around every call here.
+  // Tool execution stays sequential; recheck abort around each normalized result.
  const toolCalls = message.content.filter(block => block.type === 'tool-call')
-  // Per-step buffer of `additionalContext` attached by tools/post-execute
-  // listeners. Appended as context/message(s) only AFTER every tool/result for
-  // the step, so a multi-call step keeps tool-call/result adjacency
-  // (interleaving context between a call's result and the next call's would
-  // break the pairing the next model request relies on).
+  // Buffer context until all results are appended to preserve call/result adjacency.
  const pendingContext: HookContext[] = []
  for (const call of toolCalls) {
    /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */
@@ -884,12 +567,8 @@ async function runStep(
    } catch {
      parsedArguments = call.arguments
    }
-    // TODO(pre-tool-input-rewrite): tools/pre-execute deliberately cannot rewrite
-    // `arguments` — tool/call (the audit record) and assistant/message (the
-    // model-history source) are logged BEFORE execute, and live consumers (ACP,
-    // tool-bash presentation) read the pre-execution args, so an execution-only
-    // rewrite would desync the UI from what ran. Designing that consistently is
-    // its own proposed RFC (docs/rfc/proposed/feature/…-pre-tool-input-rewrite.md).
+    // TODO(pre-tool-input-rewrite): Keep logged history and live presentation aligned;
+    // see docs/rfc/proposed/feature/2026-06-30-pre-tool-input-rewrite.md.
    const result = await ctx.tools.execute({
      callId: call.id,
      name: call.name,
@@ -899,33 +578,24 @@ async function runStep(
    })
    session.append('tool/result', {
      turn, step,
-      // The correlation id MUST be the loop's authoritative call.id (the
-      // model-transcript id that deriveMessages turns into toolCallId), NOT
-      // result.callId — a post-execute waterfall listener returning a
-      // mismatched id would otherwise orphan the call↔result pairing in the
-      // next model request. A listener-internal id, if ever needed, belongs in
-      // a separate diagnostic field, never overloaded onto callId.
+      // Correlation comes from the immutable execution input; the result does
+      // not duplicate this authoritative transcript identity.
      callId: call.id,
      content: result.content,
      isError: result.isError,
      ...result.error ? { error: result.error } : {},
-      // The tool's private presentation payload (e.g. a result-time diff),
-      // persisted so a UI bridge reproduces the card on replay.
+      // Persist tool-owned presentation data for replay.
      ...result.meta !== undefined ? { meta: result.meta } : {},
    }, { surfaceOp: 'append', sourceEventSeqs: [callEvent.seq] })
-    // Buffer (don't append yet) any post-execute additionalContext for this call.
    if (result.additionalContext) pendingContext.push(result.additionalContext)
-    // signal CAN flip during the await above (abort() inside a tool);
-    // the analyzer can't see through the await boundary.
+    // The signal may flip while the tool is awaited.
    /* v8 ignore start -- signal.reason default unreachable: cancel()/disposal always set it */
    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
    if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
    /* v8 ignore stop */
  }

-  // Append buffered post-execute context AFTER every tool/result, preserving
-  // tool-call/result adjacency across the whole batch. inject() appends into the
-  // open turn (a context/message at its chronological position).
+  // Append buffered context after the complete result batch.
  for (const context of pendingContext) {
    agent.inject(context.content, { source: context.source })
  }
@@ -948,13 +618,8 @@ export function lastTurnNumber(session: Session): number {
 }

 /**
- * Whether a turn is currently open in the session log (a `turn/start` with no
- * matching later `turn/end`). Decided from the LOG, not agent status: status
- * can be `running` while no turn is open (an `agent/status` listener firing
- * before `turn/start`, or the post-`turn/end` flush window before status
- * returns to idle), so status is not a reliable open-turn signal. Used by
- * `inject()` to choose between appending into an open turn vs. wrapping the
- * injection in its own one-shot turn (the turn-enclosure RFC).
+ * Whether the session log has an unmatched `turn/start`. Agent status is not
+ * sufficient during pre-start and post-end windows.
 * @param session - the session whose log is inspected.
 * @returns true when the log's last turn boundary is a `turn/start` with no matching `turn/end` yet.
 */
--- a/packages/core/agent-loop/src/request-log.ts
+++ b/packages/core/agent-loop/src/request-log.ts
@@ -1,12 +1,7 @@
 /**
- * Per-loop-instance transmission bookkeeping for the reconstructability
- * contract: which header event to append before a request so the session log
- * always explains the request (the reconstructability RFC). The loop is
- * otherwise transmission-stateless — the comparison baseline is the log's own
- * folded header (`Session.requestHeader()`), so resume and fork need no
- * special path: a fresh loop instance simply logs a `'resume'` snapshot on
- * its first request and deltas from there.
- *
+ * Per-loop-instance request-header bookkeeping for reconstructability. The
+ * comparison baseline is the header folded from the session log, so a fresh
+ * loop instance needs no special resume or fork state.
 * @module dsh-agent-loop/request-log
 */

@@ -37,22 +32,10 @@ export function createTransmissionLog(): TransmissionLog {
 }

 /**
- * Append whatever header event this request owes the log, so folding the log
- * reproduces the header the request was built under. Exactly one of four
- * things happens:
- *
- * 1. This loop instance has not logged a header yet → a full `request/header`
- *    snapshot anchors the fold: reason `'initial'` when the log has no header
- *    events at all (a new conversation), `'resume'` when it does (process
- *    restart, fork seed — the boundary itself is a recorded fact, so the
- *    snapshot is appended even when nothing changed).
- * 2. The header equals the folded baseline → nothing; the log already
- *    explains this request.
- * 3. It differs and the delta round-trips (`applyHeaderDelta` on the baseline
- *    reproduces the header exactly) → a `request/header-delta`.
- * 4. It differs and the delta encoding cannot express the change (a pure tool
- *    reordering) → a full snapshot with reason `'fallback'`; deltas are an
- *    encoding optimization, never a correctness dependency.
+ * Append whatever header event makes the log reproduce this request's header.
+ * The first request from an instance always records a full `initial` or `resume`
+ * snapshot. Later requests record nothing when unchanged, a round-tripping
+ * delta when expressible, or a full `fallback` snapshot otherwise.
 *
 * @param session - the session whose log explains the request.
 * @param state - this loop instance's bookkeeping (mutated on first log).
--- a/packages/core/agent-loop/tests/agent.spec.ts
+++ b/packages/core/agent-loop/tests/agent.spec.ts
@@ -167,10 +167,8 @@ describe('ReactLoopAgent', () => {
    let flushes = 0
    ctx.on('session/flush', () => { flushes += 1 })

-    // Non-serializable injected content makes Session.append throw AFTER
-    // turn/start was recorded. The turn/end must still be appended (finally),
-    // AND the durability checkpoint must still fire — the balanced turn is in
-    // memory and a crash before the next turn/dispose would otherwise lose it.
+    // Invalid injected content throws after turn/start. `finally` must still append turn/end and
+    // flush the balanced in-memory turn so a crash cannot lose it before the next checkpoint.
    expect(() => {
      agent.inject([{ type: 'text', text: 'x', bad: 1n } as never], { source: { kind: 'plugin', plugin: 'p' } })
    }).toThrow(/non-JSON-serializable/)
@@ -252,26 +250,20 @@ describe('ReactLoopAgent', () => {
  })

  it('disposer is idempotent (double-stop)', async () => {
-    // Create a bare ReactLoopAgent and start it through the package-internal
-    // test seam. Then call its disposer twice — the second call hits the
-    // early-return branch.
+    // The internal start seam exposes one idle driver's disposer for repeated invocation.
    const ctx = new Context()
    await ctx.plugin(SessionStore)
    const session = ctx.sessions.create(SessionId('test'))
    const prepared = prepareReactLoopAgent(ctx, AgentId('bare'), { model: 'mock' }, session)
    const { agent } = prepared

-    // Start the loop to get the disposer; the agent waits for messages
-    // (idle, never-resolving cancel), so it will stay idle.
    prepared.markPublished()
    const dispose = prepared.startDriver()

-    // First dispose
    const firstDisposal = dispose()
    expect(agent.status).toBe('disposed')
    await firstDisposal

-    // Second dispose — idempotent, no throw
    await expect(dispose()).resolves.toBeUndefined()
    expect(agent.status).toBe('disposed')
  })
@@ -366,10 +358,8 @@ describe('ReactLoopAgent', () => {
  })

  it('whenIdle() subscribed while running resolves via done when the agent is then disposed', async () => {
-    // Covers the waiter's disposed arm: whenIdle() queues an internal waiter
-    // while running (not the fast path), then the disposer settles it and chains
-    // `done` (loop exit), not an eager resolve. A bare ReactLoopAgent + direct
-    // internal driver disposer keeps the emit synchronous.
+    // Queue the internal waiter while running, then dispose the bare driver. Its disposed branch
+    // must chain the loop's `done` promise rather than resolve before exit.
    const ctx = new Context()
    await ctx.plugin(LlmService)
    await ctx.plugin(SessionStore)
@@ -395,11 +385,8 @@ describe('ReactLoopAgent', () => {
  })

  it('whenIdle() subscribed while running survives a FIBER dispose (no hung promise)', async () => {
-    // The waiter is internal agent state, NOT an effect-scoped ctx.on listener:
-    // disposing the OWNING fiber runs the agent's listener disposers, which would
-    // have dropped a ctx.on-based waiter before the 'disposed' transition and
-    // hung the promise. With internal waiters, the fiber disposer still settles
-    // it. Regression for the round-3 whenIdle finding.
+    // The waiter is agent-owned state, not an effect-scoped listener that owner disposal would
+    // remove before the disposed transition. Fiber teardown must still settle it.
    const adapter = new MockAdapter(['hang'])
    const ctx = await harness(adapter)
    let agent!: ReactLoopAgent
@@ -417,10 +404,8 @@ describe('ReactLoopAgent', () => {
  })

  it('whenIdle() on a disposed agent awaits the loop exit (done), not just the status flip', async () => {
-    // The disposer emits agent/status('disposed') BEFORE the driver loop
-    // unwinds, so whenIdle() must chain `done` (true quiescence) on the
-    // disposed path. Dispose a running agent, then assert whenIdle() resolves
-    // only after `done` — i.e. the loop has actually exited.
+    // Disposed status is emitted before the driver unwinds. `whenIdle()` must chain `done` so it
+    // resolves only after true loop exit.
    const adapter = new MockAdapter(['hang'])
    const ctx = await harness(adapter)
    let agent!: ReactLoopAgent
--- a/packages/core/agent-loop/tests/cancel.spec.ts
+++ b/packages/core/agent-loop/tests/cancel.spec.ts
@@ -1,12 +1,9 @@
 /**
- * Tests for the queue-aware `Agent.cancel()` primitive. `cancel()` is the
- * broad verb — it clears queued + steering work, aborts an in-flight step, and
- * drops a turn about to start — whereas a bare step abort (the loop's private
- * `AbortController`) kills only the current step and leaves the queue intact.
- * These tests exercise every window where a cancel can land (idle, pre-step,
- * mid-step, continuation) and the marker's arm/reset rules that keep a cancel
- * from leaking to a later prompt or hanging `whenIdle()`.
- *
+ * Tests for the queue-aware `Agent.cancel()` primitive. `cancel()` is the broad verb — it
+ * clears queued + steering work, aborts an in-flight step, and drops a turn about to start —
+ * whereas a bare step abort (the loop's private `AbortController`) kills only the current step
+ * and leaves the queue intact. The suite covers every landing window plus marker
+ * reset and `whenIdle()` quiescence.
 * @module dsh-agent-loop/tests/cancel
 */

@@ -95,10 +92,8 @@ describe('Agent.cancel()', () => {
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })

-    // Queue work, then register a whenIdle() waiter while in the pre-step window
-    // (status idle, hasQueued true) — it does NOT take the fast path. Then cancel.
-    // The skip path must settle this waiter directly (no running→idle transition
-    // ever fires), or it would hang forever.
+    // This waiter cannot rely on a running→idle transition because cancellation
+    // drops the turn before it runs; the skip path must settle it directly.
    send(agent, 'q')
    const idle = agent.whenIdle()
    agent.cancel('pre-step')
@@ -234,12 +229,8 @@ describe('Agent.cancel()', () => {
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })

-    // The first composition is interrupted mid-waterfall and — like an
-    // abort-aware listener bailing on a firing signal — contributes nothing.
-    // Caching that degraded result would silently strip the prefix from every
-    // later request of this instance; the loop must discard it and recompose
-    // on the next send, and the SECOND composition's value must be what the
-    // wire and the header log carry.
+    // The interrupted first composition must not cache its degraded empty value;
+    // the next prompt recomposes and logs/sends the fresh prefix.
    const opener: Message = { role: 'user', content: [{ type: 'text', text: 'fresh opener' }] }
    let compositions = 0
    ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise<Message[]> => {
@@ -268,10 +259,8 @@ describe('Agent.cancel()', () => {
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })

-    // A turn/start listener fires right after turn/start is appended, BEFORE any
-    // AbortController is installed for the step. Cancelling there must still drop
-    // the step (the turn-scoped marker, not the step AbortController, is what
-    // catches this) — no model step runs.
+    // A turn/start listener fires before a step controller exists, so the
+    // turn-scoped marker—not step abort—must drop the pending step.
    let streamed = false
    ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true })
    const dispose = ctx.on('session/event', (session, event) => {
@@ -400,10 +389,8 @@ describe('Agent.cancel()', () => {
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })

-    // setStatus('running') emits agent/status SYNCHRONOUSLY, so a running
-    // listener can cancel in the gap between the loop's pre-step check and
-    // runTurn. The second check (after the running flip) must drop the turn —
-    // runTurn would otherwise throw on the now-empty queue.
+    // `agent/status` is synchronous, so cancellation can land after the first
+    // pre-step check; the second check must drop the now-empty turn.
    let streamed = false
    ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true })
    const dispose = ctx.on('agent/status', (subject, status) => {
@@ -421,11 +408,7 @@ describe('Agent.cancel()', () => {
  })

  it('window 2: whenIdle() does NOT resolve early when a running listener cancels then queues replacement work', async () => {
-    // The window-1 early-resolve race has a window-2 twin: a synchronous
-    // agent/status('running') listener cancels the about-to-run turn AND queues a
-    // replacement. window 2 must NOT settle waiters (via setStatus('idle')) while
-    // the replacement is still queued-and-unrun — it must fall through and run it,
-    // so whenIdle() resolves on the replacement turn's running→idle, not before.
+    // Cancellation must not settle idle while replacement work remains queued.
    const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
@@ -451,11 +434,8 @@ describe('Agent.cancel()', () => {
  })

  it('whenIdle() does NOT resolve early when a new prompt is queued during a pre-step cancel', async () => {
-    // The subtle race: a whenIdle() waiter is registered for prompt A; cancel()
-    // clears A; prompt B is queued BEFORE the loop resumes from the idle wait.
-    // The window-1 cancel branch must NOT settle the waiter while B is still
-    // queued-and-unrun — whenIdle() must wait for B's turn to actually run and
-    // settle (the quiescence contract), not resolve before B's first event.
+    // The subtle race: a whenIdle() waiter is registered for prompt A; cancel() clears A;
+    // prompt B is queued before the loop resumes from the idle wait.
    const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
@@ -465,9 +445,8 @@ describe('Agent.cancel()', () => {
    agent.cancel('drop A')     // arms marker, clears A
    send(agent, 'B')           // B races in before the loop resumes

-    // whenIdle() must resolve only AFTER B's turn fully ran — by which point B's
-    // user message and a turn/end are in the log. (Before the fix it resolved
-    // immediately, with zero events, then B ran afterward.)
+    // whenIdle() must resolve only after B's turn fully ran — by which point B's user message
+    // and a turn/end are in the log.
    await idle
    expect(userTexts(agent)).toContain('B')
    expect(agent.session.events.some(e => e.type === 'turn/end')).toBe(true)
--- a/packages/core/agent-loop/tests/config-session-id.spec.ts
+++ b/packages/core/agent-loop/tests/config-session-id.spec.ts
@@ -101,9 +101,8 @@ describe('config-driven session id', () => {
    await waitForIdle(ctx1, a1)
    await ctx1.fiber.dispose()

-    // Run 2: a CONFIG agent with resumeSessionId continues that session. The
-    // resume is deferred until sessionPersistence loads (ctx.inject), so wait
-    // for the agent to appear, then assert it is on the resumed id with history.
+    // Resume waits for the injected persistence service, so poll until the
+    // config-created agent appears with its stored history.
    const ctx2 = new Context()
    await ctx2.plugin(LlmService)
    await ctx2.plugin(SessionStore)
--- a/packages/core/agent-loop/tests/contract-regressions.spec.ts
+++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts
@@ -39,7 +39,7 @@ function send(agent: ReactLoopAgent, text: string) {
  agent.send([{ type: 'text', text }])
 }

-describe('HIGH: session log records what agent/step-result actually produced', () => {
+describe('session log records what agent/step-result actually produced', () => {
  it('a step-result rewrite is what the log, derived history, and tool dispatch all see', async () => {
    const adapter = new MockAdapter([textResponse('original'), textResponse('done')])
    const ctx = await harness(adapter)
@@ -89,7 +89,7 @@ describe('HIGH: session log records what agent/step-result actually produced', (
  })
 })

-describe('HIGH: abort during tool execution ends the turn', () => {
+describe('abort during tool execution ends the turn', () => {
  it('aborting the in-flight step inside a tool prevents both remaining tools and the next model step', async () => {
    const adapter = new MockAdapter([
      // model asks for two tool calls in one step
@@ -141,7 +141,7 @@ describe('HIGH: abort during tool execution ends the turn', () => {
  })
 })

-describe('HIGH: steering from late extension points is never stranded', () => {
+describe('steering from late extension points is never stranded', () => {
  it('steer() from an agent/turn-continuation listener overrides a stop decision', async () => {
    const adapter = new MockAdapter([
      textResponse('no tools, would stop here'),
@@ -168,21 +168,7 @@ describe('HIGH: steering from late extension points is never stranded', () => {
  })

  it('steer() from a step/end session-event listener forces a SAME-TURN next step (/goal pattern)', async () => {
-    // The /goal pattern steers from a step boundary so the model addresses a
-    // standing goal before stopping. Step boundaries have no agent/* mirror, so
-    // the surviving hook point is the durable step/end session event. With a
-    // no-tools first step the default continuation is stop; the steering queued
-    // here must force the `!shouldContinue && hasSteering` override so the SAME
-    // turn runs another step.
-    //
-    // The override is what this test guards, so it asserts the same-turn shape —
-    // NOT merely that the content reaches requests[1]. Without the override the
-    // turn would stop, and leftover steering is re-enqueued as a next-turn queued
-    // message, which ALSO lands in requests[1] (just one turn later). So a
-    // content-only assertion passes with the override disabled and guards
-    // nothing. The discriminator is the turn/step shape: override ⇒ ONE turn with
-    // TWO steps and the steering recorded as a `steering/message` BEFORE step 2;
-    // re-enqueue fallback ⇒ TWO turns.
+    // Assert the same-turn shape; content alone cannot distinguish re-enqueue.
    const adapter = new MockAdapter([
      textResponse('no tools, would stop'),
      textResponse('after goal reminder'),
@@ -200,12 +186,10 @@ describe('HIGH: steering from late extension points is never stranded', () => {
    send(agent, 'go')
    await waitForIdle(ctx, agent)

-    // Same-turn continuation: the steering forced step 2 within turn 1.
    const events = [...agent.session.events]
    expect(events.filter(e => e.type === 'turn/start')).toHaveLength(1)
    expect(events.filter(e => e.type === 'step/start')).toHaveLength(2)
-    // The steered content is recorded as steering (same turn), BEFORE step 2 —
-    // not as a fresh turn's user/message. This is the mechanism the override uses.
+    // Same-turn steering precedes the second step.
    const steeringIdx = events.findIndex(e => e.type === 'steering/message')
    const step2Idx = events.map(e => e.type).lastIndexOf('step/start')
    expect(steeringIdx).toBeGreaterThanOrEqual(0)
@@ -263,7 +247,7 @@ describe('HIGH: steering from late extension points is never stranded', () => {
  })
 })

-describe('HIGH: plugin exceptions are contained', () => {
+describe('plugin exceptions are contained', () => {
  it('a throwing agent/turn-continuation listener ends the turn with an error, loop survives', async () => {
    const adapter = new MockAdapter([textResponse('one'), textResponse('two')])
    const ctx = await harness(adapter)
@@ -318,7 +302,7 @@ describe('HIGH: plugin exceptions are contained', () => {
  })
 })

-describe('MEDIUM: disposed status is part of the agent/status contract', () => {
+describe('disposed status is part of the agent/status contract', () => {
  it('disposing the fiber emits agent/status(disposed) and ends the turn with reason disposed', async () => {
    const adapter = new MockAdapter(['hang'])
    const ctx = await harness(adapter)
@@ -365,7 +349,7 @@ describe('MEDIUM: disposed status is part of the agent/status contract', () => {
  })
 })

-describe('MEDIUM: misc registry and config fixes', () => {
+describe('adapter registration, routing, and accepted-input ownership', () => {
  it('duplicate adapter registration is rejected', async () => {
    const ctx = new Context()
    await ctx.plugin(LlmService)
@@ -524,7 +508,7 @@ describe('MEDIUM: misc registry and config fixes', () => {
  })
 })

-describe('MEDIUM: turn numbering continues across seeded (forked) sessions', () => {
+describe('turn numbering continues across seeded sessions', () => {
  it('a forked agent continues turn numbers after the seed log', async () => {
    const first = new MockAdapter([textResponse('turn one')])
    const ctx = await harness(first)
@@ -562,7 +546,7 @@ describe('MEDIUM: turn numbering continues across seeded (forked) sessions', ()
  })
 })

-describe('LOW: discriminated SessionEvent narrows without casts', () => {
+describe('discriminated SessionEvent narrows without casts', () => {
  it('narrows event.data from event.type', () => {
    const session = new Session(SessionId('s'))
    const appended: SessionEvent = session.append('tool/call', {
@@ -580,12 +564,9 @@ describe('LOW: discriminated SessionEvent narrows without casts', () => {
  })
 })

-describe('HIGH: a finish-error stream chunk ends the turn as error, not completed', () => {
+describe('a finish-error stream chunk ends the turn as error, not completed', () => {
  it('translates finish {kind:error} into a turn error with a logged error event', async () => {
-    // The second sanctioned adapter error path (besides throwing): an
-    // adapter that cannot throw mid-stream ends the stream with a
-    // finish-error chunk (e.g. the pi-ai adapter mapping a provider 401).
-    // The loop must NOT log a normal assistant/message + completed turn.
+    // A finish-error chunk must not produce a completed assistant turn.
    const errorStream: StreamChunk[] = [
      { type: 'finish', reason: { kind: 'error', message: 'provider 401', code: 'AUTH' } },
    ]
@@ -606,7 +587,7 @@ describe('HIGH: a finish-error stream chunk ends the turn as error, not complete
    // a standalone error event.
    const turnEnd = events.find(event => event.type === 'turn/end')
    expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'error', step: 1, message: 'provider 401', code: 'AUTH' })
-    // Crucially: no assistant/message was logged for the failed step.
+    // A failed step must not synthesize an assistant message.
    expect(events.some(event => event.type === 'assistant/message')).toBe(false)
  })

@@ -652,10 +633,7 @@ describe('step boundary publication order', () => {
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a-step-order'), { model: 'mock' })

-    // Session.append pushes the event BEFORE notifying session/event listeners,
-    // so a step/start listener always finds the matching event already in the
-    // log. (Step boundaries have no agent/* mirror — the session log is the live
-    // feed.)
+    // Append commits before observers run.
    const observed: { turn: number; step: number; lastEventType: string | undefined; sawStepStart: boolean }[] = []
    ctx.on('session/event', (subject, event) => {
      if (subject !== agent.session || event.type !== 'step/start') return
@@ -678,10 +656,7 @@ describe('step boundary publication order', () => {
 })

 describe('turn and step boundary recovery', () => {
-  // Harness with the invariants plugin loaded as an oracle: it throws on
-  // append if the log goes unbalanced (turn/end while a step is open,
-  // turn/start while a turn is open, etc.), so a regression surfaces as an
-  // InvariantError on the NEXT turn's append rather than a silent imbalance.
+  // The invariants plugin makes an unbalanced log fail the test.
  async function balancedHarness(adapter: MockAdapter) {
    const ctx = new Context()
    await ctx.plugin(LlmService)
@@ -833,9 +808,7 @@ describe('turn and step boundary recovery', () => {
  })

  it('a throwing agent/error listener during a step-error path still balances the turn, loop survives', async () => {
-    // First turn: model stream ends with a finish-error → step error path →
-    // failTurn emits agent/error, whose listener throws. The turn must still
-    // close balanced. Second turn proves the loop survived.
+    // Listener failure cannot interrupt error finalization or the next turn.
    const errorStream: StreamChunk[] = [{ type: 'finish', reason: { kind: 'error', message: 'provider 500' } }]
    const adapter = new MockAdapter([errorStream, textResponse('turn 2 ok')])
    const ctx = await balancedHarness(adapter)
@@ -894,9 +867,7 @@ describe('turn and step boundary recovery', () => {
  })

  it('preserves reason disposed when a pre-step listener disposes then throws (outer-catch disposed branch)', async () => {
-    // A pre-step listener requests disposal and then throws before the ordinary
-    // post-listener disposal check. The outer catch sees disposal already won
-    // and must preserve reason=disposed rather than rewrite it as a plugin error.
+    // Disposal remains authoritative when the listener also throws.
    const adapter = new MockAdapter([textResponse('never reached')])
    const ctx = await balancedHarness(adapter)
    let agent!: ReactLoopAgent
@@ -908,9 +879,6 @@ describe('turn and step boundary recovery', () => {
    ctx.on('agent/pre-step', () => {
      if (threw) return
      threw = true
-      // Request disposal, then throw in the same synchronous tick: status flips
-      // to 'disposed' (the disposer aborts the step controller) and the throw
-      // drives control into the outer catch with isDisposed() already true.
      void fiber.dispose()
      throw new Error('boom pre-step during disposal')
    })
@@ -1001,10 +969,7 @@ describe('turn and step boundary recovery', () => {
  })

  it('a throwing step/end observer cannot interrupt error finalization', async () => {
-    // A finish-error stream opens a step then fails it, driving finalization
-    // through closeStep() with the step open. Session contains the observer
-    // failure after committing step/end, so closeTurn still records the model
-    // failure and balances the turn.
+    // Observer failure after step/end commit cannot interrupt turn finalization.
    const errorStream: StreamChunk[] = [{ type: 'finish', reason: { kind: 'error', message: 'provider 500' } }]
    const adapter = new MockAdapter([errorStream, textResponse('turn 2 ok')])
    const ctx = await harness(adapter)
@@ -1078,8 +1043,7 @@ describe('tool result call identity', () => {

    // A post-execute listener transforms the result (accept-with-replacement).
    // The loop must still record the tool/result under the model's authoritative
-    // call.id (the loop ignores result.callId — which the registry always sets to
-    // exec.callId anyway — and uses call.id, the model-transcript id).
+    // call.id, which is the immutable identity carried by the execution input.
    ctx.on('tools/post-execute', (exec, _result) => {
      expect(exec.callId).toBe(CallId('c1')) // the loop passed the real id in
      return Promise.resolve({ kind: 'accept', content: [{ type: 'text', text: 'ok' }] })
@@ -1089,8 +1053,7 @@ describe('tool result call identity', () => {
    send(agent, 'use tool')
    await waitForIdle(ctx, agent)

-    // The logged tool/result.callId is the originating call.id, NOT the
-    // listener's wrong id.
+    // The logged tool/result.callId is the originating call.id.
    const resultEvent = [...agent.session.events].find(e => e.type === 'tool/result')
    expect(resultEvent?.type).toBe('tool/result')
    if (resultEvent?.type === 'tool/result') {
@@ -1112,11 +1075,7 @@ describe('tool result call identity', () => {

 describe('surface: assistant/message omits sourceEventSeqs when no chunks streamed', () => {
  it('a step-result listener injecting content over an empty stream appends with surfaceOp but no sourceEventSeqs', async () => {
-    // An empty stream yields zero assistant/chunk events (finish defaults to
-    // `stop`), so chunkSeqs is empty. A step-result listener injects content, so
-    // the content-or-usage guard fires and an assistant/message is appended. Its
-    // sourceEventSeqs MUST be omitted (not `[]`) — the surface invariant rejects
-    // an empty sourceEventSeqs, and the dev invariants plugin would throw on it.
+    // Injected result content with no chunks must omit empty sourceEventSeqs.
    const adapter = new MockAdapter([[]])
    const ctx = await harness(adapter)
    await ctx.plugin(Invariants)
@@ -1143,12 +1102,8 @@ describe('surface: assistant/message omits sourceEventSeqs when no chunks stream

 describe('disposal and cancellation during pre-step assembly', () => {
  it('disposal during system-prompt assembly drops the about-to-start step as disposed', { timeout: 30000 }, async () => {
-    // Block `system-prompt/assemble` on a promise. Start disposal (which
-    // calls stop() synchronously, setting status=disposed), then release the
-    // block. The loop must check isDisposed() after assembly and end the turn
-    // `disposed` — no LLM call. Don't await fiber.dispose() before releasing
-    // the blocker: the dispose chain awaits agent.done, which hangs until the
-    // loop unblocks.
+    // Start disposal, then release assembly. Do not await disposal first: it
+    // waits for the blocked driver to exit.
    const adapter = new MockAdapter(['hang'])
    let releaseAssemble!: () => void
    const blocked = new Promise<void>(r => void (releaseAssemble = r))
@@ -1163,7 +1118,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
    await ctx.plugin(Invariants)
    ctx.llm.registerAdapter(['mock'], adapter)

-    // Blocking listener on the parent context (survives fiber disposal).
+    // Parent-owned listener survives agent-fiber disposal.
    const unlisten = ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {
      await blocked
      return next()
@@ -1181,28 +1136,22 @@ describe('disposal and cancellation during pre-step assembly', () => {
    // Give the loop time to enter the step and reach assemble().
    await new Promise(r => setTimeout(r, 50))

-    // Start disposal — stop() sets status=disposed synchronously, then the
-    // disposer's await agent.done hangs because the loop is blocked in the
-    // waterfall. Do NOT await yet; release the blocker first.
+    // Release assembly before awaiting disposal because disposal joins the blocked driver.
    const disposalDone = fiber.dispose()

-    // Now release the blocked waterfall — the loop unblocks, checks
-    // isDisposed(), and exits, which resolves agent.done and disposalDone.
    releaseAssemble()
    await disposalDone
    await agent.done
    unlisten()

+    // Turn boundaries are durable rows; there is no `agent/*` mirror to assert.
    const e = [...agent.session.events]
    expect(e.filter(x => x.type === 'turn/start')).toHaveLength(1)
    expect(e.filter(x => x.type === 'turn/end')).toHaveLength(1)
    const turnEnd = e.findLast(x => x.type === 'turn/end')
    expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'disposed' })
-    // No step was opened, no LLM call was made.
    expect(e.some(x => x.type === 'step/start')).toBe(false)
    expect(e.some(x => x.type === 'assistant/chunk')).toBe(false)
-    // The durable turn/end record is the authoritative turn-boundary signal
-    // (turn boundaries have no agent/* mirror), so this asserts on the log.
  })

  it('cancel during system-prompt assembly drops the about-to-start step as aborted', { timeout: 30000 }, async () => {
@@ -1259,9 +1208,8 @@ describe('disposal and cancellation during pre-step assembly', () => {
  })

  it('disposal during agent/pre-step seam ends the turn disposed', { timeout: 15000 }, async () => {
-    // Block the `agent/pre-step` serial seam on a promise we control, then
-    // dispose the agent's fiber. When the block releases, the loop must see
-    // isDisposed() at the post-seam check and end the turn disposed.
+    // Start disposal, then release pre-step; awaiting disposal first would
+    // deadlock on the blocked driver.
    const adapter = new MockAdapter(['hang'])
    let releasePreStep!: () => void
    const blocker = new Promise<void>(r => void (releasePreStep = r))
@@ -1312,8 +1260,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
  })

  it('cancel during agent/pre-step seam ends the turn aborted', { timeout: 15000 }, async () => {
-    // Block `agent/pre-step`, then cancel() the agent. When the block releases,
-    // the post-seam check catches cancellation and ends the turn aborted.
+    // Release pre-step after cancellation to exercise the post-seam check.
    const adapter = new MockAdapter(['hang'])
    let releasePreStep!: () => void
    const blocker = new Promise<void>(r => void (releasePreStep = r))
--- a/packages/core/agent-loop/tests/coverage-edges.spec.ts
+++ b/packages/core/agent-loop/tests/coverage-edges.spec.ts
@@ -225,9 +225,7 @@ describe('disposed vs aborted branching', () => {
    await fiber.dispose() // dispose during hang
    await agent.done

-    // The review-fixes test for 'HIGH: disposed status' already covers
-    // this assertion path. The reason is 'disposed' because isDisposed() is
-    // checked before the abort signal check in the error path.
+    // Disposal wins abort classification because the error path checks it first.
    expect(reasons).toContainEqual({ kind: 'disposed' })
  })
 })
--- a/packages/core/agent-loop/tests/inbox.spec.ts
+++ b/packages/core/agent-loop/tests/inbox.spec.ts
@@ -64,17 +64,12 @@ describe('Inbox', () => {
    void inbox.waitForQueued(new Promise(() => {})) // first call, never resolved
    void inbox.waitForQueued(p1) // second call overwrites wakeup

-    // Cancel p1 (the latest waiter's cancel) — the wakeup was overwritten
-    // to p1's resolve, so canceling p1 triggers the finally block which
-    // clears the wakeup if it matches.
+    // Cancelling the latest waiter clears the shared callback; enqueue must neither
+    // wake the stale waiter nor fail on the cleared callback.
    r1()
    await p1

-    // Now enqueue: the first waiter's wakeup (which was overwritten) won't
-    // fire, and the second waiter's wakeup was cleared by cancel.
-    // The enqueue calls wakeup?.() but wakeup was cleared — no crash, no hang.
    inbox.enqueue({ content: [{ type: 'text', text: 'hey' }], source: { kind: 'user' } })
-    // The overwrite path + finally cleanup are exercised
  })

  it('clears wakeup in finally handler when enqueue resolves', async () => {
@@ -88,23 +83,17 @@ describe('Inbox', () => {
  })

  it('finally handler does not clear wakeup when a different waiter overwrote it', async () => {
-    // First waiter's cancel resolves AFTER a second waiter overwrote wakeup.
-    // First waiter's finally sees wakeup !== its resolve → does not clear.
+    // A stale waiter's finally must not clear the replacement waiter.
    const inbox = new Inbox()
    const { promise: c1, resolve: r1 } = resolverPair()

    void inbox.waitForQueued(c1) // wakeup = resolve1, c1.then(resolve1)
    void inbox.waitForQueued(new Promise(() => {})) // wakeup = resolve2, cancel never resolves

-    // Resolve c1 (the first cancel). c1.then(resolve1) fires → resolve1() called
-    // → waiter1's promise resolves → finally: wakeup === resolve1? NO (it's resolve2)
-    // → wakeup is NOT cleared.
    r1()
    await c1

-    // Now enqueue: wakeup() calls resolve2 → waiter2 resolves
-    // But waiter2's cancel never resolves — that's fine, enqueue resolves it.
+    // The replacement remains registered and is resolved by enqueue.
    inbox.enqueue({ content: [{ type: 'text', text: 'hey' }], source: { kind: 'user' } })
-    // No need to await anything further — enqueue is synchronous wakeup
  })
 })
--- a/packages/core/agent-loop/tests/interception.spec.ts
+++ b/packages/core/agent-loop/tests/interception.spec.ts
@@ -117,14 +117,8 @@ describe('agent/prompt-submit', () => {
  })

  it('a prompt-submit rewrite + additionalContext is VISIBLE to the agent/pre-step seam (merged ordering)', async () => {
-    // The merge of the interception seams with master's compaction seam pins one
-    // ordering: `agent/prompt-submit` runs (rewriting the prompt and injecting
-    // context) BEFORE the step loop, and `agent/pre-step` fires INSIDE the step
-    // before the single deriveMessages(). So a compaction listener on
-    // `agent/pre-step` must observe the surface AFTER the prompt rewrite/inject —
-    // otherwise it would measure/compact stale history. This cross-test proves
-    // the two seams compose in the right order (each is covered in isolation
-    // elsewhere; this asserts they see each other's effects on the same turn).
+    // Prompt rewrites and injected context land before `agent/pre-step`, so a
+    // compaction listener measures the current surface before the single derive.
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
@@ -189,9 +183,8 @@ describe('agent/prompt-submit', () => {
  })

  it('a mixed batch records a prompt/blocked for the vetoed prompt while the allowed one runs', async () => {
-    // Two prompts queued into ONE turn: block "secret", allow "safe". The turn is
-    // NOT rejected (a prompt was allowed), so without a durable prompt/blocked the
-    // vetoed prompt and its reason would vanish from the log entirely.
+    // Blocking one prompt in a mixed batch must persist its reason even though
+    // the allowed prompt keeps the turn from ending rejected.
    const adapter = new MockAdapter([textResponse('ran once')])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
@@ -515,14 +508,13 @@ describe('agent/turn-continuation (ContinuationDecision)', () => {
    await waitForIdle(ctx, agent)

    const log = events(agent)
-    // same turn, two steps
+    // The continuation stays in the turn, is logged with provenance before step 2,
+    // and reaches that step's request.
    expect(log.filter(e => e.type === 'turn/start')).toHaveLength(1)
    expect(log.filter(e => e.type === 'step/start')).toHaveLength(2)
-    // the reason was recorded as steering BEFORE step 2, with its plugin source
    const steering = log.find(e => e.type === 'steering/message')
    expect(steering?.type === 'steering/message' && steering.data.content).toEqual([{ type: 'text', text: 'keep going on the goal' }])
    expect(steering?.type === 'steering/message' && steering.data.source).toEqual({ kind: 'plugin', plugin: 'goal' })
-    // and reached the next request
    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('keep going on the goal')
  })

@@ -618,11 +610,9 @@ describe('tools/pre-execute gate (native-plugin permission pattern, end-to-end t
 })

 describe('worked example: a native hook plugin is just a cordis plugin on the seams', () => {
-  // The whole point of the interception taxonomy: a "native hook" needs no
-  // dsh-hook-protocol, no external command, no hook/* log — it is an ordinary
-  // cordis plugin subscribing to the canonical events and returning typed
-  // decisions. This proves all four seams compose end-to-end through the REAL
-  // loop, with NO hook/* SessionEvents involved (those belong to the bridge lib).
+  // The whole point of the interception taxonomy: a "native hook" needs no dsh-hook-protocol,
+  // no external command, no hook/* log — it is an ordinary cordis plugin subscribing to the
+  // canonical events and returning typed decisions.
  const NativeGuard = {
    name: 'native-guard',
    apply(ctx: Context) {
--- a/packages/core/agent-loop/tests/loop.spec.ts
+++ b/packages/core/agent-loop/tests/loop.spec.ts
@@ -183,11 +183,7 @@ describe('agent loop', () => {
  })

  it('contains a strict-variable render failure: the turn errors, the loop keeps serving turns', async () => {
-    // A persona claiming {{cwd}} on a session with NO cwd is a deployment
-    // authoring error — renderPrompt throws, the turn ends with an error, and
-    // the same agent must then RUN a later turn to completion (not merely
-    // report idle status): a rescue listener supplies the variable and the
-    // follow-up prompt reaches the model.
+    // A missing cwd variable must fail one turn without preventing a later valid turn.
    const adapter = new MockAdapter([textResponse('ok after rescue')])
    const ctx = await harness(adapter, 'In {{cwd}}.')
    const errors: Error[] = []
@@ -522,9 +518,8 @@ describe('agent loop', () => {
  })

  it('agent/pre-step fires BEFORE the step it precedes opens (events land outside the step)', async () => {
-    // A listener appending a surface node in pre-step lands it BEFORE step/start
-    // in the log — proving the seam fires outside the step. The node is still in
-    // the derived request for that step (derive happens after step/start).
+    // The append lands before step/start, yet derive happens afterwards and the
+    // same step's request must include it.
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
@@ -557,10 +552,8 @@ describe('agent loop', () => {
  })

  it('a throwing agent/pre-step listener ends the turn (error), not the loop', async () => {
-    // The seam fires before step/start, so a throw escapes to runTurn's outer
-    // catch: the not-yet-open step closes as a no-op, the failure surfaces via
-    // agent/error, and the turn ends `error` (recorded on the durable turn/end).
-    // The loop survives and a follow-up prompt still runs.
+    // Before step/start, a pre-step throw reaches the turn catch: no step needs
+    // closing, the turn records error, and the loop remains available.
    const adapter = new MockAdapter([textResponse('second turn ok')])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
@@ -627,16 +620,14 @@ describe('agent loop', () => {

    expect(adapter.requests).toHaveLength(1)
    expect(reasons).toEqual([{ kind: 'max-tokens' }])
-    // and the reason is recorded in the log's turn/end event
+    // Assert the durable row, not only the live listener.
    const turnEnd = agent.session.events.findLast(e => e.type === 'turn/end')
    expect(turnEnd!.data.reason).toEqual({ kind: 'max-tokens' })
  })

  it('a max-tokens step earlier in a turn still surfaces as max-tokens after a later completed step', async () => {
-    // Step 1 is cut off (max-tokens, no tool calls → would stop by default), so
-    // continuation must be FORCED to reach step 2 which finishes normally
-    // (stop). The rule "any max-tokens step surfaces as max-tokens" means the
-    // turn ends max-tokens even though the LAST step completed cleanly.
+    // Step 1 is cut off (max-tokens, no tool calls → would stop by default), so continuation
+    // must be FORCED to reach step 2 which finishes normally (stop).
    const adapter = new MockAdapter([
      maxTokensResponse('first half'),
      textResponse('second half'),
@@ -718,11 +709,8 @@ describe('agent loop', () => {
    expect(agent.session.events.some(e => e.type === 'tool/call')).toBe(false)
    expect(agent.session.deriveMessages()).toEqual([{ role: 'user', content: [{ type: 'text', text: 'go' }] }])
    expect(reasons).toEqual([{ kind: 'max-tokens' }])
-    // No-data-loss: a max-tokens step whose only content was a dropped tool call
-    // has EMPTY assistant content, but its usage must still be represented. It
-    // rides on an (empty-content) assistant/message — there is no standalone
-    // usage event — and that empty message is skipped by deriveMessages(), so
-    // the derived history above is NOT corrupted by a spurious assistant turn.
+    // Empty content still needs an assistant/message to carry usage; derivation
+    // skips that host so it does not create a spurious assistant turn.
    const assistantMessage = agent.session.events.find(e => e.type === 'assistant/message')
    expect(assistantMessage?.type === 'assistant/message' && assistantMessage.data).toEqual({
      turn: 1, step: 1, content: [], usage: { inputTokens: 10, outputTokens: 5 },
@@ -730,10 +718,9 @@ describe('agent loop', () => {
  })

  it('appends no assistant/message for a max-tokens step with empty content and no usage', async () => {
-    // A max-tokens step truncated to a dropped tool call AND with no usage chunk
-    // has nothing to record: empty content and no accounting → no assistant/message
-    // (the empty-content host exists only to carry usage). The turn still ends
-    // max-tokens.
+    // A max-tokens step truncated to a dropped tool call AND with no usage chunk has nothing to
+    // record: empty content and no accounting → no assistant/message (the empty-content host
+    // exists only to carry usage).
    const callId = CallId('c1')
    const adapter = new MockAdapter([[
      { type: 'block-start', index: 0, blockType: 'tool-call' },
--- a/packages/core/agent-loop/tests/properties.spec.ts
+++ b/packages/core/agent-loop/tests/properties.spec.ts
@@ -1,12 +1,7 @@
 /**
- * Property-based tests for the agent loop's inbox/turn scheduling (the
- * property-testing RFC). Deterministic by construction: schedules are driven
- * through the `agent/status` settle signal (no wall-clock sleeps), so a flake
- * is a finding, not timing noise.
- *
- * Invariants: every sent message appears exactly once in the log (none lost);
- * turn numbers strictly increase; status transitions follow the legal machine
- * idle→running→idle (and →disposed at teardown).
+ * Deterministic property tests for inbox scheduling: every sent message logs
+ * once, turn numbers increase, and status follows idle→running→idle/disposed.
+ * Schedules advance on status events rather than wall-clock sleeps.
 */

 import { describe, expect, it } from 'vitest'
@@ -146,10 +141,8 @@ describe('agent loop scheduling properties', () => {
        const ctx = await harness()
        try {
          const agent = ctx.agentLoop.create(AgentId('a'), { model: 'mock' })
-          // Capture an idle waiter before EACH send; the last one is guaranteed
-          // to resolve because the final send always triggers (or joins) a turn
-          // that ends idle. Awaiting an already-resolved waiter is a no-op, so a
-          // trailing settle step can't cause a hang.
+          // Capture before each send; the last waiter covers the final turn, and
+          // awaiting an already-settled earlier waiter is harmless.
          let lastIdle: Promise<void> | undefined
          for (const step of steps) {
            const idle = nextIdle(ctx, agent)
--- a/packages/core/agent-loop/tests/request-cache.e2e.ts
+++ b/packages/core/agent-loop/tests/request-cache.e2e.ts
@@ -9,15 +9,13 @@ import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'

 /**
- * With-key proof that log-derived requests translate into REAL provider cache
- * hits: a multi-step tool turn (plus a follow-up turn) against the live
- * DeepSeek API must report `cacheReadTokens > 0` on every request after the
- * first — the adapter maps the provider's `prompt_cache_hit_tokens`, and the
- * per-step usage recorded on `assistant/message` events is the production
- * observable for cache behavior (the reconstructability RFC's measurement
- * layer: prefix stability is corollary #1). Mocks prove the requests are
- * append-extensions; only the real API proves those bytes actually hit the
- * provider cache. Key-gated — skips entirely without $DEEPSEEK_API_KEY.
+ * With-key proof that log-derived requests translate into real provider cache hits: a
+ * multi-step tool turn (plus a follow-up turn) against the live DeepSeek API must report
+ * `cacheReadTokens > 0` on every request after the first — the adapter maps the provider's
+ * `prompt_cache_hit_tokens`, and the per-step usage recorded on `assistant/message` events is
+ * the production observable for cache behavior (the reconstructability RFC's measurement
+ * layer: prefix stability is corollary #1). Mocks establish append-extension;
+ * this key-gated test establishes a real provider cache hit.
 */

 // Long enough that the shared request prefix comfortably spans the provider's
--- a/packages/core/agent-loop/tests/request-reconstruction.spec.ts
+++ b/packages/core/agent-loop/tests/request-reconstruction.spec.ts
@@ -1,11 +1,9 @@
 /**
- * Loop-level reconstructability: every request the loop sends is a pure
- * function of the session log — messages are the derivation at the step/start
- * boundary, the header is the fold of request/header* events — and every
- * request is an append-extension of its predecessor unless a logged event
- * (compaction replace, header change) explains the difference. The requests
- * recorded by the mock adapter are the observable; the offline-rebuild test
- * at the bottom is the theorem stated end-to-end.
+ * Loop-level reconstructability: every request the loop sends is a pure function of the
+ * session log — messages are the derivation at the step/start boundary, the header is the fold
+ * of request/header* events — and every request is an append-extension of its predecessor
+ * unless a logged event (compaction replace, header change) explains the difference. Mock-adapter
+ * requests are the observable, and the final offline rebuild states the full contract end to end.
 */

 import { describe, expect, it } from 'vitest'
--- a/packages/core/agent-loop/tests/resume.spec.ts
+++ b/packages/core/agent-loop/tests/resume.spec.ts
@@ -460,10 +460,8 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
  })

  it('an idle inject() is flushed durably on its own (survives without explicit flush/dispose)', async () => {
-    // Lifecycle 1: run a turn, then inject context while idle. The idle inject
-    // wraps its context/message in a one-shot turn AND checkpoints it (the turn-enclosure RFC)
-    // — without an explicit flush or clean dispose, the notice must still reach
-    // disk, since a crash before the next turn would otherwise lose it.
+    // Idle injection creates and flushes a one-shot turn. No explicit flush or
+    // clean disposal follows, so disk presence proves its own checkpoint ran.
    const adapter1 = new MockAdapter([textResponse('answer')])
    const { ctx: ctx1, root } = await persistentHarness(adapter1)
    const a1 = (await ctx1.agents.create({ agentId: AgentId('m'), sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent as ReactLoopAgent
@@ -485,10 +483,8 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
  })

  it('an idle inject() survives persist + resume (turn-enclosed, not dropped as crash tail)', async () => {
-    // Lifecycle 1: run a turn, then inject context while idle. The idle inject
-    // wraps its context/message in a one-shot turn so it is turn-enclosed —
-    // otherwise scanLog would treat the trailing context as a crash tail and
-    // drop it on reload (the bug this guards).
+    // Turn enclosure keeps idle context out of crash-tail repair, so it must
+    // survive persistence and resume.
    const adapter1 = new MockAdapter([textResponse('answer')])
    const { ctx: ctx1, root } = await persistentHarness(adapter1)
    const a1 = (await ctx1.agents.create({ agentId: AgentId('m'), sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent as ReactLoopAgent
--- a/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
+++ b/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
@@ -934,11 +934,9 @@ describe('agent scope lifecycle', () => {
      order.push(`session-still-stored=${ctx.sessions.get(SessionId('o1-s')) !== undefined}`)
    })

-    // Open a turn so the drain has real work: the loop must finish it BEFORE
-    // the registry entry goes away (the agent/disposed contract: "its fiber
-    // and any in-flight turn have been torn down"). Wait for the turn to be
-    // OPEN in the log — a dispose landing in the pre-step window would drop
-    // the queued prompt without ever opening a turn.
+    // Open a turn so disposal must drain real work before registry removal.
+    // Waiting for turn/start avoids pre-step disposal dropping the queued prompt
+    // before a turn opens.
    const turnOpen = new Promise<void>((resolve) => {
      const off = ctx.on('session/event', (_s, event) => {
        if (event.type === 'turn/start') { off(); resolve() }
--- a/packages/core/agent-loop/tests/tool-order.spec.ts
+++ b/packages/core/agent-loop/tests/tool-order.spec.ts
@@ -1,10 +1,9 @@
 /**
- * Loop-level tool-order determinism: the request/header event — and therefore
- * the frozen request the adapter receives — carries the assembly's canonical
- * tool order (system-prompt's `toolOrder` config, or lexicographic name
- * order), regardless of the order tool plugins happened to register in.
- * Registration order is a plugin-load artifact (concurrent dynamic imports
- * race), so nothing downstream of the registry may depend on it.
+ * Loop-level tool-order determinism: the request/header event — and therefore the frozen
+ * request the adapter receives — carries the assembly's canonical tool order (system-prompt's
+ * `toolOrder` config, or lexicographic name order), regardless of the order tool plugins
+ * happened to register in. Registration order is a concurrent loading artifact
+ * and must not leak downstream.
 */

 import { describe, expect, it } from 'vitest'
@@ -93,11 +92,7 @@ describe('loop-level canonical tool order', () => {
  })

  it('fails the turn — no model request — when toolOrder names an unregistered tool', async () => {
-    // The assemble rejection escapes to runTurn's outer catch: the open turn
-    // closes with an `error` reason (agent/error mirrors it), no step opens,
-    // no request/header is logged, the adapter never sees a request, and the
-    // agent returns to idle — a misconfigured deployment fails every turn
-    // deterministically instead of silently reordering nothing.
+    // Unknown tool order fails before step or request creation and returns the agent to idle.
    const adapter = new MockAdapter([textResponse('never sent')])
    const ctx = await harness(adapter, ['ghost', TOOL_ORDER_REST])
    registerNamed(ctx, 'alpha')
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -8,28 +8,28 @@ Tracks live agents so UI, hook, and orchestrator plugins can find them without i

 ### Public API

-The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-scope`, key = the agent) — register tools/sections/variables/listeners through it for that agent alone, all unwound on disposal. `agentEvents(ctx, agent)` is the fused dispatcher for ordinary agent-subject operations (carrier + injected subject in one move); its notification mode invokes every listener and contains both synchronous throws and returned-promise rejections. The registry lifecycle pair reuses one stable routing carrier. `assembleContextFor(agent)` builds the per-agent assembly context (`agent` + `scope` together). `CreateAgentOptions.setup(agentCtx)` and `ResumeAgentOptions.setup(agentCtx)` compose a fresh or resumed agent's scoped world while both objects remain unpublished. Setup is trusted, composition-only same-process code: drive the agent only after creation resolves.
+`Agent.ctx` owns registrations visible only to that agent. `agentEvents()` couples event subjects to their scope carrier, and `assembleContextFor()` couples the agent and prompt scope. Creation and resume may compose this context through `setup`; the agent remains unpublished and must not be driven until creation resolves.

 - `ctx.agents.register(agent: Agent): () => void` — record an **already-constructed** agent. Disposed with the calling fiber.
- Advanced ordered lifecycle: `enter(agent): () => void` performs the authoritative ID collision check and inserts without announcing; `announce(agent)` emits `agent/created` exactly once. A detach requested synchronously by a creation listener is deferred until that dispatch unwinds, and every detach checks the captured entry object, so a stale capability cannot delete a later same-ID replacement. The async factory uses this split; ordinary plugins use `register()`.
+- Advanced factory lifecycle: `enter(agent)` publishes without announcing and returns an entry-bound detach; `announce(agent)` emits creation once. Detach during creation dispatch is deferred. Ordinary plugins use `register()`.
 - `ctx.agents.get(id: AgentId): Agent | undefined`
 - `ctx.agents.list(): Agent[]`

 #### Factory seam (creation)

-Agent *creation* is provided by the plugin implementing `AgentFactory` (`dsh-agent-loop`), registered via `setFactory`. This keeps creation on the `dsh-agent` interface so consumers (UI, the ACP bridge) program against `ctx.agents` without depending on the concrete loop package. The registry canonicalizes an already traced Service to its concrete target and re-traces each call through the caller's context; this avoids nested Cordis shadows while passing an explicit caller-bound `ownerCtx` to plain factories.
+The loop plugin registers `AgentFactory`, keeping consumers independent of its concrete package. Each call is traced through the caller's context so the caller owns the resulting transaction and handle.

 - `ctx.agents.setFactory(factory: AgentFactory): () => void` — register the creation factory (the loop calls this on construction). Throws on a second factory; the slot clears on dispose.
- `ctx.agents.create(options: CreateAgentOptions): Promise<AgentHandle>` — create a session and agent, await optional setup while unpublished, then publish through final `SessionStore.enter()` and `AgentRegistry.enter()` checks. Concurrent same-ID creation is unsupported: more than one operation may prepare, but only one can enter; every loser rolls its private scope/session/driver back. An optional creation-only `signal` cancels unpublished setup and is detached before the handle is returned; later cancellation uses `handle.dispose()` or `agent.cancel()`. Publication is rollback-covered and every delivered creation edge is paired during rollback. Rejects if no factory is registered.
- `ctx.agents.resume(options: ResumeAgentOptions): Promise<AgentHandle>` — load a persisted session ([session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md)), mint a fresh unpublished agent scope, await optional setup, and use the same final-entry publication sequence. Its optional `signal` is likewise creation-only. Rejects if no factory is registered or session persistence is unconfigured.
+- `ctx.agents.create(options)` creates and composes an unpublished session and agent, then atomically enters the registries and starts the loop. A creation-only signal cancels before publication; same-ID contenders arbitrate at entry and losers roll back.
+- `ctx.agents.resume(options)` loads a persisted session and follows the same composition and publication boundary. It requires [session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md).

-`AgentHandle = { agent: Agent; dispose(): Promise<void> }`. The disposer is a **consumer capability** — no observer holding the bare registry entry can tear the agent down. The caller fiber and the registered factory provider are structural co-owners: caller unload enforces structured ownership, while factory unload must stop old instances because their scoped dependency surface belongs to that provider. `dispose()` from any owner reaches one memoized quiescence boundary: it stops the loop, `await`s its exit plus every outstanding idle-injection flush (not just the `disposed` status flip), unregisters the agent, removes its session from the store, and finally unwinds its scoped world. This order captures every agent-started `session/flush` before the session is detached and keeps scoped listeners alive through those checkpoints. `ctx.agents.get(id)` still returns a bare `Agent`; the ACP bridge and in-process subagent backends hold consumer handles, while config-created agents are already owned by the loop fiber.
+`AgentHandle = { agent, dispose }` is the consumer teardown capability; registry observers receive only the bare agent. Disposal stops and drains the loop and idle-injection flushes before unregistering the agent, detaching its session, and unwinding its scope. Caller and factory unload share that memoized boundary.

 ### Live events

 `dsh-agent` declares the live `agent/*` coordination vocabulary so plugins do not depend on the concrete loop. Exact signatures, dispatch modes, scope-filtering rules, and payload contracts live in the generated [Cordis event catalog](../../../docs/cordis-catalog/events.md); the [architecture turn flow](../../../docs/architecture.md#turn-flow) shows their order relative to durable session events.

-The lifecycle edges have two important local caveats. `agent/created` runs after scoped setup and after both session and agent registry entries exist. Setup is trusted composition-only code; the immediately following non-vetoing `agent/session-start` notification is the first supported startup injection point. `agent/disposed` always means the exact agent has left the registry. AgentLoop emits it after its driver is quiescent, while ordered teardown may still be detaching the session and unwinding the scope; custom agents registered directly own any stronger driver-ordering contract themselves.
+`agent/created` runs after setup and both registry entries; the following `agent/session-start` is the first supported startup injection point. `agent/disposed` means the exact entry left the registry. The loop quiesces its driver first; directly registered custom agents own any stronger ordering.

 Most interception points are cooperative waterfalls returning seam-specific decisions. `agent/pre-step` is a serial surface-mutation checkpoint, while `agent/turn-stop` is the terminal serial fold: it runs after ordinary continuation and steering folding, and a returned stop remains in force through turn close and flush so later steering cannot create an extra step or turn. Ordinary queued prompts remain intact. The full rationale is in the [agent-scope runtime-design RFC](../../../docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way).

@@ -50,8 +50,26 @@ The handle every plugin programs against:

 - Agent creation: `AgentLoop.create()` is the concrete config-path implementation (in `dsh-agent-loop`), while programmatic consumers create/resume owned agents through `ctx.agents.create()` / `ctx.agents.resume()`. Replace the loop by implementing `Agent` and registering via `ctx.agents.register()`.
 - Event listeners: all `agent/*` events are declared here — no dependency on the loop package needed.
- Subagent delegation: implemented by `@deepseek-ai/dsh-subagent`, not by a method on `Agent`; providers create or drive ordinary `Agent` handles through the factory seam, so spawn/fork/ACP transports stay outside the core agent interface.
+- Subagent delegation is not an `Agent` method; providers create or drive ordinary handles through the factory seam, so delegation transports stay outside the core agent interface.

-### What is NOT here (TODO)
+## Model Experience
+
+### User, steering, and injected messages
+
+**What the model sees**: `send`, `steer`, and `inject` feed the owning session. `agent/prompt-submit`, `agent/session-prefix`, and other declared events let plugins block a prompt or add request material; this interface contributes no fixed prose itself.
+
+**Token effect**: Accepted content becomes retained history or a repeated session prefix; blocked content contributes no request tokens. Size is caller- and plugin-dependent.
+
+### Agent-scoped request composition
+
+**What the model sees**: Registrations through `agent.ctx` can shadow prompt sections or tools and can install agent-only interceptors during unpublished setup.
+
+**Token effect**: The package adds zero tokens itself; scoped contributions affect only that agent and disappear on disposal.
+
+## Known Limitations and Deferred Work

 - **Inter-agent channels beyond delegation** — shared state, streaming child output, and background/poll semantics remain outside the current synchronous `ctx.subagents` seam.
+- **`agent/session-start` cannot gate startup** — it remains a synchronous, veto-less notification; async composition that must finish before publication belongs in the factory's `setup(agentCtx)` transaction instead.
+- **No public step-only abort** — `cancel()` clears ALL pending work (queued + steering + in-flight); an abort that preserves queued prompts returns only with a named consumer ([stop-surface RFC](../../../docs/rfc/implemented/simplification/2026-06-20-public-agent-stop-surface.md)).
+- **`HookContext` carries exactly one `MessageSource`** — contributions from several plugins merged onto one tool call collapse under one source; mixed provenance is unrepresentable.
+- **`SessionStartSource` reserves `'clear'`/`'compact'` with no emitter yet** — only `'startup'`/`'resume'` occur until the driving subsystems land (`TODO(compaction)`).
--- a/packages/core/agent/package.json
+++ b/packages/core/agent/package.json
@@ -27,7 +27,7 @@
    "@deepseek-ai/dsh-scope": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
    "@deepseek-ai/dsh-brand": "workspace:^",
@@ -35,6 +35,6 @@
    "@deepseek-ai/dsh-scope": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
-    "cordis": "^4.0.0-rc.6"
+    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/core/agent/src/dispatch.ts
+++ b/packages/core/agent/src/dispatch.ts
@@ -1,14 +1,7 @@
 /**
- * Fused scope-carrier dispatch for agent-subject operations, plus the assembly
- * context builder. The sanctioned ordinary spelling is
- * `agentEvents(ctx, agent).waterfall('agent/request', …)`: it builds the scope
- * carrier ({@link scopeTarget} keyed by the agent) AND injects the subject as
- * the first argument in one move, so a site cannot name a different subject.
- * The registry lifecycle pair is the deliberate exception: `enter()` captures
- * one stable carrier before commit and `announce()`/detach dispatch through it
- * directly, so both lifecycle edges use the same routing identity. The dev
- * scoped-dispatch invariant checks both shapes.
- *
+ * Agent-scoped dispatch and prompt assembly helpers. Ordinary events use the
+ * fused dispatcher so subject and scope key cannot diverge; registry lifecycle
+ * code instead captures one stable carrier for both edges.
 * @module @deepseek-ai/dsh-agent/dispatch
 */

@@ -74,9 +67,7 @@ export interface AgentEventDispatch {
 }

 /**
- * Build the fused dispatcher for `agent`'s events (see the module doc). Cheap
- * (one carrier + one small object) — dispatch sites create it per run/turn
- * rather than caching it on the agent.
+ * Build a dispatcher that couples the agent subject to its scope carrier.
 * @param ctx - the context to dispatch through (any context of the app).
 * @param agent - the subject agent; also the scope-carrier key.
 * @returns the fused dispatcher.
@@ -121,11 +112,8 @@ export function agentEvents(ctx: Context, agent: Agent): AgentEventDispatch {
 }

 /**
- * The assembly context for one agent's prompt: the typed `agent` DX field and
- * the `scope` layer selector, set together (setting `agent` without `scope`
- * silently drops the agent's scoped sections/tools from the assembly — the
- * dev invariants flag it). THE way the loop (and any custom driver) builds
- * its per-step `ctx.systemPrompt.assemble(…)` input.
+ * Build the prompt assembly context with agent and scope set together, so
+ * agent-scoped prompt and tool contributions cannot be silently omitted.
 * @param agent - the agent the assembly is for.
 * @returns the context to pass to `assemble()`.
 */
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -31,59 +31,23 @@ declare module 'cordis' {
  }
 }

-/**
- * Options for programmatically creating an agent through the registry factory
- * ({@link AgentRegistry.create}). The caller supplies the live `sessionId`
- * (e.g. an ACP-generated id) and optional session metadata (the validated
- * `cwd`, fork lineage); the factory creates the session, the agent, and wires
- * them together.
- */
+/** Options for creating an agent and its caller-named session. */
 export interface CreateAgentOptions {
  /** The agent's id (the registry handle). */
  readonly agentId: AgentId
  /** The live session's id (NOT derived from agentId). */
  readonly sessionId: SessionId
-  /**
-   * Session creation metadata: validated absolute `cwd`, `parentSession`
-   * fork lineage, and the `seedLength` seed boundary. Mirrors the
-   * `cwd`/`parentSession`/`seedLength` fields of
-   * {@link CreateSessionOptions.meta} in dsh-session (the internal-only
-   * `createdAt`, used when reconstructing a persisted session, is deliberately
-   * excluded — a factory caller never sets it). This is durable session data,
-   * so the session boundary validates and snapshots it before asynchronous
-   * setup begins.
-   */
+  /** Durable session metadata, validated and detached before setup. */
  readonly meta?: { readonly cwd?: string; readonly parentSession?: SessionId; readonly seedLength?: number }
-  /**
-   * Seed events to reconstruct the child session's log from (the fork lineage
-   * primitive). When present, the factory creates the session with this event
-   * prefix so `deriveMessages()`/`lastTurnNumber` continue from it — used by the
-   * in-process FORK subagent backend to seed a child with a balanced
-   * completed-turn prefix of the parent's log. The prefix MUST be contiguous
-   * from seq 0, carry only lossless-JSON data, and be balanced (no open
-   * turn/step, no dangling tool-call), or the session constructor (and the
-   * dev-mode invariants replay) reject it. The factory passes the raw seed to
-   * the session's durable validator/snapshot boundary. Absent for a fresh
-   * (spawn) child.
-   */
+  /** Balanced contiguous event prefix for a forked session. */
  readonly seed?: readonly SessionEvent[]
  /** Per-agent options (model, …). */
  readonly agentOptions?: AgentOptions
  /** Optional creation-only cancellation signal; detached before the returned handle becomes visible. */
  readonly signal?: AbortSignal
  /**
-   * Creation-time composition of the agent's scoped world. The factory awaits
-   * setup after minting `agentCtx` but BEFORE inserting or announcing either
-   * the session or agent, so observers can never see a partially configured
-   * world. Everything registered through `agentCtx` (scoped tools, prompt
-   * sections/variables, `restrict()`, listeners, awaited child plugins) exists
-   * before `session/created`, `agent/created`, `agent/session-start`, and the
-   * first prompt assembly. A throw/rejection or owner disposal rolls the scope
-   * back without publishing either id.
-   *
-   * **Setup composes, it never drives**: the callback is trusted same-process
-   * code and receives the full scoped context, so this is a contract rather
-   * than a runtime restriction. Drive the agent only after creation resolves.
+   * Compose the unpublished scoped context before lifecycle announcements.
+   * Failure rolls back without publishing either id; setup must not drive the agent.
   */
  readonly setup?: (agentCtx: Context) => Promise<void> | void
 }
@@ -101,35 +65,15 @@ export interface ResumeAgentOptions {
  readonly agentOptions?: AgentOptions
  /** Optional creation-only cancellation signal for persistence load/setup; detached before return. */
  readonly signal?: AbortSignal
-  /**
-   * Resume-time composition of the agent's fresh scoped world. Persistence is
-   * loaded first; the factory then mints `agentCtx` and awaits setup while the
-   * reconstructed session and agent remain unpublished. The callback has the
-   * same trusted composition-only contract as
-   * {@link CreateAgentOptions.setup}: all registrations exist before either
-   * creation announcement, and rejection or owner disposal rolls the
-   * transaction back without publishing either id.
-   */
+  /** Compose after persistence load under the same unpublished rollback contract as create. */
  readonly setup?: (agentCtx: Context) => Promise<void> | void
 }

 /**
- * An owned agent plus its disposer, returned by {@link AgentRegistry.create} /
- * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: among consumers,
- * only the holder can tear this agent down. The registered factory provider is
- * also a structural owner because the scoped agent depends on that provider's
- * service surface; provider unload stops and drains every live handle it made.
- * `dispose()` stops the loop, awaits its exit and every outstanding
- * idle-injection flush (quiescence — NOT just the `disposed`
- * status flip), unregisters the agent, removes its session from the store, and
- * finally unwinds its scoped world. This order captures every agent-started
- * `session/flush` before the session is detached and keeps scoped listeners
- * alive through those checkpoints.
- *
- * `ctx.agents.get(id)` still returns a bare {@link Agent} — the handle is
- * exposed only to the consumer owner that created it; the structural provider
- * reaches the same teardown internally. Config-created agents (the loop's own
- * startup) are owned by the loop fiber and never need a handle.
+ * Holder-owned agent capability. Disposal stops and drains the loop and idle
+ * flushes before unregistering the agent, detaching its session, and unwinding
+ * its scoped context. Provider unload reaches the same quiescence boundary;
+ * registry observers receive only the bare {@link Agent}.
 */
 export interface AgentHandle {
  agent: Agent
@@ -144,30 +88,16 @@ export interface AgentHandle {
 */
 export interface AgentFactory {
  /**
-   * Create a new agent on a caller-supplied session id. Async because creation
-   * awaits unpublished setup, inserts both session and agent, emits their
-   * creation notifications in order, emits `agent/session-start`, and only
-   * then starts the loop. The sequence is
-   * rollback-covered, but notifications delivered before a later listener
-   * failure remain observable; every agent or session creation announcement
-   * that began is paired by `agent/disposed` or `session/disposed` during
-   * rollback. The owner disposes the resolved handle to stop/drain,
-   * unregister, remove the session, and unwind the scope.
-   * The registry passes a context carrying the `create()` caller's fiber and
-   * scope as `ownerCtx`. The implementation attaches the unpublished
-   * transaction and resulting lifecycle to that owner; it must not infer
-   * ownership from the factory object's registration context.
+   * Create and compose under caller ownership, publish and announce session then
+   * agent, emit session-start, and start the driver. Rollback pairs any creation
+   * announcement that began.
   * @param ownerCtx - caller-bound context that owns the transaction and live handle.
   * @param options - agent/session identity, configuration, and optional setup.
   * @returns the owned handle after setup, both announcements, and loop start complete.
   */
  createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>
  /**
-   * Load a persisted session and resume an agent on it. Async because it awaits
-   * both `ctx.sessionPersistence.load` and the optional unpublished setup
-   * transaction; must be called after that service exists (consumers inject
-   * `sessionPersistence`). Publication follows the same ordered boundary as
-   * {@link createAgent}.
+   * Load, compose, publish, announce, and resume an agent under caller ownership.
   * @param ownerCtx - caller-bound context that owns load, setup, and the live handle.
   * @param options - persisted identity, configuration, and optional setup.
   * @returns the owned handle after setup, both announcements, and loop start complete.
@@ -209,41 +139,25 @@ export class AgentRegistry extends Service {

  constructor(ctx: Context) {
    super(ctx, 'agents')
-    // The `ctx.agent` DX accessor: default `undefined` on every context, so a
-    // plain plugin context reads cleanly instead of hitting the Cordis
-    // unknown-property throw. Each Agent.ctx shadows it with an own property
-    // (own properties resolve before the context proxy is consulted), so the
-    // accessor body never needs to resolve a scope itself. Effect-scoped:
-    // unwinds with this service's fiber.
+    // Agent contexts shadow this plain-context default with an own property.
    ctx.accessor('agent', { get: () => undefined })
  }

  /**
-   * Register the agent-creation factory (the loop calls this on construction,
-   * effect-scoped). A traced Cordis service is canonicalized to its concrete
-   * target; each create/resume call is then traced through that caller's
-   * context so ownership follows the caller without stacking proxy layers.
-   * Throws if a factory is already registered. Returns the disposer; on
-   * dispose the factory slot is cleared.
+   * Register the effect-scoped creation factory, rejecting a duplicate. Service
+   * factories are retraced through each create/resume caller for ownership.
   * @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
-   * @returns the disposer that clears the factory slot. The exact
-   *   Cordis effect disposer (single-shot): composite (generator) effects may
-   *   yield it directly — exact identity nests the teardown in order.
+   * @returns the exact Cordis effect disposer.
   */
  setFactory(factory: AgentFactory): () => void {
    const dispose = this.ctx.effect(() => {
      if (this.factory !== undefined) throw new Error('an agent factory is already registered')
-      // Avoid stacking two Cordis shadow layers when a caller passes a Service
-      // already read through a context. Calls are re-traced through their
-      // actual owner context below.
+      // Store the concrete service; calls are retraced through their owner.
      const target = (factory as AgentFactory & { [symbols.original]?: AgentFactory })[symbols.original] ?? factory
      this.factory = { target }
      return () => { this.factory = undefined }
    }, 'agents.setFactory()')
-    // The exact cordis effect disposer (the agents.register() convention): a
-    // caller's composite effect can yield it for in-order teardown; the
-    // loop's constructor effect returns it directly, identity-nesting the
-    // registration under that effect.
+    // Return the exact disposer so composite effects preserve teardown order.
    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
    return dispose
  }
@@ -255,20 +169,14 @@ export class AgentRegistry extends Service {
  }

  /**
-   * Create and publish a new agent through the registered factory.
-   * Distinct from {@link register} (which records an already-constructed
-   * agent): this constructs the agent and its session. Rejects if no factory is
-   * registered or creation/setup fails. The resolved {@link AgentHandle} lets
-   * the owner tear down exactly this agent.
+   * Create and publish an owned agent and session through the active factory.
+   * Rejects if no factory is registered or creation, setup, or publication fails.
   * @param options - agent id, session id/seed/metadata, and agent options.
   * @returns the handle after setup, rollback-covered publication, and loop start complete.
   */
  async create(options: CreateAgentOptions): Promise<AgentHandle> {
    const ownerCtx = this.ctx
-    // Re-trace a Service-backed factory through the accessing context
-    // explicitly. This preserves AgentLoop's dependency origin while binding
-    // its effects to ownerCtx; plain factories receive ownerCtx as an explicit
-    // capability and need no Cordis tracker magic.
+    // Bind service effects to this caller while preserving factory dependencies.
    const { target } = this.requireFactory()
    const receiver = getTraceable(ownerCtx, target)
    // eslint-disable-next-line @typescript-eslint/unbound-method -- Reflect.apply intentionally supplies the caller-traced receiver
@@ -291,22 +199,10 @@ export class AgentRegistry extends Service {
  }

  /**
-   * Register a live agent. Throws if an agent with the same id is already
-   * registered. Emits `agent/created` on registration and `agent/disposed`
-   * when the calling fiber is disposed — both with the agent's scope carrier
-   * (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
-   * emits are scope-filtered regardless of which context invoked `register`
-   * (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
-   * requires passing the carrier). Returns the disposer.
+   * Register a live agent in the calling effect scope, with scope-filtered
+   * creation and disposal events. Duplicate ids throw.
   * @param agent - the already-constructed agent to record in the store.
-   * @returns the EXACT Cordis effect disposer (single-shot; a repeat call
-   *   returns undefined without awaiting an in-flight teardown). Exact
-   *   identity is load-bearing: a composite (generator) effect that owns a
-   *   teardown ORDER — the agent factory's lifecycle chain — must yield THIS
-   *   function so Cordis nests the unregistration at that yield position;
-   *   yielding a wrapper would leave it disposing as a concurrent sibling on
-   *   owner unload, unregistering the agent (and emitting `agent/disposed`)
-   *   while its final turn is still draining.
+   * @returns the exact Cordis effect disposer for nested teardown ordering.
   */
  register(agent: Agent): () => void {
    const dispose = this.ctx.effect(function* (this: AgentRegistry) {
@@ -318,22 +214,15 @@ export class AgentRegistry extends Service {
  }

  /**
-   * Insert an already-constructed agent without announcing it. This is the
-   * advanced ordered-lifecycle primitive used by the async agent factory: it
-   * first completes setup while the agent is unpublished, then assigns the
-   * returned detach closure into its pre-installed composite teardown before
-   * calling {@link announce}. Ordinary callers use {@link register}.
+   * Insert an unpublished agent for an ordered factory transaction.
   * @param agent - the prepared, unpublished agent.
-   * @returns an idempotent closure that removes this exact entry and emits
-   *   `agent/disposed` with listener failures contained. When called from a
-   *   synchronous `agent/created` listener, removal and disposal wait until
-   *   that creation dispatch unwinds.
+   * @returns an idempotent closure that removes this exact entry and emits the
+   * paired disposal edge; detachment during creation dispatch is deferred.
   */
  enter(agent: Agent): () => void {
    const id = agent.id
    const carrier = scopeTarget(agent, agent)
-    // This is the authoritative collision boundary. Concurrent create/resume
-    // operations may both prepare, but only one exact entry can publish.
+    // Prepared transactions arbitrate identity at this publication boundary.
    if (this.entries.has(agent) || this.store.has(id)) throw new Error(`agent "${id}" is already registered`)
    const entry: AgentEntry = {
      id,
@@ -349,11 +238,7 @@ export class AgentRegistry extends Service {
    const detach = (): void => {
      if (!entered) return
      entered = false
-      // Every callback reached by this creation dispatch must observe the same
-      // live entry, and disposal must follow creation. A listener may own
-      // the advanced detach capability, so make that ordering structural:
-      // visibility and the paired disposal are deferred until announce()'s
-      // synchronous dispatch has unwound.
+      // Creation listeners observe one stable entry before paired disposal.
      if (entry.announcing) {
        entry.detachRequested = true
        return
--- a/Show More
+++ b/Show More