Merge branch 'codex/simp-unify-agent-session-id' into codex/simp-ui-identity-residue

# Conflicts:
#	docs/config-catalog.md
#	docs/event-producer-consumer.md
#	docs/rfc/implemented/feature/2026-07-06-approval-seam.md
#	packages/ui/acp/README.md
#	packages/ui/acp/src/index.ts
#	packages/ui/jsonrpc/README.md
#	packages/ui/jsonrpc/src/server.ts

packages/AGENTS.md

@@ -2,17 +2,16 @@
 
 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).
+- **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)).
 - **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).
 - **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)).
+- 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 carry `## Known Limitations and Deferred Work` or a justified [allowlist entry](../scripts/verify-package-readme-limitations.ts) ([rationale](../docs/rfc/implemented/process/2026-07-10-readme-known-limitations-gate.md)).
+- Package READMEs put durable consumer gaps and non-obvious maintainer constraints under `## Known Limitations and Deferred Work`; ordinary cleanup stays in its TODO or RFC. Packages with none use a justified [allowlist entry](../scripts/verify-package-readme-limitations.ts) ([rationale](../docs/rfc/implemented/process/2026-07-10-readme-known-limitations-gate.md)).

packages/bash/bash-local/README.md

@@ -22,7 +22,7 @@ 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.
 
 ## Model Experience
@@ -37,6 +37,5 @@ Indirectly, through `dsh-tool-bash`, which renders this executor's bounded stdou
 - **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.
-- **`OutputCollector.snapshot()` / `totalBytes` are test-shaped residuals** — the live poll path uses `readFrom()` and a marked cleanup can inline the final snapshot and remove the unused public getter.
 
 The raw process handling lives in `src/run.ts`; `src/index.ts` is the service wiring.

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
  */
 
@@ -90,10 +82,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 +145,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,

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.
  */
@@ -262,10 +237,8 @@ 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
@@ -275,13 +248,9 @@ export class OutputCollector {
 }
 
 /**
- * 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 +280,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 +294,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 +307,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 +316,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 +328,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)
     })

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()

packages/bash/bash-local/tests/run.spec.ts

@@ -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)
@@ -360,7 +355,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'

packages/bash/bash-sandbox/README.md

@@ -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/).
 
@@ -48,7 +48,7 @@ The keyless consumer-integration proofs are `tests/bwrap.e2e.ts`, `tests/landloc
 
 ### Bash tool error, indirectly
 
-**What the model sees**: If no runner can enforce a confined mode, the foreground call fails with code `SANDBOX_UNAVAILABLE` and the exact message `sandbox mode "<mode>" is requested but no sandbox backend is usable on this host; refusing to run the command unconfined. Install bubblewrap or run a Landlock-enforcing kernel (Linux), ensure sandbox-exec is usable (macOS) — Windows has no confinement backend yet — or switch the consumer to danger-full-access.` An execution-time runner failure appends ` Runner failure: <first stderr line>`.
+**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.
 

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 prompt deliberately does not state the mode; each run's
- * `result.sandbox` reports what actually executed plus enforcement
- * completeness, and the tool layer renders denial or runner-failure facts.
+ * 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,

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' })

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'] },

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' })

packages/bash/bash/README.md

@@ -32,7 +32,7 @@ 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).
 
@@ -43,5 +43,4 @@ Indirectly, through `dsh-tool-bash`, which turns executor output and sandbox fac
 ## 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.
-- **Two overlapping surfaces flagged for pruning** — `BashTask.done` duplicates `onTaskDone` (shipped consumers use only the latter), and `get()`/`list()` have test-harness consumers only; both are marked in [the long-running-runtime RFC](../../../docs/rfc/proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md).
 - **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).

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.

packages/bash/bash/src/session-mode.ts

@@ -1,18 +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 receives neither this event
- * nor a standing mode statement. `@deepseek-ai/dsh-tool-bash` names the mode
- * only when it renders a sandbox denial. 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
  */
 
@@ -22,11 +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}); execution and ACP config-option
-     * reporting fold it without adding prompt text or a context notice.
+     * 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. Subsequent execution and ACP config-option reporting fold
- * it on read; no prompt assembly consumes it.
+ * 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).

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
 }

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

@@ -29,11 +29,11 @@ Every field is validated (positive numbers) and defaulted; there are no other tu
 
 ## 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).
 
 ## Model Experience
 
-Indirectly, through Code Mode in `dsh-tools`, which renders this worker's capped printed or returned data, exact `[dsh-code-runtime-worker] log capture truncated at <maxLogBytes> bytes` and `… [truncated]` markers, and `Error: code run failed (<kind>): <message>` failures into a retained `run_code` result while keeping binding traffic and worker internals outside context.
+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
 

packages/code-runtime/code-runtime-worker/src/bootstrap.ts

@@ -1,12 +1,7 @@
 /**
- * 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
  */
 
@@ -96,12 +91,11 @@ export function makeConsoleShim(logs: LogBuffer): Record<(typeof CONSOLE_LEVELS)
 
 /**
  * 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.
@@ -152,16 +146,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 +205,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,17 +244,12 @@ 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,

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
  */
 
@@ -282,11 +276,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
@@ -302,12 +294,8 @@ export class WorkerCodeRuntime extends CodeRuntime {
       const logs: CodeLogEntry[] = []
       const strayLogs: CodeLogEntry[] = []
 
-      // 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 => {
@@ -331,11 +319,8 @@ export class WorkerCodeRuntime extends CodeRuntime {
       worker.stdout.on('data', captureStray('stdout'))
       worker.stderr.on('data', captureStray('stderr'))
 
-      // 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 +338,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) } } : {},

packages/code-runtime/code-runtime-worker/src/protocol.ts

@@ -1,11 +1,7 @@
 /**
- * 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
  */
 

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
  */
 

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))

packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts

@@ -255,10 +255,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');

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([
   {

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
  */
 
@@ -35,26 +23,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 {
   /**

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.
 
 The protected `estimateContentTokens()` and `summarize()` methods are overridable hooks: a tokenizer-based or template-based backend can subclass `BasicCompactService` and override just those, reusing the private retention/pressure accounting 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.
 

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.
  */

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

@@ -15,24 +15,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
@@ -133,14 +119,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 index = nodes.indexOf(cp.seq)

packages/compact/compact/src/index.ts

@@ -1,24 +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 (`dsh-compact-basic`) / 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
- * an agent-owned `Session` and the durable summary event uses 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
  */
 
@@ -43,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) {
@@ -70,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(
@@ -118,37 +62,18 @@ export abstract class CompactService extends Service {
 
   /**
    * Forcibly compact a range of surface nodes into a single summary node.
+   * `start` and `end` name an inclusive span by surface position, not numeric seq
+   * order; replacements can make visible seqs non-monotonic. Both edges must be
+   * balanced so assistant tool calls remain paired with their results. A model-
+   * backed implementation forwards cancellation and rejects active, missing,
+   * reversed, or unbalanced ranges.
    *
-   * `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 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 whose session is mutated and whose routing
-   *   options are used by 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 the replaced range and its token accounting. The durable
-   *   `compact/summary` event owns the summary and bookkeeping-event identity.
+   * @param start - first surface seq, inclusive.
+   * @param end - last surface seq, inclusive.
+   * @param agent - context whose session is mutated and whose routing options guide summarization.
+   * @param signal - optional cancellation; model-backed implementations must forward it.
+   * @throws when compaction is active or the range is missing, reversed, or unbalanced.
+   * @returns the replaced range and token accounting; the durable event owns the summary.
    */
   abstract compactRegion(
     start: number,

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.

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
  */
 

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
 

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -79,14 +79,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>',
@@ -101,7 +101,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>',
     ],
@@ -116,7 +116,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>',
@@ -138,7 +138,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'permission',
-    summary: 'The permission service (`ctx.permission`).',
+    summary: 'Owns the deployment\'s permission presets and their write path.',
     methods: [
       'current(events: readonly SessionEvent[]): string',
       'resolve(name: string): PresetSpec',
@@ -155,7 +155,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>',
@@ -208,7 +208,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',
@@ -218,7 +218,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',
@@ -248,7 +248,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
   },
   {
     key: 'workflows',
-    summary: 'Abstract workflow execution service.',
+    summary: 'Workflow execution seam.',
     methods: [
       'abstract start(request: WorkflowStartRequest): WorkflowRun',
     ],
@@ -345,25 +345,25 @@ export const EVENT_API: readonly EventApiEntry[] = [
     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',
@@ -375,25 +375,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.',
+    summary: 'Awaited parallel durability checkpoint: every listener runs and the caller awaits all of them, with no waterfall veto.',
   },
   {
     name: 'skill/provider-added',
@@ -435,13 +435,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',
@@ -453,25 +453,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',

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
  */
 

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

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>()

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(

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`).

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`).

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: `

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: `

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 shared plugin tree at once**: the teaching overview of the spine behind every app package.
+Read this package for the whole plugin tree and its composition order.
 
 ## The tree it loads
 
@@ -47,7 +47,7 @@ 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
 
@@ -55,6 +55,5 @@ Indirectly, through `dsh-system-prompt`, `dsh-tool-skill`, `dsh-tool-bash`, and
 
 ## Known Limitations and Deferred Work
 
-- **FIXME: package name and location imply product core** — rename `dsh-agent-core` to `dsh-demo-bundle` and move it under `packages/support/`; it is a demo composition bundle, not the product spine.
 - **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.

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 } : {},

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

@@ -191,15 +191,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')
 

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'

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])
     }

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

@@ -98,12 +98,9 @@ function signalAbortError(id: SessionId, 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

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

@@ -166,10 +166,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/)
@@ -251,26 +249,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, SessionId('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')
   })
@@ -365,10 +357,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)
@@ -394,11 +384,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
@@ -416,10 +403,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

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
  */
 
@@ -96,10 +93,8 @@ describe('Agent.cancel()', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('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(SessionId('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(SessionId('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) => {
@@ -399,10 +388,8 @@ describe('Agent.cancel()', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('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) => {
@@ -420,11 +407,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(SessionId('a1'), { model: 'mock' })
@@ -450,11 +433,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(SessionId('a1'), { model: 'mock' })
@@ -464,9 +444,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)

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

@@ -351,9 +351,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)

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

@@ -40,7 +40,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)
@@ -90,7 +90,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
@@ -142,7 +142,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'),
@@ -169,21 +169,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'),
@@ -201,12 +187,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)
@@ -264,7 +248,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)
@@ -319,7 +303,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)
@@ -366,7 +350,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)
@@ -525,7 +509,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)
@@ -563,7 +547,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', {
@@ -581,12 +565,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' } },
     ]
@@ -607,7 +588,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)
   })
 
@@ -653,10 +634,7 @@ describe('step boundary publication order', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('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
@@ -679,10 +657,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)
@@ -834,9 +809,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)
@@ -895,9 +868,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
@@ -909,9 +880,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')
     })
@@ -1002,10 +970,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)
@@ -1113,11 +1078,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)
@@ -1144,12 +1105,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))
@@ -1164,7 +1121,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()
@@ -1182,28 +1139,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 () => {
@@ -1260,9 +1211,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))
@@ -1313,8 +1263,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))

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

@@ -226,9 +226,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' })
   })
 })

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
   })
 })

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

@@ -113,14 +113,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(SessionId('a1'), { model: 'mock' })
@@ -185,9 +179,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(SessionId('a1'), { model: 'mock' })
@@ -511,14 +504,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')
   })
 
@@ -614,11 +606,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) {

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(SessionId('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(SessionId('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' },

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

@@ -10,15 +10,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

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

@@ -451,10 +451,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({ sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent as ReactLoopAgent
@@ -476,10 +474,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({ sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent as ReactLoopAgent

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

@@ -926,11 +926,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() }

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'
@@ -94,11 +93,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')

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()`.
  */

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

@@ -1,16 +1,5 @@
 /**
  * Negative-path tests for the cordis catalog generator (`scripts/gen-cordis-catalog.ts`).
- *
- * The generated catalog is frozen by a regenerate-and-diff freshness gate, so
- * the freshness half is exercised by `pnpm run verify-cordis-catalog` in CI.
- * What a freshness diff CANNOT prove is that the generator REJECTS malformed
- * source the way it promises to — a missing `@mode` tag, a tag that
- * contradicts the signature shape, or a JSDoc-completeness violation (missing
- * prose, an undocumented parameter, a stale `@param`, a missing `@returns`, an
- * unannotated return type). These tests drive `collectEvents()` /
- * `collectServices()` against synthetic fixture packages to prove each guard
- * fires (and that well-formed declarations pass), mirroring the drift-guard
- * negative tests for verify-type-equiv.
  */
 
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'

packages/core/agent/tests/verify-export-jsdoc.spec.ts

@@ -1,15 +1,5 @@
 /**
- * Negative-path tests for the export-surface JSDoc gate
- * (`scripts/verify-export-jsdoc.ts`).
- *
- * The gate's positive half runs against the real tree in CI (`pnpm run
- * verify-export-jsdoc`, part of doc-sync). What that run cannot prove is that
- * the walk REJECTS an undocumented surface the way it promises to — and that
- * every deliberate exemption (heritage members, plugin-protocol slots,
- * constructors, overload implementations, augmentation bodies, re-exports)
- * actually holds. These tests drive `collectExportJsdocViolations()` against
- * synthetic fixture packages, mirroring the gen-cordis-catalog negative
- * tests.
+ * Negative-path tests for the export-surface JSDoc gate (`scripts/verify-export-jsdoc.ts`).
  */
 
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
@@ -160,7 +150,7 @@ describe('verify-export-jsdoc export forms', () => {
     ))).toEqual([expect.stringMatching(/exported function 'f' .* has no JSDoc\./)])
   })
 
-  it('does not treat a never-exported sibling declarator as surface (review round 2)', () => {
+  it('does not treat a never-exported sibling declarator as surface', () => {
     // `export { publicValue }` resolves to the whole variable statement; only
     // the named declarator is surface — the gate must not demand JSDoc for
     // the private sibling sharing the statement.
@@ -169,7 +159,7 @@ describe('verify-export-jsdoc export forms', () => {
     ))).toEqual([])
   })
 
-  it('unions declarators across multiple export lists over one statement (review round 2)', () => {
+  it('unions declarators across multiple export lists over one statement', () => {
     // Two lists each name one declarator of the same undocumented statement:
     // both are surface (deduplicating on first resolution would drop `b`),
     // while the never-exported `c` stays out.
@@ -182,7 +172,7 @@ describe('verify-export-jsdoc export forms', () => {
     ])
   })
 
-  it('scopes a default-export identifier to its own declarator (review round 2)', () => {
+  it('scopes a default-export identifier to its own declarator', () => {
     // `export default` of an identifier reaches the statement through the
     // same name lookup as an export list; the sibling stays private.
     expect(collectExportJsdocViolations(make(
@@ -325,7 +315,7 @@ export namespace Loose {
   })
 })
 
-describe('verify-export-jsdoc fail-closed forms (review round 1)', () => {
+describe('verify-export-jsdoc fail-closed forms', () => {
   it('checks the function contract on a non-identifier default export', () => {
     expect(collectExportJsdocViolations(make(
       '/** Doubles. */\nexport default (x: number): number => x * 2\n',
@@ -418,7 +408,7 @@ describe('verify-export-jsdoc fail-closed forms (review round 1)', () => {
   })
 })
 
-describe('verify-export-jsdoc heritage refinement (review round 1)', () => {
+describe('verify-export-jsdoc heritage refinement', () => {
   it('requires @param for parameters the base member never names', () => {
     const violations = collectExportJsdocViolations(make(`
 /** Seam. */

packages/core/scope/README.md

@@ -1,6 +1,6 @@
 # dsh-scope
 
-Scoped-context registration primitive. `createScope(ctx, key)` mints a Cordis context that TAGS everything registered through it with an opaque `ScopeKey` and OWNS those registrations' lifetime (one backing fiber drives both facts); `scopeOf(ctx)` reads the tag; `scopeTarget(base, key)` builds the dispatch carrier that makes an event scope-filtered — listeners registered through a scoped context fire only for their key's subject, while plain plugin listeners keep firing for every subject. The agent loop is the one scope minter today (one scope per live agent, key = the `Agent` object — the `Agent.ctx` contract in `dsh-agent`), but the mechanism is key-agnostic so packages below the agent layer (`dsh-session`, `dsh-system-prompt`) depend on it without a dependency cycle.
+Scoped registration primitive. `createScope(ctx, key)` creates a tagged Cordis context whose backing fiber owns every registration made through it. `scopeOf(ctx)` reads the tag, and `scopeTarget(base, key)` routes scoped events to listeners with the same key while leaving unscoped listeners global. The agent loop creates one scope per live agent, but the mechanism is key-agnostic so lower-level packages can use it without depending on agents.
 
 ## Public API
 
@@ -15,7 +15,7 @@ Scoped-context registration primitive. `createScope(ctx, key)` mints a Cordis co
 
 ## Design contract
 
-Ownership and visibility derive from ONE fact — which context a registration went through. An explicit `{ scope }` registration parameter could express "visible to X, disposed with Y", which is almost always a bug; the scoped context makes it unrepresentable. This is trusted registration and listener routing, not sandboxing or an authority hierarchy: a same-process plugin is not confined, and a child scope need not be a subset of its parent's view. Rationale, alternatives, and the security non-goal: [the agent-scope RFC](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals).
+The registration context determines both visibility and ownership, preventing a registration from being visible in one scope but disposed with another. Scopes route trusted same-process plugins; they are not sandboxes or authority boundaries. See the [agent-scope RFC](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals) for rationale and security non-goals.
 
 Handing out a scoped context hands out the minting plugin's service-resolution surface (resolution walks the minting fiber's dependency chain, not the holder's) — mint it from the plugin whose dependencies the scoped registrations need to resolve.
 

packages/core/scope/src/index.ts

@@ -73,15 +73,11 @@ export function scopeOf(ctx: Context): ScopeKey | undefined {
 }
 
 /**
- * Build the routing receiver for a scope-filtered event. Untagged listeners
- * remain global; tagged listeners run only when their key matches. A base
- * Cordis filter is composed before the scope predicate.
- *
- * The receiver is deliberately opaque: listener code obtains the real subject
- * from event arguments, never from `this`.
+ * Build an opaque receiver that preserves the base filter, admits untagged
+ * listeners globally, and admits tagged listeners only for a matching key.
  * @param base - subject or service whose existing Cordis filter is preserved.
  * @param key - routed scope identity, or `undefined` for an unscoped subject.
- * @returns an opaque dispatch carrier.
+ * @returns a carrier whose subject remains available only through event arguments.
  */
 export function scopeTarget<T extends object>(base: T, key: ScopeKey | undefined): Scoped<T> {
   const baseFilter = (base as { [CordisContext.filter]?: (ctx: Context) => boolean })[CordisContext.filter]

packages/core/session/src/index.ts

@@ -34,67 +34,41 @@ declare module 'cordis' {
 
   interface Events {
     /**
-     * A session was created in the store. A synchronous listener throw vetoes
-     * publication and rollback emits the matching `session/disposed` edge;
-     * returned-promise rejection is observed and logged but cannot retroactively
-     * veto this synchronous boundary. A synchronous listener that requests the
-     * advanced detach does not remove the entry immediately: removal and the
-     * paired `session/disposed` edge wait until the creation dispatch unwinds.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): the carrier is the
-     * session's owner scope, captured when the session was ENTERED (an agent's
-     * session is entered through `agent.ctx`, so its events dispatch in that
-     * agent's scope; a bare `sessions.create()` from a plain plugin dispatches
-     * subject-less). A listener registered through `agent.ctx` hears only that
-     * agent's sessions; a plain plugin listener hears every session.
+     * Creation announcement during session publication. A synchronous throw vetoes and rolls
+     * back with a paired disposal; detach requested during dispatch is deferred.
+     * A returned-promise rejection is logged but cannot retroactively veto this
+     * synchronous boundary.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+     * receive only sessions entered through that agent's context.
      * @param session - the session just entered and announced.
      * @mode emit
      */
     'session/created'(this: Scoped<Session>, session: Session): void
     /**
-     * A previously announced session left the store. Emitted exactly once on
-     * normal detach or publication rollback, and never for a prepared/entered
-     * session whose `session/created` announcement did not begin. Listener
-     * failures (including returned-promise rejections) are logged and contained
-     * per listener so teardown always reaches quiescence.
-     * Scope-filtered dispatch uses the same owner carrier captured at entry;
-     * agent-scoped listeners hear only their own session's teardown.
+     * Emitted once when an announced session leaves the store, including
+     * publication rollback, but never for an entry whose creation announcement
+     * did not begin. Listener failures are logged and contained.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
      * @param session - the session that is no longer live in the store.
      * @mode emit
      */
     'session/disposed'(this: Scoped<Session>, session: Session): void
     /**
-     * An event was appended to a session log (sync, fire-and-forget). This is
-     * the per-append feed a UI or invariant plugin tails. The log push is the
-     * commit point; synchronous throws and returned-promise rejections from
-     * observers are logged and contained per listener, so they cannot make a
-     * committed append appear to fail or starve later listeners. The exact
-     * callback list and Cordis internal-dispatch checks resolve before the push;
-     * callbacks themselves run only after it.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): the carrier is the
-     * session's owner scope, captured when the session was ENTERED (an agent's
-     * session is entered through `agent.ctx`, so its events dispatch in that
-     * agent's scope; a bare `sessions.create()` from a plain plugin dispatches
-     * subject-less). A listener registered through `agent.ctx` hears only that
-     * agent's sessions; a plain plugin listener hears every session.
+     * Post-commit, fire-and-forget append feed. The listener snapshot resolves
+     * before the log push, but callbacks run after it; observer failures are
+     * logged and contained without making the committed append fail.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+     * receive only events from sessions entered through that agent's context.
      * @param session - the session whose log grew.
      * @param event - the appended event, exactly as recorded.
      * @mode emit
      */
     'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
     /**
-     * Awaited durability checkpoint. The agent loop awaits
-     * `ctx.sessions.flush(session)` at every turn end; persistence
-     * plugins (JSONL, SQLite) drain their write-behind buffers here and on
-     * fiber dispose. Awaited (parallel), not a waterfall: every listener runs
-     * and the caller waits for all of them, but none can veto. Dispatch it
-     * through {@link SessionStore.flush} — the store owns the carrier — never
-     * via a raw `ctx.parallel`.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): the carrier is the
-     * session's owner scope, captured when the session was ENTERED (an agent's
-     * session is entered through `agent.ctx`, so its events dispatch in that
-     * agent's scope; a bare `sessions.create()` from a plain plugin dispatches
-     * subject-less). A listener registered through `agent.ctx` hears only that
-     * agent's sessions; a plain plugin listener hears every session.
+     * Awaited parallel durability checkpoint: every listener runs and the
+     * caller awaits all of them, with no waterfall veto. Dispatch through
+     * {@link SessionStore.flush}. Scope-filtered dispatch
+     * (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
      * @param session - the session whose buffered events must reach durable storage.
      * @mode parallel
      */
@@ -103,13 +77,9 @@ declare module 'cordis' {
 }
 
 /**
- * Renders a `context/message` or `steering/message` event as a tagged
- * synthetic user-role message (the system-reminder pattern: zero adapter
- * burden, models distinguish it from real user prompts by the envelope).
- *
- * Live-adapter review has validated the tagged-envelope rendering against
- * current DeepSeek behavior; provider-specific mismatches belong in that
- * adapter, not in the canonical session vocabulary.
+ * Render injected context as tagged synthetic user-role content, keeping the
+ * canonical session vocabulary provider-neutral. Adapter-specific exceptions
+ * belong in the adapter.
  */
 function renderTagged(tag: string, content: ContentBlock[], source: MessageSource): ContentBlock[] {
   const open = `<${tag} source=${JSON.stringify(source.kind)}>`

packages/core/session/src/json.ts

@@ -1,17 +1,4 @@
-/**
- * Lossless-JSON validation and snapshot materialization for session data.
- *
- * The session event log is the durable source of truth (the event-sourcing / session-persistence RFCs): every
- * `event.data` must round-trip losslessly through JSON so any persistence
- * backend can store and reload it byte-identically. This invariant belongs to
- * the log itself — `Session.append` enforces it at the source, so a
- * non-serializable event never enters `session.events` and the live log can
- * never diverge from what a backend can persist. Other public boundaries use
- * {@link snapshotJsonValue} when they must validate and detach in one pass;
- * {@link isJsonValue} remains the non-copying structural predicate.
- *
- * @module @deepseek-ai/dsh-session/json
- */
+/** Lossless-JSON validation and detached snapshots for durable session data. @module @deepseek-ai/dsh-session/json */
 
 /**
  * A value that round-trips losslessly through JSON: `null`, a boolean, a finite
@@ -25,19 +12,10 @@
 export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }
 
 /**
- * Materialize one detached lossless-JSON snapshot in a SINGLE recursive pass.
- * Each array slot or own enumerable string-keyed object value is read exactly
- * once, validated, and copied immediately. This is intentionally not
- * `isJsonValue(value)` followed by `structuredClone(value)`: a stateful getter
- * could return plain JSON to the check and an exotic class instance to the
- * clone, whose prototype `structuredClone` would erase before a later check.
- *
- * Accepts the same scalar/object vocabulary as {@link isJsonValue}: arrays use
- * the ordinary `Array.prototype` (subclass instances are not plain JSON
- * containers), while null-prototype objects are accepted and normalized to
- * ordinary plain objects. Sparse arrays, cycles, negative zero, non-finite
- * numbers, unsupported scalar types, and exotic object or array shells return
- * `undefined`. A throwing getter is a caller failure and propagates unchanged.
+ * Validate and detach lossless JSON in one read per property, so a stateful
+ * getter cannot change between validation and copying. Accepts ordinary arrays,
+ * plain or null-prototype objects, and JSON scalars; rejects sparse, cyclic,
+ * exotic, negative-zero, and non-finite values. Getter throws propagate.
  *
  * @param value - the candidate value to validate and detach.
  * @returns the detached snapshot, or `undefined` when the value is not
@@ -104,28 +82,12 @@ export function snapshotJsonValue<T>(value: T): T | undefined {
 }
 
 /**
- * Whether `value` is losslessly JSON-serializable: only `null`, finite numbers
- * other than negative zero, booleans, strings, plain arrays, and plain objects
- * of such values. Rejects `BigInt`, function, symbol, `undefined`, `-0` (which
- * JSON rewrites to `0`), non-finite numbers (`NaN`/`Infinity`, which JSON turns
- * into `null`), and exotic objects (`Map`/`Set`/`Date`/class instances) —
- * anything `JSON.stringify` would drop, throw on, or convert lossily. Sparse
- * arrays are rejected too: a hole serializes to `null`, so `[1, , 3]` would not
- * round-trip. Detects circular references (which would throw) and reports them
- * as non-serializable rather than propagating the throw.
- *
- * Scope — this is a structural plain-data predicate, not an invocation of
- * `JSON.stringify`: only an object's OWN ENUMERABLE STRING-keyed properties are
- * inspected (`Object.values`). Symbol-keyed and non-enumerable properties are
- * omitted from the durable data surface. Custom `toJSON` behavior is not
- * executed; boundaries that persist a value first materialize a new plain-data
- * record with {@link snapshotJsonValue}. Getters are invoked during this check,
- * so callers that need a stable detached value use that one-pass materializer
- * instead of checking and then rereading a side-effecting record.
+ * Test the same lossless JSON boundary as {@link snapshotJsonValue} without
+ * detaching it. Only own enumerable string properties participate; `toJSON`
+ * is ignored and getters run, so persistence boundaries use the snapshotter.
  * @param value - the candidate event data to test.
- * @param seen - objects on the current descent path, for circular-reference
- *   detection; the recursion threads it — callers omit it.
- * @returns true when `value` survives a JSON round-trip losslessly.
+ * @param seen - current recursion path; callers omit it.
+ * @returns whether `value` survives JSON round-trip losslessly.
  */
 export function isJsonValue(value: unknown, seen: Set<object> = new Set()): boolean {
   if (value === null) return true

packages/core/session/src/repair.ts

@@ -1,37 +1,7 @@
 /**
- * Crash-recovery repair for an interrupted session log.
- *
- * A persistence backend flushes only at `turn/end`, so a crash can leave a
- * durable log whose final turn never closed: real, fully-written events sit
- * after the last `turn/end` with no closing boundary. A single turn can be huge
- * in a long-horizon task (many steps, large tool output), so those events MUST
- * be preserved — truncating the turn would silently destroy real work. Instead,
- * on reload the backend CLOSES the orphaned turn by appending the minimal
- * synthetic boundary events:
- *
- *   1. an error `tool/result` for every `tool-call` in the interrupted turn that
- *      never got its matching `tool/result` (so the rehydrated history is a
- *      VALID provider transcript — see below),
- *   2. a `step/end` if a step was still open, then
- *   3. a `turn/end` carrying the merge-extensible `{ kind: 'interrupted' }` reason.
- *
- * The marker records that the turn was cut short by a crash, not completed by
- * the model. See the session-persistence RFC.
- *
- * Why the synthetic tool results matter: `deriveMessages()` renders the
- * `tool-call` blocks inside a durable `assistant/message` but only emits a
- * matching tool-result when a `tool/result` EVENT exists. A crash between the
- * assistant message and its tool results (the loop runs the tools AFTER logging
- * the assistant message, so a process killed mid-tool leaves the calls without
- * results) would otherwise reload a history with a dangling assistant tool-call
- * — which every provider rejects as an invalid transcript on the next request.
- * Synthesizing an error result per orphaned call keeps resume safe.
- *
- * This module computes those synthetic closers from an event list; backends
- * return them inline from `load` (so the reconstructed session is balanced and
- * immediately usable) and persist them during that mutating load before any
- * later append continues the log.
- *
+ * Crash-recovery repair for an interrupted session log. It preserves a fully
+ * written final turn and supplies the missing tool, step, and turn boundaries
+ * needed to resume with a provider-valid transcript.
  * @module @deepseek-ai/dsh-session/repair
  */
 
@@ -39,36 +9,19 @@ import type { CallId } from '@deepseek-ai/dsh-llm'
 import type { SessionEvent } from './types.ts'
 
 /**
- * Scan `events` for an open turn/step at the tail and return the synthetic
- * boundary events that close them, with `seq` continuing the log and `time`
- * copied from the last real event (the closers stand in for the crash moment;
- * reusing the last timestamp keeps them deterministic and never invents a
- * "future" time). Returns an empty array when the log is already balanced
- * (ends on a `turn/end`, or is empty) — the common, non-crash case.
+ * Return deterministic synthetic events that close an open tail turn. Unmatched
+ * calls receive error results first, followed by an open `step/end` and an
+ * interrupted `turn/end`; sequences continue the log and timestamps reuse the
+ * last real event. A balanced or empty log returns no events.
  *
- * The closers, in order: an error `tool/result` for each unmatched `tool-call`
- * in the interrupted turn, then a `step/end` if a step is open, then the
- * `turn/end {interrupted}`. The tool-results come first so a step that issued
- * tool calls is balanced (every call has a result) before its `step/end`.
- *
- * Only the LAST turn can be open: the invariants plugin guarantees a `turn/end`
- * before any later `turn/start`, so an interior open turn is impossible in a
- * valid committed log. Likewise at most one step is open within that turn.
  * @param events - the loaded durable log to scan (a valid committed prefix, possibly with a crash tail).
  * @returns the synthetic closer events to append after `events`, in order; empty when the log is already balanced.
  */
 export function interruptedTurnClosers(events: readonly SessionEvent[]): SessionEvent[] {
   let openTurn: number | null = null
   let openStep: number | null = null
-  // Track tool calls vs. their results WITHIN the currently-open turn only: a
-  // call is "pending" until its matching tool/result arrives. Reset at every
-  // turn boundary so a committed earlier turn (already balanced) never leaks a
-  // phantom pending call into the interrupted-turn repair.
-  // Track pending tool calls with their callSeq (the seq of the `tool/call`
-  // event, captured for surface sourceEventSeqs provenance on the synthetic
-  // result). CallSeq is set from `tool/call` events; the assistant/message
-  // block scan may register a call first (it appears earlier in the log), and
-  // the later `tool/call` event fills in the seq.
+  // Reset at each turn boundary so earlier calls cannot leak into tail repair.
+  // Assistant blocks register calls; later tool/call events add provenance seqs.
   const pendingCalls = new Map<CallId, { step: number; callSeq?: number }>()
   for (const event of events) {
     switch (event.type) {
@@ -97,10 +50,7 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
         }
         break
       case 'tool/call':
-        // Capture the tool/call event seq for surface provenance on the
-        // synthesized tool/result. The entry may already exist (registered by
-        // the assistant/message above) or may be new (if the assistant/message
-        // came from a prior step that was already closed).
+        // Add the tool/call seq used as provenance on a synthetic result.
         {
           const entry = pendingCalls.get(event.data.callId)
           if (entry) {
@@ -129,10 +79,8 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
   const time = last.time
   const closers: SessionEvent[] = []
 
-  // Synthesize an error tool/result for each tool-call left unanswered by the
-  // crash, so deriveMessages() yields a valid provider transcript on resume (a
-  // dangling assistant tool-call is rejected by every provider). Insertion
-  // order follows the Map (insertion = log order of the assistant messages).
+  // Close calls before their step: providers reject dangling assistant calls,
+  // and Map insertion order preserves their transcript order.
   for (const [callId, { step, callSeq }] of pendingCalls) {
     closers.push({
       type: 'tool/result',

packages/core/session/tests/derived-cache.spec.ts

@@ -1,10 +1,7 @@
 /**
- * Derived-message cache tests: the session projects each surface node exactly
- * once (O(new nodes) per call), rebuilds on a surface replace (the
- * replaceGeneration signal), returns a fresh array snapshot
- * per call over shared frozen messages, and stays deep-equal to a from-scratch
- * replay derivation at every step — the incremental==scratch property the
- * reconstructability RFC's invariant enforces in dev at request time.
+ * Derived-message cache contract against a scratch oracle: project new nodes
+ * once, rebuild on surface replacements, return fresh arrays over shared
+ * frozen messages, and remain value-equal to replay at every step.
  */
 
 import { describe, expect, it } from 'vitest'
@@ -28,7 +25,6 @@ describe('derived-message cache', () => {
     userText(session, 'two')
     session.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'reply' }] }, { surfaceOp: 'append' })
     expect(session.deriveMessages()).toEqual(scratch(session))
-    // An empty-content assistant/message (usage host) projects to nothing.
     session.append('assistant/message', { turn: 1, step: 2, content: [], usage: { inputTokens: 1, outputTokens: 0 } }, { surfaceOp: 'append' })
     expect(session.deriveMessages()).toEqual(scratch(session))
   })
@@ -48,7 +44,6 @@ describe('derived-message cache', () => {
 
     expect(session.deriveMessages()).toHaveLength(1)
     expect(session.deriveMessages()).toEqual(scratch(session))
-    // The array a caller took before the replace is untouched.
     expect(beforeReplace).toHaveLength(2)
   })
 
@@ -61,7 +56,7 @@ describe('derived-message cache', () => {
     const second = session.deriveMessages()
     expect(first).toHaveLength(1)
     expect(second).toHaveLength(2)
-    // Shared projection objects: the same frozen message instance, once ever.
+    // Array snapshots share their frozen message projections.
     expect(second[0]).toBe(first[0])
     expect(Object.isFrozen(first[0])).toBe(true)
   })
@@ -73,8 +68,7 @@ describe('Session.deriveEventMessage — the per-event projection', () => {
     const session = new Session(SessionId('per-event'))
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
     const event = session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    // The fold path (deriveMessages) and the per-event path share the
-    // projection, so an external reconstructor cannot disagree with the cache.
+    // Full and per-event derivation share one projection.
     expect(session.deriveEventMessage(event)).toEqual(session.deriveMessages().at(-1))
   })
 

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

@@ -1,16 +1,6 @@
 /**
  * Negative-path tests for the persistence log catalog generator
  * (`scripts/gen-persistence-catalog.ts`).
- *
- * The generated catalog is frozen by a regenerate-and-diff freshness gate, so
- * the freshness half is exercised by `pnpm run verify-persistence-catalog` in
- * CI. What a freshness diff CANNOT prove is that the generator REJECTS
- * malformed source the way it promises to — a member without description
- * prose, a forbidden `@mode` tag, a non-literal member name, a duplicate event
- * declaration, a missing or ambiguous `SurfaceEventType` union, a stale union
- * member. These tests drive the exported collectors against synthetic fixture
- * packages to prove each guard fires (and that well-formed declarations pass),
- * mirroring the gen-cordis-catalog negative tests.
  */
 
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'

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

@@ -13,10 +13,8 @@ import { CallId } from '@deepseek-ai/dsh-llm'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEventMap, SessionEventType, SurfaceIntent } from '@deepseek-ai/dsh-session'
 
-// An appendable event: its type/data plus, for surface-eligible types, the
-// explicit surface intent the generator declares (mirroring how a real caller
-// passes it). The intent is part of the generated fixture, NOT synthesized by
-// `build`, so each arbitrary states the marker it produces.
+// Each arbitrary supplies its own surface intent; `build` must not synthesize
+// one or the property would fail to exercise malformed fixture choices.
 type Appendable = {
   [T in SessionEventType]: { type: T; data: SessionEventMap[T]; intent?: SurfaceIntent }
 }[SessionEventType]

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

@@ -155,11 +155,8 @@ describe('interruptedTurnClosers', () => {
   })
 
   it('handles tool/call without a matching assistant/message entry gracefully', () => {
-    // A tool/call event exists in the log but no assistant/message registered
-    // the callId in pendingCalls (e.g., a plugin appended it directly, or the
-    // assistant/message from a prior step didn't have this call). The repair
-    // should still close the turn — it just won't synthesize a result for this
-    // call (there's nothing to answer).
+    // A raw tool/call with no assistant-registered pending call has nothing to
+    // answer; repair still closes the step and turn without synthesizing a result.
     const events: SessionEvent[] = [
       userTurnStart(1, 0),
       { type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 } },

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

@@ -81,9 +81,6 @@ describe('Session', () => {
     const before = structuredClone(session.events)
 
     // A misbehaving consumer tries to mutate the messages it was handed.
-    // Derived messages are frozen shared projections (cloned once off the
-    // log, then deep-frozen): every mutation attempt THROWS in strict mode —
-    // isolation by unrepresentability, not by per-call cloning.
     const messages = session.deriveMessages()
     const userBlock = messages[0]!.content[0]!
     expect(() => { if (userBlock.type === 'text') userBlock.text = 'HACKED' }).toThrow(TypeError)
@@ -132,11 +129,8 @@ describe('Session', () => {
   it('rejects a surface-eligible append with no surfaceOp marker (runtime guard for the union-widening loophole)', () => {
     const session = new Session(SessionId('s5b'))
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    // The typed overload makes surfaceOp mandatory only when the type argument is
-    // a SPECIFIC SurfaceEventType literal. A caller iterating raw events widens it
-    // to the SessionEventType union, where the conditional rest collapses to
-    // optional — the exact shape `for (const e of log) append(e.type, e.data)`
-    // produces. Reproduce that here and assert the runtime guard rejects it.
+    // A widened SessionEventType bypasses the overload's conditional requirement,
+    // so the runtime guard must still reject the missing surface marker.
     const widenedType = 'user/message' as SessionEventType
     expect(() => session.append(widenedType, { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }))
       .toThrow(/surface-eligible and requires a surfaceOp marker/)
@@ -663,10 +657,8 @@ describe('SessionStore', () => {
   })
 
   it('enter() rejects a stale prepared session whose id is already live (no overwrite)', async () => {
-    // prepare()/enter() are public cross-package primitives that a caller may
-    // separate with arbitrary work. A stale prepared session must NOT overwrite
-    // a live store entry of the same id — its detach disposer would later delete
-    // the REAL session, breaking the store-uniqueness invariant.
+    // A stale prepared object must not replace the live same-id entry; its later
+    // detach would otherwise remove the wrong session.
     const ctx = new Context()
     await ctx.plugin(SessionStore)
     const stale = ctx.sessions.prepare(SessionId('racy'))

packages/core/system-prompt/README.md

@@ -1,6 +1,6 @@
 # dsh-system-prompt
 
-System prompt assembly registry. Plugins contribute ordered text sections, tool-schema providers, and named prompt variables. The agent loop calls `assemble(context)` once per step, and `renderPrompt(assembly)` is the full system prompt the model sees. The plugin registers the harness-owned openers itself — the static `harness:identity` section and the global default `deployment:persona` section — so they remain available regardless of which loop plugin drives an agent. An agent-scoped contribution with the same persona name shadows that default for its agent.
+System prompt assembly registry. Plugins contribute ordered sections, tool schemas, and named variables. The loop assembles once per step and renders the result as the complete model prompt. This plugin owns the static harness identity and global deployment persona; an agent-scoped persona shadows the global default.
 
 ## Config
 
@@ -20,7 +20,7 @@ System prompt assembly registry. Plugins contribute ordered text sections, tool-
 
 ### Live events
 
-`system-prompt/assemble` is an expert cooperative seam: its returned assembly is authoritative, and a listener that replaces or removes entries owns preserving any active Code Mode or structured-output protocol. Prefer [`ToolRegistry.restrict()`](../tools/README.md) when tool filtering must stay aligned across model presentation, lookup, and execution. Registry change is the deliberately unfiltered notification that an assembly input changed, possibly for one scope; exact signatures, dispatch modes, and filtering contracts live in the generated [Cordis event catalog](../../../docs/cordis-catalog/events.md).
+`system-prompt/assemble` is authoritative; listeners that replace entries must preserve any active Code Mode or structured-output protocol. Use [`ToolRegistry.restrict()`](../tools/README.md) when filtering must stay aligned across presentation, lookup, and execution. Registry-change notifications are unfiltered. The generated [event catalog](../../../docs/cordis-catalog/events.md) owns signatures and dispatch contracts.
 
 ### Key types
 

packages/core/system-prompt/src/index.ts

@@ -1,13 +1,5 @@
 /**
- * System prompt assembly registry. Plugins contribute ordered text sections,
- * tool schema providers, and named prompt variables; `assemble(context)`
- * collates them through a waterfall that runs once per step, and `renderPrompt`
- * interpolates `{{variable}}` references into the final text.
- *
- * The harness-owned prompt openers live here too: this plugin registers the
- * static `harness:identity` section (order −100) and the deployment's
- * `deployment:persona` section (order 0, from its `persona` config), so they
- * exist for every agent regardless of which loop plugin drives it.
+ * Registry for ordered prompt sections, tool schemas, and prompt variables.
  *
  * @module @deepseek-ai/dsh-system-prompt
  */
@@ -25,58 +17,28 @@ declare module 'cordis' {
 
   interface Events {
     /**
-     * Waterfall around prompt assembly — mutate or extend the
-     * {@link PromptAssembly} (sections + tools + variables) before it is
-     * rendered. Bound to the {@link SystemPrompt} service; call `next()` to
-     * delegate.
-     *
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): the carrier is keyed
-     * by `context.scope` — a listener registered through `agent.ctx` fires only
-     * for that agent's assemblies; a plain plugin listener fires for every
-     * assembly (scope-less ones included, dispatched subject-less).
-     *
-     * The returned assembly is authoritative. This is an expert composition
-     * seam: a listener that removes or replaces another plugin's protocol
-     * contribution owns preserving that protocol's invariants.
-     * @param assembly - the assembly built from the registered sections, tool
-     *   providers, and variable providers; listeners may mutate it or return a
-     *   replacement.
-     * @param context - the per-assembly {@link AssembleContext} the caller
-     *   passed to {@link SystemPrompt.assemble} (e.g. which agent the prompt
-     *   is for), so a listener can filter or extend per agent.
+     * Expert waterfall over the assembled sections, tools, and variables.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
+     * receive only that scope's assemblies. The returned value is authoritative.
+     * @param assembly - the mutable assembly built from registered providers.
+     * @param context - the caller's per-assembly context.
      * @mode waterfall
      */
     'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
     /**
-     * A section, tool provider, or variable provider was registered
-     * or unregistered (the assembly inputs changed — possibly for one scope
-     * only). An UNFILTERED registry-subject notification, deliberately not
-     * scope-filtered dispatch: a global change concerns every agent's next
-     * assembly, so a scoped listener subscribing here sees every change, not
-     * just its own scope's.
+     * Emitted when any prompt provider changes. This registry notification is
+     * unfiltered because a global change affects every scope.
      * @mode emit
      */
     'system-prompt/change'(): void
   }
 }
 
-/**
- * Per-assembly input: what one {@link SystemPrompt.assemble} call is FOR.
- * Merge-extensible and agnostic of who assembles — `@deepseek-ai/dsh-agent`
- * declares the `agent` field, so section text and variable providers can be
- * functions of the calling agent. Every field is optional by nature: a bare
- * `assemble()` (tests, diagnostics) carries an empty, scope-less context, and
- * providers must tolerate absent fields.
- */
+/** Merge-extensible context for one prompt assembly. */
 export interface AssembleContext {
   /**
-   * The scope layer this assembly resolves (`@deepseek-ai/dsh-scope`): scoped
-   * sections/variables/tool-providers registered through this key's context
-   * join the assembly (shadowing same-named global contributions), and the
-   * `system-prompt/assemble` waterfall dispatches in this scope. The agent
-   * loop sets it to the agent (alongside the `agent` DX field — never set
-   * `agent` without `scope`; the dev invariants flag the mismatch). Absent =
-   * a scope-less assembly: global layer only, subject-less dispatch.
+   * Scope whose providers and waterfall listeners participate. When absent,
+   * only global providers and subject-less listeners participate.
    */
   scope?: ScopeKey
 }
@@ -111,16 +73,7 @@ export interface AssembledSection {
   text: string
 }
 
-/**
- * What one tool-schema provider contributes to an assembly
- * ({@link SystemPrompt.tools}). `schemas` is the provider's POST-restriction
- * visible set for the assembly's scope — exactly what the model may be shown.
- * `knownNames` is its PRE-restriction name universe: the set configured names
- * (`toolOrder`) are validated against, so a config typo fails loud while a
- * restricted-away tool stays a normal, non-erroneous absence. Omitted,
- * `knownNames` defaults to the names of `schemas` (right for providers with no
- * restriction concept).
- */
+/** Tool schemas visible in one assembly and their pre-restriction name set. */
 export interface ToolProviderResult {
   /** The schemas this provider contributes to THIS assembly. */
   readonly schemas: readonly ToolSchema[]
@@ -129,20 +82,8 @@ export interface ToolProviderResult {
 }
 
 /**
- * The assembled prompt.
- *
- * Tool schemas are part of the assembly by design: "what the model is told it
- * can do" is one coherent thing managed here, even though adapters transmit
- * `tools` as a separate wire field rather than prompt text. They arrive in
- * the canonical model-facing order (see {@link Config.toolOrder}).
- *
- * `variables` carries every registered prompt variable resolved against this
- * assembly's context — key present means registered, `undefined` value means
- * "no value for this assembly" (referencing it renders an error). Section
- * texts are resolved but NOT yet interpolated; {@link renderPrompt} applies
- * the variables, so waterfall listeners can still add sections or variables.
- *
- * Merge-extensible: plugins can declare extra fields on this interface.
+ * Merge-extensible assembled prompt. Sections remain uninterpolated until
+ * {@link renderPrompt}; tools are already in canonical model-facing order.
  */
 export interface PromptAssembly {
   sections: AssembledSection[]
@@ -156,22 +97,12 @@ const VARIABLE_NAME = /^[a-z][a-z0-9_]*$/
 /** A complete `{{...}}` reference group at the scan position (validated after). */
 const GROUP_AT = /^\{\{([^{}]*)\}\}/
 
-/**
- * The rest entry for {@link Config.toolOrder}: the position where registered
- * tools not named in the list are inserted (in lexicographic name order).
- * Reserved: collected tool schemas using this name are rejected before
- * ordering, so the marker can never collide with a real model-facing tool.
- */
+/** Reserved {@link Config.toolOrder} marker for unlisted tools. */
 export const TOOL_ORDER_REST = '<unlisted-tools>'
 
 /**
- * Validate a configured tool-order list's shape at service construction:
- * the {@link TOOL_ORDER_REST} rest entry exactly once, no duplicate names.
- * Returns the list (or undefined when unconfigured); throws otherwise,
- * failing the service at load — a bad order config must never reach an
- * assembly. Whether every listed name matches a registered tool is checked
- * at each assembly instead ({@link orderTools}): tool plugins register after
- * this service constructs, so the tool set does not exist yet here.
+ * Validate duplicate names and the required {@link TOOL_ORDER_REST} marker.
+ * Registered names are checked later because plugins have not loaded yet.
  */
 function validateToolOrder(toolOrder: string[] | undefined): string[] | undefined {
   if (toolOrder === undefined) return undefined
@@ -187,20 +118,9 @@ function validateToolOrder(toolOrder: string[] | undefined): string[] | undefine
 }
 
 /**
- * Order collected tool schemas by the validated policy: with no configured
- * list, plain lexicographic name order; with one, listed names take their
- * listed position and every unlisted tool lands at the
- * {@link TOOL_ORDER_REST} rest entry in lexicographic name order. A listed
- * name outside `knownNames` — the providers' PRE-restriction name universe —
- * throws: misconfiguration fails loud, and each assembly is the earliest
- * moment the registered tool set exists to check against (tool plugins
- * register after the service constructs, so load time is too early); the
- * assembly rejects, failing the caller's turn before any model request. A
- * listed name that is KNOWN but not collected (a tool restricted away for
- * this assembly's scope) is a normal absence: its position simply
- * contributes nothing — `toolOrder` stays compatible with per-agent
- * `restrict()` masks. Never drops a collected tool, and both sorts are
- * stable, so tools sharing a name keep their collection order.
+ * Apply configured tool order, inserting unlisted tools lexicographically at
+ * {@link TOOL_ORDER_REST}. Unknown configured names fail; known but restricted
+ * names may be absent.
  */
 function orderTools(tools: ToolSchema[], toolOrder: string[] | undefined, knownNames: ReadonlySet<string>): ToolSchema[] {
   const reserved = tools.find(tool => tool.name === TOOL_ORDER_REST)
@@ -226,62 +146,25 @@ function compareToolNames(a: ToolSchema, b: ToolSchema): number {
 /** Plugin config: the deployment-authored fragment of the system prompt (see {@link Config.persona} for its contract). */
 export interface Config {
   /**
-   * The deployment's persona — the ONE deployment-authored fragment of the
-   * system prompt, rendered as the order-0 `deployment:persona` section
-   * (after the harness identity, before all tool guidance). Every agent in
-   * the context shares it by default; a per-agent persona is a SCOPED section
-   * of the same name registered through that agent's `agent.ctx` (it shadows
-   * this one for that agent — the subagent seam's `persona` request field does
-   * exactly that). Template, not free-form text:
-   * every complete `{{…}}` group is interpreted strictly against the
-   * registered prompt variables (the shipped agent loop registers `{{model}}`
-   * and `{{cwd}}`), and there is no escape syntax for literal `{{…}}` prose
-   * yet (a deliberate deferral; see the prompt-variables RFC). Defaults to
-   * `''` — the empty section is dropped at render, so a persona-less
-   * deployment opens with the harness identity alone.
+   * Deployment-wide order-0 persona template. A scoped section named
+   * `deployment:persona` shadows it; `{{variable}}` references are strict.
    */
   persona?: string
   /**
-   * Explicit model-facing tool order, as a list of `ToolSchema.name`s: listed
-   * tools take their listed position, and tools absent from the list are
-   * inserted at the {@link TOOL_ORDER_REST} (`'<unlisted-tools>'`) entry in
-   * lexicographic name order. A configured list must contain the rest entry
-   * exactly once, no duplicate names, and no name without a registered tool —
-   * a misconfigured order blocks work instead of silently reaching a model
-   * request: shape violations throw at load, and an unregistered name rejects
-   * every assembly. `TOOL_ORDER_REST` is reserved for the list marker and may
-   * not be a collected tool name; such a provider output also rejects the
-   * assembly. The single assembly-time validation rejects either failure
-   * before any model request — the earliest moment the registered tool set
-   * exists to check against, since tool plugins register after this service
-   * constructs. When omitted, tools are ordered lexicographically by name.
-   * Applied to the tools
-   * {@link SystemPrompt.assemble} collects, BEFORE the
-   * `system-prompt/assemble` waterfall — like the sections' `order` sort, it
-   * canonicalizes what the registry contributed (registration order is a
-   * plugin-load artifact); a waterfall listener that mutates the tool list
-   * owns the determinism of what it emits. Rationale (and why not per-plugin
-   * weights): docs/rfc/implemented/feature/2026-07-06-explicit-tool-order.md.
+   * Model-facing tool names in order, with {@link TOOL_ORDER_REST} exactly once.
+   * Shape errors fail at load and unknown names fail at assembly; known names
+   * hidden in one scope may be absent there. Omitted means lexicographic order.
    */
   toolOrder?: string[]
 }
 
 /**
- * Renders the text part of an assembly: interpolates `{{variable}}`
- * references in each section from `assembly.variables`, drops empty sections,
- * and joins the rest with blank lines.
- *
- * Strict by design (fail loud beats shipping a malformed prompt): a reference
- * to an unregistered variable, to a registered variable with no value for
- * this assembly, a complete `{{…}}` group that is not a well-formed variable
- * name (e.g. `{{ model }}`), or a `{{` that does not open a complete group
- * while a `}}` still follows (e.g. `{{{model}}}`, `{{a{b}}`) all throw. A
- * lone `{{` with no `}}` anywhere after it is ordinary prose and passes
- * through verbatim. Substituted values are never re-scanned.
- * @param assembly - the assembly to render (typically the awaited result of
- *   {@link SystemPrompt.assemble}); only `sections` and `variables` are read.
- * @returns the full system prompt text; `''` when every section renders empty
- *   (the caller then sends no system prompt at all).
+ * Interpolate strict `{{variable}}` references, drop empty sections, and join
+ * the rest with blank lines. Malformed, unknown, or undefined references throw;
+ * a lone `{{` without any later `}}` is literal prose, and substituted values
+ * are not scanned again.
+ * @param assembly - the assembly whose sections and variables to render.
+ * @returns the rendered prompt, or `''` when all sections are empty.
  */
 export function renderPrompt(assembly: PromptAssembly): string {
   return assembly.sections
@@ -298,10 +181,7 @@ function interpolate(section: AssembledSection, variables: Record<string, string
   for (let open = text.indexOf('{{'); open >= 0; open = text.indexOf('{{', last)) {
     const group = GROUP_AT.exec(text.slice(open))
     if (group === null) {
-      // No complete simple group starts at this `{{`. A `}}` further on means
-      // a mangled reference (extra or nested braces) — fail loud. With no
-      // closing `}}` anywhere after, it is ordinary prose (shell, JSON) and
-      // passes through verbatim.
+      // A later closing brace makes this malformed; otherwise it is literal prose.
       if (text.indexOf('}}', open + 2) >= 0) {
         throw new Error(`malformed prompt variable reference at "${text.slice(open, open + 16)}…" in section "${section.name}" (references are complete simple {{name}} groups)`)
       }
@@ -309,15 +189,12 @@ function interpolate(section: AssembledSection, variables: Record<string, string
       last = open + 2
       continue
     }
-    // group[0] is the whole `{{...}}` match (a plain string, no optional
-    // index): the name is its interior. `{{}}` yields '' → the malformed path.
+    // `{{}}` yields an empty name and follows the malformed-reference path.
     const name = group[0].slice(2, -2)
     if (!VARIABLE_NAME.test(name)) {
       throw new Error(`malformed prompt variable reference "{{${name}}}" in section "${section.name}" (variable names match ${String(VARIABLE_NAME)})`)
     }
-    // Object.hasOwn, NOT `in`: `in` walks the prototype chain, so an
-    // unregistered `{{constructor}}` would resolve to Object.prototype's and
-    // splice a function's source text into the prompt instead of throwing.
+    // Do not resolve unregistered names through Object.prototype.
     if (!Object.hasOwn(variables, name)) {
       const known = Object.keys(variables)
       throw new Error(`unknown prompt variable "{{${name}}}" in section "${section.name}"; registered variables: ${known.length > 0 ? known.join(', ') : '(none)'}`)
@@ -332,22 +209,11 @@ function interpolate(section: AssembledSection, variables: Record<string, string
   return result + text.slice(last)
 }
 
-/**
- * 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. Registers the harness-owned
- * `harness:identity` and `deployment:persona` sections itself (see
- * {@link Config.persona}).
- */
+/** Registry service for the prompt inputs assembled before each model step. */
 export class SystemPrompt extends Service {
   static Config: z<Config> = z.object({
     persona: z.string().default(''),
-    // A schemastery array defaults to [] when omitted, but an omitted
-    // toolOrder must stay absent ("lexicographic order"), not become an
-    // explicitly-configured empty list (which is invalid — it lacks the
-    // rest entry). Forcing the default to undefined keeps the key out of the
-    // validated config; the cast is needed because .default() expects the
-    // array type.
+    // Preserve omission because an explicit empty order lacks the rest marker.
     toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
   })
 
@@ -363,12 +229,7 @@ export class SystemPrompt extends Service {
   constructor(ctx: Context, public config: Config) {
     super(ctx, 'systemPrompt')
     this.toolOrder = validateToolOrder(config.toolOrder)
-    // The harness-owned openers. They live HERE (not on the loop plugin) so a
-    // deployment that swaps in a different loop keeps them: the identity is a
-    // harness fact stated ahead of everything, and the persona is the
-    // deployment's config, one section of the full prompt, never the whole.
-    // An empty persona still RESERVES the section name (one owner — a plugin
-    // re-registering it throws); renderPrompt drops the empty text.
+    // Keep harness-owned openers independent of the selected loop plugin.
     this.section({
       name: 'harness:identity',
       order: -100,
@@ -377,30 +238,18 @@ export class SystemPrompt extends Service {
     this.section({
       name: 'deployment:persona',
       order: 0,
-      // The schema already defaulted an omitted persona to ''; the ?? only
-      // narrows the optional-input TYPE, it never supplies a different value.
+      // The fallback narrows the optional input type; the schema already defaults it.
       text: config.persona ?? '',
     })
   }
 
   /**
-   * Contribute a text section to the system prompt. Order is determined by
-   * `section.order` (ascending). The layer is decided by the CALLING context
-   * (`@deepseek-ai/dsh-scope`): a plain plugin context contributes globally; a
-   * scoped context (`agent.ctx`) contributes to that scope alone — and a
-   * scoped section SHADOWS a same-named global section for that scope's
-   * assemblies (most-specific-wins; this is how a per-agent persona overrides
-   * `deployment:persona`). The readonly typed contribution is borrowed until
-   * disposal; only the semantic
-   * finite-order rule is checked at runtime. Throws if the SAME layer already has the name (a
-   * duplicate would silently double prompt text — e.g. a double-loaded tool
-   * plugin; the global-duplicate message names `agent.ctx` as the per-agent
-   * alternative). Removed when the calling fiber is disposed. Emits
-   * `system-prompt/change` on register/unregister.
-   * @param section - the section to contribute (name, order, text or provider).
-   * @returns the disposer that removes the section. The exact
-   *   Cordis effect disposer (single-shot): composite (generator) effects may
-   *   yield it directly — exact identity nests the teardown in order.
+   * Register an ordered prompt section in the calling context's scope. A scoped
+   * section shadows a global section with the same name; duplicates within one
+   * layer and non-finite orders throw. Registration and disposal emit
+   * `system-prompt/change`.
+   * @param section - the section to register.
+   * @returns the exact Cordis effect disposer.
    */
   section(section: PromptSection): () => void {
     if (!Number.isFinite(section.order)) {
@@ -421,10 +270,7 @@ export class SystemPrompt extends Service {
           : `prompt section "${section.name}" is already registered in this scope`)
       }
       layer.push(section)
-      // Yield the rollback BEFORE emitting `system-prompt/change`: a generator
-      // effect collects each yielded disposer before the next step runs, so a
-      // throwing change listener removes the section instead of leaking it into
-      // every future assembly.
+      // Install rollback before notifying listeners that may throw.
       yield () => {
         const index = layer.indexOf(section)
         /* v8 ignore next 3 -- defensive: section was registered, so indexOf is guaranteed >= 0 */
@@ -434,31 +280,17 @@ export class SystemPrompt extends Service {
       }
       this.ctx.emit('system-prompt/change')
     }.bind(this), 'systemPrompt.section()')
-    // The EXACT cordis effect disposer, not a wrapper: a composite (generator)
-    // effect that owns a teardown ORDER must be able to yield THIS function —
-    // cordis nests a disposer out of the fiber's concurrent sibling list by
-    // exact function identity, so a wrapper would silently break the nesting
-    // (the agents.register() lesson). Cleanup is synchronous because this
-    // registration installs only synchronous state and notifications.
+    // 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
   }
 
   /**
-   * Contribute a tool-schema provider, evaluated at each assembly call with
-   * that assembly's {@link AssembleContext} (so it reflects the live registry
-   * state AND the assembly's scope — see {@link ToolProviderResult} for the
-   * `schemas`/`knownNames` split). The layer is decided by the calling
-   * context: a scoped provider (registered through `agent.ctx`) is consulted
-   * only for that scope's assemblies. Removed when the calling fiber is
-   * disposed. A provider must not return a schema named
-   * {@link TOOL_ORDER_REST}; that name is reserved for
-   * {@link Config.toolOrder}'s rest entry and rejects the assembly. Emits
-   * `system-prompt/change`.
-   * @param provider - evaluated at every {@link assemble} for fresh schemas.
-   * @returns the disposer that removes the provider. The exact
-   *   Cordis effect disposer (single-shot): composite (generator) effects may
-   *   yield it directly — exact identity nests the teardown in order.
+   * Register a tool-schema provider in the calling context's scope. Global and
+   * matching scoped providers both contribute; returning the reserved
+   * {@link TOOL_ORDER_REST} name makes assembly fail.
+   * @param provider - evaluated for each assembly with its context.
+   * @returns the exact Cordis effect disposer.
    */
   tools(provider: (context: AssembleContext) => ToolProviderResult): () => void {
     const scope = scopeOf(this.ctx)
@@ -471,7 +303,7 @@ export class SystemPrompt extends Service {
           return created
         })()
       layer.push(provider)
-      // Yield the rollback BEFORE emitting `system-prompt/change` (see section()).
+      // Install rollback before notifying listeners that may throw.
       yield () => {
         const index = layer.indexOf(provider)
         /* v8 ignore next 3 -- defensive: provider was registered, so indexOf is guaranteed >= 0 */
@@ -481,33 +313,18 @@ export class SystemPrompt extends Service {
       }
       this.ctx.emit('system-prompt/change')
     }.bind(this), 'systemPrompt.tools()')
-    // The EXACT cordis effect disposer, not a wrapper: a composite (generator)
-    // effect that owns a teardown ORDER must be able to yield THIS function —
-    // cordis nests a disposer out of the fiber's concurrent sibling list by
-    // exact function identity, so a wrapper would silently break the nesting
-    // (the agents.register() lesson). Cleanup is synchronous because this
-    // registration installs only synchronous state and notifications.
+    // 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
   }
 
   /**
-   * Contribute a named prompt variable, referenced from section text as
-   * `{{name}}`. The provider is evaluated at each assembly with that
-   * assembly's {@link AssembleContext}; returning `undefined` means "no value
-   * for this assembly" (a section referencing it then fails to render — a
-   * deployment must not claim facts it does not have). The layer is decided
-   * by the calling context: a scoped variable (registered through
-   * `agent.ctx`) resolves only for that scope's assemblies and SHADOWS a
-   * same-named global variable there. Throws on a name that does not match
-   * `[a-z][a-z0-9_]*` (it could never be referenced) or one already registered
-   * in the SAME layer. Removed when the calling fiber is disposed; emits
-   * `system-prompt/change` on register/unregister.
-   * @param name - the reference name (matches `[a-z][a-z0-9_]*`).
-   * @param provider - evaluated at every {@link assemble} for the value.
-   * @returns the disposer that removes the variable. The exact
-   *   Cordis effect disposer (single-shot): composite (generator) effects may
-   *   yield it directly — exact identity nests the teardown in order.
+   * Register a prompt variable in the calling context's scope. Scoped values
+   * shadow globals; invalid or duplicate names throw. A provider may return
+   * `undefined`, but rendering a section that references that value then fails.
+   * @param name - the `[a-z][a-z0-9_]*` reference name.
+   * @param provider - evaluated for each assembly.
+   * @returns the exact Cordis effect disposer.
    */
   variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void {
     if (!VARIABLE_NAME.test(name)) {
@@ -528,7 +345,7 @@ export class SystemPrompt extends Service {
           : `prompt variable "${name}" is already registered in this scope`)
       }
       layer.set(name, provider)
-      // Yield the rollback BEFORE emitting `system-prompt/change` (see section()).
+      // Install rollback before notifying listeners that may throw.
       yield () => {
         layer.delete(name)
         if (scope !== undefined && layer.size === 0) this.scopedVariableProviders.delete(scope)
@@ -536,47 +353,22 @@ export class SystemPrompt extends Service {
       }
       this.ctx.emit('system-prompt/change')
     }.bind(this), 'systemPrompt.variable()')
-    // The EXACT cordis effect disposer, not a wrapper: a composite (generator)
-    // effect that owns a teardown ORDER must be able to yield THIS function —
-    // cordis nests a disposer out of the fiber's concurrent sibling list by
-    // exact function identity, so a wrapper would silently break the nesting
-    // (the agents.register() lesson). Cleanup is synchronous because this
-    // registration installs only synchronous state and notifications.
+    // 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
   }
 
   /**
-   * Assemble the current prompt for one caller: the global layer merged with
-   * {@link AssembleContext.scope}'s layer (scoped sections/variables SHADOW
-   * same-named global ones — most-specific-wins) — section texts resolved
-   * against `context` and sorted by order across the union, tools collected
-   * from the global providers plus the scope's and put in the canonical
-   * model-facing order ({@link Config.toolOrder}, or lexicographic name order
-   * when unconfigured — provider registration order is a plugin-load artifact
-   * and never reaches the assembly; a configured order naming a tool outside
-   * the providers' `knownNames` universe rejects the assembly, while a known
-   * name restricted away for this scope is a normal absence), and every
-   * visible variable resolved against `context` into `assembly.variables`.
-   * Tool schemas are detached because assembly waterfalls may mutate them.
-   * Runs through the `system-prompt/assemble` waterfall, giving listeners the
-   * opportunity to mutate or replace the assembly; the returned value is the
-   * authoritative model-visible composition. Like the sections' `order`
-   * sort, tool canonicalization happens on the initial assembly; listener
-   * output owns its own determinism. Await the result before reading the
-   * assembly values — waterfall listeners may be async.
-   * Interpolation happens later, in {@link renderPrompt}.
-   * @param context - what this assembly is for (defaults to an empty context;
-   *   see {@link AssembleContext}).
-   * @returns the assembly after the waterfall has run.
+   * Assemble global and scoped providers, detach tool parameters, apply
+   * canonical ordering, then run the assembly waterfall. Scoped sections and
+   * variables shadow globals; the returned waterfall value is authoritative.
+   * @param context - the optional scope and plugin-defined assembly fields.
+   * @returns the authoritative post-waterfall assembly.
    */
-  // async so the misconfigured-toolOrder throw in orderTools surfaces as a
-  // rejection: a Promise-returning method must not throw synchronously
-  // (`assemble().catch(...)` would miss it).
+  // Keep configuration failures on the declared asynchronous error path.
   async assemble(context: AssembleContext = {}): Promise<PromptAssembly> {
     const scope = context.scope
-    // Variables: global layer first, then the scope's layer OVERWRITES
-    // same-named entries (shadowing — a per-agent value wins for that agent).
+    // Scoped variables shadow globals.
     const variables: Record<string, string | undefined> = {}
     for (const [name, provider] of this.variableProviders) {
       variables[name] = provider(context)
@@ -585,21 +377,13 @@ export class SystemPrompt extends Service {
     for (const [name, provider] of scopedVariables ?? []) {
       variables[name] = provider(context)
     }
-    // Sections: merge by name, scoped REPLACING same-named global entries
-    // (most-specific-wins — the per-agent persona mechanism), then sort by
-    // order across the union. Registration order within a layer is preserved
-    // for equal orders (stable sort).
+    // Scoped sections shadow globals before the stable order sort.
     const sectionByName = new Map<string, PromptSection>()
     for (const section of this.sections) sectionByName.set(section.name, section)
     for (const section of (scope === undefined ? [] : this.scopedSections.get(scope)) ?? []) {
       sectionByName.set(section.name, section)
     }
-    // Tools: consult the global providers plus the scope's, each with this
-    // assembly's context. `schemas` are what the model may see (already
-    // post-restriction, per provider); `knownNames` (defaulting to the
-    // schemas' names) form the pre-restriction universe `toolOrder` is
-    // validated against, so a restricted-away tool is a normal absence while
-    // a config typo still fails every assembly loudly.
+    // Validate order against pre-restriction names while collecting visible schemas.
     const providers = [
       ...this.toolProviders,
       ...(scope === undefined ? [] : this.scopedToolProviders.get(scope)) ?? [],

packages/core/tools/README.md

@@ -11,16 +11,16 @@ tools:
   mode: native   # native (default) | code | both
 ```
 
-`native` contributes the calling agent's visible end capabilities as wire function definitions. Under `code`, this registry contributes the reserved `run_code` transport plus the generated `tools:sdk` prompt section (see [Code Mode](#code-mode)); `both` contributes the visible native definitions and both infrastructure pieces. Restrictions cannot remove `run_code`, and registering, shadowing, or explicitly filtering that reserved name fails loudly. An expert `system-prompt/assemble` listener may replace any prompt or schema contribution; its returned assembly is authoritative, so the listener owns preserving Code Mode when the protocol should remain active. Non-native modes require a loaded `ctx.codeRuntime` with `language: 'typescript'`; a missing or mismatched runtime rejects every prompt assembly with an actionable error, and a `systemPrompt.toolOrder` naming tools the mode no longer contributes rejects the assembly the same way.
+`native` contributes visible tools as function definitions. `code` contributes the reserved `run_code` transport and generated `tools:sdk` section; `both` contributes both forms. The reserved transport cannot be registered, shadowed, restricted, or removed. Non-native modes require a TypeScript `ctx.codeRuntime`, and a `systemPrompt.toolOrder` entry for a tool the mode does not contribute rejects prompt assembly. A `system-prompt/assemble` listener may replace the registry's contributions; its returned assembly is authoritative, so that listener owns preserving a usable Code Mode protocol.
 
 ### Public API
 
 - `ctx.tools.register(definition: ToolDefinition): () => void` Register a trusted typed same-process definition. The layer is the calling context's scope: a plain plugin context registers globally; an agent's `agent.ctx` registers for that agent alone, shadowing a same-named global tool there. Duplicate names within one layer throw; non-native modes also reject the reserved `run_code` transport name. `timeoutMs`, when present, must be positive and finite. Disposed with the calling fiber.
-- `ctx.tools.restrict(filter: ToolRestriction): () => void` Scoped-only (throws on a plain context): mask the global end-capability surface for the calling agent — `allow` keeps only the listed global tools, `deny` removes them; multiple restrictions intersect; scope-local registrations are merged afterward. The readonly arrays compile once into private sets. Every listed name must exist in the current pre-restriction global registry; scope-local, unknown, and reserved `run_code` names fail loudly. A deny-list admits a later global tool unless it names that tool; an allow-list excludes later names; neither filters a later scope-local registration. `restrict({})` rejects. This is live registration composition, not a parent-derived authority ceiling; see the [agent-scope security non-goal](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals).
+- `ctx.tools.restrict(filter)` applies an agent-scoped allow/deny mask to global tools and throws from a plain context. The filter is snapshotted at registration; multiple masks intersect and scope-local tools merge afterwards. Deny masks admit later unnamed globals, while allow masks exclude later names. Unknown, local, or reserved names and empty filters reject. This is live visibility composition, not an authority boundary; see the [scope security non-goal](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals).
 - `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined` Resolution as one scope sees it (shadowing applied; a restricted-away global reads as absent) — presenters pass the calling agent so the card matches what executed.
 - `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]` Schemas of everything the scope can see (without the `execute` functions). The shipped tools' schemas are catalogued in [docs/tool-catalog.md](../../../docs/tool-catalog.md), generated by booting each tool plugin and harvesting this method (see [the tool-schema-catalog RFC](../../../docs/rfc/implemented/process/2026-07-02-tool-schema-catalog.md)).
 - `ctx.tools.guard(guard: ToolGuard): () => void` Register a monotonic synchronous execution guard after `tools/pre-execute`: returning a reason denies the call, while `undefined` leaves it unchanged. A plain-context guard applies globally; an `agent.ctx` guard applies only to that agent. Later waterfall listeners cannot turn a guard denial back into permission. Disposed with the calling fiber.
-- `ctx.tools.execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>` Assign a fresh opaque correlation token, losslessly materialize and deep-freeze arguments once at the model/tool boundary, then run the call through `tools/pre-execute` → guards → `tools/execute` → `tools/post-execute`. Invalid arguments normalize through the same authoritative result path without reaching policy or the body. The final outcome is independently materialized and deep-frozen once before `tools/result`. Optional `signal` remains the operational field an around-dispatch wrapper may replace.
+- `ctx.tools.execute(exec)` losslessly snapshots and freezes arguments, assigns an opaque token, runs the complete policy/dispatch/result pipeline, then independently snapshots the authoritative outcome before final observation. Invalid arguments use the same result path without reaching policy or the body; around wrappers may replace only `signal`.
 
 ### Injected services
 
@@ -45,7 +45,10 @@ The live registry pipeline has three transformable waterfalls followed by the ob
 ### Extension points
 
 - Tool plugins call `ctx.tools.register()` — schemas flow into the assembly automatically.
-- `tools/pre-execute` is the reorderable allow/deny/ask gate (sandbox, permission, hooks): listeners receive `(exec, next)` and call `next()` to delegate to the default (allow) or return a `PreToolDecision` to short-circuit; a `deny` skips dispatch, while an `ask` resolves through the approval seam and dispatches only after a grant. Either non-grant path yields an `isError` result. `ctx.tools.guard()` installs scope-aware monotonic policy after that waterfall when a denial must not be overridable by listener ordering. `tools/execute` is the around-dispatch seam (timeout, retry, metrics): listeners receive `(exec, next)` and call `next()` to delegate to core dispatch (returning its `ToolExecutionResult`, optionally wrapped), or return a replacement result to short-circuit dispatch; the base `next()` is dispatch-with-normalization, so `await next()` already yields an `isError` result for a thrown or unknown tool. A wrapper may change only `exec.signal` before `next()`—adding a per-call deadline, replacing a caller signal, or restoring absence afterwards—because call identity is protected before policy begins. `tools/post-execute` is the inspect/transform seam: `(exec, result, next)` → a `PostToolDecision` that can replace content, block with feedback, or attach `additionalContext`. Core dispatch is the base of the `tools/execute` waterfall; the tool body keeps its own error boundary so a thrown tool still reaches `post-execute` as an `isError`. Finally, `tools/result` observes the immutable authoritative result after every transform and error boundary. All follow the typed-decision idiom shared with the `agent/*` seams (see [`dsh-agent`](../agent/README.md)); `@deepseek-ai/dsh-timeout-policy` is the reference `tools/execute` wrapper.
+- `tools/pre-execute` is the reorderable allow/deny/ask gate; `ctx.tools.guard()` adds monotonic owner policy after it.
+- `tools/execute` wraps normalized core dispatch for timeout, retry, or metrics. Wrappers may replace only the operational signal.
+- `tools/post-execute` may replace content, block with feedback, or attach context; `tools/result` observes the immutable final outcome.
+- Exact signatures and ordering live in the generated [event catalog](../../../docs/cordis-catalog/events.md) and [pipeline](../../../docs/tool-execution-pipeline.md).
 - MCP servers: one plugin per server, discover tools, call `ctx.tools.register()` with the server's schemas.
 
 ### Typed tool parameter schemas
@@ -77,66 +80,28 @@ ctx.tools.register(defineTool({
 
 The helper converts the author-facing `SchemaSpec` (with `required: true` as a per-property boolean) to standard JSON Schema for the wire format and uses the same typed spec for execute/presentation validation. Raw JSON-Schema tool definitions (from MCP servers) are still accepted by the registry directly.
 
-A `defineTool` tool also **validates the model-generated arguments against its `SchemaSpec` before `execute` runs** (`validateArgs`). The model's JSON is untrusted — `InferArgs<S>` is a compile-time claim, not a runtime guarantee — so on a mismatch (missing required key, wrong primitive, bad enum member, nested violation) the tool throws a `ToolArgsError` (`code: 'INVALID_ARGS'`); the registry turns it into an `isError` result whose text lists the violations, which the model sees and self-corrects from. Validation mirrors the JSON Schema conversion exactly: extra keys are allowed, `default` is not applied, and an `object`/`array` prop without `properties`/`items` only type-checks. Raw-registered tools (MCP) are **not** validated by the harness — they validate their own input.
+A `defineTool` definition validates model arguments before execution and turns missing required values, wrong primitives, invalid enum members, and nested violations into `ToolArgsError` (`INVALID_ARGS`) for the normal error-result path. Extra keys are allowed, defaults are not applied, and object or array fields without `properties` or `items` receive only a type check. Raw-registered tools own their validation.
 
 See `defineTool`, `validateArgs`, `ToolArgsError`, `SchemaSpec`, `InferArgs`, and `schemaSpecToJsonSchema` in the public API for details.
 
-`defineTool` also validates an optional `timeoutMs` at definition time when present: it must be a positive finite number, or the helper throws — the budget is attached to the produced `ToolDefinition` (for `@deepseek-ai/dsh-timeout-policy`) and never reaches the model.
+Optional `timeoutMs` must be positive and finite; it is policy metadata, not model-visible schema.
 
 ### Structured-output schema subset
 
-A separate vocabulary for callers that DEMAND a machine-readable value from an agent — the subagent seam's `SubagentStartRequest.outputSchema` (and, by extension, a workflow's `agent({ schema })`). Unlike `SchemaSpec` (the author-facing DSL for tool parameters), a `StructuredOutputSchema` is an object-rooted **raw JSON Schema subset** as data: it travels verbatim to the model as a forced tool's `parameters`, and the produced value is validated against it.
-
-The subset is deliberately narrow and REJECTS LOUD outside it — accepting a keyword the validator doesn't enforce would validate less than the schema promises (accepted-then-ignored). Supported: single-string `type` (`object`/`array`/`string`/`number`/`integer`/`boolean`/`null`; type arrays rejected), `properties`/`required`/`additionalProperties` (boolean; every `required` key must be declared), `items`, scalar-only `enum`/`const`; annotations (`description`/`title`/`default`/`examples`) are ignored but must still be JSON data. `assertSupportedOutputSchema(schema)` throws `OutputSchemaError` (`code: 'UNSUPPORTED_SCHEMA'`, listing every violation) for anything else; `validateStructuredValue(schema, value)` returns path-qualified violations (empty = valid, total — never throws).
+`StructuredOutputSchema` is the object-rooted raw JSON Schema subset used by subagents and workflows for machine-readable results. It accepts one scalar `type`, object `properties`/`required`/boolean `additionalProperties`, array `items`, and scalar `enum`/`const`. The annotations `description`, `title`, `default`, and `examples` are ignored but must remain JSON data. Type arrays, undeclared required keys, and unsupported keywords fail through `OutputSchemaError` rather than being ignored; `validateStructuredValue()` returns path-qualified violations without throwing.
 
 ### Tool-owned UI presentation
 
-A tool owns how ITS calls render in a UI (an editor's tool-call card, a CLI log line) — a UI plugin must NOT special-case tool names. A `ToolDefinition` may declare two optional, pure, display-only methods that return a **`card`-tagged render intent** (a discriminated union — a tool declares its card kind once and a UI bridge switches on `card`):
+Tools optionally own pure `presentCall()` and `presentResult()` render intents, so UIs do not special-case tool names:
 
-- `presentCall(args): ToolCallView | undefined` — the PENDING state, one of:
-  - `{ card: 'generic', title, kind?, rawInput?, content?, locations? }` — the default card: a human-readable `title`, an optional `kind` (`read`/`edit`/`execute`/… for icon/treatment, default `other`), an optional `rawInput` (the salient input to show in a detail view — e.g. a background task id, NOT the whole args object), optional `content` (extra UI content blocks), and optional `locations` (`{ path, line? }[]` — files this call reads/modifies, so a capable UI can follow along; the ACP bridge forwards them as `tool_call.locations`).
-  - `{ card: 'terminal', title, description?, cwd? }` — a shell command: a capable UI renders a terminal card (the `title` is the command, `description` renders above it, `cwd` heads it); an incapable UI falls back to a generic execute card.
-  - `{ card: 'diff', title, diffs, locations? }` — a file create/modify: a capable UI renders an inline diff card from `diffs` (`{ path, oldText, newText }[]`; `oldText: null` for a new file). Used by `write`/`edit`.
-- `presentResult(args, result): ToolResultView | undefined` — the COMPLETED state, given the same `args` and the `{ content, isError, meta? }` result, one of:
-  - `{ card: 'generic', title?, content? }` — an optional replacement `title` and reformatted `content`.
-  - `{ card: 'terminal', title?, output?, exitCode?, signal? }` — a terminal run's captured `output` and exit status. A capable UI shows an exit-status pill; an incapable UI gets a fenced ` ```console ` fallback the BRIDGE derives from `output` (the tool does not encode the fences).
-  - `{ card: 'diff', title?, diffs }` — a completed file mutation as an inline diff. `diffs` is `FileDiff[]` — typically the applied hunks with surrounding context computed from the before/after content, or a whole-file diff (`oldText: null`) when there is no before-image (a file create). Used by `write`/`edit`; a `tool_call_update.content` replaces the call's content, so a mutation tool returns this even when it duplicates the call-time snippet (else the result text would clobber the pending diff).
+- Call views are `{ card: 'generic', title, kind?, rawInput?, content?, locations? }`, `{ card: 'terminal', title, description?, cwd? }`, or `{ card: 'diff', title, diffs, locations? }`.
+- Result views are `{ card: 'generic', title?, content? }`, `{ card: 'terminal', title?, output?, exitCode?, signal? }`, or `{ card: 'diff', title?, diffs }`.
 
-Returning `undefined` (or omitting a method) tells a UI to fall back to a generic presentation (title = tool name, raw args as input, raw result content). Both methods must be **pure and side-effect-free**: a UI may call them during live streaming AND during a session-log replay, so they depend only on their arguments. `result.meta` is the tool's own optional presentation payload (opaque `unknown`, JSON-serializable), attached by `execute` (see below) and persisted on the `tool/result` event, so a `presentResult` reading it stays replay-deterministic (the same `meta` is read back from the log). With `defineTool`, `args` is the typed `InferArgs<S>` shape; the helper soft-validates before calling (a malformed/older logged arg shape yields `undefined` rather than throwing, since display must never crash a replay). The views are provider-neutral — the ACP bridge (`dsh-acp`) maps each `card` to ACP `tool_call`/`tool_call_update` wire fields (a `diff` card to a `{ type: 'diff' }` content block, a `terminal` card to the `_meta` terminal convention), and relativizes a file card's title against the session cwd. See the render-intent-union RFC (`docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md`) and the applied-hunk-diffs RFC (`docs/rfc/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.md`); `dsh-tool-bash` (terminal) and `dsh-tool-fs` (diff/generic) are the reference implementations.
-
-```ts
-import { defineTool } from '@deepseek-ai/dsh-tools'
-
-const bash = defineTool({
-  name: 'bash',
-  description: 'Run a shell command.',
-  parameters: {
-    command: { type: 'string', required: true, description: 'The command to run.' },
-    description: { type: 'string', required: true, description: 'One-line summary shown in the UI.' },
-  },
-  async execute(args) {
-    return [{ type: 'text', text: `ran: ${args.command}` }]
-  },
-  // A terminal card: the command is the title, the description renders above it.
-  presentCall: args => ({ card: 'terminal', title: args.command, description: args.description }),
-  // A terminal result: the raw output + exit; the bridge derives the fenced fallback.
-  presentResult: (_args, result) => {
-    const block = result.content.length === 1 ? result.content[0] : undefined
-    if (block === undefined || block.type !== 'text') return undefined
-    return { card: 'terminal', output: block.text }
-  },
-})
-```
+Returning `undefined` selects generic fallback. Presenters depend only on their arguments because UIs call them during live streaming and log replay. Result presentation may read JSON-serializable `result.meta`, which persists with the result; `defineTool` soft-validates older logged arguments and falls back instead of crashing replay. `dsh-tool-bash` and `dsh-tool-fs` are the reference implementations; the [render-intent RFC](../../../docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md) owns the rationale.
 
 ### Code Mode
 
-Under `mode: code` (or `both`) the registry turns the tool surface into a programming API, per the [Code Mode RFC](../../../docs/rfc/implemented/feature/2026-06-15-code-mode.md): the model writes a TypeScript program (the body of an async function) and passes it to the reserved wire transport `run_code`; the program runs in `ctx.codeRuntime` (the [code-execution seam](../../code-runtime/README.md) — the shipped backend is a worker thread) with one async binding per visible end-capability tool (`await tools.bash({...})`), and ONLY what it prints or returns re-enters the model's context. Scope restrictions change those SDK bindings but cannot remove or replace the transport itself.
-
-- **The SDK section** (`tools:sdk`, order 150): a lazy prompt section regenerating, at each assembly, a `declare const tools: {...}` TypeScript declaration of the calling scope's visible end capabilities (exotic names via quoted keys), plus fixed usage instructions. Deterministic — lexicographic tool order, byte-identical text for an unchanged tool set (prefix-cache-friendly). The codegen (`jsonSchemaToTs`, exported) is total: constructs outside the `defineTool` subset degrade to `unknown`, never throw.
-- **The dispatch bridge** (`run_code`'s execute): every binding call is JSON-normalized before dispatch (a value that does not survive — `BigInt`, circulars — rejects that one call, so the dispatched form and logged form are the same JSON value by construction), serialized through a per-run queue (even `Promise.all` executes underlying calls one at a time in submission order), given the outer execution's opaque token as `parent`, and run through the complete pre-execute → guards → execute → post-execute → result pipeline. A denial reaches the program as a binding rejection, and each sub-call is logged as a `tool/code-dispatch` session event with deterministic id `<parent>:code:<n>`; `deriveMessages()` does not surface that event. Token correlation lets commit-style observers defer an inner success until the final `run_code` result without exposing the live outer execution; ordinary tool side effects are not rolled back. A sub-call's `additionalContext` is deliberately dropped because inserting it inside a running parent call would break tool-call/result adjacency.
-- **Settlement discipline**: the bridge owns a run-scoped abort that follows the outer signal in and fires when the run settles for any reason, so a budget expiry aborts an in-flight sub-tool instead of orphaning it; the bridge then drains its queue BEFORE returning, so every `tool/code-dispatch` lands inside the open turn. A failed run throws `CodeRunFailedError` (`code: 'CODE_RUN_FAILED'`, message = the failure kind + captured logs), which the pipeline converts to a structured `isError` the model self-corrects from.
-
-The wire collapse is the registry's own contribution (`systemPrompt.tools()` is mode-aware), so the logged `request/header` records it for free. When no assembly listener changes the registry's prompt or schema contributions, `code` assembles exactly `[run_code]`, pinned by tests and the snapshot goldens. Try it: `pnpm run demo:code-mode` ([the coding-agent example's Code Mode overlay](../../../examples/coding-agent/README.md#code-mode)); `pnpm run demo:code-mode acp` serves the same mode over ACP instead of the REPL.
+Under `code` or `both`, the registry exposes the reserved `run_code` transport and a deterministic TypeScript SDK for the current scope; only program output re-enters model context. Each JSON-normalized binding re-enters the complete tool pipeline sequentially with logged correlation to the outer call. Denials reject that binding, ordinary side effects are not rolled back, and mid-run `additionalContext` is omitted to preserve call/result adjacency. Run settlement aborts and drains outstanding bindings; failures surface as `CodeRunFailedError`. See the [Code Mode RFC](../../../docs/rfc/implemented/feature/2026-06-15-code-mode.md) and [code-runtime seam](../../code-runtime/README.md). Try `pnpm run demo:code-mode`.
 
 ## Model Experience
 

packages/core/tools/src/code-mode.ts

@@ -1,15 +1,7 @@
 /**
- * Code Mode: the `run_code` tool and its dispatch bridge. The model writes a
- * TypeScript program; the bridge hands it to `ctx.codeRuntime` with one async
- * binding per end capability visible to the calling agent, then serializes
- * every binding call through a per-run queue onto `ToolRegistry.execute()`.
- * Sub-calls therefore traverse the complete pre/guard/around/post/final-result
- * pipeline exactly like native calls and carry the outer execution's opaque
- * token for correlation. The bridge logs each sub-dispatch as a
- * `tool/code-dispatch` session event and returns only the program's curated
- * output. The registry itself decides WHEN this tool exists (its `mode`
- * config); this module owns only the tool and the bridge.
- *
+ * Code Mode `run_code` transport. Programs call the registry's agent-visible
+ * tools through nested, sequential executions; each sub-dispatch is logged for
+ * reconstruction, while only the outer curated result enters model history.
  * @module @deepseek-ai/dsh-tools/src/code-mode
  */
 
@@ -24,16 +16,11 @@ import type { ToolDefinition, ToolRegistry } from './index.ts'
 declare module '@deepseek-ai/dsh-session' {
   interface SessionEventMap {
     /**
-     * One bridged sub-dispatch from a `run_code` program: the parent
-     * `run_code` call id, the deterministic sub-call id
-     * (`<parent>:code:<n>`), the tool `name` with its JSON-normalized
-     * `arguments` — the exact value dispatched, normalized BEFORE dispatch,
-     * so this append can never fail on payload shape — whether the sub-call
-     * errored, and a bounded `resultSummary` of its model-facing text.
-     * Log-only: `deriveMessages()` ignores it, so sub-calls never re-enter
-     * model context; persistence and UIs get every call. Appended inside the
-     * parent `run_code`'s execution (the bridge drains its queue before
-     * returning), so the turn-enclosure invariant holds by construction.
+     * One bridged sub-dispatch from a `run_code` program: the parent `run_code` call id, the
+     * deterministic sub-call id (`<parent>:code:<n>`), the tool `name` with its
+     * JSON-normalized `arguments` — the exact value dispatched, normalized before dispatch, so
+     * this append can never fail on payload shape — whether the sub-call errored, and a
+     * bounded `resultSummary` of its model-facing text.
      */
     'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; resultSummary: string }
   }
@@ -89,16 +76,11 @@ function summarize(text: string): string {
 }
 
 /**
- * JSON-normalize one binding call's argument into TWO independent parses of
- * the same canonical text: `dispatched` goes to the tool, `logged` to the
- * `tool/code-dispatch` event — identical by construction (the runtime's
- * structured-clone boundary is wider than JSON; the session log accepts only
- * JSON), and separate objects, so a tool mutating its args can neither
- * desync the log from what was dispatched nor re-poison the append. A value
- * that does not survive the round-trip (`undefined` — the log rejects it as
- * event data — `BigInt`, a circular structure, a bare function) rejects that
- * one call BEFORE dispatch with a model-correctable error: nothing ever
- * executes unlogged.
+ * JSON-normalize one binding call's argument into TWO independent parses of the same canonical
+ * text: `dispatched` goes to the tool, `logged` to the `tool/code-dispatch` event — identical
+ * by construction (the runtime's structured-clone boundary is wider than JSON; the session log
+ * accepts only JSON), and separate objects, so a tool mutating its args can neither desync the
+ * log from what was dispatched nor re-poison the append.
  */
 function jsonNormalizeArgs(value: unknown): { dispatched: unknown; logged: unknown } {
   if (value === undefined) {
@@ -139,7 +121,7 @@ function asRunCodeMeta(meta: unknown): RunCodeMeta | undefined {
 
 /**
  * Build the `run_code` {@link ToolDefinition}: one required `code` parameter,
- * executed through the dispatch bridge described in the module doc. The
+ * executed through the dispatch bridge described above. The
  * registry reserves it as presentation infrastructure under non-native modes,
  * outside the filterable global/scoped capability layers.
  * @param registry - the owning registry (sub-calls go through its `execute`,
@@ -172,11 +154,9 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
       exec.signal?.addEventListener('abort', onOuterAbort, { once: true })
 
       let dispatches = 0
-      // The per-run serialization queue: every binding call chains onto the
-      // tail, so even `Promise.all` executes the underlying tool calls one at
-      // a time in submission order (the tool contract carries no
-      // concurrency-safety metadata yet). The fold keeps the tail non-rejecting
-      // so one failed dispatch never poisons the chain.
+      // The per-run serialization queue: every binding call chains onto the tail, so even
+      // `Promise.all` executes the underlying tool calls one at a time in submission order (the
+      // tool contract carries no concurrency-safety metadata yet).
       let queue: Promise<void> = Promise.resolve()
       const enqueue = <T>(task: () => Promise<T>): Promise<T> => {
         const turn = queue.then(() => {
@@ -211,11 +191,9 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
             signal: runController.signal,
           })
           const text = textOf(result.content)
-          // Sub-call `additionalContext` is deliberately DROPPED here: the
-          // loop's buffering (append after the step's tool/results) has no
-          // safe analogue from inside a running run_code — injecting now
-          // would break tool-call/result adjacency. Deferred until a real
-          // hook needs it through Code Mode.
+          // Sub-call `additionalContext` is deliberately DROPPED here: the loop's buffering
+          // (append after the step's tool/results) has no safe analogue from inside a running
+          // run_code — injecting now would break tool-call/result adjacency.
           exec.agent?.session.append('tool/code-dispatch', {
             parentCallId: exec.callId,
             subCallId,
@@ -266,18 +244,8 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
             signal: runController.signal,
           })
         } finally {
-          // Quiescence before returning, whether the runtime fulfilled or
-          // REJECTED (a backend that starts a binding call and then throws
-          // must not leak a live sub-dispatch past this settlement): fire
-          // the run-scoped abort (cancelling an in-flight sub-dispatch,
-          // abandoning queued ones), then await the queue's drain — an
-          // aborted sub-call still settles and logs its event INSIDE the
-          // open turn; nothing can append after we return. `queue` is the
-          // FOLDED tail (every link swallows its rejection into undefined),
-          // so this await cannot itself reject — an abandoned queued call
-          // can never mask the runtime's own failure, returned or thrown;
-          // rejections surface only on the per-call promises the program
-          // holds.
+          // Abort sub-dispatches and drain the folded queue before closing the turn.
+          // Binding failures remain observable through their individual promises.
           runController.abort('run_code settled')
           await queue
         }
@@ -297,13 +265,7 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
         exec.signal?.removeEventListener('abort', onOuterAbort)
       }
     },
-    // The program IS the title, the way command tools title their cards with
-    // the command: an execute-card's title is the one slot an ACP client
-    // always shows (Zed's execute cards render no body content and no raw
-    // input without a real terminal attached), so anywhere else the code
-    // would be invisible. Multi-line titles are the execute-card idiom —
-    // capable clients render them whole; others truncate to the first line
-    // and still hold the full program in rawInput.
+    // ACP execute cards use the program as their visible title.
     presentCall: args => ({
       card: 'generic',
       title: args.code,

packages/core/tools/src/index.ts

@@ -1,18 +1,6 @@
 /**
- * Tool registry and execution pipeline. Plugins register tools; the registry
- * feeds schemas into the system prompt, and `execute()` dispatches each call
- * through `tools/pre-execute` (the extensible allow/deny gate) → monotonic
- * registered guards → `tools/execute` (an around-dispatch wrapper for
- * timeout/retry/metrics plugins) → `tools/post-execute` (inspect/replace the
- * result, attach context) → the observe-only `tools/result` notification.
- *
- * The registry also owns HOW its tools are presented to the model — its
- * `mode` config: `'native'` (every tool as a wire function definition,
- * today's behavior and the default), `'code'` (the registry's canonical wire
- * contribution is one tool, `run_code`, plus a generated TypeScript SDK prompt section), or
- * `'both'`. See `code-mode.ts` (the tool + dispatch bridge) and
- * `ts-types.ts` (the SDK codegen); design in the Code Mode RFC.
- *
+ * Tool registry, model presentation modes, and pre/guard/around/post/result
+ * execution pipeline.
  * @module @deepseek-ai/dsh-tools
  */
 
@@ -83,79 +71,34 @@ declare module 'cordis' {
 
   interface Events {
     /**
-     * Waterfall BEFORE a tool runs — the gate where sandbox, permission, and
-     * hook plugins allow or deny a call (Claude Code's `PreToolUse`). Listeners
-     * receive `(exec, next)`: call `next()` to delegate to the default (allow),
-     * or return a {@link PreToolDecision} without calling `next()` to
-     * short-circuit. A `deny` skips dispatch and yields an `isError` result; the
-     * tool body never runs. Input rewrite is deliberately NOT offered here (see
-     * {@link PreToolDecision}); `ask` is serviced by the `ctx.approval` seam
-     * when one is mounted, and degrades to deny otherwise.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) keys the carrier by `exec.agent`: a
-     * listener registered through `agent.ctx` fires only for that agent's
-     * calls, while a plain plugin listener fires for every call (including
-     * agent-less ones, which dispatch subject-less).
+     * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing
+     * approval support turns `ask` into denial.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
      * @param exec - the pending call (name, parsed arguments, caller agent).
      * @mode waterfall
      */
     'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>
     /**
-     * Around-dispatch waterfall wrapping the registry's core tool dispatch,
-     * between the `tools/pre-execute` gate and the `tools/post-execute` seam. A
-     * listener receives `(exec, next)`: call `next()` to delegate to dispatch
-     * (returning its {@link ToolExecutionResult}, optionally wrapped), or return a
-     * replacement result without calling `next()` to short-circuit dispatch. The
-     * base `next()` IS the dispatch-with-normalization thunk — a thrown tool (or
-     * unknown tool) is already normalized to an `isError` result by the time a
-     * listener's `await next()` returns, so a wrapper never sees a raw throw from
-     * the tool body. This is the seam a timeout/retry/metrics plugin wraps: it can
-     * set or replace the one mutable field, `exec.signal` (e.g. with a per-call
-     * deadline), BEFORE `next()`, restore/delete it afterward, and inspect the result AFTER. Call identity
-     * (`token`, `callId`, `name`, `arguments`, `agent`, and `parent`) is immutable throughout the
-     * pipeline so a wrapper cannot change which tool and scope the pipeline
-     * accepted. (Cordis `next()` ignores passed arguments and re-invokes
-     * downstream with the shared payload, so a wrapper changes `exec.signal` in
-     * place rather than passing a new object to `next()`.)
-     * Multiple listeners compose by registration order — an outer one wraps the
-     * inner ones plus dispatch.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): the carrier is keyed by
-     * `exec.agent` — a listener registered through `agent.ctx` wraps only that
-     * agent's calls; a plain plugin listener wraps every call (including
-     * agent-less ones, which dispatch subject-less).
+     * Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns
+     * a normalized result; wrappers may change only `exec.signal`, while call
+     * identity remains immutable.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
      * @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).
      * @mode waterfall
      */
     'tools/execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
     /**
-     * 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`). Listeners receive
-     * `(exec, result, next)`: call `next()` to delegate to the default (accept
-     * unchanged), or return a {@link PostToolDecision} to override. Core tool
-     * dispatch runs earlier as the base `next()` of the `tools/execute`
-     * waterfall, all inside `execute`'s outer try/catch (and the tool body keeps
-     * its own inner try/catch, so a thrown tool still reaches `post-execute` as an
-     * `isError` result).
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): the carrier is keyed by
-     * `exec.agent` — a listener registered through `agent.ctx` fires only for
-     * that agent's calls; a plain plugin listener fires for every call
-     * (including agent-less ones, which dispatch subject-less).
+     * Accept, replace, enrich, or block a normalized dispatch result. `next()`
+     * accepts it unchanged; thrown tools still reach this seam as errors.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
      * @param exec - the call that just ran (name, parsed arguments, caller agent).
      * @param result - the dispatch outcome a listener may accept, replace, or block.
      * @mode waterfall
      */
     'tools/post-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
     /**
-     * Synchronous notification of the authoritative FINAL tool outcome, after the
-     * complete pre/execute/post pipeline, final lossless-JSON validation, and
-     * outer error normalization.
-     * Unlike the three waterfalls, this seam cannot transform the result: each
-     * listener receives the now-frozen execution object and a deep-frozen result
-     * snapshot; listener failures are contained and logged, and
-     * {@link ToolRegistry.execute} still returns the outcome.
-     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by
-     * `exec.agent`, using the same carrier as the pipeline.
+     * Observe the frozen, lossless-JSON final outcome. Listener failures are contained.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
      * @param exec - the execution object that traversed the pipeline.
      * @param result - a deep-frozen snapshot of the final returned result.
      * @mode emit
@@ -174,18 +117,10 @@ declare module 'cordis' {
   }
 }
 
-// TODO(review): revisit these shapes when concurrency metadata becomes useful
+// TODO(concurrency): revisit these shapes when concurrency metadata becomes useful
 // (for example, a read-only hint that would permit safe parallel execution).
 
-/**
- * What a tool's `execute` returns. The bare {@link ContentBlock}`[]` form is the
- * common case (model-facing content only); the object form additionally attaches
- * a tool-private `meta` presentation payload that the registry threads onto the
- * `tool/result` session event and hands back to the tool's `presentResult`.
- * `meta` is opaque to the core (`unknown` — the tool owns and narrows its shape),
- * and MUST be JSON-serializable: it persists on the durable log (the session
- * enforces this at `append`), so replay reproduces the card.
- */
+/** Tool output, optionally with lossless-JSON presentation metadata persisted for replay. */
 export type ToolExecuteReturn = ContentBlock[] | { content: ContentBlock[]; meta?: unknown }
 
 /** A registered tool: its schema plus the execution function. */
@@ -236,12 +171,7 @@ export interface ToolResult {
 
 declare const toolExecutionTokenBrand: unique symbol
 
-/**
- * Opaque identity for one trip through the tool pipeline. Nested
- * transports carry the enclosing execution's token instead of its live object,
- * so observe-only result listeners can correlate calls without gaining a
- * mutation path into an outer around-dispatch wrapper.
- */
+/** Opaque call identity that permits correlation without exposing mutable execution state. */
 export type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]: true }
 
 /**
@@ -308,14 +238,8 @@ export interface ToolExecutionResult {
    */
   error?: ToolErrorInfo
   /**
-   * Extra model-facing context a `tools/post-execute` listener attached for the
-   * NEXT request (Claude Code's PostToolUse `additionalContext`). It is NOT part
-   * of this call's `content` — `content`/`feedback` shape the tool RESULT, but
-   * `additionalContext` is a SEPARATE `context/message`. A step can carry
-   * multiple tool calls, so the loop BUFFERS every call's `additionalContext`
-   * and appends them only AFTER all `tool/result`s for the step, keeping
-   * tool-call/result adjacency intact. Carried on the result purely to ferry it
-   * from `execute()` up to the loop's per-step buffer.
+   * Model-facing context for the next request, separate from this tool result.
+   * The loop buffers it until all step results are logged, preserving pairing.
    */
   additionalContext?: HookContext
   /**
@@ -328,19 +252,10 @@ export interface ToolExecutionResult {
 }
 
 /**
- * The decision a `tools/pre-execute` listener returns for one pending call.
- * Maps onto Claude Code's `PreToolUse` `permissionDecision`.
- *
- * - `allow` proceeds to dispatch. (Input rewrite — changing `exec.arguments` —
- *   is deliberately NOT offered: `tool/call` and `assistant/message` are logged
- *   BEFORE execution and live consumers, e.g. the ACP bridge and `dsh-tool-bash`
- *   presentation, read the pre-execution arguments, so an execution-only rewrite
- *   would desync the UI from what RAN. That consistency redesign is its own
- *   `proposed` RFC; `TODO(pre-tool-input-rewrite)` anchors it at the call site.)
- * - `deny` skips dispatch; the loop records an `isError` result carrying `reason`.
- * - `ask` is the permission-prompt intent: serviced as a one-shot decision by
- *   the `ctx.approval` seam when one is mounted (`allowed-once` proceeds to
- *   dispatch; every other outcome denies), degrading to `deny` when none is.
+ * Pre-dispatch decision. `allow` runs the call; `deny` materializes an error;
+ * `ask` runs only after an approval service returns `allowed-once` and otherwise
+ * denies. Input rewriting is excluded because arguments are already logged and
+ * presented.
  */
 export type PreToolDecision =
   | { kind: 'allow' }
@@ -348,16 +263,8 @@ export type PreToolDecision =
   | { kind: 'ask'; reason?: string }
 
 /**
- * The decision a `tools/post-execute` listener returns for one finished call.
- * Maps onto Claude Code's `PostToolUse` decision.
- *
- * - `accept` keeps the call successful; optional `content` REPLACES the
- *   model-facing result (clean: `tool/result` is logged AFTER `execute()`
- *   returns, so a replaced result is the single source of truth for both derived
- *   history and UI). Optional `additionalContext` rides to the next request.
- * - `block` turns the call into an `isError` result whose content is the
- *   corrective `feedback` (the model is told the call was rejected and why),
- *   optionally also attaching `additionalContext`.
+ * Post-dispatch decision: accept or replace content, attach context for the next
+ * request, or block by turning corrective feedback into an error result.
  */
 export type PostToolDecision =
   | { kind: 'accept'; content?: ContentBlock[]; additionalContext?: HookContext }
@@ -400,35 +307,17 @@ export type ToolPresentationMode = 'native' | 'code' | 'both'
 /** Plugin config: how the registered tools are presented to the model. */
 export interface Config {
   /**
-   * The presentation mode. `'native'` (the default) contributes every
-   * visible end capability as a native wire function definition. Under
-   * `'code'` this registry contributes exactly ONE wire tool,
-   * `run_code`, plus the generated `tools:sdk` prompt section declaring every other tool as a
-   * TypeScript API the program calls. `'both'` contributes every native
-   * definition AND `run_code` + the SDK section. Non-native modes require a
-   * loaded `ctx.codeRuntime` whose `language` is `'typescript'` — a missing
-   * or mismatched runtime rejects every prompt assembly with an actionable
-   * error (misconfiguration fails loud, before any model request). A
-   * configured `systemPrompt.toolOrder` naming native tools likewise rejects
-   * every assembly under `'code'` (those names are no longer contributed) —
-   * a deployment switching modes updates its order config or drops it.
+   * Model presentation. `native` (default) sends every visible schema; `code`
+   * sends only `run_code` plus a generated SDK prompt; `both` sends both forms.
+   * Code modes require a TypeScript runtime and fail prompt assembly when it is
+   * absent or mismatched. Under `code`, native names in `toolOrder` are invalid.
    */
   mode?: ToolPresentationMode
 }
 
 /**
- * A per-scope restriction over the GLOBAL tool surface, registered via
- * {@link ToolRegistry.restrict}. `allow` keeps only the listed global tools;
- * `deny` removes the listed ones; both present = allow first, then deny.
- * Restrictions never touch scoped registrations — a tool registered through
- * the same scope is merged after the global filter (which is what keeps e.g. a
- * structured-output capture tool alive under an allow-list). The readonly
- * filter values compile to private sets at registration, but resolution uses the live global registry:
- * a later global name passes a deny-only filter unless explicitly denied and
- * fails an allow-list unless explicitly allowed. The
- * reserved `run_code` presentation transport is likewise outside capability
- * filtering, and naming it explicitly is rejected. Multiple restrictions on
- * one scope compose by intersection: every one must admit.
+ * Per-scope filter over global tools. Restrictions intersect and do not affect
+ * scoped registrations or the reserved Code Mode transport.
  */
 export interface ToolRestriction {
   /** Global tool names that stay visible; everything else is removed. */
@@ -469,26 +358,8 @@ interface ToolGuardRegistration {
 }
 
 /**
- * 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. The
- * registry contributes its schemas into the system-prompt assembly — WHICH
- * schemas is governed by its `mode` config
- * (see {@link Config.mode}); under a non-native mode it also owns the reserved
- * `run_code` presentation transport and the `tools:sdk` prompt section.
- *
- * Two registration layers (`@deepseek-ai/dsh-scope`): a registration through a
- * plain plugin context is GLOBAL (visible to every agent); one through a
- * scoped context (`agent.ctx`) is filed in that scope's layer — visible to
- * that agent alone, disposed with the scope, and SHADOWING a global tool of
- * the same name for that agent (most-specific-wins; within one layer a
- * duplicate name still throws). {@link restrict} masks the global layer per
- * scope. One private visibility resolver feeds the registry's prompt
- * contribution, {@link get}, and {@link execute} — and, under a non-native
- * mode, the SDK section and `run_code`'s bindings — so those registry-owned
- * presentation and dispatch paths agree. An expert `system-prompt/assemble`
- * listener may deliberately replace the final wire composition and owns any
- * resulting divergence.
+ * Tool registry and execution pipeline. Scoped registrations shadow globals;
+ * one visibility resolver feeds presentation, lookup, and dispatch.
  */
 export class ToolRegistry extends Service {
   static inject = ['systemPrompt']
@@ -526,13 +397,7 @@ export class ToolRegistry extends Service {
       ctx.systemPrompt.section({
         name: 'tools:sdk',
         order: SDK_SECTION_ORDER,
-        // A lazy thunk over the live registry, per assembly CONTEXT:
-        // regenerated at each assembly over the CALLING SCOPE's visible set
-        // (scoped tools join, restricted globals vanish — the SDK declares
-        // exactly what that agent's programs can call), in lexicographic
-        // tool order, so an unchanged tool set renders byte-identical text
-        // (prefix-cache-friendly) and a mid-session registration surfaces
-        // exactly like a native-mode tool change.
+        // Regenerate from the calling scope's visible tools in stable order.
         text: (context) => {
           this.requireCodeRuntime()
           return renderToolsSdk(this.schemas(context.scope).filter(schema => schema.name !== RUN_CODE_NAME))
@@ -542,22 +407,8 @@ export class ToolRegistry extends Service {
   }
 
   /**
-   * The registry's contribution to the wire tool list, per {@link Config.mode},
-   * as ONE SCOPE sees it (scoped layer joins, shadowing and restrictions
-   * applied — {@link schemas}). Because `PromptAssembly.tools` is what the
-   * loop's request header snapshots, the mode's collapse is logged and
-   * reconstructable for free. Under a non-native mode this is also the loud
-   * misconfiguration gate: no usable code runtime → every assembly rejects
-   * before any model request.
-   *
-   * The `knownNames` universe distinguishes the two ways a tool can be off
-   * the wire: a per-scope RESTRICTION is runtime state, so `knownNames` stays
-   * pre-restriction and a restricted-away tool in `toolOrder` is a normal
-   * absence — while the MODE collapse is deployment config, so under
-   * `mode: 'code'` the universe is `[run_code]` and a `toolOrder` naming a
-   * native tool is dead configuration that fails every assembly loud. Under
-   * `mode: 'both'`, the provider adds the reserved transport to the
-   * capability-only known-name universe for `toolOrder` validation.
+   * Build one scope's wire schemas and names for prompt-order validation.
+   * Restrictions do not make known tools invalid, but a mode collapse does.
    */
   private wireSchemas(scope?: ScopeKey): ToolProviderResult {
     const view = this.view(scope)
@@ -595,23 +446,10 @@ export class ToolRegistry extends Service {
   }
 
   /**
-   * Register a tool. The layer is decided by the CALLING context: a plain
-   * plugin context registers globally; a scoped context (`agent.ctx`)
-   * registers into that scope's layer — visible to that agent alone, disposed
-   * with the scope, and shadowing a same-named global tool for that agent.
-   * Throws if the SAME layer already has the name (cross-layer name twins are
-   * the shadowing feature, not an error; the global-duplicate message names
-   * `agent.ctx` as the per-agent alternative), or if a non-native mode reserves
-   * the `run_code` name for its presentation transport. The visible schema set
-   * flows into prompt assembly automatically. Definitions are trusted typed
-   * same-process contributions; JSON materialization happens when the schema or
-   * result reaches its model/log boundary. Emits `tools/change` on
-   * register/unregister.
-   * @param definition - the tool's schema plus its execute (and optional
-   *   presentation) functions.
-   * @returns the disposer that unregisters the tool. The exact
-   *   Cordis effect disposer (single-shot): composite (generator) effects may
-   *   yield it directly — exact identity nests the teardown in order.
+   * Register globally or in the calling agent scope. Scoped tools shadow
+   * globals; duplicates within one layer and the reserved `run_code` name fail.
+   * @param definition - the tool schema, execution, and optional presentation functions.
+   * @returns the exact disposer that unregisters the tool.
    */
   register(definition: ToolDefinition): () => void {
     const scope = scopeOf(this.ctx)
@@ -632,52 +470,26 @@ export class ToolRegistry extends Service {
           : `tool "${name}" is already registered in this scope`)
       }
       layer.set(name, definition)
-      // Yield the rollback BEFORE emitting `tools/change`: a generator effect
-      // collects each yielded disposer before the next step runs, so a throwing
-      // `tools/change` listener removes the tool instead of leaking it (a leak
-      // would wedge the duplicate-name check until restart). The duplicate
-      // throw above fires before any mutation — it leaks nothing.
+      // Install rollback before notifying listeners.
       yield () => {
         layer.delete(name)
-        // An emptied scope layer is dropped so a disposed scope leaves no
-        // residue keyed by its (dead) key.
+        // Drop empty scope layers.
         if (scope !== undefined && layer.size === 0) this.scoped.delete(scope)
         this.ctx.emit('tools/change')
       }
       this.ctx.emit('tools/change')
     }.bind(this), 'tools.register()')
-    // The EXACT cordis effect disposer, not a wrapper: a composite (generator)
-    // effect that owns a teardown ORDER must be able to yield THIS function —
-    // cordis nests a disposer out of the fiber's concurrent sibling list by
-    // exact function identity, so a wrapper would silently break the nesting
-    // (the agents.register() lesson). Cleanup is synchronous because this
-    // registration installs only synchronous state and notifications.
+    // 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
   }
 
   /**
-   * Restrict the GLOBAL tool surface for the calling scope. Must be called
-   * through a scoped context (`agent.ctx`) — restricting "everyone" is not a
-   * thing (throw), and an empty filter (neither `allow` nor `deny`) is a no-op
-   * that can only be a bug (throw — the materialized-empty-config trap).
-   * Validates every listed name against the CURRENT global end-capability
-   * universe and throws on an unknown or scope-local name (fail loud
-   * beats a typo silently filtering nothing) — register restrictions after the
-   * global tools they mask exist (the agent-creation `setup` window satisfies
-   * this). A non-native mode's reserved `run_code` presentation transport is
-   * not a filterable capability; naming it explicitly throws, while omitting
-   * it from an allow-list cannot remove it. The readonly arrays are compiled to
-   * private sets at registration. Resolution still uses the live global registry, so a later
-   * global name passes a deny-only filter unless named and fails an allow-list
-   * unless named. Multiple restrictions compose by intersection. Scoped
-   * registrations are merged after restrictions and therefore remain visible.
-   * Disposed with the calling fiber (revocable independently); emits
-   * `tools/change`.
+   * Restrict global tools for the calling agent scope. Empty filters, unknown
+   * names, scope-local names, and reserved transport names fail. Restrictions
+   * intersect; scoped registrations remain visible.
    * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
-   * @returns the disposer that lifts this restriction. The exact
-   *   Cordis effect disposer (single-shot): composite (generator) effects may
-   *   yield it directly — exact identity nests the teardown in order.
+   * @returns the exact disposer that lifts this restriction.
    */
   restrict(filter: ToolRestriction): () => void {
     const scope = scopeOf(this.ctx)
@@ -715,12 +527,7 @@ export class ToolRegistry extends Service {
       }
       this.ctx.emit('tools/change')
     }.bind(this), 'tools.restrict()')
-    // The EXACT cordis effect disposer, not a wrapper: a composite (generator)
-    // effect that owns a teardown ORDER must be able to yield THIS function —
-    // cordis nests a disposer out of the fiber's concurrent sibling list by
-    // exact function identity, so a wrapper would silently break the nesting
-    // (the agents.register() lesson). Cleanup is synchronous because this
-    // registration installs only synchronous state and notifications.
+    // 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
   }
@@ -842,15 +649,8 @@ export class ToolRegistry extends Service {
   }
 
   /**
-   * The model-facing schemas of everything `scope` can see — exactly the
-   * fields (`name`, `description`, `parameters`) this registry contributes to
-   * system-prompt assembly before its expert transformation waterfall.
-   * Constructed EXPLICITLY rather than by stripping
-   * known non-schema members: a `ToolDefinition` also carries `execute` and the
-   * optional `presentCall`/`presentResult` UI callbacks, and those (especially
-   * the functions) must never leak into a model request. An allowlist can't
-   * drift when a new non-schema member is added to the definition; a denylist
-   * (rest-destructure) would silently leak it.
+   * Project visible definitions onto the allowlisted model-facing schema fields,
+   * excluding execution and presentation callbacks.
    * @param scope - the viewing scope (the agent); omitted = the global view.
    * @returns one deep-cloned schema per visible tool.
    */
@@ -869,27 +669,13 @@ export class ToolRegistry extends Service {
   }
 
   /**
-   * Execute one tool call through the `tools/pre-execute` → guards →
-   * `tools/execute` (around dispatch) → `tools/post-execute` → `tools/result`
-   * pipeline. `pre-execute` is the extensible gate
-   * (allow/deny/ask), `tools/execute` wraps core dispatch (a timeout/retry/metrics
-   * seam), and `post-execute` is the inspect/transform seam; core dispatch sits
-   * as the base `next()` of the `tools/execute` waterfall. The whole thing is
-   * wrapped in one outer try/catch so a throwing listener (in any waterfall)
-   * becomes an `isError` result instead of failing the turn; the tool body ALSO
-   * keeps its own inner try/catch, so a thrown tool becomes an `isError` result
-   * that `tools/execute` and `post-execute` listeners can still inspect. If the
-   * tool is not registered (or not visible to the calling agent — a
-   * restricted-away global is exactly as absent as a nonexistent one), the
-   * result is an `isError` carrying a `UNKNOWN_TOOL` structured error. A thrown
-   * {@link HarnessError} surfaces its `{ name, code }` on the result. Before
-   * the final observe-only notification, the authoritative outcome is
-   * materialized as a detached lossless-JSON snapshot; an invalid outcome is
-   * normalized to an error.
+   * Execute through pre-policy, guards, around-dispatch, post-policy, and final
+   * notification. Tool and listener failures resolve as materialized error
+   * results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is
+   * the same lossless, frozen snapshot final observers receive.
    * @param exec - the typed same-process call input. The registry assigns its
    *   correlation token before policy begins.
-   * @returns the materialized final result after every waterfall; listener and
-   *   tool failures resolve as `isError` results rather than rejections.
+   * @returns the materialized final result.
    */
   async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult> {
     const token = createExecutionToken()

packages/core/tools/src/json-schema.ts

@@ -1,31 +1,9 @@
 /**
- * Structured-output JSON Schema subset: the vocabulary a caller uses to demand
- * a machine-readable result from a subagent (`SubagentStartRequest.outputSchema`)
- * or a workflow `agent()` call.
- *
- * This is deliberately NOT full JSON Schema. The schema travels verbatim to the
- * model as a forced tool's `parameters`, and the value the model produces is
- * validated here — so every accepted keyword must be one this module actually
- * enforces. Accepting a keyword we don't enforce would validate less than the
- * schema promises (accepted-then-ignored), so anything outside the subset is
- * REJECTED LOUD by {@link assertSupportedOutputSchema} instead. The subset:
- *
- * - `type` — a single string (`object`/`array`/`string`/`number`/`integer`/
- *   `boolean`/`null`); type ARRAYS (`["string","null"]`) are rejected.
- * - `properties`/`required`/`additionalProperties` (boolean) on objects; every
- *   `required` key must be declared in `properties`. `additionalProperties`
- *   absent keeps standard JSON Schema semantics (extra keys allowed).
- * - `items` on arrays (absent ⇒ any JSON items).
- * - `enum` (non-empty, scalars only) and `const` (scalar) on scalar types.
- * - Annotations `description`/`title`/`default`/`examples` are allowed and
- *   ignored (they constrain nothing), except that they must still be JSON data
- *   — the schema is serialized onto the wire, so a non-JSON annotation would be
- *   silently mangled.
- *
- * Values checked by {@link validateStructuredValue} are expected to be plain
- * host-realm JSON data (model tool-call arguments are parsed wire JSON; a
- * caller holding foreign-realm data materializes it first).
- *
+ * Structured-output JSON Schema subset for subagents and workflows. It supports
+ * one scalar `type`; object `properties`/`required`/boolean
+ * `additionalProperties`; array `items`; scalar `enum`/`const`; and JSON-valued
+ * annotations. Unsupported or misplaced keywords reject rather than being
+ * accepted without enforcement, and structured-output roots must be objects.
  * @module dsh-tools/json-schema
  */
 

packages/core/tools/src/presentation.ts

@@ -1,20 +1,7 @@
 /**
  * Tool render-intent vocabulary: the provider-neutral types a tool declares via
- * `ToolDefinition.presentCall`/`ToolDefinition.presentResult` to say
- * how ONE of its calls renders in a UI (an editor's tool-call card, a CLI log
- * line). A UI bridge switches on the `card` tag to map each intent to its own
- * wire shape, so a UI never special-cases tool names.
- *
- * This is the UI-facing surface of `dsh-tools`, kept separate from the registry
- * and execution core in `index.ts`: this module owns ONLY presentation
- * vocabulary and references none of the execution types, so the dependency runs
- * one way (`index.ts` imports these views for the `ToolDefinition` method
- * signatures). The opaque `meta` presentation channel is execution plumbing and
- * lives with the registry in `index.ts`, not here.
- *
- * See the render-intent-union RFC
- * (docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md).
- *
+ * `ToolDefinition.presentCall`/`ToolDefinition.presentResult` to say how one of its calls
+ * renders in a UI (an editor's tool-call card, a CLI log line).
  * @module @deepseek-ai/dsh-tools/src/presentation
  */
 
@@ -56,14 +43,8 @@ export interface FileDiff {
 }
 
 /**
- * How a tool wants ONE of its calls shown in a UI (an editor's tool-call card, a
- * CLI log line) BEFORE the result is known — the *pending* state. A `card`-tagged
- * discriminated union: a tool declares its render INTENT once and a UI bridge
- * switches on `card` to map it to the bridge's own wire shape. Provider-neutral —
- * the tool owns its presentation, so a UI never special-cases tool names.
- *
- * Returned by `ToolDefinition.presentCall`. See the render-intent-union
- * RFC (docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md).
+ * Provider-neutral pending-call presentation. Tools declare one tagged intent;
+ * UI bridges map it without special-casing tool names.
  */
 export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView
 
@@ -186,16 +167,10 @@ export interface TerminalResultView {
 }
 
 /**
- * A completed file mutation rendered as an inline diff card, the *result-time*
- * analogue of {@link DiffCallView}. Set by a tool whose `execute` applied a file
- * change (e.g. `write`, `edit`): `diffs` are the change to show — typically the
- * APPLIED hunks computed from the before/after content (one entry per hunk, each
- * with surrounding context lines), so the editor shows the real change in place;
- * a tool with no before-image (e.g. a file create) may instead give a whole-file
- * diff (`oldText: null`). A `tool_call_update`'s content REPLACES the call's
- * content in an editor, so a mutation tool returns this even when it duplicates
- * the call-time snippet — otherwise the model-facing result text would replace
- * (clobber) the pending diff card.
+ * A completed file mutation rendered as an inline diff card, the result-time
+ * analogue of {@link DiffCallView}. Because a completed UI update replaces the
+ * pending card content, mutation tools return this even when it repeats the
+ * call-time diff; otherwise raw result text would replace the diff.
  */
 export interface DiffResultView {
   card: 'diff'

packages/core/tools/src/schema.ts

@@ -1,23 +1,4 @@
-/**
- * Typed tool-parameter schema DSL.
- *
- * Plugin authors write per-property specs with `required: true` as a boolean
- * (the `SchemaSpec` type). A type-level helper (`InferArgs`) maps a SchemaSpec
- * to the TS argument type. At runtime, `schemaSpecToJsonSchema()` converts a
- * SchemaSpec to standard JSON Schema (`type: 'object'`, `properties`,
- * `required` array) for the wire format sent to the model.
- *
- * # Why a custom DSL and not schemastery?
- *
- * Schemastery is a validation/transformation library (StandardSchema v1) used
- * for plugin Config. Tool parameters need JSON Schema specifically (the LLM
- * wire format), not validation. A lightweight DSL focused on JSON Schema
- * generation, with type inference for the tool's `execute` args, gives plugin
- * authors the best DX with the smallest surface area. Schemastery would add
- * unnecessary indirection and wouldn't cleanly produce JSON Schema.
- *
- * @module dsh-tools/schema
- */
+/** Typed tool-parameter DSL with argument inference and JSON Schema output. @module dsh-tools/schema */
 
 import { assertNever, HarnessError } from '@deepseek-ai/dsh-llm'
 import type { ToolDefinition, ToolExecuteReturn, ToolExecution, ToolResult } from './index.ts'
@@ -328,39 +309,13 @@ export interface DefineToolOptions<S extends SchemaSpec> {
 }
 
 /**
- * Define a tool with a typed parameter schema.
- *
- * Use this instead of constructing a raw {@link ToolDefinition} for all
- * first-party tools. The `parameters` use the boolean-required style
- * (`required: true` as a per-property flag), and `execute` receives typed
- * args derived from the schema.
- *
- * ```ts
- * const tool = defineTool({
- *   name: 'read_file',
- *   description: 'Read a file from disk.',
- *   parameters: {
- *     path: { type: 'string', required: true, description: 'Absolute file path' },
- *     offset: { type: 'number' },
- *     limit: { type: 'number', description: 'Max lines to read' },
- *   },
- *   async execute(args) {
- *     // args: { path: string; offset?: number; limit?: number }
- *   },
- * })
- * ```
- *
- * Raw JSON-Schema tool definitions (from MCP servers) are still accepted
- * by `ToolRegistry.register()` directly — `defineTool` is sugar for
- * first-party plugin authors.
- *
+ * Define a first-party tool whose execution and presentation arguments are
+ * inferred from its per-property schema. Raw JSON-Schema definitions remain
+ * valid inputs to {@link ToolRegistry.register}; this helper is authoring sugar.
  * @param options - the tool's name, description, typed parameter schema,
  *   execute body, and optional presenters.
- * @returns a registry-ready {@link ToolDefinition}: its `execute` validates the
- *   raw args first (throwing {@link ToolArgsError} on mismatch, which the
- *   registry turns into an isError result), and its presenters validate softly
- *   (returning undefined on mismatch, since replay may feed them older-schema
- *   args).
+ * @returns a registry-ready definition with strict execution validation and
+ *   soft presenter validation for replay compatibility.
  */
 export function defineTool<S extends SchemaSpec>(options: DefineToolOptions<S>): ToolDefinition {
   // Object-literal execute methods don't use `this`; the reference is safe.

packages/core/tools/src/ts-types.ts

@@ -1,17 +1,8 @@
 /**
- * Code Mode codegen: the pure projection from registered tool schemas to the
- * TypeScript SDK text the model programs against (the `tools:sdk` prompt
- * section). Sibling of `json-schema.ts` — `schemas()` (native function
- * calling) and this module (the generated `declare const tools` surface) are
- * two projections of the same store.
- *
- * TOTAL by design: {@link jsonSchemaToTs} maps the JSON-Schema subset the
- * `defineTool` DSL emits and degrades every construct outside it (`$ref`,
- * `oneOf`, `integer`, future MCP shapes, …) to `unknown` without ever
- * throwing — codegen must never be the thing that fails an assembly.
- * Deterministic: a fixed tool set renders byte-identical text (tools in
- * lexicographic name order), so the section is prefix-cache-friendly.
- *
+ * Code Mode codegen: the pure projection from registered tool schemas to the TypeScript SDK
+ * text the model programs against (the `tools:sdk` prompt section). Sibling of
+ * `json-schema.ts` — `schemas()` (native function calling) and this module (the generated
+ * `declare const tools` surface) are two projections of the same store.
  * @module @deepseek-ai/dsh-tools/src/ts-types
  */
 
@@ -33,10 +24,8 @@ function pad(indent: number): string {
 /** A one-line JSDoc block for a schema `description`, or no lines when there is none. */
 function docLines(description: unknown, indent: number): string[] {
   if (typeof description !== 'string' || description.length === 0) return []
-  // Keep the doc a single-line comment per property: descriptions are prose
-  // (possibly with newlines); collapse whitespace so the rendered SDK stays
-  // stable and compact. A comment-closer inside the description is escaped so
-  // it cannot terminate the generated JSDoc early.
+  // Collapse prose to stable one-line docs and escape comment closers so a
+  // schema description cannot terminate generated JSDoc.
   const collapsed = description.replace(/\s+/g, ' ').trim()
   return [`${pad(indent)}/** ${collapsed.replaceAll('*/', String.raw`*\/`)} */`]
 }

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

@@ -349,10 +349,8 @@ describe('the run_code dispatch bridge', () => {
       return { logs: [], value: 'done' }
     }
 
-    // Model a timeout-style outer wrapper: it temporarily installs a signal,
-    // delegates, then restores the exact prior shape. A nested result observer
-    // is observe-only and must not receive the live outer execution object;
-    // freezing the correlation value it sees therefore cannot break restore.
+    // Freeze the nested observer's parent correlation. If that were the live
+    // outer execution object, the timeout-style wrapper could not restore it.
     ctx.on('tools/execute', async (exec, next) => {
       if (exec.name !== RUN_CODE_NAME) return next()
       const previous = exec.signal
@@ -576,11 +574,8 @@ describe('the run_code dispatch bridge', () => {
       },
     }))
     runtime.behavior = async (request) => {
-      // Start a sub-dispatch, keep its rejection held, and fail the run once
-      // the tool is genuinely in flight — a seam error AFTER work has begun.
-      // The bridge's settlement still owes quiescence: without the finally,
-      // run_code would return now and the slow tool would finish (and log)
-      // afterwards.
+      // Start a sub-dispatch, keep its rejection held, and fail the run once the tool is
+      // genuinely in flight — a seam error after work has begun.
       request.bindings[0]!.functions.slow!({ id: 'orphan' }).catch(() => 'held')
       await inFlight
       throw new Error('backend exploded')

packages/core/tools/tests/gen-tool-catalog.spec.ts

@@ -1,17 +1,5 @@
 /**
- * Guarantee tests for the tool-schema catalog generator
- * (`scripts/gen-tool-catalog.ts`).
- *
- * The generated catalog is frozen by a regenerate-and-diff freshness gate, so
- * the freshness half is exercised by `pnpm run verify-tool-catalog` in CI. What
- * a freshness diff CANNOT prove is (a) that BOOTING the tool plugins yields the
- * shipped schema — the whole reason this generator boots instead of parsing
- * source (a runtime-spread enum resolves to its literal members) — and (b) that
- * the completeness guard REJECTS a tool package missing from the boot manifest,
- * the property that replaces the AST pass's "nothing silently omitted". These
- * tests drive the exported `collectToolCatalog` / `assertManifestComplete` /
- * `render` directly, mirroring the negative-path style of the cordis-catalog
- * generator tests.
+ * Guarantee tests for the tool-schema catalog generator (`scripts/gen-tool-catalog.ts`).
  */
 
 import { describe, expect, it } from 'vitest'
@@ -62,11 +50,8 @@ describe('gen-tool-catalog collectToolCatalog', () => {
   })
 
   it('records the shipped `subagent_fork` alias in a note (config-driven tool name)', async () => {
-    // `tool-subagent`'s registered name is the load-time `toolName` config, so
-    // the shipped agents surface this one package as both `subagent` and
-    // `subagent_fork`. Booting yields only the default name; the note is how a
-    // reader learns the fork alias the model also sees. Without it the catalog
-    // would silently under-report the shipped tool surface.
+    // `tool-subagent`'s registered name is the load-time `toolName` config, so the shipped
+    // agents surface this one package as both `subagent` and `subagent_fork`.
     const catalog = await collectToolCatalog()
     const subagent = catalog.find(entry => entry.pkg === '@deepseek-ai/dsh-tool-subagent')
     expect(subagent?.schemas.map(s => s.name)).toEqual(['subagent'])

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

@@ -703,16 +703,9 @@ describe('ToolRegistry', () => {
   })
 
   it('register() returns the EXACT effect disposer: a composite yield nests the teardown in order', async () => {
-    // The registry-disposer convention (set by agents.register): the returned
-    // function IS the cordis effect disposer, so a composite (generator)
-    // effect that yields it has the unregistration run at that yield's LIFO
-    // position on owner unload. A wrapper would leave the inner effect
-    // disposing as a CONCURRENT SIBLING of the composite; the async probe
-    // below (disposed first, LIFO) yields the event loop exactly like the
-    // agent factory's stop-and-drain link, and a sibling unregistration fires
-    // in that window — the probe would observe the tool already gone. Pins
-    // the convention for the whole register-method family (system-prompt
-    // registrars, registerProvider, setFactory share the same return).
+    // Registry methods return the exact Cordis effect disposer so a composite yield places
+    // unregistration at its LIFO position. A wrapper would create a concurrent sibling; this async
+    // probe yields during earlier teardown and would then observe the tool already removed.
     const ctx = await setup()
     const order: string[] = []
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
@@ -999,20 +992,18 @@ describe('schema DSL edge cases', () => {
         port: { type: 'number' },
       },
     })
-    // no 'required' key in the nested object because nothing is required
     const config = jsonSchema.properties['config'] as Record<string, unknown>
     expect('required' in config).toBe(false)
   })
 })
 
-describe('schema DSL regressions (Codex review round 2)', () => {
+describe('schema DSL optional and nested contracts', () => {
   it('InferArgs makes non-required keys genuinely optional (omittable)', () => {
     type Args = InferArgs<{
       path: { type: 'string'; required: true }
       limit: { type: 'number' }
     }>
     expectTypeOf<Args>().toEqualTypeOf<{ path: string; limit?: number }>()
-    // omitting the optional key is assignable — the actual regression
     const omitted: Args = { path: '/tmp' }
     expect(omitted.limit).toBeUndefined()
   })

packages/fs/fs-local/README.md

@@ -6,7 +6,7 @@ The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepse
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
 
 await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
-// ctx.fs is now the local backend; load @deepseek-ai/dsh-fs-policy for the
+// ctx.fs uses the local backend; load @deepseek-ai/dsh-fs-policy for the
 // freshness policy gate and @deepseek-ai/dsh-tool-fs to expose read/write/edit.
 ```
 
@@ -23,7 +23,7 @@ The raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `sr
 
 ## Model Experience
 
-Indirectly, through `dsh-tool-fs`, which renders this provider's line-windowed UTF-8 content, mutation acknowledgements, and exact provider messages under `Error: <message>` into capped retained tool results while versions, atomic-write mechanics, and directory metadata remain internal.
+Indirectly, through [`dsh-tool-fs`](../tool-fs/README.md), which renders this provider's line-windowed UTF-8 content, mutation acknowledgements, and exact provider messages in capped retained results while versions, atomic-write mechanics, and directory metadata remain internal.
 
 ## Known Limitations and Deferred Work
 

packages/fs/fs-local/src/fsio.ts

@@ -1,20 +1,7 @@
 /**
- * Cordis-free local-filesystem I/O for `@deepseek-ai/dsh-fs-local`. Kept
- * separate from the service class (mirroring `dsh-bash-local`'s `run.ts`) so
- * the raw stat/read/write/edit mechanics can be unit-tested without a Context.
- *
- * This is the PROVIDER layer: it hands back decoded whole-file text (validated
- * UTF-8, binary rejected) — never line windows or numbered lines, which are
- * model-facing read policy owned by `@deepseek-ai/dsh-fs-policy`. Large files
- * stream their text in chunks so a huge file never has to be held whole in
- * memory; the binary/NUL sample and cross-chunk UTF-8 decoding stay here.
- *
- * Writes are atomic: content goes to a temp file opened exclusively (`wx`,
- * `0o600`, so a pre-existing path can never be clobbered and write-in-progress
- * bytes stay owner-only) inside a randomly-named private staging directory
- * (`0o700`) next to the target, then `rename`d over the target. Edits are
- * read-modify-write over the same atomic primitive.
- *
+ * Cordis-free local filesystem mechanics. This provider layer returns validated UTF-8 text,
+ * streams large files, and rejects binary data; line windows belong to `dsh-tool-fs`. Writes
+ * stage an exclusive owner-only file in a private sibling directory and atomically rename it.
  * @module @deepseek-ai/dsh-fs-local/fsio
  */
 
@@ -121,14 +108,9 @@ export interface LocalDirEntry {
 }
 
 /**
- * Resolve a path to its absolute display path and realpath identity. Relative
- * paths are based on `cwd`. When the file itself does not yet exist, the
- * `targetKey` realpaths the nearest EXISTING ancestor directory and re-appends
- * the still-missing suffix, so a not-yet-created file gets the same stable key
- * it will have after creation — even when an ancestor (e.g. `cwd`) is a symlink
- * and intermediate directories are created by the write. Two input paths
- * reaching the same file via symlinks share one key. Falls back to the absolute
- * path only when no ancestor (not even the filesystem root) can be resolved.
+ * Resolve a path to its absolute display path and realpath identity. For a missing target,
+ * realpath the nearest existing ancestor and append the missing suffix, preserving identity
+ * across symlinked ancestors before and after creation.
  * @param cwd - base directory a relative `path` resolves against.
  * @param path - absolute or relative path; empty/whitespace-only throws `FS_NOT_FOUND`.
  * @returns the absolute display path plus the realpath-derived stable target key.
@@ -363,15 +345,11 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
 }
 
 /**
- * Atomically write `content` to `absolutePath`: create parent dirs, write to a
- * randomly-named temp file opened exclusively (`wx`, `0o600`) inside a private
- * (`0o700`) staging directory, fsync, optionally chmod to the final mode while
- * still private, then rename over the target. `mode` (when given) preserves an
- * existing file's permissions across the replace.
- * @param absolutePath - the final destination (typically a target key); missing parent dirs are created.
+ * Atomically replace a file through a private, synced staging file in the same directory.
+ * @param absolutePath - destination; missing parent directories are created.
  * @param content - the full UTF-8 text to write.
- * @param mode - final file mode applied before the rename (an existing file's, to preserve permissions); undefined leaves `0o600`.
- * @param signal - aborts the write (`FS_ABORTED`); checked before the rename, so the target is never left torn.
+ * @param mode - final mode, or `0o600` when omitted.
+ * @param signal - cancellation checked before the final rename.
  * @param internals - test seam for pinning temp names and observing the staged file.
  */
 export async function writeFileAtomic(
@@ -492,12 +470,8 @@ export async function readForEdit(
 }
 
 /**
- * Best-effort read of a file's current text for a before/after diff basis, used
- * by an overwrite. Returns the LF-normalized decoded content, or `null` when the
- * file is binary or not valid UTF-8 — a write must succeed regardless of the
- * prior bytes, so an undiffable prior file simply yields no contextual-hunk basis
- * (the caller treats `null` the same as an absent file: the result renders a
- * whole-file diff rather than an applied hunk).
+ * Best-effort overwrite diff basis. Binary or invalid UTF-8 returns `null` so the write still
+ * succeeds and presentation falls back to a whole-file diff.
  * @param absolutePath - the file to read (typically a target key); it must exist.
  * @param signal - aborts the read (`FS_ABORTED`).
  * @returns the LF-normalized text, or null for a binary or non-UTF-8 file.
@@ -515,12 +489,11 @@ export async function readTextForDiff(absolutePath: string, signal?: AbortSignal
 }
 
 /**
- * Apply a literal replacement to LF-normalized content. Throws
- * `FS_EDIT_NOT_FOUND` on empty `oldString` or zero matches and
- * `FS_AMBIGUOUS_EDIT` on multiple matches when `replaceAll` is false. Returns
- * the edited content (still LF-normalized) and the replacement count.
+ * Apply a literal replacement to LF-normalized content. Empty or missing search text throws
+ * `FS_EDIT_NOT_FOUND`; multiple matches throw `FS_AMBIGUOUS_EDIT` unless `replaceAll` is true.
  * @param content - the current file content, already LF-normalized.
- * @param oldString - literal text to find; CRLF inside it is normalized to LF before matching.
+ * @param oldString - literal text to find; CRLF inside it is normalized to LF before
+ *   matching.
  * @param newString - literal replacement text, normalized the same way.
  * @param replaceAll - replace every match instead of requiring exactly one.
  * @param displayPath - the caller-facing path used in error messages.

packages/fs/fs-local/src/index.ts

@@ -1,15 +1,6 @@
 /**
- * Local-filesystem implementation of the `ctx.fs` provider seam.
- * {@link LocalFileSystem} subclasses {@link FileSystem} and backs the seven
- * text-storage primitives with the host filesystem via
- * {@link module:@deepseek-ai/dsh-fs-local/fsio}. Path resolution uses
- * `realpath`, so the stable `targetKey` is the real file identity (two input
- * paths reaching the same file through symlinks share one key, and writes land
- * on the link target — preserving the link).
- *
- * Future sandboxed/remote/virtual backends are sibling packages implementing
- * the same interface; loading this one populates `ctx.fs`.
- *
+ * Host-filesystem implementation of `ctx.fs`. Realpath-derived target identity makes aliases
+ * share stale guards, and writes through a symlink update its target without replacing the link.
  * @module @deepseek-ai/dsh-fs-local
  */
 
@@ -156,18 +147,10 @@ export class LocalFileSystem extends FileSystem {
         // createIfAbsent onto an existing file: a blind overwrite — require a read first.
         throw new FsError(`cannot overwrite existing "${target.displayPath}" without reading it first`, 'FS_NOT_OBSERVED')
       }
-      // expected === undefined: unconditional create-or-overwrite (the bare
-      // provider) — no version guard, no read-first requirement. Still atomic
-      // (the per-target lock is unconditional), so the write is never torn.
+      // No expectation means an unconditional but still atomic write.
 
-      // Capture the prior text (the before/after diff basis) BEFORE the write.
-      // `null` for a create (no existing file) OR an existing-but-undiffable
-      // file (binary/invalid-UTF-8) — a null `before` gives no contextual-hunk
-      // basis, so a consumer falls back to a whole-file diff (the tool still
-      // renders a result-time diff card, not the raw result text).
-      // TODO(overwrite-diff-bound): this reads the whole prior file into memory
-      // for a UI-only diff; bound the pre-read and fall back to no contextual
-      // basis above a size threshold (see the applied-hunk-diffs RFC non-goals).
+      // Preserve prior text for contextual diffs; null falls back to a whole-file diff.
+      // TODO(overwrite-diff-bound): cap this UI-only pre-read for large files.
       const before = existing ? await readTextForDiff(target.targetKey, signal) : null
       await writeFileAtomic(target.targetKey, content, existing?.mode, signal, this.internals)
       const after = await probe(target.targetKey)
@@ -191,10 +174,9 @@ export class LocalFileSystem extends FileSystem {
   ): Promise<FsEditOutcome> {
     return this.withLock(target.targetKey, async () => {
       const existing = await probe(target.targetKey)
-      // Stale guard BEFORE literal matching: an edit based on an old read reports
+      // Stale guard before literal matching: an edit based on an old read reports
       // FS_STALE_VERSION, not FS_EDIT_NOT_FOUND/FS_AMBIGUOUS_EDIT against newer content.
-      // A missing target reports FS_STALE_VERSION on BOTH paths (guarded and
-      // unconditional) — one "cannot edit this target now" code.
+      // Missing targets use the same stale code on guarded and unconditional edit paths.
       if (!existing) throw new FsError(`cannot edit "${target.displayPath}": file changed since it was read`, 'FS_STALE_VERSION')
       if (existing.type !== 'file') throw new FsError(`cannot edit "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
       // expected === undefined: unconditional edit of the current content — no

packages/fs/fs-policy/README.md

@@ -37,7 +37,7 @@ Three `fs/*` events (declared by `@deepseek-ai/dsh-fs`, dispatched by `@deepseek
 
 ## Observed state is the prior-observation record; freshness is provider CAS
 
-Observed state is a `WeakMap<owner, Map<targetKey, FsVersion>>`. An entry exists **iff** the owner has read, written, OR edited that target (every success emits `fs/observed`), so its presence is the prior-observation record — there is no `hasRead` flag and no `full`/`partial` view. This plugin does **no** filesystem I/O: "have you observed this file?" is a `WeakMap` lookup, and "is the version you read still current?" is decided inside `ctx.fs.editText`/`writeText` in the same atomic lock that performs the mutation — this plugin only supplies `vObserved` as the basis. A windowed read of lines 100-150 records the file's version, and a later edit of line 120 is authorized as long as the file is unchanged. State is held weakly and dropped on disposal (HMR safety); persistence across sessions is deferred.
+Observed state is a weak owner-to-target version map updated after every successful read or mutation; presence alone is the prior-observation record. The plugin performs no filesystem I/O: it supplies the observed version to the provider's atomic mutation guard. A windowed read observes the whole file version, so a later targeted edit is allowed only while that file remains unchanged. State is discarded on plugin disposal and is not persisted across sessions.
 
 ## Single-slot, first-wins
 
@@ -51,7 +51,7 @@ Because the plugin influences the world only through events, removing it does no
 
 ### Filesystem tool outcome
 
-**What the model sees**: This plugin adds no prompt or schema. Through `dsh-tool-fs`, an edit without a prior read becomes exactly `Error: edit requires reading "<path>" first` with code `FS_NOT_OBSERVED`; guarded mutations whose observed version is stale receive the backend's exact `Error: cannot <write-or-edit> "<path>": file changed since it was read` with code `FS_STALE_VERSION`. Observation state itself is never shown.
+**What the model sees**: This plugin adds no prompt or schema. It rejects an edit without a prior read with code `FS_NOT_OBSERVED` and exact message `edit requires reading "<path>" first`. Guarded mutations whose observed version is stale propagate the provider-owned `FS_STALE_VERSION` error. [`dsh-tool-fs`](../tool-fs/README.md) owns the model-facing error wrapper; observation state is never shown.
 
 **Token effect**: Zero tokens on allowed operations beyond the ordinary tool result. A denial adds the small retained error result and avoids any success payload.
 

packages/fs/fs-policy/src/index.ts

@@ -1,45 +1,8 @@
 /**
- * The fs-policy PLUGIN: observed-state, read-before-edit, and
- * "write/edit must be based on the version you read" — added on top of the
- * `ctx.fs` provider seam through the `fs/*` event gate, NOT through a method
- * service. This plugin registers NO `ctx.fsPolicy` service and exposes no
- * `read`/`write`/`edit`/`resolve` methods; it influences the world only by
- * deciding the `fs/write-intent`/`fs/edit-intent` waterfalls and
- * recording on `fs/observed`. That is what keeps `@deepseek-ai/dsh-tool-fs`
- * (the executor) free of any method coupling to the policy layer — removing
- * this plugin gracefully loses the policy and leaves the unconstrained bare
- * provider, rather than breaking the tool at a service-injection boundary.
- *
- * ## Observed state IS the prior-observation record
- *
- * State lives here as `WeakMap<owner, Map<targetKey, { version }>>`. An entry
- * exists iff the owner has read, written, OR edited that target (every success
- * emits `fs/observed`), so its presence means "this owner has observed this
- * target at this version". This is what lets a create-then-edit or
- * edit-then-edit sequence work without an intervening re-read: the mutation
- * refreshes the recorded version to its own result. The owner is derived
- * structurally from `{ agent?: { session? } }` and held weakly, so a collected
- * session frees its state; disposal drops everything (HMR safety).
- *
- * ## Freshness via provider CAS, not stat
- *
- * This plugin does NO filesystem I/O. "Have you observed this file?" is a
- * `WeakMap` lookup (no record ⇒ `FS_NOT_OBSERVED`). "Is the version you read
- * still current?" is decided INSIDE `ctx.fs.editText`/`writeText`, in the same
- * atomic lock that performs the mutation — this plugin only supplies the
- * observed version as the CAS basis. Stat-ing and comparing here would open a
- * TOCTOU gap the provider lock has to back up anyway, so it is deliberately
- * avoided.
- *
- * ## Single-slot, first-wins
- *
- * The `fs/write-intent`/`fs/edit-intent` listeners do NOT call
- * `next()`: each fully decides its single slot. The slot is first-wins by
- * registration order — this plugin owning it is the default-deployment
- * convention, not an event-enforced invariant (a decider registered before /
- * `prepend`ed would win instead). This is not a composable authorization chain;
- * layered permission/audit/sandbox interception belongs on `tools/execute`.
- *
+ * Event-only filesystem observation policy; it registers no service. A weak owner/target map
+ * records every successful read or mutation, single-slot intent listeners supply that version,
+ * and the provider performs the atomic freshness check. Without this plugin, tools retain the
+ * bare provider's unconditional mutation behavior. See the package README for composition rules.
  * @module @deepseek-ai/dsh-fs-policy
  */
 
@@ -145,15 +108,11 @@ export function apply(ctx: Context): void {
   // holds (a throw rejects, never escapes synchronously through the waterfall).
   ctx.on('fs/write-intent', (target, actor) => Promise.resolve().then(() => gate.writeIntent(target, actor)))
 
-  // fs/edit-intent: occupy the single decision slot — do NOT call next().
-  // Deferred the same way so an FS_NOT_OBSERVED throw becomes a rejected promise
-  // the edit tool's `await ctx.waterfall(...)` surfaces as its isError result.
+  // fs/edit-intent: occupy the single decision slot — do not call next().
   ctx.on('fs/edit-intent', (target, actor) => Promise.resolve().then(() => gate.editIntent(target, actor)))
 
-  // fs/observed: synchronous, side-effect-only WeakMap write. The tool emits
-  // this with a plain (unguarded) ctx.emit, so this listener MUST NOT throw —
-  // a throw would surface as the tool's isError result for a mutation that
-  // already succeeded. A WeakMap.set honors that contract.
+  // fs/observed must remain synchronous and non-throwing: the mutation already succeeded, and
+  // emit does not await promises. WeakMap.set satisfies that contract.
   ctx.on('fs/observed', (target, version, actor) => {
     gate.observe(target, version, actor)
   })

packages/fs/fs-policy/tests/policy.spec.ts

@@ -1,14 +1,4 @@
-/**
- * Tests for the fs-policy PLUGIN: it registers no service, only the
- * three `fs/*` listeners. We dispatch those events directly (the unbound
- * waterfalls the tool would dispatch, and the `fs/observed` emit) and assert the
- * decisions: createIfAbsent vs replaceIfVersion, FS_NOT_OBSERVED for an unread
- * edit, observed-state-as-prior-observation (read/write/edit all record),
- * multi-owner isolation, single-slot first-wins, and disposal/HMR release.
- *
- * No `ctx.fs` provider is needed — the plugin does no filesystem I/O; it only
- * decides intents and records versions on its own WeakMap.
- */
+/** Event-level policy tests; no filesystem provider is needed because the plugin performs no I/O. */
 
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'

packages/fs/fs/src/index.ts

@@ -1,59 +1,8 @@
 /**
- * The filesystem provider seam (`ctx.fs`): an abstract service defining the
- * text-storage primitives a backend provides — resolve a path into a stable
- * target, stat its metadata, read/stream its text, write it atomically with an
- * explicit intent, and apply a guarded literal edit — without saying HOW.
- * Implementations subclass {@link FileSystem} and register themselves as the
- * `fs` service; `@deepseek-ai/dsh-fs-local` (the host filesystem) is the first.
- * Future implementations swap in sandboxed, remote, virtual, or project-scoped
- * backends without touching the model-facing tool schemas
- * (`@deepseek-ai/dsh-tool-fs`).
- *
- * The split mirrors the bash seam (`BashExecutor`/`LocalBashExecutor`). See the
- * capability-seam RFC for why a swappable capability is three (here four)
- * packages.
- *
- * ## This is a provider seam, not the policy layer
- *
- * `ctx.fs` is deliberately close to fsspec-style storage primitives. It owns
- * UTF-8 decoding, binary/NUL rejection, atomic full-file writes, and the
- * literal-edit critical section — but NOT line windows, numbered lines,
- * rendered footers, or observed-state. Read windowing lives in the model-facing
- * tool (`@deepseek-ai/dsh-tool-fs`); observed-state and read-before-write/edit
- * are policy a plugin (`@deepseek-ai/dsh-fs-policy`) adds through the `fs/*`
- * event gate. So a sandboxed/remote backend inherits no model-facing observation
- * policy it has no business carrying.
- *
- * `editText` stays on this seam (not composed in the policy layer from a read
- * plus a write) because version guard + literal match + atomic rewrite must
- * stay inside one mutation critical section for correct error attribution and
- * one-wins/one-stale concurrency, and a remote backend may implement it as a
- * native compare-and-edit.
- *
- * ## The version guard is OPTIONAL — additive policy, not subtractive
- *
- * `ctx.fs` on its own is a complete, unconstrained text-storage seam: `read`
- * reads, `write` unconditionally creates-or-overwrites, `edit` unconditionally
- * replaces literal text in the current content. Both mutations take their
- * version guard as an OPTIONAL argument — omit it for the unconstrained
- * bare-provider behavior, supply it to guard against a concurrent change. The
- * mutation runs inside the backend's per-target lock either way, so an
- * unconditional write/edit is still atomic; "unconditional" drops the *version*
- * precondition, not the atomicity. Observed-state, read-before-edit, and
- * version-guarded write/edit are NOT provider behavior — they are policy a
- * plugin (`@deepseek-ai/dsh-fs-policy`) adds on top by supplying the guard.
- *
- * ## The fs policy events live here, not in the policy plugin
- *
- * This package owns the `fs/write-intent`, `fs/edit-intent`, and
- * `fs/observed` event vocabulary (see {@link Events}). The emitter is
- * `@deepseek-ai/dsh-tool-fs` and the default listener is
- * `@deepseek-ai/dsh-fs-policy`; the events live in the one package both
- * already depend on, so the emitter shares a vocabulary with the policy listener
- * without depending on the policy plugin. The events carry only `dsh-fs`
- * vocabulary plus an opaque `object` actor — no model-facing concepts (line
- * windows, numbered lines) and no agent/session owner structure leak down.
- *
+ * Filesystem text-storage provider seam. Backends own stable target identity,
+ * text decoding, binary rejection, and atomic mutations. Read windows and
+ * observed-state policy stay in consumer and policy plugins; `editText` remains
+ * here so version check, literal match, and rewrite share one critical section.
  * @module @deepseek-ai/dsh-fs
  */
 
@@ -92,44 +41,25 @@ declare module 'cordis' {
 
   interface Events {
     /**
-     * Single-slot decision: produce the write intent for the next
-     * {@link FileSystem.writeText}. The tool dispatches this as an unbound
-     * waterfall (no `this`) and supplies a default thunk returning `undefined`
-     * (unconditional create-or-overwrite — the bare provider). The
-     * `@deepseek-ai/dsh-fs-policy` policy listener returns `createIfAbsent`
-     * (unobserved actor) or `{ kind: 'replaceIfVersion', version: vObserved }`
-     * (observed) and does NOT call `next()` — one decision, not a composable
-     * chain. The slot is first-wins: the first non-`next()` decider (registration
-     * order, or `prepend`) occupies it; a second decider is a misconfiguration,
-     * not layering. `actor` is the opaque tool-execution context, never read here.
+     * Single-slot decision for the next {@link FileSystem.writeText}. Calling
+     * `next()` yields the bare provider's unconditional write; the first listener
+     * that returns an intent owns the decision rather than composing with peers.
      * @param target - the resolved target about to be written.
      * @param actor - the opaque tool-execution context the decider keys off.
      * @mode waterfall
      */
     'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
     /**
-     * Single-slot decision: produce the optional version guard for the next
-     * {@link FileSystem.editText}. The tool dispatches this as an unbound
-     * waterfall and supplies a default thunk returning `undefined` (unconditional
-     * edit of the current content — the bare provider; no `stat`). The
-     * `@deepseek-ai/dsh-fs-policy` policy listener returns
-     * `{ version: vObserved }`, or throws `FS_NOT_OBSERVED` if the actor is unset
-     * or has not observed the target. Does NOT call `next()`: one decision,
-     * first-wins (see {@link Events.'fs/write-intent'}).
+     * Single-slot decision for the next {@link FileSystem.editText}. Calling
+     * `next()` yields an unconditional edit; the first returned guard wins.
      * @param target - the resolved target about to be edited.
      * @param actor - the opaque tool-execution context the decider keys off.
      * @mode waterfall
      */
     'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
     /**
-     * Record that an actor observed a target at a version, after a successful
-     * read/write/edit. Fire-and-forget (plain `emit`). A listener MUST be a
-     * synchronous, side-effect-only recorder (`@deepseek-ai/dsh-fs-policy`'s
-     * is a `WeakMap.set`): the tool does not guard the emit, so a listener that
-     * throws surfaces as the tool's `isError` result, and cordis `emit` does not
-     * await listener promises — async or fallible audit/telemetry does not
-     * belong here. No listener ⇒ nothing recorded. `actor` is the opaque
-     * tool-execution context.
+     * Record a successful observation. Listeners must be synchronous recorders:
+     * throws fail the tool call and returned promises are not awaited.
      * @param target - the target that was read/written/edited.
      * @param version - the version the actor now holds as its observation.
      * @param actor - the observing tool-execution context; undefined records nothing useful.
@@ -140,34 +70,10 @@ declare module 'cordis' {
 }
 
 /**
- * Abstract filesystem provider service. Subclass, implement the seven storage
- * primitives, and load the subclass as a plugin — it registers as `ctx.fs` (one
- * implementation per context; loading a second throws, cordis' standard
- * duplicate-service behavior).
- *
- * Semantics every backend must honor:
- * - {@link resolve} returns a stable {@link FsTarget}; the same underlying file
- *   reached by different input paths must yield the same `targetKey` so stale
- *   guards and target lookup agree across paths (e.g. through symlinks).
- * - {@link stat} returns {@link FsInfo} metadata (never content) or `undefined`
- *   when the target is absent.
- * - {@link readText}/{@link streamText} read the whole regular text file (the
- *   stream for large files); both own regular-file checks, UTF-8 decoding,
- *   binary/NUL rejection, and `FS_NOT_TEXT`.
- * - {@link listDir} returns direct children of a directory in stable name order
- *   with resolved child targets and cheap metadata only. It never reads file
- *   contents. Missing targets throw `FS_NOT_FOUND`, non-directories throw
- *   `FS_NOT_DIRECTORY`, permission failures throw `FS_PERMISSION_DENIED`, and
- *   other backend I/O failures throw `FS_IO_ERROR`.
- * - {@link writeText} is atomic temp-file + rename. `expected` is OPTIONAL:
- *   omit it for an unconditional create-or-overwrite (the bare-provider default),
- *   or supply a {@link FsWriteIntent} to guard the write.
- * - {@link editText} verifies `expected.version` BEFORE literal matching (so a
- *   stale edit reports `FS_STALE_VERSION`, not `FS_EDIT_NOT_FOUND`/
- *   `FS_AMBIGUOUS_EDIT` against newer content), then applies literal replacement
- *   and writes atomically — all inside one mutation critical section. `expected`
- *   is OPTIONAL: omit it for an unconditional edit of the current content (a
- *   missing target still reports `FS_STALE_VERSION`).
+ * Abstract filesystem provider. Targets must preserve identity across aliases;
+ * reads expose regular UTF-8 text or typed errors, listings are stable and
+ * content-free, and mutations are atomic. Optional guards add stale protection
+ * without changing the unguarded provider contract.
  */
 export abstract class FileSystem extends Service {
   constructor(ctx: Context) {
@@ -175,18 +81,10 @@ export abstract class FileSystem extends Service {
   }
 
   /**
-   * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May
-   * perform I/O (a remote/sandboxed backend may need a round-trip to map a path
-   * to a stable identity), hence async even though the local backend only
-   * normalizes + realpaths.
+   * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a
+   * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence
+   * async even though the local backend only normalizes + realpaths.
    *
-   * `opts.cwd` is the base directory a RELATIVE `path` resolves against; an
-   * absolute `path` ignores it. Omitted ⇒ the backend's own default base (the
-   * local backend uses its configured `cwd`). The CALLER supplies this — the
-   * seam does not read a session or agent — so a tool can resolve against the
-   * caller's per-session workspace (`exec.agent.session.header.cwd`) without the
-   * provider depending on `dsh-agent`/`dsh-session`. Mirrors how `dsh-tool-bash`
-   * defaults a bash `workdir` to the session cwd.
    * @param path - the path to resolve; relative paths resolve against `opts.cwd`.
    * @param opts - `cwd` overrides the backend's default base for relative paths.
    * @returns the stable target; the same file yields the same `targetKey`.
@@ -230,10 +128,8 @@ export abstract class FileSystem extends Service {
   abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
 
   /**
-   * Create or fully replace a UTF-8 text file atomically. `expected` is the
-   * create-vs-replace decision and stale guard when supplied; OMITTING it is an
-   * unconditional create-or-overwrite (the bare provider — no version guard, no
-   * read-first requirement). Atomic either way.
+   * Atomically create or replace UTF-8 text. `expected` guards intent and
+   * staleness; omission allows unconditional overwrite.
    * @param target - the resolved target to write.
    * @param content - the full new file content.
    * @param expected - the write intent guarding the write; omit for unconditional.
@@ -243,11 +139,9 @@ export abstract class FileSystem extends Service {
   abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>
 
   /**
-   * Apply a literal edit to an existing UTF-8 text file. When `expected` is
-   * supplied, verifies `expected.version` as the stale guard BEFORE literal
-   * matching; OMITTING it edits the current content unconditionally (no version
-   * guard). Either way applies the replacement and writes atomically — one
-   * mutation critical section — and a missing target reports `FS_STALE_VERSION`.
+   * Atomically edit literal text. When supplied, the version guard is checked
+   * before matching so stale content reports `FS_STALE_VERSION`; omission edits
+   * the current content without a freshness precondition.
    * @param target - the resolved target to edit.
    * @param edit - the literal search/replace request.
    * @param expected - the version guard; omit for an unconditional edit.

packages/fs/fs/src/types.ts

@@ -1,21 +1,7 @@
 /**
- * Vocabulary for the filesystem provider seam (`ctx.fs`): the opaque
- * target/version identities, the metadata `stat` returns, the write-intent
- * and outcome shapes, the literal-edit request/outcome, and the typed error
- * taxonomy.
- *
- * These types are shared by every backend (`@deepseek-ai/dsh-fs-local` and
- * future sandboxed/remote backends) and by the policy layer
- * (`@deepseek-ai/dsh-fs-policy`). They are deliberately a *text-storage*
- * vocabulary half a level above byte-level fsspec: `readText`/`streamText` hand
- * back decoded text, never raw bytes. Host-path assumptions stay out — `targetKey`
- * and `version` are opaque branded tokens, and `displayPath` is the only field a
- * consumer may show.
- *
- * Model-facing concepts (line windows, numbered lines, observed-state) do NOT
- * live here; they belong to the consumer tool and the policy plugin
- * (`@deepseek-ai/dsh-tool-fs` / `@deepseek-ai/dsh-fs-policy`).
- *
+ * Vocabulary for the filesystem provider seam (`ctx.fs`): the opaque target/version
+ * identities, the metadata `stat` returns, the write-intent and outcome shapes, the
+ * literal-edit request/outcome, and the typed error taxonomy.
  * @module @deepseek-ai/dsh-fs/types
  */
 
@@ -104,17 +90,10 @@ export interface FsDirEntry {
 }
 
 /**
- * The explicit intent of a guarded {@link FileSystem.writeText} call.
- * `createIfAbsent` creates a missing target and rejects an existing one with
- * `FS_NOT_OBSERVED` (the path the policy plugin uses when the owner has no prior
- * read). `replaceIfVersion` replaces only when the target exists at the observed
- * version; a missing target or a version mismatch throws `FS_STALE_VERSION`.
- *
- * `writeText` takes this OPTIONALLY: omitting `expected` is the third,
- * unconstrained state — an unconditional create-or-overwrite (the bare
- * provider). The union itself carries only the two GUARDED intents; "no guard"
- * is expressed by omission, so the write and edit mutations share one symmetric
- * shape (`expected?`: omit = unconditional, present = guarded).
+ * Guarded write intent. `createIfAbsent` rejects an existing target with
+ * `FS_NOT_OBSERVED`; `replaceIfVersion` rejects absence or mismatch with
+ * `FS_STALE_VERSION`. Omitting the intent from `writeText` means unconditional
+ * create-or-overwrite, not a third union arm.
  */
 export type FsWriteIntent =
   | { kind: 'createIfAbsent' }

packages/fs/tool-fs/src/diff.ts

@@ -1,14 +1,6 @@
 /**
- * Result-time contextual-diff computation for the `write`/`edit` tools. Turns a
- * before/after pair of file texts into one {@link FileDiff} per applied hunk —
- * each hunk's `oldText`/`newText` reconstructed from the unified-diff lines with
- * ±{@link DIFF_CONTEXT} surrounding context lines, matching how claude-agent-acp
- * renders an editor inline diff.
- *
- * This is display-only presentation vocabulary (a UI concern), so it lives in
- * the model-facing tool, NOT the `dsh-fs` storage seam — the backend returns
- * only the raw before/after text (storage facts) and the tool computes the diff.
- *
+ * Result-time contextual diff presentation for write and edit. Storage returns before/after
+ * text; this model-facing layer derives one three-line-context card per applied hunk.
  * @module @deepseek-ai/dsh-tool-fs/src/diff
  */
 
@@ -29,18 +21,12 @@ export const DIFF_CONTEXT = 3
 export type FsDiffMeta = { diffs: FileDiff[] }
 
 /**
- * Compute one {@link FileDiff} per hunk between `before` and `after`, each
- * carrying the applied change plus {@link DIFF_CONTEXT} context lines. Returns an
- * empty array when the texts are identical (no hunks). For a scattered
- * `replace_all` edit the patch yields multiple hunks, so multiple `FileDiff`s
- * come back — matching the editor rendering one diff block per site.
+ * Compute one {@link FileDiff} per hunk between `before` and `after`, each carrying the
+ * applied change plus {@link DIFF_CONTEXT} context lines. Pure insertions use `oldText: null`,
+ * patch-only no-newline markers are omitted, and scattered replacements remain separate hunks.
  *
- * Each hunk's `oldText` is its `-` (removed) and context lines joined by `\n`;
- * `newText` is its `+` (added) and context lines. A hunk with no old lines
- * (a pure insertion) reports `oldText: null` (nothing to diff against), mirroring
- * the call-time card's new-file convention. The unified-diff "\ No newline at end
- * of file" markers are dropped — they annotate the patch, not file content.
- * @param path - the path stamped on every produced diff (the model-facing `file_path`; the bridge relativizes it).
+ * @param path - the path stamped on every produced diff (the model-facing `file_path`; the
+ *   bridge relativizes it).
  * @param before - the file text before the change (the backend's LF-normalized diff basis).
  * @param after - the file text after the change, on the same basis.
  * @returns one diff per applied hunk, in file order; empty when the texts are identical.
@@ -81,14 +67,10 @@ function isFileDiff(value: unknown): value is FileDiff {
 }
 
 /**
- * Narrow an opaque `tool/result` `meta` back to this tool's {@link FileDiff}
- * hunks, or `undefined` when it is absent/malformed. `presentResult` runs on
- * arbitrary logged `meta` (possibly from an older shape or a hand-edited log), so
- * it validates defensively rather than trusting the payload — a bad `meta` yields
- * `undefined`, and the caller decides the fallback (edit → the generic result
- * rendering; write → an args-derived whole-file diff), never a thrown presenter.
- * @param meta - the opaque `tool/result` meta payload (live or replayed from the session log).
- * @returns the validated non-empty hunk list, or undefined for an absent/empty/malformed payload.
+ * Narrow opaque live or replayed result metadata to non-empty file diffs. Malformed metadata
+ * returns `undefined` so presentation can fall back instead of throwing during replay.
+ * @param meta - result metadata.
+ * @returns validated hunks, or `undefined` for absent or malformed data.
  */
 export function diffsFromMeta(meta: unknown): FileDiff[] | undefined {
   if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) return undefined

packages/fs/tool-fs/src/edit.ts

@@ -1,14 +1,7 @@
 /**
- * The model-facing `edit` tool: update an existing UTF-8 text file by replacing
- * literal text, requiring a unique match by default. The tool is the executor:
- * it dispatches the `fs/edit-intent` waterfall to obtain the optional
- * version guard, calls `ctx.fs.editText` directly, and emits `fs/observed`. The
- * default thunk returns `undefined` (unconditional edit of the current content
- * — the bare provider); a policy plugin (`@deepseek-ai/dsh-fs-policy`)
- * occupies the single decision slot, returning `{ version: vObserved }` or
- * throwing `FS_NOT_OBSERVED` for an unread file. The tool stats ZERO times
- * either way; a missing target is reported by the provider as `FS_STALE_VERSION`.
- *
+ * Model-facing literal edit, unique-match by default. It obtains an optional guard from the
+ * single intent slot, calls `ctx.fs.editText` without a separate stat, then records the observed
+ * version; no policy means an unconditional atomic edit.
  * @module @deepseek-ai/dsh-tool-fs/src/edit
  */
 
@@ -96,22 +89,16 @@ export function applyEditTool(ctx: Context): void {
       )
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)
-      // The result-time applied-hunk diff (before→after with context lines). An
-      // edit always changes content (parseEditArgs requires old_string to differ
-      // and editText matches at least once), so there is always at least one hunk.
-      // The bridge renders these as an inline diff that supersedes the call-time
-      // snippet; the display path is the model-facing `file_path` (the bridge
-      // relativizes it).
+      // An edit necessarily changes content, so result metadata carries at least one applied hunk.
       const diffs = computeHunkDiffs(input.filePath, outcome.before, outcome.after)
       return {
         content: [{ type: 'text', text: formatEditOutput(target.displayPath, input.replaceAll) }],
         meta: { diffs },
       }
     },
-    // Pure display: a diff card of the literal replacement (old_string →
-    // new_string), derived from the call args. `oldText: old_string || null`
-    // matches claude-agent-acp's Edit arm; new_string is a required arg here, so
-    // it maps straight to newText. A follow-along location points at the file.
+    // Pure display: a diff card of the literal replacement (old_string → new_string), derived
+    // from the call args. `oldText: old_string || null` matches claude-agent-acp's Edit arm;
+    // new_string is a required arg here, so it maps straight to newText.
     presentCall(args): DiffCallView {
       return {
         card: 'diff',
@@ -120,10 +107,8 @@ export function applyEditTool(ctx: Context): void {
         locations: [{ path: args.file_path }],
       }
     },
-    // Result-time display: the applied contextual-diff hunks carried on `meta`.
-    // On success with diffs, a `diff` result card supersedes the call-time
-    // snippet; on error (nothing applied) or malformed meta, fall through to the
-    // generic "updated successfully" rendering.
+    // Applied metadata replaces the call-time snippet; errors or malformed replay metadata use
+    // the generic result rendering.
     presentResult(args, result: ToolResult): DiffResultView | undefined {
       if (result.isError) return undefined
       const diffs = diffsFromMeta(result.meta)

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

@@ -1,24 +1,7 @@
 /**
- * The model-facing filesystem tool suite (`read`, `write`, `edit`) over the
- * `ctx.fs` provider seam. This single plugin registers all three tools.
- *
- * ## The tool is the executor; policy is an event gate
- *
- * The tool reads/writes/edits through `ctx.fs` DIRECTLY and owns model-facing
- * concerns only — tool names, JSON schemas, argument validation, prompt
- * sections, read windowing, result formatting. It does NOT inject a policy
- * service. Instead, on each write/edit it dispatches a single-slot waterfall
- * (`fs/write-intent`/`fs/edit-intent`) to obtain the OPTIONAL version guard, and
- * after every read/write/edit it emits `fs/observed` with a plain (unguarded)
- * `ctx.emit`. A policy plugin (`@deepseek-ai/dsh-fs-policy`) occupies the
- * decision slot and listens for `fs/observed` to add observed-state +
- * read-before-edit + version-guarded write/edit; a deployment that loads these
- * tools is expected to also load it. With no policy plugin the waterfalls fall
- * through to their `undefined` default (the unconstrained bare provider) and
- * `fs/observed` is unheard — the tool still functions. This package never
- * imports `node:fs`, `node:path`, or an `@deepseek-ai/dsh-fs-local`
- * implementation.
- *
+ * Model-facing read, write, and edit tools over `ctx.fs`. This package owns schemas, validation,
+ * read windows, formatting, and observation events, never a concrete provider. An optional
+ * event policy supplies mutation guards; without one the tools use unconditional provider calls.
  * @module @deepseek-ai/dsh-tool-fs
  */
 

packages/fs/tool-fs/src/read-render.ts

@@ -1,18 +1,7 @@
 /**
- * Cordis-free read rendering for `@deepseek-ai/dsh-tool-fs`: turn a file's
- * decoded text into a bounded, line-numbered window (offset/limit, byte cap,
- * per-line truncation) and format it as the model-facing text block. This is
- * the `read` tool's RENDERING detail — not a storage primitive, not freshness
- * policy — so it lives apart from the tool's I/O and event wiring as a pure,
- * independently-testable module (no cordis, no filesystem).
- *
- * The provider (`ctx.fs.readText`/`streamText`) hands back already-decoded text
- * (UTF-8 validated, binary rejected); {@link buildWindow} only scans that text
- * for newlines and builds the requested window. A capped line buffer means a
- * newline-free giant line can never balloon memory even when streamed.
- * {@link formatReadOutput} turns the resulting {@link FileReadOutcome} into the
- * `<path>/<content>` envelope the model sees.
- *
+ * Pure read presentation: turn provider-decoded text into a bounded, line-numbered window and
+ * model-facing envelope. Chunk scanning caps the current line, so even one newline-free giant
+ * line cannot grow memory without bound.
  * @module @deepseek-ai/dsh-tool-fs/read-render
  */
 
@@ -113,12 +102,8 @@ function finish(acc: WindowAccumulator, request: ReadWindow, displayPath: string
 }
 
 /**
- * Build a bounded, line-numbered window from a file's decoded text chunks.
- * Accepts an `AsyncIterable<string>` (a chunked `streamText`) or an
- * `Iterable<string>` (a whole-file `readText` wrapped as `[text]`), so one code
- * path serves both. Scans for newlines with a capped line buffer (a newline-free
- * giant line is truncated, never buffered past `request.maxLineLength`),
- * enforces the byte cap, and throws `FS_NOT_FOUND` for an offset past EOF.
+ * Build one window from streamed or whole-file chunks, enforcing line and byte caps and throwing
+ * `FS_NOT_FOUND` when the requested offset is past EOF.
  * @param chunks - decoded text chunks in file order; chunk boundaries carry no meaning.
  * @param request - the resolved window; the caller has already applied its defaults and caps.
  * @param displayPath - the caller-facing path used in the offset-out-of-range error.

packages/fs/tool-fs/src/read.ts

@@ -1,14 +1,6 @@
 /**
- * The model-facing `read` tool: inspect a UTF-8 text file and return
- * line-numbered content with pagination guidance. The tool is the executor — it
- * stats and reads through `ctx.fs` directly, builds the line window
- * ({@link module:@deepseek-ai/dsh-tool-fs/read-render}), and emits `fs/observed`
- * so a policy plugin (`@deepseek-ai/dsh-fs-policy`) can record the read. With
- * no policy plugin the emit is simply unheard. This module owns the
- * model-facing schema, argument validation, and the read I/O; the rendering
- * (windowing + formatting) lives in `read-render.ts` and the
- * freshness/observation policy is not its concern.
- *
+ * Model-facing UTF-8 read. It performs one provider stat for type, routing, and observed version,
+ * streams large or size-unknown files, renders a bounded window, then emits the observation.
  * @module @deepseek-ai/dsh-tool-fs/src/read
  */
 
@@ -98,9 +90,7 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
       const target = await ctx.fs.resolve(input.filePath, cwd !== undefined ? { cwd } : undefined)
 
       // One stat: type check + size routing + the version recorded as observed.
-      // A writer racing between this stat and the read can at worst make a LATER
-      // guarded edit spuriously FS_STALE_VERSION (fail-closed: re-read; editText
-      // re-checks the version in its lock).
+      // A concurrent write can only make a later guarded mutation fail stale and require reread.
       const info = await ctx.fs.stat(target, exec.signal)
       if (!info) throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
       if (info.type !== 'file') throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
@@ -128,12 +118,10 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
       ctx.emit('fs/observed', target, info.version, exec)
       return [{ type: 'text', text: formatReadOutput(target.displayPath, outcome) }]
     },
-    // Pure display: a generic card titled by the file with the read window
-    // appended (`Read foo.txt (5 - 8)`), `read` kind (icon), and a follow-along
-    // location whose line is the read's offset (defaulting to 1). The window is
-    // derived from the RAW args (offset/limit as the model passed them), NOT the
-    // tool's defaulted 1/configured limit, so an unbounded read shows a bare
-    // title (and the presenter stays a pure function of args, config-free).
+    // Pure display: a generic card titled by the file with the read window appended (`Read
+    // foo.txt (5 - 8)`), `read` kind (icon), and a follow-along location whose line is the
+    // read's offset (defaulting to 1). The window reflects raw args, so an omitted limit keeps
+    // the title bare instead of smuggling config into this pure presenter.
     presentCall(args): GenericCallView {
       const { offset, limit } = args
       const window = limit !== undefined && limit > 0

packages/fs/tool-fs/src/session-cwd.ts

@@ -1,18 +1,10 @@
 /**
- * Derive the working directory a filesystem tool resolves relative paths
- * against: the calling agent's per-session workspace
- * (`exec.agent.session.header.cwd`), so each ACP session's `read`/`write`/`edit`
- * act on ITS workspace, not the server's launch dir — mirroring how
+ * Derive the working directory a filesystem tool resolves relative paths against: the calling
+ * agent's per-session workspace (`exec.agent.session.header.cwd`), so each ACP session's
+ * `read`/`write`/`edit` act on ITS workspace, not the server's launch dir — mirroring how
  * `dsh-tool-bash` defaults a bash `workdir` to the session cwd.
- *
- * The `agent` is optional-chained — a non-agent caller yields `undefined`, and
- * the tool then calls `ctx.fs.resolve(path)` with no base so the backend applies
- * its own configured default (preserving the non-ACP / no-session behavior).
- * `session`/`header` are non-optional on a real `Agent`, so only `agent` needs
- * the guard (mirroring `dsh-tool-bash`'s `resolveWorkdir`). Returning `undefined`
- * rather than reading `process.cwd()` here keeps the default in ONE place (the
- * provider), per the "explicit > implicit at seams" convention.
- *
+ * Non-agent calls return `undefined`, leaving the fallback in the provider rather than reading
+ * `process.cwd()` at the tool seam.
  * @module @deepseek-ai/dsh-tool-fs/session-cwd
  */
 

packages/fs/tool-fs/src/write.ts

@@ -1,13 +1,7 @@
 /**
- * The model-facing `write` tool: create or fully replace a UTF-8 text file. The
- * tool is the executor: it dispatches the `fs/write-intent` waterfall to
- * obtain the optional version guard, calls `ctx.fs.writeText` directly, and
- * emits `fs/observed`. The default thunk returns `undefined` (unconditional
- * create-or-overwrite — the bare provider); a policy plugin
- * (`@deepseek-ai/dsh-fs-policy`) occupies the single decision slot and
- * returns `createIfAbsent`/`replaceIfVersion` instead. The tool stats ZERO
- * times either way.
- *
+ * Model-facing full-file write. It obtains an optional intent from the single policy slot, calls
+ * `ctx.fs.writeText` without a stat, then records the resulting version; no policy means an
+ * unconditional atomic create-or-overwrite.
  * @module @deepseek-ai/dsh-tool-fs/src/write
  */
 
@@ -75,20 +69,17 @@ export function applyWriteTool(ctx: Context): void {
       const outcome = await ctx.fs.writeText(target, input.content, intent, exec.signal)
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)
-      // Attach a contextual hunk as `meta` ONLY for an overwrite (a before-version
-      // exists). A create has no "before" — `outcome.before` is null — so it
-      // carries no `meta`; `presentResult` then renders a whole-file diff from the
-      // args, so the completed card is still a diff (never the result text).
+      // Overwrites carry applied hunks. Creates have no prior text, so result presentation uses
+      // the args-derived whole-file diff instead.
       const diffs = outcome.before !== null ? computeHunkDiffs(input.filePath, outcome.before, outcome.after) : []
       return {
         content: [{ type: 'text', text: formatWriteOutput(target.displayPath, outcome) }],
         ...diffs.length > 0 ? { meta: { diffs } } : {},
       }
     },
-    // Pure display: a diff card (an editor renders write as a new-file / full-
-    // replace diff). `oldText: null` — a call-time presenter has no access to the
-    // file's prior content, so even an overwrite renders new-file style, matching
-    // claude-agent-acp. A follow-along location points at the written file.
+    // Pure display: a diff card (an editor renders write as a new-file / full- replace diff).
+    // `oldText: null` — a call-time presenter has no access to the file's prior content, so
+    // even an overwrite renders new-file style, matching claude-agent-acp.
     presentCall(args): DiffCallView {
       return {
         card: 'diff',
@@ -97,14 +88,10 @@ export function applyWriteTool(ctx: Context): void {
         locations: [{ path: args.file_path }],
       }
     },
-    // Result-time display: a `diff` card so the completed `tool_call_update`
-    // re-installs the diff rather than the model-facing result text (an ACP
-    // `tool_call_update.content` REPLACES the call's content, so a text result
-    // would clobber the pending diff card). An OVERWRITE uses the applied
-    // contextual hunks on `meta`; a CREATE has no `meta` (no prior content), so
-    // its whole-file new-file diff is derived from `args.content` (replay-safe,
-    // matching the call-time card). An error falls through to generic rendering
-    // so its message shows.
+    // Result-time display: a `diff` card so the completed `tool_call_update` re-installs the
+    // diff rather than the model-facing result text (an ACP `tool_call_update.content` REPLACES
+    // the call's content, so a text result would clobber the pending diff card). Overwrites use
+    // applied metadata; creates and identical overwrites use the replay-safe args fallback.
     presentResult(args, result: ToolResult): DiffResultView | undefined {
       if (result.isError) return undefined
       const diffs = diffsFromMeta(result.meta)

packages/fs/tool-fs/tests/harness.ts

@@ -11,15 +11,9 @@ import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 
 /**
- * Shared harness for the fs-tools with-key e2e: a minimal real agent stack (the
- * DeepSeek adapter + the real fs provider + the read-before-write/edit policy +
- * the model-facing read/write/edit tools). Lives outside the *.e2e.ts pattern so
- * importing it never re-registers another file's tests.
- *
- * `fsCwd` is the local backend's default base; a per-session cwd (set via a
- * session header) overrides it, but this harness creates agents without a
- * session cwd, so the provider default IS the workspace. `persona` is the
- * deployment persona (the system-prompt plugin's per-context config).
+ * Build the real fs-tool stack for with-key e2e tests. Agents have no session
+ * cwd, so `fsCwd` is their workspace; `persona` configures the deployment prompt.
+ * This helper lives outside the e2e glob so imports do not register tests.
  */
 export async function fsHarness(fsCwd: string, persona = ''): Promise<Context> {
   const ctx = new Context()

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

@@ -1,16 +1,8 @@
 /**
- * Integration tests: the real local backend (`dsh-fs-local`) plus the model
- * tools (`dsh-tool-fs`) as the executor, exercised through `ctx.tools.execute()`
- * so nothing bypasses the tool registry. Two deployments:
- *
- *  - DEFAULT — with the real `dsh-fs-policy` policy gate plugin: read-before-
- *    write/edit, version-guarded mutation, FS_NOT_OBSERVED for unread edits.
- *  - BARE — WITHOUT the policy plugin: every `fs/*` waterfall falls through to
- *    its undefined default, so write/edit are unconditional. This proves the
- *    tool carries no dependency on the policy plugin.
- *
- * These verify the WORLD — files are read back from disk and asserted
- * byte-for-byte — not the tool's self-report.
+ * End-to-end tool-registry tests against the real local backend. The policy deployment verifies
+ * observed-state and guarded mutation; the bare deployment proves unconditional tools have no
+ * policy-service dependency. Assertions read files back byte-for-byte rather than trusting tool
+ * messages.
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
@@ -28,9 +20,7 @@ import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 let dir: string
 let ctx: Context
 let fiber: Awaited<ReturnType<Context['plugin']>>
-// A stable session object stands in for an agent session (the file-state
-// owner). It carries a `header` (no `cwd`) so `sessionCwd(exec)` resolves to
-// `undefined` and the backend falls back to its configured cwd (= `dir`).
+// No header cwd: sessionCwd returns undefined and the provider's configured test dir applies.
 const session = { header: {} }
 
 let callCounter = 0
@@ -290,13 +280,9 @@ describe('bare provider (no dsh-fs-policy)', () => {
   })
 })
 
-// --------------------------------------------------------------------------
-// Per-session cwd: a relative file_path resolves against the CALLING session's
-// workspace (`exec.agent.session.header.cwd`), NOT the backend's config.cwd —
-// so an ACP editor's per-session dir wins, matching dsh-tool-bash. The regression
-// this guards: before the seam fix the tool passed no cwd, so a relative write
-// landed in config.cwd instead of the session dir.
-// --------------------------------------------------------------------------
+// Per-session cwd: a relative file_path resolves against the calling session's workspace
+// (`exec.agent.session.header.cwd`), not the backend's config.cwd — so an ACP editor's
+// per-session dir wins, matching dsh-tool-bash.
 describe('per-session cwd', () => {
   let sessionDir: string
   beforeEach(async () => {
@@ -399,9 +385,8 @@ describe('signal, concurrency, and the fs/observed contract', () => {
   })
 
   it('a throwing fs/observed listener surfaces as isError, but the mutation already hit disk', async () => {
-    // fs/observed is a plain ctx.emit AFTER the write succeeded; a throwing
-    // listener cannot roll the write back — it only turns the tool result into
-    // isError. The file must still carry the written bytes.
+    // fs/observed is a plain ctx.emit after the write succeeded; a throwing listener cannot
+    // roll the write back — it only turns the tool result into isError.
     ctx.on('fs/observed', () => { throw new Error('recording bug') })
     const result = await callOwned('write', { file_path: 'w.txt', content: 'durable' })
     expect(result.isError).toBe(true)