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

# Conflicts:
#	docs/config-catalog.md
#	examples/acp-agent/tests/snapshots/text-turn/session.jsonl
#	pnpm-lock.yaml

.agents/skills/dsh-pre-push-checks/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: dsh-pre-push-checks
+description: Use before pushing, force-pushing, marking ready for review, claiming checks pass, or bypassing a local hook on a deepseek-harness branch, especially after merges, review fixes, package graph changes, docs/catalog updates, snapshots, e2e behavior, or built artifact changes.
+---
+
+# DSH Pre-Push Checks
+
+Use this skill to choose and run the smallest sufficient verification set before a `deepseek-harness` push. Do not treat the local pre-push hook as the full CI contract: CI also runs coverage, build, demo smoke, and built-bin smoke.
+
+## First Steps
+
+1. Confirm the checkout and branch.
+
+```sh
+git status --short --branch
+git rev-parse --show-toplevel
+```
+
+2. Inspect the outgoing diff.
+
+```sh
+git diff --stat
+git diff --name-only origin/$(git branch --show-current)...HEAD
+```
+
+If the branch has no upstream or the command is not meaningful for the stack shape, use `git diff --name-only origin/master...HEAD` or the PR base branch.
+
+3. If the branch was just merged with `master`, or the user says master changed, run the gates after resolving the merge and before pushing or marking ready. Do not present a conflict-resolution commit as ready with only typecheck/lint evidence.
+
+## Required Baseline
+
+Run these before every non-trivial push:
+
+```sh
+pnpm run typecheck
+pnpm run lint
+pnpm run test:coverage
+```
+
+Why `test:coverage`, not only `test`: CI enforces per-file 100% coverage. A branch can pass `pnpm run test` and still fail CI.
+
+## Add Gates By Touched Surface
+
+Run `pnpm run doc-sync` and `pnpm run verify-module-graph` when the diff touches Markdown docs, package manifests, package imports/exports, generated catalogs, RFCs, architecture docs, translation pairs, Mermaid diagrams, or comments that cite docs/packages.
+
+Run `pnpm run build` and `pnpm run hygiene` when the diff touches any package `package.json`, dependency graph, public exports, build config, declaration surface, bundled runtime path, or code that will be consumed from built `lib/`.
+
+Run snapshot tests when the diff changes ACP/editor-facing transcript behavior: ACP bridge updates, agent-loop observable output, tool call/result presentation, session log rendering, stdout/stderr protocol output, or snapshot fixtures.
+
+```sh
+pnpm run test:snapshot
+```
+
+Run built-bin smoke tests after `pnpm run build` when app packages, app boot, package runtime imports, bin entries, loader behavior, or published artifact paths change.
+
+```sh
+pnpm exec vitest run --config vitest.e2e.config.ts packages/ui/stdio-agent/tests/built-bin.e2e.ts packages/ui/acp-agent/tests/built-bin.e2e.ts
+```
+
+Run real e2e when behavior depends on a real model/API, tool-use loop, ACP integration, prompt injection, or end-to-end agent UX. If `.env` is available, use it; do not print secrets.
+
+```sh
+pnpm run test:e2e
+```
+
+Run a targeted test first for the changed package, but never use targeted tests as the only push evidence unless the change is test-only and cannot affect shared behavior.
+
+## Full Local CI Approximation
+
+Use this before high-risk pushes, after large merges, before asking for review on a major PR, or when prior pushes have caused CI churn. The authoritative command list is the root [AGENTS.md § Run the CI gates locally before marking a PR ready](../../../AGENTS.md#run-the-ci-gates-locally-before-marking-a-pr-ready); run that block rather than copying a local variant into this skill. Add `pnpm run test:e2e` when a key is available and the feature has real-agent behavior.
+
+## Handling Failures
+
+If a gate fails, stop and fix or explain the blocker. Do not push and hope CI differs.
+
+If a failure looks environment-specific, prove it:
+
+- Record the exact command, failing test, and platform-specific mismatch.
+- Confirm the relevant non-platform gates pass.
+- Prefer fixing the test for cross-platform determinism if the test is part of the required local gate.
+- Bypass a local hook only when the user explicitly asks to push or agrees, and state exactly which hook failed and why it is not expected to fail on CI.
+
+Known pattern to watch for: Linux CI and macOS local behavior can differ for shell utilities such as `sed -i`. Treat this as evidence to investigate, not as automatic permission to bypass.
+
+## Push Procedure
+
+1. Local commits may happen before the full gate set, but do not push, mark ready, or claim checks pass until the relevant gates pass or any blocker is explicitly documented.
+2. Let the normal pre-commit hook run. If it changes files, inspect and commit or amend the change intentionally rather than hiding it.
+3. Push normally first so the pre-push hook can run.
+4. If a local hook is bypassed after user approval, use the narrow bypass and say so in the final response.
+5. After push, verify the remote ref matches local HEAD.
+
+```sh
+git rev-parse HEAD origin/$(git branch --show-current)
+```
+
+For GitHub PRs, check CI after push:
+
+```sh
+gh pr checks
+```
+
+If checks are pending, say pending. If checks fail, inspect logs before claiming the push is good.

.agents/skills/dsh-pre-push-checks/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "DSH Pre-Push Checks"
+  short_description: "Run the right DeepSeek Harness gates before push"
+  default_prompt: "Use $dsh-pre-push-checks before pushing this DeepSeek Harness branch."

.github/workflows/ci.yml

@@ -95,13 +95,13 @@ jobs:
 
   node-compat:
     runs-on: ubuntu-latest
-    name: node 26
+    name: node ${{ matrix.node }}
     env:
       DSH_GATE_CONCURRENCY: '2'
     strategy:
       fail-fast: false
       matrix:
-        node: [26]
+        node: ['22.19', 24, 26]
     steps:
       - uses: actions/checkout@v6
 

.github/workflows/e2e.yml

@@ -49,6 +49,7 @@ permissions:
 jobs:
   e2e:
     runs-on: ubuntu-latest
+    name: e2e
     # Run on every trusted event. Skip untrusted PRs (forks + Dependabot) where
     # the secret is withheld — they would otherwise hard-fail the preflight.
     if: >-

AGENTS.md

@@ -34,7 +34,7 @@ Per-package map: the group READMEs, indexed from [packages/README.md](packages/R
 ## Commands
 
 ```sh
-pnpm install            # pnpm workspaces, node >= 24
+pnpm install            # pnpm workspaces, node ^22.19 || >=24
 pnpm run test           # vitest unit tests
 pnpm run test:coverage  # THE gating test run: per-file 100% coverage on packages/*/*/src
 pnpm run test:e2e       # real-API tests; self-skip without DEEPSEEK_API_KEY
@@ -83,21 +83,22 @@ Real-API tests and demos read `DEEPSEEK_API_KEY` (and optional `DEEPSEEK_BASE_UR
 - Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package.
 - ESM everywhere (`"type": "module"`). Cross-package imports use package names, never relative paths; in-package relative imports use explicit `.ts` extensions. Dev/test/demo run unbuilt via tsx + the root tsconfig `paths` map; builds are for outside consumers only.
 - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
-- **Typed events via declaration merging**; extensible unions use the merge-extensible-map pattern (`ContentBlockMap`, `SessionEventMap`, …). Every new event's JSDoc carries an `@mode` tag and a `@param` per payload parameter (`this`/trailing `next` exempt); every public service-class method documents each parameter and non-void return (`@param`/`@returns`) — the catalog generator hard-errors otherwise ([completeness RFC](docs/rfc/implemented/process/2026-07-04-cordis-jsdoc-completeness-gate.md)); mode semantics are in the [generated events catalog](docs/cordis-catalog/events.md) header ([catalog RFC](docs/rfc/implemented/process/2026-06-20-generated-cordis-catalog.md)).
+- **Typed events via declaration merging**; extensible unions use the merge-extensible-map pattern (`ContentBlockMap`, `SessionEventMap`, …). Every new event's JSDoc carries an `@mode` tag and a `@param` per payload parameter (`this`/trailing `next` exempt); every public service-class method documents each parameter and non-void return (`@param`/`@returns`) — the catalog generator hard-errors otherwise; mode semantics are in the [generated events catalog](docs/cordis-catalog/events.md) header.
 - **Discriminated unions: `switch` on the tag**, not if-chains. Closed unions end with `default: assertNever(...)`; merge-extensible unions must NOT — handle known cases and fall through `default` with a comment.
 - **Waterfall listeners MUST call `next()`** to delegate; returning without it is the veto ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
-- **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event ([reconstructability RFC](docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)).
+- **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
 - **Plugins, not loop changes**: new behavior goes on the documented extension seams; changing `agent-loop` requires updating docs/architecture.md.
-- **Capability seams are three packages** — interface / implementation / consumer ([capability seams](docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)); don't split preemptively.
+- **Capability seams are three packages** — interface / implementation / consumer; don't split preemptively.
 - **Explicit > implicit at package seams**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()` (the `dsh-bash` request/spec split is the template).
 - **No hardcoded tunables in plugins**: anything two deployments could want different — timeouts, caps, model names, base URLs — is a defaulted, validated `Config` field, not a literal; a `DEFAULT_*` constant or test-only seam is not configurability. The test: changeable from `cordis.yml`, no code edit. Protocol/wire constants, external-spec values, security invariants stay hardcoded.
-- **Opaque cross-boundary ids are branded** (`Branded<B>` from `dsh-brand`), never bare `string` ([branded IDs](docs/rfc/implemented/architecture/2026-06-20-branded-ids.md)).
+- **Misconfiguration fails loud**: a config value referencing something that does not exist (a `toolOrder` tool name, a plugin path) throws — at load when the check is self-contained, else at the earliest moment the referent exists (for `toolOrder`, every prompt assembly) — never a silent skip.
+- **Opaque cross-boundary ids are branded** (`Branded<B>` from `dsh-brand`), never bare `string`.
 - **An empty `catch` names what it swallows** and why nothing else can reach it; keep the `try` to one statement.
 - **Symmetry is usually more correct**: parallel values get parallel form; asymmetry smells of a missed extraction.
-- **Tests document behavior, not golden truth**: a green test pins what the code DOES, not what it SHOULD do. Before preserving a behavior solely for its test, ask whether it is load-bearing; an artifact changes together with its test, with the why in the PR ([worked example](docs/rfc/implemented/simplification/2026-06-19-drop-mutable-session-summary.md)).
-- **RFCs are proposals, not golden truth**: validate its premise against current code before implementing; friction is evidence of over-reach — amend on the way to `implemented/` ([worked example](docs/rfc/implemented/simplification/2026-06-20-public-agent-stop-surface.md)).
+- **Tests document behavior, not golden truth**: a green test pins what the code DOES, not what it SHOULD do. Before preserving a behavior solely for its test, ask whether it is load-bearing; an artifact changes together with its test, with the why in the PR.
+- **RFCs are proposals, not golden truth**: validate its premise against current code before implementing; friction is evidence of over-reach — amend on the way to `implemented/`.
 - **Testing policy** — [docs/testing.md](docs/testing.md). Transcript/UX changes need snapshots or a PR note. Snapshot fixtures must replay on macOS/Linux; avoid GNU/BSD-only commands (e.g. `sed -i`); fix fixtures, not normalizers.
-- **A tool's ACP render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([render-intent RFC](docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md), [cookbook](docs/cookbook/adding-a-tool.md)).
+- **A tool's ACP render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **A new capability seam, lifecycle shape, or transcript surface names its coverage at every tier (unit, e2e, snapshot) at plan time** and verifies the harness can express it — a gap is scheduled work, not a mid-build surprise.
 - **Merge PRs with merge commits** (`gh pr merge --merge`), never squash/rebase. **Never rewrite a pushed branch**; update a child by merging its parent down. **A review fix lands on the PR that introduced the issue, as a separate commit**, then merges down ([stacked-review guide](docs/cookbook/responding-to-pr-review-on-a-stack.md)).
 - TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
@@ -109,13 +110,13 @@ Real-API tests and demos read `DEEPSEEK_API_KEY` (and optional `DEEPSEEK_BASE_UR
 
 ## Type safety and documentation
 
-Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` carries a comment saying why a narrower type is infeasible. Every module has a module-level doc comment; every export (and non-obvious method) has a JSDoc explaining semantics — contracts, disposal, errors — not the name restated; internal helpers only where non-obvious; one-liners when one line suffices. Lean toward the stricter lint rule and the extra mechanical gate: encode invariants in checks (`verify-*` scripts), preferring a narrow justified escape hatch over a rule left off globally. Type gymnastics are acceptable inside core packages when they buy plugin-author DX (the `defineTool` schema DSL is the canonical example).
+Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` carries a comment saying why a narrower type is infeasible. Every module has a module-level doc comment; every export (and non-obvious method) has a JSDoc explaining semantics — contracts, disposal, errors — not the name restated; internal helpers only where non-obvious; one-liners when one line suffices. The export half is mechanical: `verify-export-jsdoc` (in `doc-sync`) requires description prose on every package export plus `@param`/`@returns` (and an annotated return) on function-like ones. Heritage-declared members, plugin-protocol slots, and constructors are exempt — their docs' one home is the seam declaration, the framework protocol, and the class doc respectively. Lean toward the stricter lint rule and the extra mechanical gate: encode invariants in checks (`verify-*` scripts), preferring a narrow justified escape hatch over a rule left off globally. Type gymnastics are acceptable inside core packages when they buy plugin-author DX (the `defineTool` schema DSL is the canonical example).
 
 Docs are part of every change: code changes update their README and JSDoc in the SAME change; a bilingual-pair edit updates the counterpart and re-records ([i18n contract](docs/i18n/README.md)). The writing rules — document the current state never the history, one physical line per paragraph, one home per fact — and the word-budget gate live in [docs/AGENTS.md](docs/AGENTS.md).
 
 ## Editing these instructions
 
-`AGENTS.md` is the real file; `CLAUDE.md` is a symlink to it (root, `packages/`, `examples/`). Edit `AGENTS.md`, never the symlink. This file is budget-gated (`verify-doc-budgets`): condense first if it is possible without sacrificing clarity; truly needed additions may justify a ceiling raise.
+`AGENTS.md` is the real file; `CLAUDE.md` is a symlink to it (root, `packages/`, `examples/`). Edit `AGENTS.md`, never the symlink. Keep it self-contained: state each principle inline instead of citing RFCs (they stay discoverable via the RFC index); linking high-level docs — architecture, testing, cookbooks — is fine. This file is budget-gated (`verify-doc-budgets`): condense first if it is possible without sacrificing clarity; truly needed additions may justify a ceiling raise.
 
 ## Vendoring policy
 

docs/AGENTS.md

@@ -16,7 +16,7 @@ Every fact has exactly one home — the tier whose job it is — and every other
 | [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
 | [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the RFC each guide links) |
 | Package README | The per-package contract: config, semantics, limitations, extension points | JSDoc restatement, generated-catalog restatement (event/tool tables), other packages' concerns |
-| [development.md](development.md) | Human-facing setup and daily workflow; a bilingual pair under the [i18n contract](i18n/README.md) | Gate-by-gate enumerations that drift from `package.json` scripts |
+| [development.md](development.md) | First-stop contributor onboarding: local setup, daily workflow, and CI shape at summary level; a bilingual pair under the [i18n contract](i18n/README.md) | Runtime/version rationale (→ RFCs), gate-by-gate enumerations that drift from `package.json` scripts |
 | Generated catalogs: [cordis events](cordis-catalog/events.md), [cordis services](cordis-catalog/services.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive enumerations regenerated from source, freshness-gated | Hand edits of any kind |
 | Skills (`.agents/skills/`) | Workflows: how to carry out a recurring task against the contracts | The contracts themselves (→ docs) |
 

docs/config-catalog.md

@@ -40,7 +40,8 @@ Source: [`packages/ui/acp/src/index.ts:236`](../packages/ui/acp/src/index.ts)
  * App config: the swappable per-deployment values. `model` configures the
  * agent template the ACP bridge creates each session's agent from (NOT a
  * pre-created agent — ACP creates agents at `session/new`); `persona` is the
- * deployment persona (forwarded to the system-prompt plugin);
+ * deployment persona (forwarded to the system-prompt plugin); `toolOrder` is
+ * the explicit model-facing tool order (forwarded to the system-prompt plugin);
  * `persistenceRoot` is the JSONL backend's directory.
  */
 export interface Config {
@@ -48,12 +49,14 @@ export interface Config {
   model: string
   /** Deployment persona (the system-prompt plugin's `persona` config). */
   persona?: string
+  /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */
+  toolOrder?: string[]
   /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
   persistenceRoot?: string
 }
 ```
 
-Source: [`packages/ui/acp-agent/src/index.ts:50`](../packages/ui/acp-agent/src/index.ts)
+Source: [`packages/ui/acp-agent/src/index.ts:51`](../packages/ui/acp-agent/src/index.ts)
 
 ## `@deepseek-ai/dsh-agent-core`
 
@@ -61,29 +64,36 @@ Source: [`packages/ui/acp-agent/src/index.ts:50`](../packages/ui/acp-agent/src/i
 /**
  * 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` to the system-prompt plugin (the
- * deployment's persona section). Both are optional INPUT here because each
- * owner's schema supplies the default (`[]` / `''`); the schema is the
- * INTERSECTION of the owners' own schemas, so validation and defaulting can
- * never drift from them.
+ * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
+ * plugin (the deployment's persona section and the explicit model-facing tool
+ * order). Every field is optional INPUT here because each owner's schema
+ * supplies the default (`[]` / `''` / absent — lexicographic); the schema is
+ * the INTERSECTION of the owners' own schemas, so validation and defaulting
+ * can never drift from them.
  */
 export interface Config {
   /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
   agents?: AgentLoopConfig['agents']
   /** The deployment persona (see dsh-system-prompt's `Config`). */
   persona?: SystemPromptConfig['persona']
+  /** The explicit model-facing tool order (see dsh-system-prompt's `Config`). */
+  toolOrder?: SystemPromptConfig['toolOrder']
 }
 ```
 
 Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt)
 
-Source: [`packages/core/agent-core/src/index.ts:68`](../packages/core/agent-core/src/index.ts)
+Source: [`packages/core/agent-core/src/index.ts:69`](../packages/core/agent-core/src/index.ts)
 
 ## `@deepseek-ai/dsh-agent-loop`
 
 Requires: `agents` · `sessions` · `llm` · `tools` · `systemPrompt`
 
 ```ts config-catalog
+/**
+ * Plugin config: the agents to create — or resume, via `resumeSessionId` —
+ * declaratively at startup, so a cordis.yml deployment needs no code.
+ */
 export interface Config {
   /** Agents created from configuration at startup. */
   agents: (AgentOptions & {
@@ -109,7 +119,7 @@ export interface Config {
 
 Depends on: [`AgentId`](../packages/core/agent/src/index.ts) · [`AgentOptions`](../packages/core/agent/src/index.ts) · [`SessionId`](../packages/core/session/src/index.ts)
 
-Source: [`packages/core/agent-loop/src/index.ts:32`](../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:36`](../packages/core/agent-loop/src/index.ts)
 
 ## `@deepseek-ai/dsh-bash-local`
 
@@ -268,6 +278,12 @@ Source: [`packages/support/invariants/src/index.ts:45`](../packages/support/inva
 Requires: `llm`
 
 ```ts config-catalog
+/**
+ * Plugin config, validated by the same-named schemastery schema. Every field
+ * is optional in yml: credentials/endpoint fall back to the environment (a
+ * missing API key fails plugin load, not the first call), and omitted
+ * thinking fields send nothing on the wire, so the provider default applies.
+ */
 export interface Config {
   /** API key; falls back to $DEEPSEEK_API_KEY. Required one way or the other. */
   apiKey?: string
@@ -282,13 +298,18 @@ export interface Config {
 }
 ```
 
-Source: [`packages/llm/llm-deepseek/src/index.ts:37`](../packages/llm/llm-deepseek/src/index.ts)
+Source: [`packages/llm/llm-deepseek/src/index.ts:43`](../packages/llm/llm-deepseek/src/index.ts)
 
 ## `@deepseek-ai/dsh-llm-pi-ai`
 
 Requires: `llm`
 
 ```ts config-catalog
+/**
+ * Plugin config, validated by the same-named schemastery schema. Every field
+ * is optional in yml: credentials/endpoint fall back to the environment (a
+ * missing API key fails plugin load, not the first call).
+ */
 export interface Config {
   /** API key; falls back to $DEEPSEEK_API_KEY. Required one way or the other. */
   apiKey?: string
@@ -308,13 +329,14 @@ export interface Config {
 export type PiAiReasoning = 'off' | 'high' | 'xhigh'
 ```
 
-Source: [`packages/llm/llm-pi-ai/src/index.ts:32`](../packages/llm/llm-pi-ai/src/index.ts)
+Source: [`packages/llm/llm-pi-ai/src/index.ts:37`](../packages/llm/llm-pi-ai/src/index.ts)
 
 ## `@deepseek-ai/dsh-llm-replay`
 
 Requires: `llm`
 
 ```ts config-catalog
+/** Plugin config: the {@link ReplayConfig} inputs, each defaulting to its `DSH_SNAPSHOT_*` env var in `apply`. */
 export interface Config {
   /** Override the fixture path; defaults to `$DSH_SNAPSHOT_FILE`. */
   file?: string
@@ -329,13 +351,14 @@ export interface Config {
 }
 ```
 
-Source: [`packages/support/llm-replay/src/index.ts:415`](../packages/support/llm-replay/src/index.ts)
+Source: [`packages/support/llm-replay/src/index.ts:429`](../packages/support/llm-replay/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-persistence-jsonl`
 
 Requires: `sessions`
 
 ```ts config-catalog
+/** Plugin config: where the JSONL backend keeps its session logs (`root` is required — no default). */
 export interface Config {
   /**
    * Root directory for all session files. Required (no default): a default of
@@ -346,7 +369,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:34`](../packages/session-persistence/session-persistence-jsonl/src/index.ts)
+Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:35`](../packages/session-persistence/session-persistence-jsonl/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-persistence-sqlite`
 
@@ -390,7 +413,8 @@ Source: [`packages/session-persistence/session-persistence-sqlite/src/index.ts:5
  * App config: the swappable per-demo values, each routed to where the app wires
  * it. `model`/`resumeSessionId` configure the pre-created `main` agent (through
  * {@link @deepseek-ai/dsh-agent-core}'s forwarded `agents` list); `persona` is
- * the deployment persona (forwarded to the system-prompt plugin);
+ * the deployment persona (forwarded to the system-prompt plugin); `toolOrder`
+ * is the explicit model-facing tool order (forwarded to the system-prompt plugin);
  * `persistenceRoot` is the JSONL backend's directory; `welcome` is the UI banner.
  */
 export interface Config {
@@ -398,6 +422,8 @@ export interface Config {
   model: string
   /** Deployment persona (the system-prompt plugin's `persona` config). */
   persona?: string
+  /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */
+  toolOrder?: string[]
   /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
   persistenceRoot?: string
   /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */
@@ -411,7 +437,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/ui/stdio-agent/src/index.ts:61`](../packages/ui/stdio-agent/src/index.ts)
+Source: [`packages/ui/stdio-agent/src/index.ts:62`](../packages/ui/stdio-agent/src/index.ts)
 
 ## `@deepseek-ai/dsh-subagent-acp`
 
@@ -481,7 +507,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/subagent/subagent-fork/src/index.ts:34`](../packages/subagent/subagent-fork/src/index.ts)
+Source: [`packages/subagent/subagent-fork/src/index.ts:38`](../packages/subagent/subagent-fork/src/index.ts)
 
 ## `@deepseek-ai/dsh-subagent-mock`
 
@@ -528,11 +554,12 @@ export interface Config {
 }
 ```
 
-Source: [`packages/subagent/subagent-spawn/src/index.ts:26`](../packages/subagent/subagent-spawn/src/index.ts)
+Source: [`packages/subagent/subagent-spawn/src/index.ts:36`](../packages/subagent/subagent-spawn/src/index.ts)
 
 ## `@deepseek-ai/dsh-system-prompt`
 
 ```ts config-catalog
+/** 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
@@ -547,10 +574,33 @@ export interface Config {
    * deployment opens with the harness identity alone.
    */
   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.
+   */
+  toolOrder?: string[]
 }
 ```
 
-Source: [`packages/core/system-prompt/src/index.ts:113`](../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:179`](../packages/core/system-prompt/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-fs`
 
@@ -608,6 +658,7 @@ Source: [`packages/subagent/tool-subagent/src/index.ts:44`](../packages/subagent
 Requires: `tools` · `web` · `systemPrompt`
 
 ```ts config-catalog
+/** Plugin config: which web tools to register, and the `web_search` source cap. */
 export interface Config {
   /** Register `web_search`. Defaults to true. */
   search?: boolean
@@ -618,7 +669,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/tool-web/src/index.ts:36`](../packages/web/tool-web/src/index.ts)
+Source: [`packages/web/tool-web/src/index.ts:37`](../packages/web/tool-web/src/index.ts)
 
 ## `@deepseek-ai/dsh-web`
 
@@ -644,6 +695,7 @@ Source: [`packages/web/web/src/index.ts:68`](../packages/web/web/src/index.ts)
 Requires: `web`
 
 ```ts config-catalog
+/** Plugin config: the provider's transport and size limits plus its `User-Agent` (all defaulted). */
 export interface Config {
   /** Maximum accepted request URL length. */
   maxUrlLength?: number
@@ -662,13 +714,14 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-fetch-local/src/index.ts:33`](../packages/web/web-fetch-local/src/index.ts)
+Source: [`packages/web/web-fetch-local/src/index.ts:34`](../packages/web/web-fetch-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-search-deepseek`
 
 Requires: `web`
 
 ```ts config-catalog
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
 export interface Config {
   /** DeepSeek API key. Falls back to `$DEEPSEEK_API_KEY`. Empty → unavailable. */
   apiKey?: string
@@ -685,13 +738,14 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-search-deepseek/src/index.ts:47`](../packages/web/web-search-deepseek/src/index.ts)
+Source: [`packages/web/web-search-deepseek/src/index.ts:48`](../packages/web/web-search-deepseek/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-search-exa`
 
 Requires: `web`
 
 ```ts config-catalog
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
 export interface Config {
   /** Exa API key. Falls back to `$EXA_API_KEY`. Empty → provider unavailable. */
   apiKey?: string
@@ -706,13 +760,14 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-search-exa/src/index.ts:38`](../packages/web/web-search-exa/src/index.ts)
+Source: [`packages/web/web-search-exa/src/index.ts:39`](../packages/web/web-search-exa/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-search-perplexity`
 
 Requires: `web`
 
 ```ts config-catalog
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
 export interface Config {
   /** Perplexity API key. Falls back to `$PERPLEXITY_API_KEY`. Empty → unavailable. */
   apiKey?: string
@@ -727,7 +782,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-search-perplexity/src/index.ts:32`](../packages/web/web-search-perplexity/src/index.ts)
+Source: [`packages/web/web-search-perplexity/src/index.ts:33`](../packages/web/web-search-perplexity/src/index.ts)
 
 ## Loadable plugins with no config
 

docs/cordis-catalog/events.md

@@ -23,7 +23,7 @@ An agent was registered in the AgentRegistry and is ready to receive messages.
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:248`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:264`](../../packages/core/agent/src/types.ts)
 
 ### `agent/disposed` — emit
 
@@ -35,7 +35,7 @@ An agent was disposed and removed from the registry; its fiber and any in-flight
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:255`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:271`](../../packages/core/agent/src/types.ts)
 
 ### `agent/error` — emit
 
@@ -47,7 +47,7 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:404`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:420`](../../packages/core/agent/src/types.ts)
 
 ### `agent/pre-step` — serial
 
@@ -61,7 +61,7 @@ Serial (awaited in registration order), not a waterfall: a listener mutates the
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:333`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:349`](../../packages/core/agent/src/types.ts)
 
 ### `agent/prompt-submit` — waterfall
 
@@ -73,7 +73,7 @@ Waterfall: decide what happens to ONE drained queued message before it becomes a
 
 Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:346`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:362`](../../packages/core/agent/src/types.ts)
 
 ### `agent/queued` — emit
 
@@ -85,7 +85,7 @@ A message entered the agent's inbox (queued or steering). `source` is the resolv
 
 Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:273`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
 ### `agent/request` — waterfall
 
@@ -97,7 +97,7 @@ Waterfall: shape the step's call configuration — model switching, sampling ove
 
 Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:369`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:385`](../../packages/core/agent/src/types.ts)
 
 ### `agent/session-start` — emit
 
@@ -109,7 +109,7 @@ The agent's session lifecycle began, fired once before its first turn. `source`
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:288`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:304`](../../packages/core/agent/src/types.ts)
 
 ### `agent/status` — emit
 
@@ -121,7 +121,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). Drive lifecycle
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:264`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:280`](../../packages/core/agent/src/types.ts)
 
 ### `agent/step-result` — waterfall
 
@@ -133,7 +133,7 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va
 
 Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:379`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:395`](../../packages/core/agent/src/types.ts)
 
 ### `agent/turn-continuation` — waterfall
 
@@ -145,7 +145,7 @@ Waterfall: override the turn-continuation decision via a typed ContinuationDecis
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:392`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:408`](../../packages/core/agent/src/types.ts)
 
 ## `fs/*`
 
@@ -307,7 +307,7 @@ A tool was registered or unregistered (the available tool set changed).
 'tools/change'(): void
 ```
 
-Source: [`packages/core/tools/src/index.ts:87`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:97`](../../packages/core/tools/src/index.ts)
 
 ### `tools/post-execute` — waterfall
 
@@ -319,7 +319,7 @@ Waterfall AFTER a tool runs — where hook plugins inspect the result and accept
 
 Types: [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md)
 
-Source: [`packages/core/tools/src/index.ts:82`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:92`](../../packages/core/tools/src/index.ts)
 
 ### `tools/pre-execute` — waterfall
 
@@ -331,7 +331,7 @@ Waterfall BEFORE a tool runs — the gate where sandbox, permission, and hook pl
 
 Types: [ToolExecution](../core-data-structures/tools.md)
 
-Source: [`packages/core/tools/src/index.ts:66`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:76`](../../packages/core/tools/src/index.ts)
 
 ## Inherited events (cordis core + loader/hmr/timer)
 

docs/cordis-catalog/services.md

@@ -21,7 +21,7 @@ createAgent(options: CreateAgentOptions): AgentHandle
 async resume(options: ResumeAgentOptions): Promise<AgentHandle>
 ```
 
-Source: [`packages/core/agent-loop/src/index.ts:64`](../../packages/core/agent-loop/src/index.ts)
+Source: [`packages/core/agent-loop/src/index.ts:68`](../../packages/core/agent-loop/src/index.ts)
 
 ## `ctx.agents` — `AgentRegistry`
 
@@ -124,7 +124,7 @@ stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 
 Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
 
-Source: [`packages/llm/llm/src/index.ts:84`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:88`](../../packages/llm/llm/src/index.ts)
 
 ## `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
 
@@ -146,7 +146,7 @@ abstract list(): Promise<SessionHeader[]>
 
 Types: [SessionEvent](../core-data-structures/core.md)
 
-Source: [`packages/session-persistence/session-persistence/src/index.ts:98`](../../packages/session-persistence/session-persistence/src/index.ts)
+Source: [`packages/session-persistence/session-persistence/src/index.ts:102`](../../packages/session-persistence/session-persistence/src/index.ts)
 
 ## `ctx.sessions` — `SessionStore`
 
@@ -164,7 +164,7 @@ list(): Session[]
 fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
 ```
 
-Source: [`packages/core/session/src/index.ts:389`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:405`](../../packages/core/session/src/index.ts)
 
 ## `ctx.subagents` — `SubagentService`
 
@@ -187,10 +187,10 @@ Registry service (`ctx.systemPrompt`): plugins contribute ordered text sections,
 section(section: PromptSection): () => void
 tools(provider: () => ToolSchema[]): () => void
 variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void
-assemble(context: AssembleContext = {}): Promise<PromptAssembly>
+async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
 ```
 
-Source: [`packages/core/system-prompt/src/index.ts:198`](../../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:291`](../../packages/core/system-prompt/src/index.ts)
 
 ## `ctx.tools` — `ToolRegistry`
 
@@ -205,7 +205,7 @@ async execute(exec: ToolExecution): Promise<ToolExecutionResult>
 
 Types: [ToolDefinition](../core-data-structures/tools.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md)
 
-Source: [`packages/core/tools/src/index.ts:268`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:278`](../../packages/core/tools/src/index.ts)
 
 ## `ctx.userInteraction` — `UserInteractionService`
 

docs/core-data-structures/core.md

@@ -188,7 +188,7 @@ The model-facing `ToolSchema` is the wire shape; the registered `ToolDefinition`
 
 ### The request envelope: `LlmCallConfig` and the logged header
 
-Requests are built by the loop, not shaped per call: the non-content half of a request — the `EpochHeader`: this call configuration plus the rendered system prompt and assembled tool schemas — is logged session state (`request/header` snapshot and delta events, [session.md](session.md#the-request-header-events-requestheader-and-requestheader-delta)), so every conversation request is a pure function of the session log ([reconstructability RFC](../rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)). The `agent/request` waterfall receives a frozen `LlmCallConfig` seed and a listener returns a replacement to switch model or sampling — the loop logs whatever the request actually uses. Loop-built requests arrive at `llm/stream` deep-frozen; mutation throws.
+Requests are built by the loop, not shaped per call: the non-content half of a request — the `EpochHeader`: this call configuration plus the rendered system prompt and the tool schemas in the assembly's canonical order (dsh-system-prompt's `toolOrder` config, lexicographic when unset) — is logged session state (`request/header` snapshot and delta events, [session.md](session.md#the-request-header-events-requestheader-and-requestheader-delta)), so every conversation request is a pure function of the session log ([reconstructability RFC](../rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)). The `agent/request` waterfall receives a frozen `LlmCallConfig` seed and a listener returns a replacement to switch model or sampling — the loop logs whatever the request actually uses. Loop-built requests arrive at `llm/stream` deep-frozen; mutation throws.
 
 FIXME(call-config-shape): revisit the exact definition of this type — which fields are genuinely epoch-level for cache purposes (`model` certainly; the sampling scalars sit here out of caution), and where provider-specific extras (reasoning options, extra body params) belong when an adapter needs them.
 

docs/core-data-structures/subagent.md

@@ -20,7 +20,7 @@ interface SubagentCapabilities {
 
 ## The start request
 
-What a caller asks for when starting a subagent. The tool layer builds this from the model's `{ description, prompt }` plus its own config; the service validates the start-time capabilities against the named provider, then passes it to `provider.start`. `parent` is REQUIRED — in-process backends read `parent.session.header` for the working directory, the `parentSession` lineage, and the delegation depth. The three optional fields (`outputSchema`, `maxDepth`, `toolFilter`) each gate on the matching `SubagentCapabilities` flag.
+What a caller asks for when starting a subagent. The tool layer builds this from the model's `{ description, prompt }` plus its own config; the service validates the start-time capabilities against the named provider, then passes it to `provider.start`. `parent` is REQUIRED — in-process backends read `parent.session.header` for the working directory, the `parentSession` lineage, and the delegation depth. The three optional fields (`outputSchema`, `maxDepth`, `toolFilter`) each gate on the matching `SubagentCapabilities` flag. `outputSchema` is an object-rooted JSON Schema within the subset `assertSupportedOutputSchema` (dsh-tools) enforces — a schema outside it is rejected loud at start; the in-process backends realize it with a forced `structured_output` capture tool (see the [driver README](../../packages/subagent/subagent-inprocess/README.md)).
 
 ```ts type-equiv
 interface SubagentStartRequest {
@@ -28,7 +28,7 @@ interface SubagentStartRequest {
   parent: Agent
   signal?: AbortSignal
   agentOptions?: AgentOptions
-  outputSchema?: SchemaSpec
+  outputSchema?: StructuredOutputSchema
   maxDepth?: number
   toolFilter?: { allow?: string[]; deny?: string[] }
 }

docs/core-data-structures/tools.md

@@ -138,6 +138,40 @@ type PostToolDecision =
 
 Call `next()` to delegate to the default (allow / accept-unchanged), or return a decision to short-circuit. A `pre-execute` `deny` (or `ask`, which degrades to deny until the permission system lands) skips dispatch and yields an `isError` result; input rewrite is deliberately NOT offered on `PreToolDecision` (it would desync the pre-execution audit/history/UI from what ran — its own proposed RFC). A `post-execute` `accept` may replace the model-facing `content` (clean, because `tool/result` is logged after `execute()` returns); a `block` turns the call into an `isError` whose content is the corrective `feedback`. Core dispatch sits between the waterfalls as plain code; the tool body keeps its own try/catch so a thrown tool still reaches `post-execute` as an `isError`. An unregistered tool routes through the same catch as a tool-thrown error, so both failure classes get a structured `{ name, code }` (`ToolNotFoundError` → `UNKNOWN_TOOL`) — the loop records a failed tool call instead of failing the whole turn.
 
+## The structured-output schema subset
+
+The vocabulary a caller uses to demand a machine-readable result from a subagent (`SubagentStartRequest.outputSchema`, [subagent.md](subagent.md#the-start-request)) or a workflow `agent()` call. It is deliberately NOT full JSON Schema: the schema travels verbatim to the model as a forced tool's `parameters`, and the produced value is validated client-side by `validateStructuredValue` — so every accepted keyword must be one the validator actually enforces, and `assertSupportedOutputSchema` rejects anything else loud (`OutputSchemaError`, listing every violation). Both walkers reason over own enumerable properties only (JSON carries nothing else) and reject non-plain objects (`Date`, `Map`) that would serialize lossily.
+
+```ts type-equiv
+type StructuredScalar = string | number | boolean | null
+```
+
+```ts type-equiv
+type StructuredSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
+```
+
+```ts type-equiv
+interface StructuredSchemaNode {
+  type: StructuredSchemaType
+  properties?: Record<string, StructuredSchemaNode>
+  required?: string[]
+  additionalProperties?: boolean
+  items?: StructuredSchemaNode
+  enum?: StructuredScalar[]
+  const?: StructuredScalar
+  description?: string
+  title?: string
+  default?: unknown
+  examples?: unknown
+}
+```
+
+A schema is an object-rooted node (`enum`/`const` are scalar-only; `description`/`title`/`default`/`examples` are annotations, allowed and ignored but still required to be JSON data — they ride the wire):
+
+```ts type-equiv
+type StructuredOutputSchema = StructuredSchemaNode & { type: 'object' }
+```
+
 ## Tool-presentation UI vocabulary
 
 How a tool wants its call shown in a UI (an editor tool-call card, a CLI log line), provider-neutral so a tool describes itself without depending on any client protocol. `presentCall`/`presentResult` return a **`card`-tagged render intent** — a discriminated union a UI bridge switches on:

docs/core-data-structures/web.md

@@ -91,4 +91,4 @@ Selection never depends on registration, config, or HMR order: a capability has
 
 ## The service
 
-`WebService` (`ctx.web`, defined in [`packages/web/web/src/index.ts`](../../packages/web/web/src/index.ts)) is a provider registry plus a provider-selecting execution surface, close to `LlmService`'s shape: `registerSearchProvider`/`registerFetchProvider` (duplicate ids throw `WEB_DUPLICATE_PROVIDER`, return disposers) and `search`/`fetch` (resolve the provider at call time, throw a structured `WebError` when the capability cannot run). Providers issue requests with the platform-native `fetch` (Node 24), mirroring `dsh-llm-deepseek`; the `dsh-web-fetch-local` provider owns safe retrieval (http/https-only, credential rejection, byte/char/timeout/redirect caps, same-origin-only redirects with per-hop re-validation, charset decoding) while `dsh-tool-web` owns presentation (HTML→markdown). SSRF / private-network blocking is deferred (see the RFC) — until it lands, `web_fetch` must not be enabled where it can reach sensitive internal targets.
+`WebService` (`ctx.web`, defined in [`packages/web/web/src/index.ts`](../../packages/web/web/src/index.ts)) is a provider registry plus a provider-selecting execution surface, close to `LlmService`'s shape: `registerSearchProvider`/`registerFetchProvider` (duplicate ids throw `WEB_DUPLICATE_PROVIDER`, return disposers) and `search`/`fetch` (resolve the provider at call time, throw a structured `WebError` when the capability cannot run). Providers issue requests with platform-native `fetch` at the repo's Node floor, mirroring `dsh-llm-deepseek`; the `dsh-web-fetch-local` provider owns safe retrieval (http/https-only, credential rejection, byte/char/timeout/redirect caps, same-origin-only redirects with per-hop re-validation, charset decoding) while `dsh-tool-web` owns presentation (HTML→markdown). SSRF / private-network blocking is deferred (see the RFC) — until it lands, `web_fetch` must not be enabled where it can reach sensitive internal targets.

docs/development.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-development.md: 97ca3f6b9fc9653ab658e480e6155fc1e121854f
-development.zh.md: e837afb6a01ed4d0c4801886bd6ca6a7602ac573
+development.md: bd6f6b561480419abea7a42a44b4078e2c59b1cb
+development.zh.md: 54bf19765d2b4dc419e6b71684dbcfcd28230541

docs/development.md

@@ -2,11 +2,11 @@
 
 English | [中文](development.zh.md)
 
-This guide covers the local setup needed to work on DeepSeek Harness and understand the local hooks, daily checks, and CI gates.
+This onboarding guide helps project contributors get started with the local environment, daily workflow, and CI flow; see the RFCs for design rationale and technical trade-offs.
 
 ## Prerequisites
 
-- Node.js 24 or newer. The repo declares `node >=24`; CI runs the matrix on Node 24 and 26.
+- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor RFC](rfc/implemented/process/2026-07-06-node-engine-floor.md).
 - Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.
 - Git.
 - Optional: a DeepSeek API key for the REPL/ACP agent demos and real-API e2e tests.
@@ -63,11 +63,11 @@ lefthook is configured in `lefthook.yml` as an early local checkpoint before rev
 
 The vendor manifest guard checks that changes under `vendor/*/src` are staged with the matching `vendor/README.md` manifest update. See `vendor/README.md` before editing vendored code.
 
-These hooks do not exactly mirror CI. Notably, `pre-push` runs unit tests without coverage, while CI runs `pnpm run test:coverage`; CI also runs echo-agent and built-bin smoke tests and exercises the matrix on Node 24 and 26.
+These hooks do not exactly mirror CI. Notably, `pre-push` runs unit tests without coverage, while CI runs `pnpm run test:coverage`; CI also runs echo-agent and built-bin smoke tests and exercises the compatibility matrix on Node 22.19, 24, and 26.
 
 ## CI gates
 
-The keyless GitHub workflow has six jobs: five Node 24 lanes run static gates, lint, coverage, snapshot replay, and artifact gates separately, and the Node 26 compatibility job runs `pnpm run check:node-compat`. The lane schedulers fan out independent gates from `package.json`: constraints, typecheck, lint, coverage, snapshot replay, `doc-sync` members, module-graph freshness, `knip`, and the echo-agent smoke test.
+The keyless GitHub workflow has eight jobs: five Node 24 lanes run static gates, lint, coverage, snapshot replay, and artifact gates separately, and three compatibility jobs run `pnpm run check:node-compat` on Node 22.19, 24, and 26. The lane schedulers fan out independent gates from `package.json`: constraints, typecheck, lint, coverage, snapshot replay, `doc-sync` members, module-graph freshness, `knip`, and the echo-agent smoke test.
 
 `pnpm run build` feeds the artifact lane, and `publint`, `verify-node-next-types`, and built-bin smoke tests wait for build output. The separate real-API workflow runs `pnpm run test:e2e` with a secret and `DSH_E2E_MAX_WORKERS=14`.
 
@@ -85,6 +85,7 @@ pnpm run lint:fix       # eslint . --fix
 pnpm run doc-typecheck  # compile checked TypeScript snippets in Markdown docs
 pnpm run gen-cordis-catalog     # regenerate docs/cordis-catalog/events.md + services.md from source
 pnpm run verify-cordis-catalog  # fail if either cordis catalog is stale
+pnpm run verify-export-jsdoc    # fail if a module-level package export lacks complete JSDoc
 pnpm run gen-doc-graphs     # regenerate generated relationship docs from source and curated graph definitions
 pnpm run verify-doc-graphs  # fail if generated relationship docs are stale
 pnpm run gen-rfc-index          # regenerate the docs/rfc/README.md index tables from the RFC tree

docs/development.zh.md

@@ -2,11 +2,11 @@
 
 [English](development.md) | 中文
 
-本指南覆盖参与 DeepSeek Harness 开发所需的本地环境搭建，并帮助你理解本地钩子、日常检查与 CI 门禁。
+本文面向参与项目开发的贡献者，帮助你上手本地环境、日常工作流和 CI 流程。相关设计考量和技术取舍参见 RFC，不在这里展开。
 
 ## 前置条件
 
-- Node.js 24 或更新版本。仓库声明 `node >=24`；CI 在 Node 24 和 26 上跑矩阵。
+- Node.js 支持 22.19+ 和 24+。CI 覆盖 22.19、24、26；见 [Node engine floor RFC](rfc/implemented/process/2026-07-06-node-engine-floor.md)。
 - 启用了 Corepack 的 pnpm。仓库在 `package.json` 中钉住 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，先运行 `corepack enable`。
 - Git。
 - 可选：一个 DeepSeek API key，用于 REPL/ACP agent（智能体）演示和真实 API 的 e2e 测试。
@@ -63,11 +63,11 @@ lefthook 在 `lefthook.yml` 中配置，作为评审前的本地早期检查点
 
 vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。编辑 vendor 代码前先看 `vendor/README.md`。
 
-这些钩子并不与 CI 完全一致。特别是：`pre-push` 跑不带覆盖率的单元测试，而 CI 跑 `pnpm run test:coverage`；CI 还会跑 echo-agent 和 built-bin 冒烟测试，并在 Node 24 和 26 上跑矩阵。
+这些钩子并不与 CI 完全一致。特别是：`pre-push` 跑不带覆盖率的单元测试，而 CI 跑 `pnpm run test:coverage`；CI 还会跑 echo-agent 和 built-bin 冒烟测试，并在 Node 22.19、24 和 26 上跑兼容性矩阵。
 
 ## CI 门禁
 
-keyless GitHub 工作流有六个 job：五个 Node 24 lane 分别运行 static gates、lint、coverage、snapshot replay 和 artifact gates，Node 26 兼容性 job 运行 `pnpm run check:node-compat`。各 lane 调度器并发运行来自 `package.json` 的独立门禁：constraints、typecheck、lint、coverage、snapshot replay、`doc-sync` 成员、module graph 新鲜度、`knip` 和 echo-agent 冒烟测试。
+keyless GitHub 工作流有八个 job：五个 Node 24 lane 分别运行 static gates、lint、coverage、snapshot replay 和 artifact gates，三个兼容性 job 在 Node 22.19、24 和 26 上运行 `pnpm run check:node-compat`。各 lane 调度器并发运行来自 `package.json` 的独立门禁：constraints、typecheck、lint、coverage、snapshot replay、`doc-sync` 成员、module graph 新鲜度、`knip` 和 echo-agent 冒烟测试。
 
 `pnpm run build` 供给 artifact lane，`publint`、`verify-node-next-types` 和 built-bin 冒烟测试等待 build 输出。单独的真实 API 工作流带密钥运行 `pnpm run test:e2e`，并设置 `DSH_E2E_MAX_WORKERS=14`。
 
@@ -85,6 +85,7 @@ pnpm run lint:fix       # eslint . --fix
 pnpm run doc-typecheck  # compile checked TypeScript snippets in Markdown docs
 pnpm run gen-cordis-catalog     # regenerate docs/cordis-catalog/events.md + services.md from source
 pnpm run verify-cordis-catalog  # fail if either cordis catalog is stale
+pnpm run verify-export-jsdoc    # fail if a module-level package export lacks complete JSDoc
 pnpm run gen-doc-graphs     # regenerate generated relationship docs from source and curated graph definitions
 pnpm run verify-doc-graphs  # fail if generated relationship docs are stale
 pnpm run gen-rfc-index          # regenerate the docs/rfc/README.md index tables from the RFC tree

docs/event-producer-consumer.md

@@ -7,17 +7,17 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 
 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
-| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:248`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) |
-| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:255`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:404`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
-| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:333`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) |
-| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:346`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:273`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
-| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:369`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
-| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:288`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:264`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) |
-| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:379`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
-| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:392`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:264`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) |
+| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:271`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`emit`) | [`stdio-agent`](../packages/ui/stdio-agent) |
+| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:420`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
+| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:349`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic) |
+| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:362`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:385`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:304`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:280`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`stdio-agent`](../packages/ui/stdio-agent) |
+| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:395`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
+| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:408`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:123`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:138`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:109`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
@@ -31,8 +31,8 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:91`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:38`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | - |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:44`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
-| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:87`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
-| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:82`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:66`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:97`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
+| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:92`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:76`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 
 Maintenance mode: hybrid generated: Cordis event declarations and most producer/listener edges are AST-scanned; dynamic dispatch sites are classified in `scripts/gen-doc-graphs.ts`.

docs/module-graph.md

@@ -179,6 +179,8 @@ flowchart TD
   pkg_subagent_inprocess --> pkg_llm
   pkg_subagent_inprocess --> pkg_session
   pkg_subagent_inprocess --> pkg_subagent
+  pkg_subagent_inprocess --> pkg_system_prompt
+  pkg_subagent_inprocess --> pkg_tools
   pkg_tool_subagent --> pkg_agent
   pkg_tool_subagent --> pkg_llm
   pkg_tool_subagent --> pkg_subagent
@@ -255,7 +257,7 @@ flowchart TD
 | [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-interaction`](../packages/core/user-interaction) |
 | [`agent-core`](../packages/core/agent-core) | `core` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/bash/tool-bash), [`tools`](../packages/core/tools) |
 | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) |
-| [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`subagent-mock`](../packages/support/subagent-mock) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) |

docs/persistence-catalog.md

@@ -23,7 +23,7 @@ Raw stream chunk — token-level replay fidelity.
 
 Types: [StreamChunk](core-data-structures/llm-streaming.md)
 
-Source: [`packages/core/session/src/types.ts:298`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:304`](../packages/core/session/src/types.ts)
 
 #### `assistant/message` — surface
 
@@ -35,7 +35,7 @@ Assembled assistant message for one step (derived history uses this). Carries th
 
 Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md)
 
-Source: [`packages/core/session/src/types.ts:305`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:311`](../packages/core/session/src/types.ts)
 
 ### `compact/*`
 
@@ -83,7 +83,7 @@ In-session context injection (file-change notices, subdir AGENTS.md, skill conte
 
 Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:296`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:302`](../packages/core/session/src/types.ts)
 
 ### `hook/*`
 
@@ -119,7 +119,7 @@ A queued prompt an `agent/prompt-submit` listener VETOED — the durable record
 
 Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:290`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:296`](../packages/core/session/src/types.ts)
 
 ### `request/*`
 
@@ -131,7 +131,7 @@ Full snapshot of the EpochHeader the NEXT request is built under, with the Reque
 'request/header': { header: EpochHeader; reason: RequestHeaderReason }
 ```
 
-Source: [`packages/core/session/src/types.ts:350`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:356`](../packages/core/session/src/types.ts)
 
 #### `request/header-delta` — log-only
 
@@ -141,7 +141,7 @@ Amendment to the folded EpochHeader: at least one of a SystemDelta, a ToolsDelta
 'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig }
 ```
 
-Source: [`packages/core/session/src/types.ts:361`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:367`](../packages/core/session/src/types.ts)
 
 ### `steering/*`
 
@@ -155,7 +155,7 @@ Steering content injected between steps of a running turn.
 
 Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:323`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:329`](../packages/core/session/src/types.ts)
 
 ### `step/*`
 
@@ -167,7 +167,7 @@ Closes step `step` of turn `turn`.
 'step/end': { turn: number; step: number }
 ```
 
-Source: [`packages/core/session/src/types.ts:277`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:283`](../packages/core/session/src/types.ts)
 
 #### `step/start` — log-only
 
@@ -177,7 +177,7 @@ Opens step `step` of turn `turn` — one model call plus the tool executions it
 'step/start': { turn: number; step: number }
 ```
 
-Source: [`packages/core/session/src/types.ts:275`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:281`](../packages/core/session/src/types.ts)
 
 ### `todo/*`
 
@@ -193,7 +193,7 @@ NOT a SurfaceEventType: it produces no LLM message and never reaches `deriveMess
 
 Types: [TodoItem](core-data-structures/session.md)
 
-Source: [`packages/core/session/src/types.ts:337`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:343`](../packages/core/session/src/types.ts)
 
 ### `tool/*`
 
@@ -207,7 +207,7 @@ The model requested one tool invocation: `name` with the raw `arguments` JSON st
 
 Types: [CallId](core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:311`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:317`](../packages/core/session/src/types.ts)
 
 #### `tool/result` — surface
 
@@ -219,7 +219,7 @@ A completed tool call's model-facing result, plus an optional tool-private `meta
 
 Types: [CallId](core-data-structures/core.md) · [ContentBlock](core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:321`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:327`](../packages/core/session/src/types.ts)
 
 ### `turn/*`
 
@@ -233,7 +233,7 @@ Closes turn `turn` with the TurnEndReason that ended it. The loop fires the awai
 
 Types: [TurnEndReason](core-data-structures/session.md)
 
-Source: [`packages/core/session/src/types.ts:273`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:279`](../packages/core/session/src/types.ts)
 
 #### `turn/start` — log-only
 
@@ -245,7 +245,7 @@ Opens turn `turn`. `trigger` records what started it — a drained message batch
 
 Types: [TurnTrigger](core-data-structures/session.md)
 
-Source: [`packages/core/session/src/types.ts:267`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:273`](../packages/core/session/src/types.ts)
 
 ### `user/*`
 
@@ -259,4 +259,4 @@ A user-visible prompt (queued message drained at turn start).
 
 Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md)
 
-Source: [`packages/core/session/src/types.ts:279`](../packages/core/session/src/types.ts)
+Source: [`packages/core/session/src/types.ts:285`](../packages/core/session/src/types.ts)

docs/rfc/INDEX.md

@@ -12,6 +12,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Multiplex concurrent ACP sessions over one connection](proposed/feature/2026-06-14-acp-multi-session.md) | 2026-06-14 |
 | [Optional Code Mode — model writes TypeScript against an SDK of all tools](proposed/feature/2026-06-15-optional-code-mode.md) | 2026-06-15 |
 | [Pre-tool input rewrite — a consistent design](proposed/feature/2026-06-30-pre-tool-input-rewrite.md) | 2026-06-30 |
+| [Claude Code and Codex subagent backends (out-of-process delegation to external coding agents)](proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md) | 2026-07-07 |
 
 ### Simplification
 
@@ -61,6 +62,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Interception seams — the typed-Decision surface a hook programs against](implemented/feature/2026-06-30-interception-seams.md) | 2026-06-30 |
 | [SessionStore fork API](implemented/feature/2026-06-30-session-store-fork-api.md) | 2026-06-30 |
 | [Subagent lifecycle enrichment — lastAssistantMessage (observe-only)](implemented/feature/2026-06-30-subagent-observe-enrich.md) | 2026-06-30 |
+| [Explicit model-facing tool order](implemented/feature/2026-07-06-explicit-tool-order.md) | 2026-07-06 |
 
 ### Simplification
 
@@ -144,7 +146,9 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Generate the RFC index tables](implemented/process/2026-07-04-generate-rfc-index-tables.md) | 2026-07-04 |
 | [Generated persistence log event catalog](implemented/process/2026-07-04-persistence-log-catalog.md) | 2026-07-04 |
 | [One gated in-file format for RFCs](implemented/process/2026-07-05-uniform-rfc-format.md) | 2026-07-05 |
+| [Export-surface JSDoc gate](implemented/process/2026-07-06-export-surface-jsdoc-gate.md) | 2026-07-06 |
 | [Generated plugin config catalog](implemented/process/2026-07-06-generated-config-catalog.md) | 2026-07-06 |
+| [Raise the Node LTS engine floor to 22.19](implemented/process/2026-07-06-node-engine-floor.md) | 2026-07-06 |
 | [Parallel GitHub CI gates](implemented/process/2026-07-06-parallel-github-ci-gates.md) | 2026-07-06 |
 | [Parallel pre-push gates](implemented/process/2026-07-06-parallel-pre-push-gates.md) | 2026-07-06 |
 

docs/rfc/implemented/architecture/2026-06-24-web-capability-seam.md

@@ -66,7 +66,7 @@ flowchart LR
 
 `@deepseek-ai/dsh-web` depends only on Cordis and low-level harness support. It declares `ctx.web`, provider interfaces, request/result types, the provider status type, and error codes. It does not import tool, agent, session, LLM, or provider packages.
 
-Provider packages depend on `@deepseek-ai/dsh-web` and Cordis. They own credentials, endpoint config, provider-specific request mapping, provider-specific response parsing, and provider-specific error translation into `WebError`. They issue network requests with the platform-native `fetch` (Node 24), mirroring `@deepseek-ai/dsh-llm-deepseek`'s adapter, NOT a cordis HTTP-client service (`ctx.http`/`@cordisjs/plugin-http`) — even where a Perplexity provider's request is shaped like an OpenAI-compatible chat completion, that wire shape is a provider-private detail and does not make the provider depend on `ctx.llm`. A provider does NOT own the `ctx.web` key (two search providers cannot both own it): like `dsh-llm-deepseek`, each provider package is a function/namespace plugin (`inject: ['web']`) whose `apply` constructs the backend and calls `ctx.web.registerSearchProvider` / `registerFetchProvider`. `@deepseek-ai/dsh-web` is the `export default` service that owns the key.
+Provider packages depend on `@deepseek-ai/dsh-web` and Cordis. They own credentials, endpoint config, provider-specific request mapping, provider-specific response parsing, and provider-specific error translation into `WebError`. They issue network requests with platform-native `fetch` at the repo's Node floor, mirroring `@deepseek-ai/dsh-llm-deepseek`'s adapter, NOT a cordis HTTP-client service (`ctx.http`/`@cordisjs/plugin-http`) — even where a Perplexity provider's request is shaped like an OpenAI-compatible chat completion, that wire shape is a provider-private detail and does not make the provider depend on `ctx.llm`. A provider does NOT own the `ctx.web` key (two search providers cannot both own it): like `dsh-llm-deepseek`, each provider package is a function/namespace plugin (`inject: ['web']`) whose `apply` constructs the backend and calls `ctx.web.registerSearchProvider` / `registerFetchProvider`. `@deepseek-ai/dsh-web` is the `export default` service that owns the key.
 
 `@deepseek-ai/dsh-tool-web` depends on `@deepseek-ai/dsh-web`, `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-system-prompt`, and Cordis. It never imports concrete provider packages.
 

docs/rfc/implemented/feature/2026-07-06-explicit-tool-order.md

@@ -0,0 +1,49 @@
+# RFC: Explicit model-facing tool order
+
+Status: implemented
+
+## Problem
+
+The order of the tool list a model call carries — `request/header.tools` on the session log and `GenerateOptions.tools` on the wire — was an emergent artifact: the tool registry returns schemas in registration order, the system-prompt assembly concatenates providers in registration order, and the loop logged and dispatched the result verbatim. Registration order is plugin load order, and plugin load order is a race: the cordis loader imports every `cordis.yml` entry concurrently, so which tool plugin registers first depends on module-import completion timing. The plugin dependency relation cannot rescue this — it is a partial order under which independent tool plugins (e.g. `tool-subagent` vs `tool-todo`) are incomparable, so both interleavings are legal linearizations. This stopped being theoretical when a CI runner resolved the race differently from every recording machine: snapshot goldens pinned one permutation of `request/header.tools`, the `node 22.18` CI leg produced the other, and 5/5 snapshot tests failed on a diff that was pure array reordering. Tool order is part of the request bytes (prompt-cache stability, potentially model behavior) and, since the reconstructability contract, part of the durable session log — it must be a decision, not a residue.
+
+## Decision
+
+The system-prompt assembly owns the canonical model-facing tool order, exactly where it already owns section order. `toolOrder?: string[]` on `dsh-system-prompt` is the optional explicit policy:
+
+- A listed tool that is registered takes its listed position.
+- A listed name with no registered tool is a configuration error. Shape errors (rest entry missing or duplicate names) fail from the service constructor; an unregistered name rejects every `assemble()` — the earliest moment the registered tool set exists to check against (tool plugins register after the service constructs), and the only universal one (registrations can change at any time; cordis has no "all plugins loaded" event). Under the shipped loop the first turn fails before any model request — see the consequences below for the exact blast radius.
+- A registered tool absent from the list is inserted at the `'<unlisted-tools>'` rest entry (`TOOL_ORDER_REST`), in lexicographic name order among the other unlisted tools.
+- No collected tool may use `TOOL_ORDER_REST` as its `ToolSchema.name`; the assembly rejects that reserved name before ordering.
+- The list must contain the rest entry exactly once and no duplicate names.
+- When `toolOrder` is unset, the canonical order is plain lexicographic name order (code-unit comparison, locale-independent), so determinism requires no configuration.
+
+The policy is applied where the list is born: `assemble()`, before the `system-prompt/assemble` waterfall. The assembly canonicalizes the tools it collects from providers the same way it sorts sections by their `order` field — on the initial assembly, killing the registration-order entropy at its source. Everything downstream inherits the order untouched: the waterfall, the loop's `EpochHeader`, the `request/header` event, the deep-frozen request, and the dev invariant's cross-check all see one deterministic list, with no new loop change.
+
+Scope is deliberately narrow: this fixes the REGISTRATION-ORDER race, not plugin behavior. A `system-prompt/assemble` listener may still add, remove, or rearrange tools — same as it may edit sections after their sort — and owns the determinism of what it emits; the waterfall contract already demands deterministic listeners (the reconstructability invariant would catch a listener that diverges between build and replay).
+
+Config plumbing follows the `persona` precedent, and `toolOrder` sits beside it: the app configs (`dsh-stdio-agent`, `dsh-acp-agent`) accept the key and forward it through `dsh-agent-core` (whose schema is the intersection of the owners' schemas) to the `SystemPrompt` child. One schemastery footnote is load-bearing: a schemastery array defaults to `[]`, but an omitted `toolOrder` must stay ABSENT (= lexicographic) rather than become an explicitly-configured empty list (invalid — it lacks the rest entry), so every schema on the chain forces the default to `undefined`.
+
+## Alternatives considered
+
+- **Registration order (the status quo)** — a concurrent-import race, host-dependent (the CI flake above), invisible in review.
+- **A linearization of the plugin dependency graph** — the relation is partial and independent tool plugins are incomparable; the flake happened with the partial order fully satisfied.
+- **Per-plugin `weight` on each tool contribution** — scatters the order across plugins yet still needs a global numbering convention nobody owns (the section `order` bands show that coordination cost being paid by hand).
+- **Sorting in `ToolRegistry.schemas()` (the registry layer)** — equally deterministic, but the registry is a membership store consumed by more than the assembly; ordering is a prompt-composition concern, and the assembly already owns the composition policy for sections.
+- **A `LlmService` config + `orderTools()` method the loop calls before logging the header** — works, but adds a public service method and a loop edit solely to apply a policy at a distance; every future request composer must remember the call. Canonicalizing where the list is born makes an unordered list unrepresentable, with zero new surface.
+- **Normalizing inside `llm.stream()`** — runs after the header event is logged (the flake survives) and rebuilds the deep-frozen envelope, silently disarming the reconstruction invariant.
+- **An exhaustive list (no rest entry)** — every newly loaded tool plugin would break boot; the mandatory rest entry keeps unlisted tools deterministic and their position explicit.
+- **A boot-time validation pass (a `SystemPrompt.assertToolOrderSatisfied()` called by `dsh-app-boot` after `loader.await()`)** — would turn the misconfiguration into a startup death instead of a first-turn failure, but costs a public service method plus a structural coupling from the generic boot glue to one service, and cannot replace the assembly-time check anyway (embedded callers never run app boot; registrations change after boot). No existing event can host the check either: cordis v4 has no ready-like event, `loader/entry-init`/`internal/status` fire mid-load (racy against tool registration, the very entropy this RFC kills), and the agent lifecycle events are no earlier than the assembly. One enforcement point at `assemble()` was judged worth the later failure moment.
+
+## Consequences
+
+- Every assembly — and therefore every `request/header` event and model request — has a deterministic tool order on every host; the CI-vs-local golden flip is structurally gone. The default order is lexicographic, no longer registration order.
+- `PromptAssembly.tools` itself is canonical, so every assembly consumer (the loop, waterfall listeners, any future prompt inspector) sees the model-facing order; provider registration order is observable nowhere downstream of the registry.
+- The snapshot suite's single pinned request-header fixture (`text-turn`) carries the new canonical tool order; every other ACP snapshot keeps the header bulk scrubbed as `{{system}}`/`{{tools}}`, per the pinned-header design.
+- A pure tool reordering between steps is representable only as a `request/header` `'fallback'` snapshot (the name-keyed `ToolsDelta` cannot express it); with a stable canonical order such reorders no longer occur in practice, so the fallback path stays a safety valve.
+- The `toolOrder` key rides the app → `agent-core` → `SystemPrompt` forwarding chain, so deployments set it next to `persona` in the app config; `dsh-llm` and the agent loop are untouched.
+- A misspelled or unloaded tool name in `toolOrder` fails the turn at prompt assembly, not the boot: the loop assembles inside the turn (after `turn/start`, before `step/start`), so the rejection reaches the turn's outer catch — the turn closes balanced with an `error` reason carrying the message, `agent/error` mirrors it, no step opens, no `request/header` is logged, no request reaches the adapter, and the agent returns to idle. Every turn fails identically until the config is fixed; the process itself stays up (matching the repo rule that explicit config references must not be silently ignored — the enforcement point is the assembly because no earlier universal moment exists).
+- A tool provider that returns the reserved rest-entry name has the same prompt-assembly failure shape as an unknown listed name. This keeps the sentinel from becoming an ambiguous real tool and preserves the "never drops a tool" ordering contract.
+
+## Testing
+
+Unit tests on `dsh-system-prompt` pin the ordering semantics (lexicographic default, listed/rest placement, unknown-name rejection at assembly, reserved tool-name rejection, stable handling of shared names, provider-order independence), the pre-waterfall contract (listeners observe the canonical list; a listener-appended tool is not re-sorted), and each invalid-list rejection at load. Loop-level tests assert the `request/header` fold carries the canonical order for scrambled registration orders (identical across permutations), that a configured `toolOrder` reaches both the logged header and the dispatched deep-frozen request, that the frozen loop-built envelope survives to the adapter, and that an unregistered `toolOrder` name fails the turn with a balanced `error` `turn/end`, an `agent/error`, no step, no logged header, and no dispatched request. Forwarding is asserted at every level that exposes the key (`dsh-agent-core`, `dsh-stdio-agent`, `dsh-acp-agent`). The snapshot tier replays all scenarios while only the pinned `text-turn` header carries the full canonical tool list; non-pinning fixtures continue to compare through `{{tools}}`.

docs/rfc/implemented/process/2026-06-11-quality-gates.md

@@ -14,7 +14,7 @@ Every AGENTS.md promise gets a command that exits non-zero, wired into git hooks
 - ESLint strict-type-checked + @stylistic (the house style, enforced); vendored code excluded.
 - Per-file 100% coverage on `packages/*/src` (v8); unreachable defensive guards carry `/* v8 ignore */ ` with stated reasons instead of deletion.
 - knip (dead code/deps), publint (package correctness), workspace constraints (workspace rules: private, cordis peer+dev, uniform version, ESM), and a NodeNext consumer typecheck for built package declarations.
-- lefthook pre-commit (lint staged, typecheck, vendor-manifest guard) and pre-push (tests, hygiene); CI runs the full matrix on node 24/26 plus a demo smoke test driving the echo-agent end to end.
+- lefthook pre-commit (lint staged, typecheck, vendor-manifest guard) and pre-push (tests, hygiene); CI runs the full matrix on node 22.19/24/26 plus a demo smoke test driving the echo-agent end to end.
 
 ## Consequences
 

docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md

@@ -0,0 +1,43 @@
+# RFC: Export-surface JSDoc gate
+
+Status: implemented
+
+## Problem
+
+The [cordis JSDoc completeness gate](2026-07-04-cordis-jsdoc-completeness-gate.md) made undocumented parameters and results impossible on the cordis surface — `interface Events` members and `ctx.<key>` service classes — but that surface is a fraction of what a plugin author imports. The AGENTS.md rule "every export (and non-obvious method) has a JSDoc explaining semantics" stayed prose-checkable only by review everywhere else, and nothing at all asked for `@param`/`@returns` on ordinary exported functions. A survey at adoption found 203 under-documented module-level exports across 34 packages: seam-adjacent helpers (`runBash`, `readForEdit`, `htmlToMarkdown`), format codecs, whole undocumented interfaces and type aliases — exactly the names an IDE consumer hovers.
+
+## Decision
+
+A new gate, `scripts/verify-export-jsdoc.ts` (`pnpm run verify-export-jsdoc`, wired into `doc-sync` beside `verify-cordis-catalog`), walks every module-level exported name under each `packages/<group>/<pkg>/src/` tree. The parsing and check helpers moved from `gen-cordis-catalog.ts` into a shared `scripts/jsdoc.ts`, so "documented" means the same thing on both surfaces: description prose ends at the first block tag, every checkable parameter needs a non-empty `@param`, a non-void ANNOTATED return needs a non-empty `@returns`, a stale `@param` errors, and violations aggregate into one report.
+
+The contract by declaration kind:
+
+- Every exported name needs JSDoc with non-empty description prose.
+- Function-like exports (function declarations; consts with function initializers or an INLINE callable annotation; non-identifier function default exports) follow the full function contract, with wrapper expressions (parentheses, `as`/`satisfies` casts, non-null assertions) peeled before classifying. A const whose declarator is annotated with a NAMED type (`export const f: Handler = …`) defers the signature contract to that type's own declaration and `@returns` stays optional; an inline `(x: T) => U` annotation or single-call-signature literal is the surface signature itself and gets the full contract, and a literal mixing call/construct signatures with anything else is refused outright (no single signature to hold the tags against — extract a named type).
+- Exported classes need class-level prose; public methods (statics included — reachable on the exported name) follow the function contract; public properties and accessors need prose (a get/set pair is covered by the getter). Overload implementations are exempt — the signatures carry the docs.
+- Exported interfaces, type aliases, and enums need prose on the declaration; member-level enforcement is deliberately deferred (the highest-value member surface — seam service classes — is already under the cordis gate).
+- Exported namespaces recurse (inside an ambient `declare` namespace every member exports implicitly); the namespace itself needs prose only when it does not merge with a documented same-name declaration (the Config-namespace idiom documents the plugin once).
+- `declare module` / `declare global` bodies and `export … from` re-export statements are skipped: an augmentation is not an export of the package, and a re-exported definition is checked where it is defined. An `export import X = N.member` alias documents ITSELF — its target may be a non-exported namespace member no walk visits — and only prose-only target kinds are gate-supported: a callable, class, or namespace target carries signature/member contracts the alias prose cannot hold, so the gate refuses it and demands the declaration be exported directly.
+- Everything else fails CLOSED: `export =` is refused outright, parameters the base never names keep their `@param` duty even as binding patterns, and an exported statement kind the dispatch does not recognize is itself a violation — no export form can pass unchecked by omission.
+
+Three exemption families keep the gate from demanding boilerplate, in the spirit of the cordis gate's `this`/`next` exemptions (documenting an exempt name anyway is allowed; only absence goes unchecked):
+
+- **Heritage members.** A class member whose name exists on an `extends`/`implements` heritage type is exempt: the seam declaration is the doc's one home, and the IDE inherits it on hover — re-documenting every `LocalBashExecutor.run` invites drift. The exemption stops where the override grows surface the base never documented: a protected-only base member does not exempt a public override, parameters the base never names keep their `@param` duty (an underscore-prefixed rename of a base parameter — the deliberately-unused marker — is the same parameter), and a concrete result above a void base return keeps its `@returns` duty (an unannotated override's inferred return is classified by the checker, so a faithful void override needs no boilerplate annotation). Heritage lookups and that one return classification are the walk's only TYPE CHECKER questions (heritage types live across package boundaries, resolved through the repo `paths` map); everything else stays pure AST, and the annotated-return requirement is kept for symmetry with the cordis gate (it bound nothing at adoption — every exported function was already annotated).
+- **Plugin-protocol slots.** Top-level `name` / `inject` / `reusable` / `Config` consts and the `apply` entry, plus the same slots as statics on a plugin class, are framework protocol: their shape is fixed by cordis, and the module doc comment plus the `interface Config` carry the plugin's real semantics.
+- **Constructors**, mirroring the cordis gate: plugin classes are framework-constructed, and the class doc owns the story.
+
+`collectExportJsdocViolations()` returns the violation list (the CLI exits 1 on non-empty) so the negative-path tests in `packages/core/agent/tests/verify-export-jsdoc.spec.ts` assert on findings directly, driving fixture packages through every rejection and every exemption.
+
+## Alternatives considered
+
+- **eslint-plugin-jsdoc** (`require-jsdoc`/`require-param`/`require-returns`) — covers the mechanical core but cannot express the repo's contract: the heritage-member exemption needs cross-package type resolution, the protocol-slot and namespace-merge idioms are cordis-specific, and the completeness semantics (prose-above-tags, stale-tag errors, aggregate reporting) already have one home in `scripts/jsdoc.ts` shared with the catalog generator. Two subtly different definitions of "documented" is the failure mode this repo's one-home rule exists to prevent.
+- **Extending `gen-cordis-catalog.ts`** — the catalog generator renders a curated surface and gates its freshness; a repo-wide walk has no catalog to render. Sharing the helpers while keeping the walks separate keeps each gate's scope legible.
+- **Enforcing interface/type-alias member docs** — deferred: it would multiply the checked surface for members that are largely self-describing fields, while the seam classes carrying the load-bearing member contracts are already gated. Revisit if member-doc drift shows up in review.
+
+## Consequences
+
+- A new export cannot land undocumented: `verify-export-jsdoc` fails `doc-sync`, which pre-push and CI already run. The 203 gaps found at adoption were filled in the same change, so the gate landed green.
+- Exported functions must annotate return types (universal at adoption, now load-bearing) and use identifier parameters where `@param` must name them.
+- Seam docs are canonical: an implementation inherits its heritage docs, and behavior notes worth keeping on the implementation are additions, not requirements.
+- The gate builds a `ts.Program` (~6s) — the one doc gate that pays for type resolution; acceptable inside `doc-sync`, which already compiles doc snippets.
+- The protocol-slot names are reserved by convention at module top level; a non-protocol export coincidentally named `apply` or `Config` would go unchecked — accepted, documented here.

docs/rfc/implemented/process/2026-07-06-node-engine-floor.md

@@ -0,0 +1,37 @@
+# RFC: Raise the Node LTS engine floor to 22.19
+
+Status: implemented
+
+## Problem
+
+The Node 22 branch of the root `engines.node` range is a contract for the installed workspace, not only for the runtime APIs the harness source calls directly. It must be no lower than package `engines.node` declarations for dependencies the workspace installs on that branch; otherwise `pnpm install --engine-strict` fails at an advertised LTS version, and non-strict installs run outside a dependency's supported runtime.
+
+## Decision
+
+Set `engines.node` to `^22.19.0 || >=24.0.0` and test the keyless CI compatibility matrix on `['22.19', 24, 26]`. The real-API e2e workflow stays on Node 24 because it exercises API integration rather than the runtime floor.
+
+Two Node features gate the source runtime:
+
+- **`node:sqlite`** — `packages/session-persistence/session-persistence-sqlite` does a top-level `import { DatabaseSync } from 'node:sqlite'`. The module dropped its `--experimental-sqlite` flag requirement at **22.13** (LTS) and **23.4** (Current); before those, importing it throws at load.
+- **Native TypeScript type-stripping** — the `packages/ui/stdio-agent/tests/built-bin.e2e.ts` smoke boots the published `lib/bin.js` under plain `node` (no tsx) and loads the example's `.ts` plugins (`mock-llm.ts`, `echo-tool.ts`). Type-stripping is the default from **22.18** (LTS) and **23.6** (Current); before those it needs `--experimental-strip-types`.
+
+Those source features clear on the 22.x line at **22.18**, but the installed Pi adapter dependency raises the advertised LTS floor. `@deepseek-ai/dsh-llm-pi-ai` depends on `@earendil-works/pi-ai@0.79.3`, whose package declares `engines.node >=22.19.0`, so the LTS floor is **22.19**. The 24.x branch remains `>=24.0.0`. The disjoint range excludes Node 23 entirely: Node 23.0–23.5 still has at least one flagged source feature, and the 23 line is non-LTS/EOL, so advertising `>=23.6` would add a dead release line and a CI leg no deployment should use.
+
+`@types/node` remains pinned to the 22.x line (`^22.20.0`) to match the LTS support line: reaching for a Node 23+/24+/25+ API fails `tsc` on every machine and in the typecheck gate, rather than compiling clean and surviving to a runtime failure only a floor matrix leg could catch. The whole tree typechecks clean against the Node 22 type surface today, so the pin costs nothing.
+
+## Consequences
+
+- The advertised LTS branch no longer undercuts the Pi adapter dependency floor.
+- CI proves the Node 22 LTS floor directly with Node 22.19, keeps the Node 24 branch on `node: 24`, and keeps Node 26 for the next even line.
+- The built-bin smoke needs no version-conditional flag: at 22.19 type-stripping is already the default, so the test stays the plain `node lib/bin.js` path it documents.
+- A future dependency or source API that raises the runtime floor must move `engines.node`, the compatibility matrix, and this RFC in the same change.
+
+## Alternatives considered
+
+- **Keep `^22.18.0 || >=24.0.0`.** Rejected: it advertises an LTS version lower than the Pi adapter dependency floor. `@earendil-works/pi-ai@0.79.3` requires `>=22.19.0`.
+- **Downgrade or pin `@earendil-works/pi-ai` to preserve the 22.18 advertised range.** Rejected: the current Pi adapter dependency is part of the intended workspace, and 22.19 is still inside the Node 22 LTS line.
+- **Floor `>=22.13` (the `node:sqlite` boundary) plus `--experimental-strip-types` in the built-bin smoke on 22.13–22.17.** Rejected: it adds a version-conditional test flag for one narrow range and dresses up an experimental-flag dependency as first-class support. The Pi adapter dependency already requires a higher LTS floor.
+- **Open-ended `>=22.19`.** Rejected: it advertises support for Node 23.0–23.5, where `node:sqlite` (until 23.4) or type-stripping (until 23.6) is still flagged.
+- **Include Node 23.6+ (`^22.19.0 || >=23.6.0`).** Rejected: 23.6+ does run both source features unflagged, but Node 23 is end-of-life; advertising a dead release line adds a range term and a CI leg for a runtime no deployment should use.
+- **Matrix `[22, 24, 26]` instead of pinning `22.19`.** Rejected: floating major-version entries drift upward over time and silently stop exercising the declared LTS floor.
+- **Keep `@types/node` ahead of the floor (`^25`).** Rejected: types ahead of the runtime floor let a Node 24/25-only API compile clean and fail only at runtime on 22.x. Pinning `@types/node` to the 22.x line turns that into a compile error everywhere.

docs/rfc/implemented/testing/2026-06-19-real-api-e2e-ci.md

@@ -54,7 +54,7 @@ The repo secret is named `DEEPSEEK_API_KEY_EXTERNAL`; it is mapped to the `DEEPS
 
 ### Scope, runtime shape
 
-Run **only** `test:e2e`. The keyless gates (typecheck/lint/coverage/snapshot/build/hygiene) already run in ci.yml on every push and PR; repeating them here would duplicate signal and slow the real-API job. No build step — e2e tests run unbuilt via tsx + the tsconfig paths map. Single Node 24 (the `engines` floor): these tests exercise *API integration*, not node-version compat, which ci.yml's Node 24/26 jobs already own; a second Node version would double real-API calls for no added signal. `vitest.e2e.config.ts` runs files through a bounded worker pool (`DSH_E2E_MAX_WORKERS`, default `4`, CI value `14`) so CI and local with-key runs parallelize independent files while retaining a one-line serial escape hatch for quota investigations. `timeout-minutes: 45` bounds a wedged run given 120s/test and `retry: 2`. `cancel-in-progress` is enabled only for `pull_request` runs — a superseded PR run is on a stale commit and worth cancelling, whereas a push/schedule run is already producing the post-merge/nightly signal and is never cancelled.
+Run **only** `test:e2e`. The keyless gates (typecheck/lint/coverage/snapshot/build/hygiene) already run in ci.yml on every push and PR; repeating them here would duplicate signal and slow the real-API job. No build step — e2e tests run unbuilt via tsx + the tsconfig paths map. Single Node 24 (the primary line): these tests exercise API integration, not node-version compatibility, which ci.yml's Node 22.19/24/26 matrix owns. `vitest.e2e.config.ts` runs files through a bounded worker pool (`DSH_E2E_MAX_WORKERS`, default `4`, CI value `14`) so CI and local with-key runs parallelize independent files while retaining a one-line serial escape hatch for quota investigations. `timeout-minutes: 45` bounds a wedged run given 120s/test and `retry: 2`. `cancel-in-progress` is enabled only for `pull_request` runs — a superseded PR run is on a stale commit and worth cancelling, whereas a push/schedule run is already producing the post-merge/nightly signal and is never cancelled.
 
 ## Security
 

docs/rfc/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md

@@ -0,0 +1,87 @@
+# RFC: Claude Code and Codex subagent backends (out-of-process delegation to external coding agents)
+
+Status: proposed
+
+## Problem
+
+The subagent seam ([the seam RFC](../../implemented/feature/2026-06-21-subagent-capability-seam.md)) hosts multiple named providers on `ctx.subagents`, and the ACP backend ([the ACP backend RFC](../../implemented/feature/2026-06-22-acp-subagent-backend.md)) proved the seam generalizes across a process boundary; its Future-providers section explicitly named the Codex app-server and the Claude Code Agent SDK as mechanically similar siblings. Those two are the engines actually worth delegating to today: a harness turn should be able to hand a self-contained task to a real Claude Code or a real Codex — a separate product with its own model, tools, and sandbox — and get back one final answer, without the parent deployment leaking its secrets into the child or the child's behavior silently depending on whatever `~/.claude` / `~/.codex` state exists on the host machine.
+
+## Proposal
+
+Two sibling provider packages, structural variants of the ACP backend, plus one extraction:
+
+- `@deepseek-ai/dsh-subagent-claude-code` — drives a Claude Code child through `@anthropic-ai/claude-agent-sdk`'s `query()` (the SDK runs in the parent process and spawns its bundled `claude` CLI as the subprocess). Provider name `claude-code`: the child is the Claude Code *product*, not an Anthropic model adapter — "claude" stays reserved for a future `dsh-llm` adapter.
+- `@deepseek-ai/dsh-subagent-codex` — spawns `codex app-server` and drives one thread/turn over its JSON-RPC-over-stdio protocol with a hand-rolled newline-JSON client (~200–300 lines) in the package.
+- `@deepseek-ai/dsh-subagent-process` — a pure library (the `subagent-inprocess` precedent) extracting what `dsh-subagent-acp` already carries and both new backends need: the credential env scrub (`SENSITIVE_ENV_PATTERN`/`buildChildEnv`), the EOF → SIGTERM → SIGKILL dispose ladder, and new isolated-config-dir helpers (`mkdtemp` create, best-effort remove). The ACP backend migrates onto it; `bash-local`'s sibling copy is left alone to bound the change.
+
+Both providers copy the ACP backend's seam posture verbatim: fresh child per `start`, exactly one prompt round-trip, capabilities all `false`, `inheritsParentContext: false`, `request.parent`/`request.agentOptions` ignored, `id = AgentId(randomUUID())`, `result` never rejects — child-level failure flattens to a stop reason and the original error goes to `ctx.logger` via an `onError` spec callback. Model exposure is zero new code: `dsh-tool-subagent` is loaded once per provider with a distinct `toolName` (`subagent_claude_code`, `subagent_codex`). No new session events are needed — the only model-visible artifact is the tool result, so reconstructability holds exactly as it did for ACP. To be explicit about the boundary: the session log reconstructs the model-visible transcript, not workspace mutation history — a child granted write access mutates files as an ambient side effect outside the log, exactly as the bash tools and the ACP backend already do; replay reproduces requests, not the disk.
+
+## Verified interface facts (pinned versions)
+
+Both integration surfaces were verified against pinned implementations before this proposal — types and bundled source read, keyless spikes run — not from vendor docs alone. The pins are the verification baseline, not a runtime contract: the backends perform no runtime version probe (no `codex --version` gate, no SDK version sniffing). Compatibility is enforced at development time — every dependency bump re-runs the keyless suites against the real load path — and at runtime by failing loudly: a protocol-level surprise settles `error` via `onError`, never a silent misbehavior.
+
+**`@anthropic-ai/claude-agent-sdk` 0.3.202.** `options.env` REPLACES the child environment (no merge with `process.env`), which is exactly what the scrub needs. `settingSources` defaults to loading ALL filesystem settings — isolation requires explicitly passing `[]`. Result subtypes are `success` | `error_during_execution` | `error_max_turns` | `error_max_budget_usd` | `error_max_structured_output_retries`. On abort the SDK escalates the CLI child itself: stdin EOF immediately, SIGTERM ~2s later if the child ignores it (observed; no leftover processes) — no bespoke kill fallback needed. `outputFormat: {type: 'json_schema'}` and an `agents` option exist, giving future landing points for the seam's `outputSchema` capability and named subagent types; both are out of scope here.
+
+**codex CLI 0.142.5, `codex app-server` (v2 vocabulary).** LF-delimited JSON, JSON-RPC 2.0 shapes with the `"jsonrpc"` header omitted.
+
+- Lifecycle: `initialize{clientInfo}` + `initialized` → `thread/start` (accepts `cwd`, `model`, `sandbox`, `approvalPolicy`, `ephemeral`; succeeds unauthenticated) → `turn/start{threadId, input:[{type:'text',text}]}` returns an `inProgress` turn immediately; the terminal signal is the `turn/completed` notification carrying `Turn{status: completed|interrupted|failed|inProgress, error}`.
+- Approvals are server-initiated requests — `item/commandExecution/requestApproval`, `item/fileChange/requestApproval`, `item/permissions/requestApproval`, `item/tool/requestUserInput`, `mcpServer/elicitation/request` — answered with `accept`/`decline`-family decisions.
+- Auth: `account/login/start{type:'apiKey', apiKey}` is a first-class RPC and `account/read` reports `requiresOpenaiAuth` — and an unauthenticated `turn/start` does NOT fail fast (it hangs in retry), so the backend MUST pre-check auth and settle `error` loudly instead of waiting on the turn.
+- Isolation: `CODEX_HOME` redirection is honored (the `initialize` response echoes it, so tests can assert isolation), and `ephemeral: true` threads leave no session files at all.
+
+## Isolation and credentials
+
+Deployments authenticate with API keys only, and the child must not see the host user's Claude Code / Codex configuration: behavior has to be a function of `cordis.yml` alone. Each run gets a fresh `mkdtemp` config dir — `CLAUDE_CONFIG_DIR` for Claude Code (paired with an explicit `settingSources: []`), `CODEX_HOME` for Codex — removed best-effort on dispose; a config field can pin a persistent dir instead. The child env reuses the ACP backend's `buildChildEnv` semantics verbatim via the extraction: the ambient env is forwarded MINUS credential-shaped vars (`/KEY|SECRET|TOKEN/i`), with `config.env` layered on top — so `PATH`, `HOME`, `TMPDIR`, locale, and proxy vars survive and the CLIs run normally, while only credential-shaped ambient vars are scrubbed (`ANTHROPIC_API_KEY` enters explicitly through `config.env` for Claude Code), and the Codex key travels via the `account/login/start` RPC into the isolated `CODEX_HOME` rather than a hand-written `auth.json`.
+
+## Permission and approval policy
+
+Instead of collapsing to ACP's single `permission: allow|reject` knob, each backend exposes its engine's native vocabulary as config, with conservative defaults: Claude Code gets `permissionMode` (default `default`) plus `permission: allow|reject` (default `reject`) as the `canUseTool` auto-answer for whatever falls through; Codex gets `sandboxMode` (default `read-only`) and `approvalPolicy` (default `never`) plus the same `permission` fallback for approval requests that still arrive. Defaults are deliberately do-no-harm (the out-of-box child cannot write files); examples demonstrate opening up (`acceptEdits` / `workspace-write`). The mechanical rule: EVERY server-initiated request is settled programmatically and promptly — the enumerated approval/user-input/elicitation requests by the configured policy, an unknown request method with a JSON-RPC method-not-found error response (never left pending), unknown notifications consumed — so no child request can wedge a turn waiting on an answer that will never come. Prompts never reach a human in this cut, matching ACP.
+
+## StopReason mapping
+
+Claude Code: `success` → `completed`; `error_max_turns`, `error_during_execution`, `error_max_budget_usd`, `error_max_structured_output_retries` → `error` (aligning with the ACP call on `max_turn_requests`: an unfinished task is not success); generator abort → `aborted`; anything unknown → `error`. Codex: `Turn.status` `completed` → `completed`; `interrupted` → `aborted`; `failed` with `codexErrorInfo: 'contextWindowExceeded'` → `max-tokens`, any other `failed` → `error`; transport/spawn/auth-precheck failure → `error` (or `aborted` if cancel was requested). In both, `cancel()` is the ACP shape: flag + abort/interrupt + a cancel-settled race arm so an uncooperative child cannot stall the result.
+
+Liveness posture, stated explicitly: teardown timing is config, turn duration is not. Both backends take the dispose ladder's grace periods as defaulted validated config fields (the ACP backend's `disposeEofGraceMs`/`disposeGraceMs` shape, carried by the extraction), but there is deliberately NO turn-duration or startup timeout — matching ACP, liveness during a turn belongs to the caller via `cancel()`/the abort signal, a subagent turn is legitimately minutes long, and the Codex auth precheck removes the one verified guaranteed-hang; a deployment wanting a wall-clock bound cancels from the parent.
+
+## Testing
+
+Named at every tier per the root AGENTS.md rule, and de-risked up front:
+
+- **Keyless unit/integration**, mirroring the ACP spec list per backend (round-trip and output accumulation, every stop mapping, both cancel paths, already-aborted, permission auto-answer under both policies, unknown-message tolerance, bad-command spawn failure, HMR provider cleanup, export shape, isolation assertions on child env and temp-dir removal; Codex adds the auth-precheck failure path). Claude Code's harness is a scripted fake `claude` executable behind `pathToClaudeCodeExecutable` driven by the REAL SDK — a spike already passed end-to-end keyless in 24ms (the fake CLI answers one `control_request/initialize` and speaks plain stream-json, ~40 lines). Codex's harness is a scripted mock app-server subprocess speaking the verified wire protocol, the `mock-acp-server.ts` shape.
+- **With-key e2e** per backend: the real engine does real file work verified on disk, under a pinned opened-up config so acceptance and the do-no-harm defaults don't collide — `permissionMode: 'acceptEdits'` for Claude Code, `sandboxMode: 'workspace-write'` + `approvalPolicy: 'never'` for Codex; self-skips report exactly what is missing (binary vs key). CI has no secrets, so these run locally per the with-key policy.
+- **Snapshot**: deferred as `TODO(claude-code-subagent-replay)` / `TODO(codex-subagent-replay)` — the same distinct replay shape the ACP backend deferred ([the per-session replay RFC](../../implemented/testing/2026-06-22-subagent-snapshot-replay.md)); the keyless suites carry deterministic coverage meanwhile.
+
+## Alternatives considered
+
+### Why not the official `@openai/codex-sdk` instead of a hand-rolled client?
+
+The dispose ladder and env scrub require owning the child process (spawn args, env, signals, exit await); the SDK hides the process. The wire format is trivial to frame (LF JSON), the shapes are generatable per pinned version (`codex app-server generate-json-schema`), and the repo precedent (`hook-protocol`) is to own thin protocol cores rather than wrap someone's runtime. The SDK would save protocol-evolution maintenance but costs the exact control this backend exists to have.
+
+### Why not a model-visible `subagent_type` parameter (one Task-style tool)?
+
+Claude Code's own Task tool puts the subagent type in the model-facing schema, selecting a prompt-plus-toolset persona. Here the choice is between EXECUTION ENGINES, and only the deployer knows which engines have credentials configured — so selection stays deployment config, preserving `dsh-tool-subagent`'s documented one-provider-per-tool contract. A persona-style type selector would be a separate RFC against the tool, not the backends.
+
+### Why not login-state credentials and the user's own config?
+
+Inheriting `~/.claude` / `~/.codex` (subscription login, user settings, skills, MCP servers) would make child behavior depend on host-machine state and punch an implicit exception through the "credentials enter explicitly via `config.env`, never ambiently" rule the ACP backend and bash executor established. API-key-only plus forced config-dir isolation keeps runs reproducible; deployments wanting shared state can point the config-dir field at a persistent directory deliberately.
+
+### Why not a driver-injection seam for the Claude Code keyless tests?
+
+Injecting a fake `query()` would mock our own boundary and leave the real SDK load path untested (the real-over-mock policy in docs/testing.md). The risk that justified considering it — the SDK↔CLI stream-json control protocol being internal — was retired by the spike: the fake-CLI harness works against the real pinned SDK today. If an SDK upgrade breaks the mock, the keyless suite fails the upgrade PR, which is the gate working.
+
+### Why not ACP adapters (e.g. `claude-code-acp`) reusing the existing backend?
+
+Community shims wrap both engines in ACP, which would make them "just config" on `dsh-subagent-acp`. But that inserts an unofficial third-party layer between the harness and the engine, erases the native control surfaces this RFC exposes (permissionMode, sandboxMode/approvalPolicy, config-dir isolation, apiKey RPC), and trades first-party protocol stability for a shim's release cadence. First-party surfaces — the Agent SDK and the app-server — are the supported integration points.
+
+## Acceptance criteria
+
+On a machine with both engines and keys configured: a REPL-driven model completes one real file task through `subagent_claude_code` and one through `subagent_codex`, the tool result being the child's final answer, with only `tool/call` + `tool/result` in the parent session log. Keyless suites pass at 100% per-file coverage in a credential-less environment, asserting isolation (scrubbed child env, no temp config dirs left after dispose) and that child behavior is unchanged by the presence or absence of `~/.claude` / `~/.codex`. Cancelling a parent turn quiesces both backends in bounded time with no leftover child processes. E2e suites self-skip cleanly, naming the missing prerequisite.
+
+## Risks
+
+- `codex app-server` is CLI-flagged experimental and its v1/v2 vocabularies coexist; the client pins 0.142.5, implements v2 only, and consumes unknown methods/notifications without crashing, but a future codex bump can still force rework (regenerate schemas and re-run the keyless suite on every bump — the development-time enforcement behind the no-runtime-version-probe stance above).
+- The Claude Code fake-CLI mock rides an internal protocol: any SDK upgrade must go through the keyless suite, and a breaking control-protocol change means reworking the mock (fallback: the driver-injection seam rejected above becomes the escape hatch).
+- The SDK's optionalDependencies weigh ~280MB per platform — accepted, and confined to the one backend package.
+- The SDK's SIGKILL branch beyond EOF→SIGTERM was not observed and is trusted; e2e keeps a no-leftover-process assertion.
+- Codex is a deployment prerequisite (no npm-bundled binary); a missing or incompatible binary surfaces as a loud spawn/protocol `error`, not a version probe.
+- Every run pays a fresh child process and only the final answer surfaces — thoughts, tool cards, and usage are consumed and dropped; pooling, intermediate-progress surfacing, `sendMessage`/`resume`, `outputSchema` via the SDK's `outputFormat`, and named subagent types via the SDK's `agents` option are all deliberate deferrals.

package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "packageManager": "pnpm@11.7.0",
   "engines": {
-    "node": ">=24"
+    "node": "^22.19.0 || >=24.0.0"
   },
   "workspaces": [
     "vendor/*",
@@ -47,6 +47,7 @@
     "gen-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts",
     "gen-rfc-index": "tsx scripts/gen-rfc-index.ts",
     "verify-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts --check",
+    "verify-export-jsdoc": "tsx scripts/verify-export-jsdoc.ts",
     "gen-tool-catalog": "tsx scripts/gen-tool-catalog.ts",
     "verify-tool-catalog": "tsx scripts/gen-tool-catalog.ts --check",
     "gen-config-catalog": "tsx scripts/gen-config-catalog.ts",
@@ -58,7 +59,7 @@
     "gen-module-graph": "tsx scripts/gen-module-graph.ts",
     "verify-module-graph": "tsx scripts/gen-module-graph.ts --check",
     "constraints": "tsx scripts/check-workspace-constraints.ts",
-    "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets",
+    "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets",
     "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types",
     "demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml",
     "demo:repl": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml",
@@ -70,7 +71,7 @@
     "@stylistic/eslint-plugin": "^5.10.0",
     "@types/jsdom": "^28.0.3",
     "@types/mdast": "^4.0.4",
-    "@types/node": "^25.3.5",
+    "@types/node": "^22.20.0",
     "@vitest/coverage-v8": "^4.1.8",
     "eslint": "^10.4.1",
     "fast-check": "^4.8.0",

packages/bash/bash-local/src/run.ts

@@ -56,6 +56,8 @@ export const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i
  * 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.
  */
 export function childEnv(extra?: Record<string, string>): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = {}
@@ -147,6 +149,14 @@ export class OutputCollector {
     private readonly spillDir: string,
   ) {}
 
+  /**
+   * Ingest one stream chunk, counting it toward the whole-stream total. On
+   * first overflow of the in-memory cap a spill file is opened and every chunk
+   * (already-collected ones included) is appended there from then on; the
+   * in-memory tail then drops whole chunks from its head (or the head of a
+   * single over-cap chunk) until it fits the cap again.
+   * @param chunk - the raw bytes from one stream 'data' event.
+   */
   push(chunk: Buffer): void {
     this.total += chunk.length
     const overflows = this.bytes + chunk.length > this.maxBytes
@@ -190,7 +200,10 @@ export class OutputCollector {
   // the bottom of this file) and `totalBytes` is read only by a test. The live
   // background-poll path goes through `readFrom()`, so inline snapshot() into
   // finalize() and drop or privatize the totalBytes getter.
-  /** Read the collected tail without finalizing (the final-result snapshot). */
+  /**
+   * Read the collected tail without finalizing (the final-result snapshot).
+   * @returns the retained tail text, the truncation flag, and the spill path when one was created.
+   */
   snapshot(): CollectedOutput {
     return {
       text: Buffer.concat(this.chunks).toString('utf8'),
@@ -209,6 +222,8 @@ export class OutputCollector {
    * pushed since `fromByte`. When `fromByte` has already slid out of the
    * in-memory tail window, the read is `lossy` — it returns the whole
    * retained tail and the gap is only recoverable from the spill file.
+   * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 for the first read).
+   * @returns the delta text, the offset for the next read, the `lossy` flag, and the spill path when one was created.
    */
   readFrom(fromByte: number): { text: string; nextOffset: number; lossy: boolean; spillPath?: string } {
     const windowStart = this.total - this.bytes
@@ -223,7 +238,12 @@ export class OutputCollector {
     }
   }
 
-  /** Close the spill file (if any) and return the final output. */
+  /**
+   * Close the spill file (if any) and return the final output. A failed close
+   * (delayed writeback fault) stops advertising the spill path — the file may
+   * be missing its tail — but still returns the in-memory result.
+   * @returns the final collected output: tail text, truncation flag, and the spill path when intact.
+   */
   finalize(): CollectedOutput {
     if (this.spillFd !== undefined) {
       try {
@@ -249,6 +269,8 @@ export class OutputCollector {
  * 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).
+ * @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.
  */
 export function killGroup(pid: number, sig: NodeJS.Signals): void {
   if (pid <= 0) return
@@ -290,6 +312,9 @@ export interface RunningBash {
  * 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()`.
  */
 export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningBash {
   const spillDir = internals.spillDir ?? privateSpillDir()

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

@@ -40,12 +40,14 @@ async function readUntil(
 ): Promise<BashTaskRead> {
   const deadline = Date.now() + timeoutMs
   let last: BashTaskRead | undefined
+  let delta = ''
   while (Date.now() < deadline) {
     last = bash.readOutput(id)
-    if (last.delta.includes(expected)) return last
+    delta += last.delta
+    if (delta.includes(expected)) return { ...last, delta }
     await new Promise(resolve => setTimeout(resolve, 20))
   }
-  throw new Error(`task ${id} output did not include ${JSON.stringify(expected)}; last delta was ${JSON.stringify(last?.delta ?? '')}`)
+  throw new Error(`task ${id} output did not include ${JSON.stringify(expected)}; output was ${JSON.stringify(delta)}, last delta was ${JSON.stringify(last?.delta ?? '')}`)
 }
 
 describe('LocalBashExecutor.run', () => {
@@ -90,8 +92,8 @@ describe('LocalBashExecutor.run', () => {
 
   it('kill escalation uses the configured graceMs (a TERM-trapping task dies by SIGKILL)', async () => {
     const { bash } = await setup() // setup pins graceMs: 200 via config
-    const task = bash.start(bash.resolve({ command: 'trap \'\' TERM; sleep 60' }))
-    await new Promise(resolve => setTimeout(resolve, 100))
+    const task = bash.start(bash.resolve({ command: 'trap \'\' TERM; echo trap-ready; sleep 60' }))
+    await readUntil(bash, task.id, 'trap-ready')
     bash.kill(task.id)
     await task.done
     expect(task.signal).toBe('SIGKILL')

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

@@ -1,4 +1,4 @@
-import { mkdtempSync, readFileSync, statSync } from 'node:fs'
+import { existsSync, mkdtempSync, readFileSync, statSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
@@ -56,6 +56,15 @@ async function waitForStdout(running: RunningBash, expected: string, timeoutMs =
   throw new Error(`stdout did not include ${JSON.stringify(expected)} after ${timeoutMs}ms`)
 }
 
+async function waitForFile(file: string, timeoutMs = 5_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    if (existsSync(file)) return
+    await new Promise(resolve => setTimeout(resolve, 20))
+  }
+  throw new Error(`${file} did not exist after ${timeoutMs}ms`)
+}
+
 describe('runBash', () => {
   it('captures stdout on success', async () => {
     const result = await runBash(spec('echo hello')).done
@@ -119,7 +128,7 @@ describe('runBash', () => {
     // group must take the sleep down with bash.
     const pidFile = join(spillDir, `grandchild-${Date.now()}.pid`)
     const running = runBash(spec(`sleep 60 & echo $! > ${pidFile}; wait`))
-    await new Promise(resolve => setTimeout(resolve, 300))
+    await waitForFile(pidFile)
     const grandchild = Number(readFileSync(pidFile, 'utf8').trim())
     expect(grandchild).toBeGreaterThan(0)
 

packages/bash/bash/src/types.ts

@@ -11,7 +11,11 @@ import type { Branded } from '@deepseek-ai/dsh-brand'
 /** Identifies one background task within an executor (generated `bash-N`). */
 export type BashTaskId = Branded<'BashTaskId'>
 
-/** Brand a string as a {@link BashTaskId}. */
+/**
+ * Brand a string as a {@link BashTaskId}.
+ * @param id - the raw task-id string (the executor generates `bash-N`).
+ * @returns the same string, branded; no validation is performed.
+ */
 export function BashTaskId(id: string): BashTaskId {
   return id as BashTaskId
 }
@@ -26,7 +30,12 @@ export function BashTaskId(id: string): BashTaskId {
  */
 export type OwnerToken = Branded<'OwnerToken'>
 
-/** Brand a string as an {@link OwnerToken}. */
+/**
+ * Brand a string as an {@link OwnerToken}. Only the consuming boundary
+ * (`dsh-tool-bash`) should cast its own id vocabulary in — see the type's doc.
+ * @param id - the consumer's raw owner identity (the tool layer passes the owning agent's session id).
+ * @returns the same string, branded; no validation is performed.
+ */
 export function OwnerToken(id: string): OwnerToken {
   return id as OwnerToken
 }

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

@@ -99,6 +99,8 @@ function streamText(output: CollectedOutput): string {
  * stderr section, then exit-status markers. Non-zero exits are REPORTED, not
  * errored — the model decides how to react; only infrastructure failures
  * (spawn errors, aborts) surface as isError results.
+ * @param result - the completed foreground run from the executor.
+ * @returns the model-facing text: output body (or `(no output)`), then any timeout/signal/exit markers, each on its own line.
  */
 export function renderResult(result: BashRunResult): string {
   const out = streamText(result.stdout)

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

@@ -216,6 +216,11 @@ export class BasicCompactService extends CompactService {
    * Estimate the token count of content blocks — chars divided by the
    * `charsPerToken` config, with per-block overhead. Override in a subclass to
    * plug in a real tokenizer.
+   *
+   * @param blocks - the blocks to estimate; `tool-result` blocks recurse into
+   *   their nested content, and unknown (merge-extended) types fall back to
+   *   their JSON-stringified length.
+   * @returns the estimated token count.
    */
   estimateContentTokens(blocks: readonly ContentBlock[]): number {
     const { charsPerToken } = this.config
@@ -246,6 +251,11 @@ export class BasicCompactService extends CompactService {
   /**
    * Estimate token count for a single session event. Returns 0 for non-message
    * event types (boundaries, chunks, usage, errors, compact markers).
+   *
+   * @param event - any session event; only the message-bearing types carry
+   *   content to count.
+   * @returns the estimated token count of the event's content, or 0 for a
+   *   non-message event.
    */
   estimateEventTokens(event: SessionEvent): number {
     switch (event.type) {
@@ -260,7 +270,14 @@ export class BasicCompactService extends CompactService {
     }
   }
 
-  /** Estimate total tokens across a list of messages plus optional system prompt. */
+  /**
+   * Estimate total tokens across a list of messages plus optional system prompt.
+   *
+   * @param messages - the derived conversation messages; each adds a fixed
+   *   role-framing overhead on top of its content estimate.
+   * @param systemPrompt - counted at chars / `charsPerToken` when provided.
+   * @returns the estimated token footprint of the whole request.
+   */
   estimateTokens(messages: readonly Message[], systemPrompt?: string): number {
     let total = 0
     for (const msg of messages) {
@@ -293,6 +310,13 @@ export class BasicCompactService extends CompactService {
    * used (`model`, `maxTokens`) — the caller logs the envelope on the
    * `compact/summary` provenance event, so an overriding subclass (template
    * or remote summarizer) reports its own envelope honestly.
+   *
+   * @param text - plain-text rendering of the conversation region to condense.
+   * @param agent - supplies the fallback model and the session id stamped on
+   *   the call; throws when neither it nor the config names a model.
+   * @param signal - optional abort signal, forwarded into the model call.
+   * @returns the text-only summary blocks plus the call envelope used
+   *   (`model`, and `maxTokens` when the summarizer has a cap).
    */
   async summarize(
     text: string, agent: Agent, signal?: AbortSignal,

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

@@ -54,6 +54,9 @@ export type ResolvedConfig = Required<BasicCompactConfig>
  * 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.
  */
 export function resolveConfig(config: BasicCompactConfig): ResolvedConfig {
   const resolved: ResolvedConfig = { auto: true, charsPerToken: 4, ...config }

packages/core/agent-core/README.md

@@ -35,11 +35,11 @@ This is the [interface/implementation/consumer seam](../../../docs/rfc/implement
 
 ```ts
 import type { Config } from '@deepseek-ai/dsh-agent-core'
-// { agents?, persona? } — the schema is z.intersect([AgentLoop.Config, SystemPrompt.Config]),
+// { agents?, persona?, toolOrder? } — the schema is z.intersect([AgentLoop.Config, SystemPrompt.Config]),
 // so validation and defaulting can never drift from the owners'.
 ```
 
-The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — and `persona` to `dsh-system-prompt` (default `''`), the deployment's persona section. Forwarding is exactly why the owners can live in the shared spine even though the apps disagree on what to configure.
+The bundle FORWARDS each field to the child that owns it: `agents` to `agent-loop` (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`) — `persona` to `dsh-system-prompt` (default `''`), the deployment's persona section — and `toolOrder` to `dsh-system-prompt` (absent — lexicographic), the explicit model-facing tool order. Forwarding is exactly why the owners can live in the shared spine even though the apps disagree on what to configure.
 
 ## Why a code bundle, not a shared YAML include
 

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

@@ -59,17 +59,20 @@ export const name = 'agent-core'
 /**
  * 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` to the system-prompt plugin (the
- * deployment's persona section). Both are optional INPUT here because each
- * owner's schema supplies the default (`[]` / `''`); the schema is the
- * INTERSECTION of the owners' own schemas, so validation and defaulting can
- * never drift from them.
+ * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
+ * plugin (the deployment's persona section and the explicit model-facing tool
+ * order). Every field is optional INPUT here because each owner's schema
+ * supplies the default (`[]` / `''` / absent — lexicographic); the schema is
+ * the INTERSECTION of the owners' own schemas, so validation and defaulting
+ * can never drift from them.
  */
 export interface Config {
   /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
   agents?: AgentLoopConfig['agents']
   /** The deployment persona (see dsh-system-prompt's `Config`). */
   persona?: SystemPromptConfig['persona']
+  /** The explicit model-facing tool order (see dsh-system-prompt's `Config`). */
+  toolOrder?: SystemPromptConfig['toolOrder']
 }
 
 /** Intersect the owners' schemas so validation + defaulting stay identical. */
@@ -78,11 +81,11 @@ export const Config = z.intersect([AgentLoop.Config, SystemPrompt.Config]) as un
 /**
  * Load the spine. Each `ctx.plugin(...)` mounts one child of the bundle fiber;
  * `agent-loop` receives the forwarded `agents` list and `system-prompt` the
- * forwarded `persona`. Load order is irrelevant (cordis pends each fiber on
- * its `inject` until the services it needs exist), but the listing mirrors the
- * dependency layering for readability: the LLM vocabulary and core registries
- * first, then the dev tripwire and the bash tool consumer, then the loop that
- * drives them.
+ * forwarded `persona` and `toolOrder`. Load order is irrelevant (cordis pends
+ * each fiber on its `inject` until the services it needs exist), but the
+ * listing mirrors the dependency layering for readability: the LLM vocabulary
+ * and core registries first, then the dev tripwire and the bash tool consumer,
+ * then the loop that drives them.
  */
 export function apply(ctx: Context, config: Config): void {
   ctx.plugin(Timer)
@@ -91,8 +94,13 @@ export function apply(ctx: Context, config: Config): void {
   // 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.
-  ctx.plugin(SystemPrompt, { persona: config.persona ?? '' })
+  // introduce different ones. toolOrder has no owner-supplied default value —
+  // ABSENT means "lexicographic order" — so it is forwarded conditionally
+  // rather than via ??.
+  ctx.plugin(SystemPrompt, {
+    persona: config.persona ?? '',
+    ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
+  })
   ctx.plugin(ToolRegistry)
   ctx.plugin(AgentRegistry)
   ctx.plugin(invariants)

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

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
+import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import * as agentCore from '../src/index.ts'
 import { AgentId } from '@deepseek-ai/dsh-agent'
 
@@ -67,6 +68,23 @@ describe('dsh-agent-core bundle', () => {
     await ctx.fiber.dispose()
   })
 
+  it('forwards toolOrder to the system-prompt assembly', async () => {
+    const ctx = await mount({ toolOrder: ['zulu', TOOL_ORDER_REST] })
+    // The bundle's own bash tools pend on the absent `ctx.bash` executor in
+    // this providerless mount, so register two plain tools to order.
+    for (const name of ['alpha', 'zulu']) {
+      ctx.get('tools')!.register({
+        name,
+        description: name,
+        parameters: {},
+        execute: async () => [],
+      })
+    }
+    const assembly = await ctx.get('systemPrompt')!.assemble()
+    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha'])
+    await ctx.fiber.dispose()
+  })
+
   it('re-exports the loop config schema as its own', () => {
     expect(agentCore.Config).toBeDefined()
     expect(agentCore.name).toBe('agent-core')

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

@@ -22,6 +22,10 @@ import { isTurnOpen, lastTurnNumber, runLoop } from './loop.ts'
  * the agent/* event taxonomy — plugins never need this class.
  */
 export class ReactLoopAgent implements Agent {
+  /**
+   * The queued + steering FIFOs behind {@link send}/{@link steer}. Public so
+   * the driver loop can drain it; {@link cancel} clears it wholesale.
+   */
   readonly inbox = new Inbox()
 
   private _status: AgentStatus = 'idle'
@@ -256,6 +260,8 @@ export class ReactLoopAgent implements Agent {
    * promise (unblocking the idle wait), releases any `whenIdle` waiters, and
    * aborts the current request if any. The returned `agent.done` promise
    * resolves once the loop exits.
+   * @returns the disposer — idempotent and infallible (it runs inside the
+   *   fiber's LIFO disposal chain, where a throw would skip later disposers).
    */
   start(): () => void {
     this.done = runLoop(this.ctx, this, {

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

@@ -24,30 +24,47 @@ export class Inbox {
   private steeringMessages: InboxMessage[] = []
   private wakeup: (() => void) | undefined
 
-  /** Resolves when a queued message arrives (used by the idle loop). */
+  /** True while queued messages are pending — read by the idle wait's fast path and the loop's turn-start checks. */
   get hasQueued(): boolean {
     return this.queuedMessages.length > 0
   }
 
+  /** True while steering messages are pending — read by `cancel()`'s arm gate and the loop's stop-override check. */
   get hasSteering(): boolean {
     return this.steeringMessages.length > 0
   }
 
+  /**
+   * Add a message to the queued FIFO and wake a parked {@link waitForQueued}.
+   * @param message - the message to queue for the next turn start.
+   */
   enqueue(message: InboxMessage): void {
     this.queuedMessages.push(message)
     this.wakeup?.()
   }
 
+  /**
+   * Add a message to the steering FIFO. Deliberately no wakeup: steering is
+   * drained between steps of a running turn, never by the idle wait —
+   * `Agent.steer()` on an idle agent falls back to `send()` instead.
+   * @param message - the message to inject between steps of the running turn.
+   */
   steer(message: InboxMessage): void {
     this.steeringMessages.push(message)
   }
 
-  /** Drain all queued messages (turn start). */
+  /**
+   * Drain all queued messages (turn start).
+   * @returns the drained messages in arrival order; the queued FIFO is left empty.
+   */
   drainQueued(): InboxMessage[] {
     return this.queuedMessages.splice(0)
   }
 
-  /** Drain all steering messages (between steps). */
+  /**
+   * Drain all steering messages (between steps).
+   * @returns the drained messages in arrival order; the steering FIFO is left empty.
+   */
   drainSteering(): InboxMessage[] {
     return this.steeringMessages.splice(0)
   }
@@ -62,7 +79,12 @@ export class Inbox {
     this.steeringMessages.length = 0
   }
 
-  /** Wait until a queued message arrives or `cancel` resolves. */
+  /**
+   * Wait until a queued message arrives or `cancel` resolves.
+   * @param cancel - a promise whose resolution abandons the wait without a
+   *   message (the driver loop passes the agent's disposed promise so a parked
+   *   loop can exit).
+   */
   waitForQueued(cancel: Promise<void>): Promise<void> {
     if (this.hasQueued) return Promise.resolve()
     const { promise, resolve } = Promise.withResolvers<void>()

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

@@ -29,6 +29,10 @@ declare module 'cordis' {
   }
 }
 
+/**
+ * Plugin config: the agents to create — or resume, via `resumeSessionId` —
+ * declaratively at startup, so a cordis.yml deployment needs no code.
+ */
 export interface Config {
   /** Agents created from configuration at startup. */
   agents: (AgentOptions & {

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

@@ -185,6 +185,9 @@ export interface LoopHandle {
  *     re-enqueue leftover steering as queued          ⟵ steering is never stranded
  *   idle (emit agent/status) unless more queued
  * ```
+ * @param ctx - the plugin context the loop reaches events (agent/…, session/flush) and services (systemPrompt, llm, tools) through.
+ * @param agent - the agent this invocation drives for its whole lifetime (its inbox, session, and options).
+ * @param handle - the bridge to the agent's mutable state: status/abort setters plus the disposal and cancel-marker reads.
  */
 export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopHandle): Promise<void> {
   // Per-instance transmission bookkeeping: whether THIS loop instance has
@@ -875,7 +878,11 @@ function withoutToolCalls(message: Message): Message {
   return { ...message, content: message.content.filter(block => block.type !== 'tool-call') }
 }
 
-/** The last turn number in a (possibly seeded) session log, or 0. */
+/**
+ * The last turn number in a (possibly seeded) session log, or 0.
+ * @param session - the session whose log is scanned for the latest `turn/start`.
+ * @returns the latest `turn/start`'s turn number, or 0 when the log has none (the next turn is this plus one).
+ */
 export function lastTurnNumber(session: Session): number {
   const lastStart = session.events.findLast(event => event.type === 'turn/start')
   return lastStart?.data.turn ?? 0
@@ -889,6 +896,8 @@ export function lastTurnNumber(session: Session): number {
  * returns to idle), so status is not a reliable open-turn signal. Used by
  * `inject()` to choose between appending into an open turn vs. wrapping the
  * injection in its own one-shot turn (the turn-enclosure RFC).
+ * @param session - the session whose log is inspected.
+ * @returns true when the log's last turn boundary is a `turn/start` with no matching `turn/end` yet.
  */
 export function isTurnOpen(session: Session): boolean {
   const last = session.events.findLast(e => e.type === 'turn/start' || e.type === 'turn/end')

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

@@ -19,7 +19,10 @@ export interface TransmissionLog {
   loggedHeader: boolean
 }
 
-/** Fresh bookkeeping for a newly-started loop instance. */
+/**
+ * Fresh bookkeeping for a newly-started loop instance.
+ * @returns state with `loggedHeader` false, so the instance's first request appends an anchoring snapshot.
+ */
 export function createTransmissionLog(): TransmissionLog {
   return { loggedHeader: false }
 }

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

@@ -0,0 +1,117 @@
+/**
+ * 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.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore, { foldRequestHeader } from '@deepseek-ai/dsh-session'
+import SystemPrompt, { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
+import type { Config as SystemPromptConfig } from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import { MockAdapter, textResponse } from './mock-adapter.ts'
+
+async function harness(adapter: MockAdapter, toolOrder?: SystemPromptConfig['toolOrder']) {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: 'stable base', ...toolOrder !== undefined ? { toolOrder } : {} })
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return ctx
+}
+
+function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'idle') {
+        dispose()
+        resolve()
+      }
+    })
+  })
+}
+
+function registerNamed(ctx: Context, name: string) {
+  ctx.tools.register(defineTool({
+    name,
+    description: `the ${name} tool`,
+    parameters: {},
+    async execute() {
+      return [{ type: 'text', text: name }]
+    },
+  }))
+}
+
+/** Run one text-only turn and return the harness context + agent. */
+async function runTurn(registrationOrder: string[], toolOrder?: SystemPromptConfig['toolOrder']) {
+  const adapter = new MockAdapter([textResponse('done')])
+  const ctx = await harness(adapter, toolOrder)
+  for (const name of registrationOrder) registerNamed(ctx, name)
+  const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+  agent.send([{ type: 'text', text: 'go' }])
+  await waitForIdle(ctx, agent)
+  return { ctx, agent, adapter }
+}
+
+describe('loop-level canonical tool order', () => {
+  it('logs the request/header with tools in canonical order, not registration order', async () => {
+    const { agent, adapter } = await runTurn(['zulu', 'alpha', 'mike'])
+    const header = foldRequestHeader(agent.session.events)
+    expect(header?.tools?.map(tool => tool.name)).toEqual(['alpha', 'mike', 'zulu'])
+    // The dispatched request is built FROM the logged header (whose tools the
+    // assembly already canonicalized) and reaches the adapter deep-frozen —
+    // the marker the reconstruction invariant keys on.
+    expect(adapter.requests[0]?.tools?.map(tool => tool.name)).toEqual(['alpha', 'mike', 'zulu'])
+    expect(Object.isFrozen(adapter.requests[0])).toBe(true)
+    expect(adapter.requests[0]?.sessionId).toBe(agent.session.id)
+  })
+
+  it('produces the same header order for any registration order', async () => {
+    const first = await runTurn(['alpha', 'mike', 'zulu'])
+    const second = await runTurn(['zulu', 'mike', 'alpha'])
+    const names = (run: typeof first) => foldRequestHeader(run.agent.session.events)?.tools?.map(tool => tool.name)
+    expect(names(first)).toEqual(['alpha', 'mike', 'zulu'])
+    expect(names(second)).toEqual(names(first))
+  })
+
+  it('honors a configured toolOrder in the logged header and the dispatched request', async () => {
+    const { agent, adapter } = await runTurn(['alpha', 'zulu', 'mike'], ['zulu', TOOL_ORDER_REST])
+    const header = foldRequestHeader(agent.session.events)
+    expect(header?.tools?.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'mike'])
+    expect(adapter.requests[0]?.tools?.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'mike'])
+    expect(Object.isFrozen(adapter.requests[0])).toBe(true)
+  })
+
+  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.
+    const adapter = new MockAdapter([textResponse('never sent')])
+    const ctx = await harness(adapter, ['ghost', TOOL_ORDER_REST])
+    registerNamed(ctx, 'alpha')
+    const errors: Error[] = []
+    ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error))
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    agent.send([{ type: 'text', text: 'go' }])
+    await waitForIdle(ctx, agent)
+    expect(adapter.requests).toHaveLength(0)
+    expect(errors.map(e => e.message)).toEqual(['toolOrder lists unregistered tool "ghost"; registered tools: alpha'])
+    expect(foldRequestHeader(agent.session.events)).toBeUndefined()
+    const end = agent.session.events.find(e => e.type === 'turn/end')
+    expect(end?.type === 'turn/end' && end.data.reason).toMatchObject({ kind: 'error', step: 1 })
+    // The turn is balanced (turn/start → turn/end) with no step events inside.
+    expect(agent.session.events.some(e => e.type === 'step/start')).toBe(false)
+  })
+})

packages/core/agent/src/types.ts

@@ -50,7 +50,11 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 /** Identifies one live agent in the registry. */
 export type AgentId = Branded<'AgentId'>
 
-/** Brand a string as an {@link AgentId}. */
+/**
+ * Brand a string as an {@link AgentId}.
+ * @param id - the raw agent id string.
+ * @returns the same string, branded (a compile-time cast — no runtime cost).
+ */
 export function AgentId(id: string): AgentId {
   return id as AgentId
 }
@@ -80,10 +84,22 @@ export interface AgentOptions {
   model?: string
 }
 
+/**
+ * Options for {@link Agent.send}/{@link Agent.steer}/{@link Agent.inject}. An
+ * absent `source` resolves to `{ kind: 'user' }`, so a plugin supplying content
+ * must label itself here or its message is recorded as a user prompt (see
+ * {@link HookContext} on why that label is load-bearing).
+ */
 export interface SendOptions {
   source?: MessageSource
 }
 
+/**
+ * An agent's lifecycle state, emitted on every transition as `agent/status`:
+ * `idle` (parked, waiting for queued work), `running` (a turn is in progress),
+ * `disposed` (terminal — no transition leaves it, and `send`/`steer`/`inject`
+ * throw).
+ */
 export type AgentStatus = 'idle' | 'running' | 'disposed'
 
 /**

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

@@ -0,0 +1,555 @@
+/**
+ * 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.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { collectExportJsdocViolations } from '../../../../scripts/verify-export-jsdoc.ts'
+
+const roots: string[] = []
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+/** Write fixture files under `packages/group/fix/src/` and return the scan root. */
+function fixture(files: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), 'export-jsdoc-'))
+  roots.push(root)
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = join(root, 'packages', 'group', 'fix', 'src', rel)
+    mkdirSync(dirname(abs), { recursive: true })
+    writeFileSync(abs, content)
+  }
+  return root
+}
+
+/** Single-file fixture shorthand: the content becomes `src/index.ts`. */
+const make = (content: string): string => fixture({ 'index.ts': content })
+
+describe('verify-export-jsdoc functions and consts', () => {
+  it('accepts a fully documented surface', () => {
+    expect(collectExportJsdocViolations(make(`
+/**
+ * Add one to a count.
+ * @param n - the count to bump.
+ * @returns the count plus one.
+ */
+export function bump(n: number): number { return n + 1 }
+
+/**
+ * Fire-and-forget (void needs no @returns).
+ * @param flag - whether to arm.
+ */
+export function poke(flag: boolean): void { void flag }
+
+/** The default retry budget. */
+export const RETRIES = 3
+
+/**
+ * Halve a count.
+ * @param n - the count to halve.
+ * @returns the count halved.
+ */
+export const halve = (n: number): number => n / 2
+`))).toEqual([])
+  })
+
+  it('flags an exported function with no JSDoc at all', () => {
+    expect(collectExportJsdocViolations(make(
+      'export function bare(): void {}\n',
+    ))).toEqual([expect.stringMatching(/exported function 'bare' .* has no JSDoc\./)])
+  })
+
+  it('flags a missing @param and a missing @returns', () => {
+    const violations = collectExportJsdocViolations(make(
+      '/** Docs without tags. */\nexport function f(x: number): number { return x }\n',
+    ))
+    expect(violations).toEqual([
+      expect.stringMatching(/exported function 'f' .* is missing @param x\./),
+      expect.stringMatching(/exported function 'f' .* is missing @returns \(return type: number\)\./),
+    ])
+  })
+
+  it('flags an unannotated (inferred) return type', () => {
+    expect(collectExportJsdocViolations(make(
+      '/**\n * Docs.\n * @param x - value.\n */\nexport function f(x: number) { return x }\n',
+    ))).toEqual([expect.stringMatching(/no return type annotation/)])
+  })
+
+  it('flags tags-only JSDoc with no description prose', () => {
+    expect(collectExportJsdocViolations(make(
+      '/**\n * @param x - value.\n */\nexport function f(x: number): void {}\n',
+    ))).toEqual([expect.stringMatching(/no description prose above its block tags/)])
+  })
+
+  it('flags a stale @param and a binding-pattern parameter', () => {
+    const violations = collectExportJsdocViolations(make(
+      '/**\n * Docs.\n * @param ghost - not real.\n */\nexport function f({ a }: { a: number }): void {}\n',
+    ))
+    expect(violations).toEqual([
+      expect.stringMatching(/parameter '\{ a \}' is a binding pattern; the export surface needs simple identifier parameters/),
+      expect.stringMatching(/@param ghost does not match any parameter \(stale tag\?\)/),
+    ])
+  })
+
+  it('exempts a `this` receiver annotation from @param', () => {
+    expect(collectExportJsdocViolations(make(
+      '/**\n * Docs.\n * @param x - value.\n */\nexport function f(this: object, x: number): void {}\n',
+    ))).toEqual([])
+  })
+
+  it('waives @returns for a declarator-annotated const but not an unannotated one', () => {
+    expect(collectExportJsdocViolations(make(`
+type Fn = (x: number) => number
+/**
+ * Uses the named signature.
+ * @param x - value.
+ */
+export const good: Fn = x => x
+/**
+ * No signature anywhere.
+ * @param x - value.
+ */
+export const bad = (x: number) => x
+`))).toEqual([expect.stringMatching(/exported const 'bad' .* has no return type annotation/)])
+  })
+
+  it('requires description prose on a non-function const', () => {
+    expect(collectExportJsdocViolations(make(
+      'export const LIMIT = 10\n',
+    ))).toEqual([expect.stringMatching(/exported const 'LIMIT' .* has no JSDoc\./)])
+  })
+})
+
+describe('verify-export-jsdoc type-level exports', () => {
+  it('requires description prose on interfaces, type aliases, and enums', () => {
+    const violations = collectExportJsdocViolations(make(
+      'export interface I { a: number }\nexport type T = number\nexport enum E { A }\n',
+    ))
+    expect(violations).toEqual([
+      expect.stringMatching(/exported interface 'I' .* has no JSDoc\./),
+      expect.stringMatching(/exported type 'T' .* has no JSDoc\./),
+      expect.stringMatching(/exported enum 'E' .* has no JSDoc\./),
+    ])
+  })
+
+  it('skips `declare module` augmentation bodies (the cordis gate owns them)', () => {
+    expect(collectExportJsdocViolations(make(
+      "declare module 'cordis' {\n  interface Events {\n    'fix/x'(): void\n  }\n}\nexport {}\n",
+    ))).toEqual([])
+  })
+})
+
+describe('verify-export-jsdoc export forms', () => {
+  it('resolves an `export { … }` list to the local declaration', () => {
+    expect(collectExportJsdocViolations(make(
+      'function f(): void {}\nexport { f }\n',
+    ))).toEqual([expect.stringMatching(/exported function 'f' .* has no JSDoc\./)])
+  })
+
+  it('does not treat a never-exported sibling declarator as surface (review round 2)', () => {
+    // `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.
+    expect(collectExportJsdocViolations(make(
+      '/** The public knob. */\nconst publicValue = 1, privateHelper = 2\nexport { publicValue }\nvoid privateHelper\n',
+    ))).toEqual([])
+  })
+
+  it('unions declarators across multiple export lists over one statement (review round 2)', () => {
+    // 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.
+    const violations = collectExportJsdocViolations(make(
+      'const a = 1, b = 2, c = 3\nexport { a }\nexport { b }\nvoid c\n',
+    ))
+    expect(violations).toEqual([
+      expect.stringMatching(/exported const 'a' .* has no JSDoc\./),
+      expect.stringMatching(/exported const 'b' .* has no JSDoc\./),
+    ])
+  })
+
+  it('scopes a default-export identifier to its own declarator (review round 2)', () => {
+    // `export default` of an identifier reaches the statement through the
+    // same name lookup as an export list; the sibling stays private.
+    expect(collectExportJsdocViolations(make(
+      '/** The app entry. */\nconst app = 1, scratch = 2\nexport default app\nvoid scratch\n',
+    ))).toEqual([])
+  })
+
+  it('reports a re-exported module once, at its defining file', () => {
+    const violations = collectExportJsdocViolations(fixture({
+      'index.ts': "export * from './other.ts'\n",
+      'other.ts': 'export function f(): void {}\n',
+    }))
+    expect(violations).toEqual([expect.stringMatching(/other\.ts:1\) has no JSDoc\./)])
+  })
+
+  it('exempts overload implementations when the signatures are documented', () => {
+    expect(collectExportJsdocViolations(make(`
+/**
+ * From a number.
+ * @param x - the number.
+ * @returns its text.
+ */
+export function f(x: number): string
+/**
+ * From a flag.
+ * @param x - the flag.
+ * @returns its text.
+ */
+export function f(x: boolean): string
+export function f(x: number | boolean): string { return String(x) }
+`))).toEqual([])
+  })
+})
+
+describe('verify-export-jsdoc classes', () => {
+  it('flags an undocumented class, method, property, and accessor', () => {
+    const violations = collectExportJsdocViolations(make(`
+export class C {
+  state = 1
+  get view(): number { return this.state }
+  run(x: number): number { return x }
+}
+`))
+    expect(violations).toEqual([
+      expect.stringMatching(/exported class 'C' .* has no JSDoc\./),
+      expect.stringMatching(/exported class property 'C.state' .* has no JSDoc\./),
+      expect.stringMatching(/exported class accessor 'C.view' .* has no JSDoc\./),
+      expect.stringMatching(/exported class method 'C.run' .* has no JSDoc\./),
+    ])
+  })
+
+  it('exempts members declared by an extends/implements heritage type', () => {
+    expect(collectExportJsdocViolations(make(`
+/** Seam. */
+export abstract class Base {
+  /**
+   * Do it.
+   * @param x - input.
+   * @returns output.
+   */
+  abstract run(x: number): number
+}
+/** Iface. */
+export interface Sized {
+  /** Byte size. */
+  size: number
+}
+/** Impl. */
+export class Impl extends Base implements Sized {
+  size = 0
+  run(x: number): number { return x }
+}
+`))).toEqual([])
+  })
+
+  it('skips private/protected/#private members and constructors', () => {
+    expect(collectExportJsdocViolations(make(`
+/** Documented. */
+export class C {
+  #secret = 1
+  private hidden(): void {}
+  protected hook(): void {}
+  constructor(x: number) { void x }
+}
+`))).toEqual([])
+  })
+
+  it('exempts plugin-protocol statics but checks other statics', () => {
+    const violations = collectExportJsdocViolations(make(`
+/** Plugin. */
+export class C {
+  static Config = { a: 1 }
+  static inject = ['bash']
+  static reusable = true
+  static other = 1
+}
+`))
+    expect(violations).toEqual([expect.stringMatching(/exported class property 'C.other' .* has no JSDoc\./)])
+  })
+
+  it("covers a set accessor by the getter's doc", () => {
+    expect(collectExportJsdocViolations(make(`
+/** Documented. */
+export class C {
+  /** The current width. */
+  get width(): number { return 1 }
+  set width(_v: number) {}
+}
+`))).toEqual([])
+  })
+})
+
+describe('verify-export-jsdoc plugin protocol and namespaces', () => {
+  it('exempts top-level plugin-protocol exports', () => {
+    expect(collectExportJsdocViolations(make(`
+export const name = 'fix'
+export const inject = ['bash']
+export const reusable = true
+export const Config = { parse: true }
+export function apply(): void {}
+`))).toEqual([])
+  })
+
+  it('recurses into namespaces with qualified names and honors the merge idiom', () => {
+    const violations = collectExportJsdocViolations(make(`
+/** The plugin class. */
+export class Fix {}
+export namespace Fix {
+  export interface Config { a: number }
+}
+export namespace Loose {
+  export const x = 1
+}
+`))
+    expect(violations).toEqual([
+      expect.stringMatching(/exported interface 'Fix.Config' .* has no JSDoc\./),
+      expect.stringMatching(/exported namespace 'Loose' .* has no JSDoc\./),
+      expect.stringMatching(/exported const 'Loose.x' .* has no JSDoc\./),
+    ])
+  })
+})
+
+describe('verify-export-jsdoc fail-closed forms (review round 1)', () => {
+  it('checks the function contract on a non-identifier default export', () => {
+    expect(collectExportJsdocViolations(make(
+      '/** Doubles. */\nexport default (x: number): number => x * 2\n',
+    ))).toEqual([
+      expect.stringMatching(/default export .* is missing @param x\./),
+      expect.stringMatching(/default export .* is missing @returns \(return type: number\)\./),
+    ])
+    expect(collectExportJsdocViolations(make(
+      '/**\n * Doubles.\n * @param x - the input.\n * @returns twice the input.\n */\nexport default (x: number): number => x * 2\n',
+    ))).toEqual([])
+  })
+
+  it('treats an inline function-type annotation as the surface signature', () => {
+    expect(collectExportJsdocViolations(make(
+      '/** Maps a number. */\nexport declare const f: (x: number) => number\n',
+    ))).toEqual([
+      expect.stringMatching(/exported const 'f' .* is missing @param x\./),
+      expect.stringMatching(/exported const 'f' .* is missing @returns \(return type: number\)\./),
+    ])
+    expect(collectExportJsdocViolations(make(
+      '/**\n * Maps a number.\n * @param x - the input.\n * @returns the mapped value.\n */\nexport const f: (x: number) => number = v => v\n',
+    ))).toEqual([])
+  })
+
+  it('recurses into an ambient declare namespace where members export implicitly', () => {
+    expect(collectExportJsdocViolations(make(
+      'export declare namespace N {\n  function f(x: number): number\n}\n',
+    ))).toEqual([
+      expect.stringMatching(/exported namespace 'N' .* has no JSDoc\./),
+      expect.stringMatching(/exported function 'N.f' .* has no JSDoc\./),
+    ])
+  })
+
+  it('requires an export-import alias to document itself (its target may be unwalked)', () => {
+    expect(collectExportJsdocViolations(make(
+      '/** Holder. */\nexport namespace N {\n  /** The value. */\n  export const x = 1\n}\nexport import y = N.x\n',
+    ))).toEqual([expect.stringMatching(/exported alias 'y' .* has no JSDoc\./)])
+    expect(collectExportJsdocViolations(make(
+      'namespace N {\n  export const x = 1\n}\n/** Alias surfacing the internal counter. */\nexport import y = N.x\n',
+    ))).toEqual([])
+  })
+
+  it('refuses an export-import alias to a callable, class, or namespace target', () => {
+    const refusal = /exported alias 'g' .* aliases a callable, class, or namespace target/
+    expect(collectExportJsdocViolations(make(
+      'namespace N {\n  export function f(x: number): number { return x }\n}\n/** Alias. */\nexport import g = N.f\n',
+    ))).toEqual([expect.stringMatching(refusal)])
+    expect(collectExportJsdocViolations(make(
+      'namespace N {\n  export class C {\n    run(x: number): number { return x }\n  }\n}\n/** Alias. */\nexport import g = N.C\n',
+    ))).toEqual([expect.stringMatching(refusal)])
+    expect(collectExportJsdocViolations(make(
+      'namespace N {\n  export namespace Sub {\n    export function f(x: number): number { return x }\n  }\n}\n/** Alias. */\nexport import g = N.Sub\n',
+    ))).toEqual([expect.stringMatching(refusal)])
+  })
+
+  it('classifies wrapped function initializers and default exports (parens, satisfies)', () => {
+    expect(collectExportJsdocViolations(make(
+      'type Fn = (x: number) => number\n/** Wrapped. */\nexport const f = (((x: number): number => x)) satisfies Fn\n',
+    ))).toEqual([
+      expect.stringMatching(/exported const 'f' .* is missing @param x\./),
+      expect.stringMatching(/exported const 'f' .* is missing @returns \(return type: number\)\./),
+    ])
+    expect(collectExportJsdocViolations(make(
+      'type Fn = (x: number) => number\n/** Wrapped. */\nexport default (((x: number): number => x * 2) satisfies Fn)\n',
+    ))).toEqual([
+      expect.stringMatching(/default export .* is missing @param x\./),
+      expect.stringMatching(/default export .* is missing @returns \(return type: number\)\./),
+    ])
+  })
+
+  it('treats a single-call-signature type literal as the surface signature', () => {
+    expect(collectExportJsdocViolations(make(
+      '/** Maps. */\nexport declare const f: { (x: number): number }\n',
+    ))).toEqual([
+      expect.stringMatching(/exported const 'f' .* is missing @param x\./),
+      expect.stringMatching(/exported const 'f' .* is missing @returns \(return type: number\)\./),
+    ])
+  })
+
+  it('refuses a hybrid callable type literal instead of narrowing the check', () => {
+    expect(collectExportJsdocViolations(make(
+      '/** Hybrid. */\nexport declare const f: { (x: number): number; flush: () => void }\n',
+    ))).toEqual([expect.stringMatching(/exported const 'f'.*callable type literal is not gate-classifiable; extract a named type/)])
+  })
+
+  it('refuses an export-equals assignment instead of failing open', () => {
+    expect(collectExportJsdocViolations(make(
+      'const x = 1\nexport = x\n',
+    ))).toEqual([expect.stringMatching(/export-equals assignment .* is not a gate-supported export form/)])
+  })
+})
+
+describe('verify-export-jsdoc heritage refinement (review round 1)', () => {
+  it('requires @param for parameters the base member never names', () => {
+    const violations = collectExportJsdocViolations(make(`
+/** Seam. */
+export abstract class Base {
+  /**
+   * Do it.
+   * @param x - input.
+   * @returns output.
+   */
+  abstract run(x: number): number
+}
+/** Impl. */
+export class Impl extends Base {
+  override run(x: number, verbose?: boolean): number { return verbose ? x : -x }
+}
+`))
+    expect(violations).toEqual([expect.stringMatching(/exported class method 'Impl.run' .* is missing @param verbose\./)])
+  })
+
+  it('does not exempt a public override of a protected-only base member', () => {
+    expect(collectExportJsdocViolations(make(`
+/** Seam. */
+export abstract class Base {
+  /** Subclass hook. */
+  protected hook(): void {}
+}
+/** Impl. */
+export class Impl extends Base {
+  override hook(): void {}
+}
+`))).toEqual([expect.stringMatching(/exported class method 'Impl.hook' .* has no JSDoc\./)])
+  })
+
+  it('treats an underscore-prefixed rename of a base parameter as the same parameter', () => {
+    expect(collectExportJsdocViolations(make(`
+/** Seam. */
+export abstract class Base {
+  /**
+   * Load it.
+   * @param cwd - the working directory to scope the lookup.
+   * @returns the loaded value.
+   */
+  abstract load(cwd: string): number
+}
+/** Impl (ignores cwd). */
+export class Impl extends Base {
+  load(_cwd: string): number { return 1 }
+}
+`))).toEqual([])
+  })
+
+  it('flags a binding-pattern parameter an override adds beyond the base', () => {
+    expect(collectExportJsdocViolations(make(`
+/** Seam. */
+export abstract class Base {
+  /**
+   * Do it.
+   * @param x - input.
+   * @returns output.
+   */
+  abstract run(x: number): number
+}
+/** Impl. */
+export class Impl extends Base {
+  override run(x: number, { verbose }: { verbose?: boolean } = {}): number { return verbose ? x : -x }
+}
+`))).toEqual([expect.stringMatching(/exported class method 'Impl.run' .* is a binding pattern/)])
+  })
+
+  it('revives the @returns duty when an override grows a concrete result over a void base', () => {
+    const voidBase = `
+/** Seam. */
+export abstract class Base {
+  /** Do it (fire-and-forget). */
+  abstract run(): void
+}
+`
+    expect(collectExportJsdocViolations(make(`${voidBase}
+/** Impl. */
+export class Impl extends Base {
+  override run(): number { return 1 }
+}
+`))).toEqual([expect.stringMatching(/exported class method 'Impl.run' .* is missing @returns \(return type: number\)\./)])
+    expect(collectExportJsdocViolations(make(`${voidBase}
+/** Impl. */
+export class Impl extends Base {
+  /**
+   * Do it and count.
+   * @returns how many were done.
+   */
+  override run(): number { return 1 }
+}
+`))).toEqual([])
+  })
+
+  it('classifies an unannotated override return over a void base via the checker', () => {
+    const voidBase = `
+/** Seam. */
+export abstract class Base {
+  /** Do it (fire-and-forget). */
+  abstract run(): void
+}
+`
+    expect(collectExportJsdocViolations(make(`${voidBase}
+/** Impl. */
+export class Impl extends Base {
+  override run() { return 1 }
+}
+`))).toEqual([expect.stringMatching(/exported class method 'Impl.run' .* non-void result its heritage declaration does not document/)])
+    expect(collectExportJsdocViolations(make(`${voidBase}
+/** Impl (faithful void, no annotation needed). */
+export class Impl extends Base {
+  override run() {}
+}
+`))).toEqual([])
+  })
+
+  it('keeps the full exemption when the base return already carries the @returns duty', () => {
+    expect(collectExportJsdocViolations(make(`
+/** Seam. */
+export abstract class Base {
+  /**
+   * Count things.
+   * @returns the count.
+   */
+  abstract run(): number
+}
+/** Impl. */
+export class Impl extends Base {
+  override run(): number { return 1 }
+}
+`))).toEqual([])
+  })
+})

packages/core/session/src/index.ts

@@ -153,10 +153,15 @@ export class Session {
     this.header = header ?? { version: SESSION_FORMAT_VERSION, id, createdAt: Date.now() }
   }
 
+  /**
+   * The append-only event log, exposed live by reference (readonly-typed, not
+   * a snapshot): later appends are visible through the same array.
+   */
   get events(): readonly SessionEvent[] {
     return this.log
   }
 
+  /** The next event's sequence number — always the log length (the `seq = log.length` contiguity contract). */
   get seq(): number {
     return this.log.length
   }
@@ -175,6 +180,9 @@ export class Session {
    *   declare how it joins the surface, the sole source of derived history) and
    *   rejected by the compiler for non-surface types like `turn/start` or
    *   `assistant/chunk`.
+   * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of
+   *   `data` that entered the log, so reading `event.data` back sees the logged
+   *   value, never the caller's still-mutable input.
    * @throws if `data` is not losslessly JSON-serializable (BigInt, function,
    *   symbol, undefined, non-finite number, circular ref, or an exotic object
    *   like Map/Set/Date). The event log is the durable source of truth, so this
@@ -365,6 +373,14 @@ export class Session {
 /** A fork source: either the live session object or its live store id. */
 export type SessionForkSource = Session | SessionId
 
+/**
+ * Rejection codes for session forking: the fork source id is unknown to the
+ * live store (`SESSION_NOT_FOUND`) or names a session object that is not the
+ * store's live instance (`SESSION_NOT_LIVE`); the requested child id is
+ * already taken (`SESSION_ALREADY_EXISTS`); the boundary is not a contiguous
+ * existing seq (`INVALID_BOUNDARY`); or the boundary event is not a
+ * `turn/end` — a fork must cut on a closed turn (`OPEN_TURN`).
+ */
 export type SessionForkErrorCode =
   | 'SESSION_NOT_FOUND'
   | 'SESSION_NOT_LIVE'

packages/core/session/src/json.ts

@@ -40,6 +40,10 @@ export type JsonValue = null | boolean | number | string | JsonValue[] | { [key:
  * hiding under a symbol/non-enumerable key cannot make the round-trip lossy.
  * Getters are invoked during the check (again as `JSON.stringify` would), so the
  * contract is for plain data records, not objects with side-effecting accessors.
+ * @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.
  */
 export function isJsonValue(value: unknown, seen: Set<object> = new Set()): boolean {
   if (value === null) return true

packages/core/session/src/repair.ts

@@ -54,6 +54,8 @@ import type { SessionEvent } from './types.ts'
  * 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

packages/core/session/src/surface.ts

@@ -29,6 +29,8 @@ const SURFACE_EVENT_TYPES = new Set<string>([
  * surface-eligible event that is MISSING its mandatory marker (e.g. validating
  * a seed/load log); use {@link isSurfaceEvent} to narrow to a fully-formed
  * {@link SurfaceEvent} with `surfaceOp` present.
+ * @param type - the event type string to test.
+ * @returns true when the type is one of the five message-producing types.
  */
 export function isSurfaceEligibleType(type: string): boolean {
   return SURFACE_EVENT_TYPES.has(type)
@@ -38,6 +40,8 @@ export function isSurfaceEligibleType(type: string): boolean {
  * Narrow a {@link SessionEvent} to {@link SurfaceEvent}: checks that the
  * event's `type` is surface-eligible AND that `surfaceOp` is present.
  * The narrowed type has mandatory {@link SurfaceOp}.
+ * @param event - the event to narrow.
+ * @returns true when the event is surface-eligible and carries its `surfaceOp` marker.
  */
 export function isSurfaceEvent(event: SessionEvent): event is SurfaceEvent {
   if (!SURFACE_EVENT_TYPES.has(event.type)) return false

packages/core/session/src/tool-pairing.ts

@@ -74,6 +74,12 @@ function nodeDelta(event: SessionEvent): number {
  * surface successor (`SurfaceNode.next`), or `null` when `end` is the tail —
  * for the cut after `end`.
  *
+ * @param nodes - the surface linked list in head→tail order.
+ * @param events - the session log each node's `seq` indexes into.
+ * @param beforeSeq - names the cut (the node it sits immediately before);
+ *   `null` — or any seq not on the surface — means the after-tail cut.
+ * @returns true when every `tool-call` before the cut is answered before it
+ *   (the unanswered-call depth at the cut is zero).
  * @throws if the surface prefix drives the unanswered-call depth negative — a
  *   `tool/result` with no preceding open `tool-call` on the surface. That is a
  *   corrupt surface (a structural invariant violation), surfaced loudly here

packages/core/session/src/types.ts

@@ -4,7 +4,11 @@ import type { CallId, ContentBlock, LlmCallConfig, MessageSource, StreamChunk, T
 /** Identifies one session in the store (and its persistence artifacts). */
 export type SessionId = Branded<'SessionId'>
 
-/** Brand a string as a {@link SessionId}. */
+/**
+ * Brand a string as a {@link SessionId}.
+ * @param id - the raw session id string.
+ * @returns the same string, branded (a compile-time cast — no runtime cost).
+ */
 export function SessionId(id: string): SessionId {
   return id as SessionId
 }
@@ -102,6 +106,7 @@ export interface TurnTriggerMap {
   injection: { kind: 'injection'; source: MessageSource }
 }
 
+/** The union over {@link TurnTriggerMap} — what started a turn; plugins extend it by merging variants into the map. */
 export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap]
 
 /**
@@ -156,6 +161,7 @@ export interface TurnEndReasonMap {
   interrupted: { kind: 'interrupted' }
 }
 
+/** The union over {@link TurnEndReasonMap} — why a turn ended; plugins extend it by merging variants into the map. */
 export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap]
 
 /**
@@ -361,6 +367,7 @@ export interface SessionEventMap {
   'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig }
 }
 
+/** The appendable event-type keys of {@link SessionEventMap}, plugin-merged extensions included. */
 export type SessionEventType = keyof SessionEventMap
 
 /**

packages/core/system-prompt/README.md

@@ -7,15 +7,16 @@ System prompt assembly registry. Plugins contribute ordered text sections, tool-
 | Key | Default | Meaning |
 |---|---|---|
 | `persona` | `''` | The deployment persona: the ONE deployment-authored prompt fragment, rendered as the order-0 `deployment:persona` section and shared by every agent in the context (subagents included). A template — complete `{{…}}` groups are interpreted strictly against the registered variables (the shipped loop registers `{{model}}`/`{{cwd}}`), with no escape syntax for literal braces yet. Empty ⇒ the section is dropped at render. |
+| `toolOrder` | — | Explicit model-facing tool order, as a list of `ToolSchema.name`s with one `'<unlisted-tools>'` rest entry (`TOOL_ORDER_REST`): listed tools take their listed position, unlisted tools land at the rest entry in lexicographic name order. Absent ⇒ plain lexicographic name order. Applied to the collected tools BEFORE the `system-prompt/assemble` waterfall — like the sections' `order` sort, it canonicalizes what the registry contributed (registration order is a plugin-load artifact), and a waterfall listener that mutates the list owns the determinism of what it emits. Misconfiguration fails loud: a list without exactly one rest entry, or with duplicates, throws at load; a listed name with no registered tool rejects every `assemble()`; a tool provider returning the reserved rest-entry name also rejects. Under the shipped loop the turn fails before any model request. Why a central list and not per-plugin weights: [Explicit model-facing tool order](../../../docs/rfc/implemented/feature/2026-07-06-explicit-tool-order.md). |
 
 ## Service: `SystemPrompt` (ctx key: `systemPrompt`)
 
 ### Public API
 
 - `ctx.systemPrompt.section(section: PromptSection): () => void` Contribute a section. Duplicate names throw. Disposed with the calling fiber.
-- `ctx.systemPrompt.tools(provider: () => ToolSchema[]): () => void` Contribute tool schemas (evaluated at each assembly). Disposed with the calling fiber.
+- `ctx.systemPrompt.tools(provider: () => ToolSchema[]): () => void` Contribute tool schemas (evaluated at each assembly). A provider must not return a schema named `TOOL_ORDER_REST`; that name is reserved for `toolOrder`'s rest entry. Disposed with the calling fiber.
 - `ctx.systemPrompt.variable(name: string, provider: (context) => string | undefined): () => void` Contribute a prompt variable, referenced from section text as `{{name}}`. Duplicate or unreferenceable names throw; `undefined` means "no value for this assembly". Disposed with the calling fiber.
-- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>` Assemble the prompt for one caller. Runs through the `system-prompt/assemble` waterfall.
+- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>` Assemble the prompt for one caller. Runs through the `system-prompt/assemble` waterfall. Rejects when a configured `toolOrder` names a tool no provider contributed, or when a provider returns the reserved rest-entry name.
 
 ### Events
 

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

@@ -88,7 +88,8 @@ export interface AssembledSection {
  *
  * 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.
+ * `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
@@ -110,6 +111,71 @@ 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.
+ */
+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.
+ */
+function validateToolOrder(toolOrder: string[] | undefined): string[] | undefined {
+  if (toolOrder === undefined) return undefined
+  const seen = new Set<string>()
+  for (const name of toolOrder) {
+    if (seen.has(name)) throw new Error(`toolOrder lists "${name}" more than once`)
+    seen.add(name)
+  }
+  if (!seen.has(TOOL_ORDER_REST)) {
+    throw new Error(`toolOrder must contain the "${TOOL_ORDER_REST}" rest entry (where unlisted tools are inserted)`)
+  }
+  return toolOrder
+}
+
+/**
+ * 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 with no collected tool throws — misconfiguration fails loud, and this
+ * 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. Never drops a tool, and both sorts are stable, so tools sharing a
+ * name keep their collection order.
+ */
+function orderTools(tools: ToolSchema[], toolOrder: string[] | undefined): ToolSchema[] {
+  const reserved = tools.find(tool => tool.name === TOOL_ORDER_REST)
+  if (reserved !== undefined) {
+    throw new Error(`tool provider returned reserved tool name "${TOOL_ORDER_REST}" (reserved for toolOrder's rest entry)`)
+  }
+  if (toolOrder === undefined) return tools.sort(compareToolNames)
+  const registered = new Set(tools.map(tool => tool.name))
+  const unknown = toolOrder.filter(name => name !== TOOL_ORDER_REST && !registered.has(name))
+  if (unknown.length > 0) {
+    throw new Error(`toolOrder lists unregistered tool${unknown.length > 1 ? 's' : ''} ${unknown.map(name => `"${name}"`).join(', ')}; registered tools: ${[...registered].sort().join(', ') || '(none)'}`)
+  }
+  const listed = new Set(toolOrder)
+  const rest = tools.filter(tool => !listed.has(tool.name)).sort(compareToolNames)
+  return toolOrder.flatMap(name =>
+    name === TOOL_ORDER_REST ? rest : tools.filter(tool => tool.name === name))
+}
+
+/** Lexicographic (code-unit) name comparison — locale-independent, so the order is identical on every machine. */
+function compareToolNames(a: ToolSchema, b: ToolSchema): number {
+  return a.name < b.name ? -1 : a.name > b.name ? 1 : 0
+}
+
+/** 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
@@ -124,6 +190,29 @@ export interface Config {
    * deployment opens with the harness identity alone.
    */
   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.
+   */
+  toolOrder?: string[]
 }
 
 /**
@@ -138,6 +227,10 @@ export interface Config {
  * 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).
  */
 export function renderPrompt(assembly: PromptAssembly): string {
   return assembly.sections
@@ -198,14 +291,23 @@ function interpolate(section: AssembledSection, variables: Record<string, string
 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.
+    toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
   })
 
   private sections: PromptSection[] = []
   private toolProviders: (() => ToolSchema[])[] = []
   private variableProviders = new Map<string, (context: AssembleContext) => string | undefined>()
+  private readonly toolOrder: string[] | undefined
 
   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
@@ -261,7 +363,10 @@ export class SystemPrompt extends Service {
   /**
    * Contribute a tool-schema provider that is evaluated at each assembly
    * call (so it can reflect the live registry state). The provider is
-   * removed when the calling fiber is disposed. Emits `system-prompt/change`.
+   * 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.
    */
@@ -318,19 +423,28 @@ export class SystemPrompt extends Service {
 
   /**
    * Assemble the current prompt for one caller: section texts are resolved
-   * against `context` and sorted by order, tools collected from all
-   * providers, and every registered variable resolved against `context` into
-   * `assembly.variables`. Tool schemas are deep-cloned because adapters and
-   * request waterfalls may mutate schema objects. Runs through the
-   * `system-prompt/assemble` waterfall, giving listeners the opportunity to
-   * mutate or replace the assembly before it reaches the model. Await the
-   * result before reading the assembly values — waterfall listeners may be
-   * async. Interpolation happens later, in {@link renderPrompt}.
+   * against `context` and sorted by order, tools collected from all providers
+   * 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 no provider contributed rejects the assembly), and every
+   * registered variable resolved against `context` into `assembly.variables`.
+   * Tool schemas are deep-cloned because adapters and request waterfalls may
+   * mutate schema objects. Runs through the `system-prompt/assemble`
+   * waterfall, giving listeners the opportunity to mutate or replace the
+   * assembly before it reaches the model — like the sections' `order` sort,
+   * tool canonicalization happens on the initial assembly, and a listener
+   * owns the determinism of whatever it emits. 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(context: AssembleContext = {}): Promise<PromptAssembly> {
+  // 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).
+  async assemble(context: AssembleContext = {}): Promise<PromptAssembly> {
     const variables: Record<string, string | undefined> = {}
     for (const [name, provider] of this.variableProviders) {
       variables[name] = provider(context)
@@ -343,8 +457,10 @@ export class SystemPrompt extends Service {
           text: typeof section.text === 'function' ? section.text(context) : section.text,
         }))
         .sort((a, b) => a.order - b.order),
-      tools: this.toolProviders.flatMap(provider =>
-        provider().map(tool => ({ ...tool, parameters: structuredClone(tool.parameters) }))),
+      tools: orderTools(
+        this.toolProviders.flatMap(provider =>
+          provider().map(tool => ({ ...tool, parameters: structuredClone(tool.parameters) }))),
+        this.toolOrder),
       variables,
     }
     return this.ctx.waterfall(this, 'system-prompt/assemble', assembly, context, () => Promise.resolve(assembly))

packages/core/system-prompt/tests/tool-order.spec.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SystemPrompt, { PromptAssembly, TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
+import type { ToolSchema } from '@deepseek-ai/dsh-llm'
+
+function tool(name: string, description = name): ToolSchema {
+  return { name, description, parameters: { type: 'object', properties: {} } }
+}
+
+async function mount(config: { persona?: string; toolOrder?: string[] } = {}): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt, config)
+  return ctx
+}
+
+function names(assembly: PromptAssembly): string[] {
+  return assembly.tools.map(t => t.name)
+}
+
+describe('SystemPrompt tool order', () => {
+  // The ONE place the public constant's value is pinned; everything else
+  // (tests and deployment configs alike) references TOOL_ORDER_REST.
+  it('exports the rest entry as "<unlisted-tools>"', () => {
+    expect(TOOL_ORDER_REST).toBe('<unlisted-tools>')
+  })
+
+  it('assembles tools in lexicographic name order when no toolOrder is configured', async () => {
+    const ctx = await mount()
+    ctx.systemPrompt.tools(() => [tool('charlie'), tool('alpha')])
+    ctx.systemPrompt.tools(() => [tool('bravo')])
+    expect(names(await ctx.systemPrompt.assemble())).toEqual(['alpha', 'bravo', 'charlie'])
+  })
+
+  it('assembles the same order regardless of provider registration order', async () => {
+    const forward = await mount()
+    forward.systemPrompt.tools(() => [tool('alpha')])
+    forward.systemPrompt.tools(() => [tool('zulu')])
+    const backward = await mount()
+    backward.systemPrompt.tools(() => [tool('zulu')])
+    backward.systemPrompt.tools(() => [tool('alpha')])
+    expect(names(await forward.systemPrompt.assemble())).toEqual(['alpha', 'zulu'])
+    expect(names(await backward.systemPrompt.assemble())).toEqual(['alpha', 'zulu'])
+  })
+
+  it('applies a configured toolOrder: listed positions, rest at the rest entry lexicographically', async () => {
+    const ctx = await mount({ toolOrder: ['todo_write', TOOL_ORDER_REST, 'bash'] })
+    ctx.systemPrompt.tools(() => [tool('bash'), tool('echo_b'), tool('todo_write'), tool('echo_a')])
+    expect(names(await ctx.systemPrompt.assemble())).toEqual(['todo_write', 'echo_a', 'echo_b', 'bash'])
+  })
+
+  it('rejects the assembly when toolOrder names a tool that is not registered (misconfiguration blocks work)', async () => {
+    const ctx = await mount({ toolOrder: ['todo_write', 'ghost', TOOL_ORDER_REST, 'wraith'] })
+    ctx.systemPrompt.tools(() => [tool('bash'), tool('todo_write')])
+    await expect(ctx.systemPrompt.assemble()).rejects.toThrow(
+      'toolOrder lists unregistered tools "ghost", "wraith"; registered tools: bash, todo_write')
+  })
+
+  it('names the single unregistered tool when no tools are registered at all', async () => {
+    const ctx = await mount({ toolOrder: ['ghost', TOOL_ORDER_REST] })
+    await expect(ctx.systemPrompt.assemble()).rejects.toThrow(
+      'toolOrder lists unregistered tool "ghost"; registered tools: (none)')
+  })
+
+  it.each([
+    ['without an explicit toolOrder', undefined],
+    ['with only the rest entry configured', [TOOL_ORDER_REST]],
+  ])('rejects a provider tool named like the reserved rest entry %s', async (_case, toolOrder) => {
+    const ctx = await mount(toolOrder === undefined ? {} : { toolOrder })
+    ctx.systemPrompt.tools(() => [tool(TOOL_ORDER_REST)])
+    await expect(ctx.systemPrompt.assemble()).rejects.toThrow(
+      `tool provider returned reserved tool name "${TOOL_ORDER_REST}"`)
+  })
+
+  it('keeps collection order between tools that share a name (stable sort)', async () => {
+    const ctx = await mount()
+    ctx.systemPrompt.tools(() => [tool('dup', 'first'), tool('anchor'), tool('dup', 'second')])
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(assembly.tools.map(t => t.description)).toEqual(['anchor', 'first', 'second'])
+  })
+
+  it('canonicalizes BEFORE the assemble waterfall: listeners see the ordered list and own their own edits', async () => {
+    const ctx = await mount()
+    ctx.systemPrompt.tools(() => [tool('zulu'), tool('alpha')])
+    let seen: string[] | undefined
+    ctx.on('system-prompt/assemble', function (assembly, _context, next) {
+      seen = assembly.tools.map(t => t.name)
+      // A listener-appended tool is NOT re-sorted — same contract as sections:
+      // canonicalization applies to what the registry contributed, and a
+      // listener owns the determinism of what it emits.
+      assembly.tools.push(tool('aardvark'))
+      return next()
+    })
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(seen).toEqual(['alpha', 'zulu'])
+    expect(names(assembly)).toEqual(['alpha', 'zulu', 'aardvark'])
+  })
+
+  it.each([
+    ['an empty list', []],
+    ['a list without the rest entry', ['bash', 'todo_write']],
+  ])('rejects %s at load (the rest entry is required)', async (_case, toolOrder) => {
+    await expect(new Context().plugin(SystemPrompt, { toolOrder })).rejects.toThrow(`must contain the "${TOOL_ORDER_REST}" rest entry`)
+  })
+
+  it.each([
+    ['a duplicate tool name', ['bash', 'bash', TOOL_ORDER_REST]],
+    ['a duplicate rest entry', [TOOL_ORDER_REST, 'bash', TOOL_ORDER_REST]],
+  ])('rejects %s at load', async (_case, toolOrder) => {
+    await expect(new Context().plugin(SystemPrompt, { toolOrder })).rejects.toThrow('more than once')
+  })
+
+  it('throws from direct construction too', () => {
+    expect(() => new SystemPrompt(new Context(), { toolOrder: ['bash'] })).toThrow('rest entry')
+  })
+})

packages/core/tools/README.md

@@ -71,6 +71,12 @@ A `defineTool` tool also **validates the model-generated arguments against its `
 
 See `defineTool`, `validateArgs`, `ToolArgsError`, `SchemaSpec`, `InferArgs`, and `schemaSpecToJsonSchema` in the public API for details.
 
+### 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).
+
 ### 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`):

packages/core/tools/src/index.ts

@@ -28,6 +28,16 @@ export {
   type JsonSchemaObject,
 } from './schema.ts'
 
+export {
+  assertSupportedOutputSchema,
+  validateStructuredValue,
+  OutputSchemaError,
+  type StructuredOutputSchema,
+  type StructuredSchemaNode,
+  type StructuredSchemaType,
+  type StructuredScalar,
+} from './json-schema.ts'
+
 // The render-intent vocabulary a tool declares via `presentCall`/`presentResult`
 // lives in its own UI-facing module; re-export it so `@deepseek-ai/dsh-tools`
 // stays the single public surface for consumers (producers + the ACP bridge).

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

@@ -0,0 +1,345 @@
+/**
+ * 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).
+ *
+ * @module dsh-tools/json-schema
+ */
+
+import { assertNever, HarnessError } from '@deepseek-ai/dsh-llm'
+
+/** The scalar values `enum`/`const` may carry (finite numbers only). */
+export type StructuredScalar = string | number | boolean | null
+
+/** The `type` keywords the subset accepts. */
+export type StructuredSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
+
+/**
+ * One node of the structured-output schema subset. Recursive via `properties`
+ * and `items`; see the module doc for the exact keyword semantics.
+ */
+export interface StructuredSchemaNode {
+  type: StructuredSchemaType
+  /** Nested property schemas (`type: 'object'` only). */
+  properties?: Record<string, StructuredSchemaNode>
+  /** Required property names; each must appear in `properties`. */
+  required?: string[]
+  /** `false` rejects undeclared keys; absent/`true` allows them (JSON Schema default). */
+  additionalProperties?: boolean
+  /** Item schema (`type: 'array'` only); absent ⇒ any JSON items. */
+  items?: StructuredSchemaNode
+  /** Allowed values (scalar types only). */
+  enum?: StructuredScalar[]
+  /** The single allowed value (scalar types only). */
+  const?: StructuredScalar
+  /** Annotation, ignored for validation. */
+  description?: string
+  /** Annotation, ignored for validation. */
+  title?: string
+  /** Annotation, ignored for validation (must still be JSON data). */
+  default?: unknown
+  /** Annotation, ignored for validation (must still be JSON data). */
+  examples?: unknown
+}
+
+/** A structured-output schema: an OBJECT-rooted {@link StructuredSchemaNode}. */
+export type StructuredOutputSchema = StructuredSchemaNode & { type: 'object' }
+
+/**
+ * Thrown by {@link assertSupportedOutputSchema} when a schema falls outside the
+ * supported subset. Extends {@link HarnessError} (`code: 'UNSUPPORTED_SCHEMA'`)
+ * so seam code and tool results can route on it; `violations` lists every
+ * offending path, not just the first.
+ */
+export class OutputSchemaError extends HarnessError {
+  /** The individual violation messages, in walk order. */
+  readonly violations: string[]
+
+  constructor(violations: string[]) {
+    super(`unsupported output schema: ${violations.join('; ')}`, 'UNSUPPORTED_SCHEMA')
+    this.name = 'OutputSchemaError'
+    this.violations = violations
+  }
+}
+
+/** The keywords the subset accepts, checked (`constraint`) or ignored (`annotation`). */
+const CONSTRAINT_KEYWORDS = new Set(['type', 'properties', 'required', 'additionalProperties', 'items', 'enum', 'const'])
+const ANNOTATION_KEYWORDS = new Set(['description', 'title', 'default', 'examples'])
+
+const SCHEMA_TYPES: readonly StructuredSchemaType[] = ['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']
+
+/**
+ * Whether a value is a PLAIN JSON object — non-null, non-array, and with a
+ * prototype chain of at most one link (`null`-proto, or any realm's
+ * `Object.prototype`, whose own prototype is `null`). Realm-agnostic on
+ * purpose: a schema materialized in another realm carries THAT realm's
+ * `Object.prototype`, which an identity check would wrongly reject. Exotic
+ * hosts (`Date`, `Map`, class instances) have longer chains and are rejected —
+ * they would serialize lossily (`Date` → string, `Map` → `{}`) instead of
+ * failing loud.
+ */
+function isObjectLike(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const proto: unknown = Object.getPrototypeOf(value)
+  return proto === null || Object.getPrototypeOf(proto) === null
+}
+
+/** Whether a value is a supported scalar (`enum`/`const` member): string, finite number, boolean, or null. */
+function isStructuredScalar(value: unknown): value is StructuredScalar {
+  return value === null || typeof value === 'string' || typeof value === 'boolean'
+    || (typeof value === 'number' && Number.isFinite(value))
+}
+
+/**
+ * Whether a value is JSON data (annotation payloads only): scalars, arrays, and
+ * object-likes of such values. Realm-agnostic on purpose (no prototype check) —
+ * the schema may have been materialized from another realm; structural JSON-ness
+ * is what the wire needs. Cycles are rejected via `seen`.
+ */
+function isJsonData(value: unknown, seen: Set<object>): boolean {
+  if (isStructuredScalar(value)) return true
+  // The scalar check above already returned for null, so `object` here is a real object.
+  if (typeof value !== 'object') return false
+  if (seen.has(value)) return false
+  seen.add(value)
+  try {
+    if (Array.isArray(value)) return value.every(entry => isJsonData(entry, seen))
+    // A non-plain object (Date, Map, class instance) is NOT JSON data even when
+    // it has no enumerable values — it would serialize lossily, not loudly.
+    if (!isObjectLike(value)) return false
+    return Object.values(value).every(entry => isJsonData(entry, seen))
+  } finally {
+    seen.delete(value)
+  }
+}
+
+/** Collect subset violations for one schema node (recursive walk). */
+function checkSchemaNode(node: unknown, path: string, violations: string[], seen: Set<object>): void {
+  if (!isObjectLike(node)) {
+    violations.push(`${path} must be a schema object`)
+    return
+  }
+  if (seen.has(node)) {
+    violations.push(`${path} is circular`)
+    return
+  }
+  seen.add(node)
+
+  for (const key of Object.keys(node)) {
+    if (CONSTRAINT_KEYWORDS.has(key)) continue
+    if (ANNOTATION_KEYWORDS.has(key)) {
+      if (!isJsonData(node[key], new Set())) violations.push(`${path}.${key} annotation must be JSON data`)
+      continue
+    }
+    violations.push(`${path}.${key} is not a supported keyword (subset: type/properties/required/additionalProperties/items/enum/const + annotations)`)
+  }
+  if (typeof node.description !== 'undefined' && typeof node.description !== 'string') {
+    violations.push(`${path}.description must be a string`)
+  }
+  if (typeof node.title !== 'undefined' && typeof node.title !== 'string') {
+    violations.push(`${path}.title must be a string`)
+  }
+
+  const type = node.type
+  if (typeof type !== 'string' || !(SCHEMA_TYPES as readonly unknown[]).includes(type)) {
+    violations.push(Array.isArray(type)
+      ? `${path}.type must be a single type string (type arrays are not supported)`
+      : `${path}.type must be one of ${SCHEMA_TYPES.join('/')}`)
+    seen.delete(node)
+    return
+  }
+  const schemaType = type as StructuredSchemaType
+
+  // Keywords that only make sense on one type are rejected elsewhere — an
+  // `items` on an object (or `properties` on a string) is a schema-author bug
+  // the subset surfaces rather than ignores.
+  const allowedFor: Record<string, StructuredSchemaType[]> = {
+    properties: ['object'],
+    required: ['object'],
+    additionalProperties: ['object'],
+    items: ['array'],
+    enum: ['string', 'number', 'integer', 'boolean', 'null'],
+    const: ['string', 'number', 'integer', 'boolean', 'null'],
+  }
+  for (const [key, types] of Object.entries(allowedFor)) {
+    if (key in node && !types.includes(schemaType)) {
+      violations.push(`${path}.${key} is not supported on type "${schemaType}"`)
+    }
+  }
+
+  switch (schemaType) {
+    case 'object': {
+      const properties = node.properties
+      if (properties !== undefined) {
+        if (!isObjectLike(properties)) {
+          violations.push(`${path}.properties must be an object of schemas`)
+        } else {
+          for (const [key, child] of Object.entries(properties)) {
+            checkSchemaNode(child, `${path}.properties.${key}`, violations, seen)
+          }
+        }
+      }
+      const required = node.required
+      if (required !== undefined) {
+        if (!Array.isArray(required) || required.some(entry => typeof entry !== 'string')) {
+          violations.push(`${path}.required must be an array of strings`)
+        } else {
+          const declared = isObjectLike(properties) ? properties : {}
+          // The guard above proved every entry is a string.
+          for (const key of required as string[]) {
+            // Own-property check: `in` would let inherited names (`toString`)
+            // satisfy the declared-in-properties contract via the prototype.
+            if (!Object.hasOwn(declared, key)) violations.push(`${path}.required names "${key}" which is not in properties`)
+          }
+        }
+      }
+      if (node.additionalProperties !== undefined && typeof node.additionalProperties !== 'boolean') {
+        violations.push(`${path}.additionalProperties must be a boolean`)
+      }
+      break
+    }
+    case 'array': {
+      if (node.items !== undefined) checkSchemaNode(node.items, `${path}.items`, violations, seen)
+      break
+    }
+    case 'string':
+    case 'number':
+    case 'integer':
+    case 'boolean':
+    case 'null': {
+      const allowed = node.enum
+      if (allowed !== undefined) {
+        if (!Array.isArray(allowed) || allowed.length === 0 || !allowed.every(entry => isStructuredScalar(entry))) {
+          violations.push(`${path}.enum must be a non-empty array of scalars`)
+        }
+      }
+      if ('const' in node && !isStructuredScalar(node.const)) {
+        violations.push(`${path}.const must be a scalar`)
+      }
+      break
+    }
+    /* v8 ignore start -- defensive: schemaType was membership-checked against SCHEMA_TYPES above, so no runtime value reaches here */
+    default:
+      assertNever(schemaType, 'assertSupportedOutputSchema')
+    /* v8 ignore stop */
+  }
+
+  seen.delete(node)
+}
+
+/**
+ * Assert `schema` is a supported {@link StructuredOutputSchema} — object-rooted
+ * and entirely within the enforced subset. Throws {@link OutputSchemaError}
+ * (`UNSUPPORTED_SCHEMA`) listing EVERY violation; returns (and narrows) on
+ * success. Call this at the seam boundary, before any child is created.
+ * @param schema - the caller-supplied schema (unknown until asserted).
+ * @returns nothing — the assertion signature narrows `schema` to
+ * {@link StructuredOutputSchema} in the caller's scope on normal return.
+ */
+export function assertSupportedOutputSchema(schema: unknown): asserts schema is StructuredOutputSchema {
+  const violations: string[] = []
+  checkSchemaNode(schema, 'schema', violations, new Set())
+  if (violations.length === 0 && (schema as StructuredSchemaNode).type !== 'object') {
+    violations.push('schema.type must be "object" (structured output is object-rooted)')
+  }
+  if (violations.length > 0) throw new OutputSchemaError(violations)
+}
+
+/** Collect violations for one value against an (already asserted) schema node. */
+function checkValue(node: StructuredSchemaNode, value: unknown, path: string): string[] {
+  switch (node.type) {
+    case 'object': {
+      if (!isObjectLike(value)) return [`"${path}" must be an object`]
+      const violations: string[] = []
+      const properties = node.properties ?? {}
+      // Own-property discipline throughout: JSON carries own enumerable
+      // properties only, so an inherited `toString` must not satisfy
+      // `required`, dodge `additionalProperties: false`, or be validated as if
+      // the value carried it.
+      for (const key of node.required ?? []) {
+        if (!Object.hasOwn(value, key) || value[key] === undefined) violations.push(`missing required property "${path}.${key}"`)
+      }
+      for (const [key, child] of Object.entries(properties)) {
+        if (!Object.hasOwn(value, key) || value[key] === undefined) continue
+        violations.push(...checkValue(child, value[key], `${path}.${key}`))
+      }
+      if (node.additionalProperties === false) {
+        for (const key of Object.keys(value)) {
+          if (!Object.hasOwn(properties, key)) violations.push(`"${path}.${key}" is not a declared property (additionalProperties: false)`)
+        }
+      }
+      return violations
+    }
+    case 'array': {
+      if (!Array.isArray(value)) return [`"${path}" must be an array`]
+      if (!node.items) return []
+      const items = node.items
+      return value.flatMap((entry, index) => checkValue(items, entry, `${path}[${index}]`))
+    }
+    case 'string': {
+      if (typeof value !== 'string') return [`"${path}" must be a string`]
+      break
+    }
+    case 'number': {
+      if (typeof value !== 'number' || !Number.isFinite(value)) return [`"${path}" must be a finite number`]
+      break
+    }
+    case 'integer': {
+      if (typeof value !== 'number' || !Number.isInteger(value)) return [`"${path}" must be an integer`]
+      break
+    }
+    case 'boolean': {
+      if (typeof value !== 'boolean') return [`"${path}" must be a boolean`]
+      break
+    }
+    case 'null': {
+      if (value !== null) return [`"${path}" must be null`]
+      break
+    }
+    default:
+      return assertNever(node.type, 'validateStructuredValue')
+  }
+  // Scalar constraint checks, shared by every scalar branch above.
+  if (node.enum && !node.enum.includes(value)) {
+    return [`"${path}" must be one of ${JSON.stringify(node.enum)}`]
+  }
+  if ('const' in node && value !== node.const) {
+    return [`"${path}" must be ${JSON.stringify(node.const)}`]
+  }
+  return []
+}
+
+/**
+ * Validate a value against an (already {@link assertSupportedOutputSchema}-
+ * asserted) schema. Returns human-readable, path-qualified violation messages
+ * — empty means valid. Total: never throws, however malformed the value.
+ * @param schema - the asserted schema to check against.
+ * @param value - the candidate value (e.g. parsed tool-call arguments).
+ * @returns every violation found, in walk order (empty = valid).
+ */
+export function validateStructuredValue(schema: StructuredOutputSchema, value: unknown): string[] {
+  return checkValue(schema, value, 'value')
+}

packages/core/tools/src/schema.ts

@@ -155,6 +155,9 @@ export interface JsonSchemaObject {
  * `properties`, `required` array).
  *
  * This is a plain function — no schemastery or other framework dependency.
+ * @param spec - the author-facing per-property schema to convert.
+ * @returns the wire-format JSON Schema; the top-level `required` array is
+ *   omitted entirely when no property is marked required.
  */
 export function schemaSpecToJsonSchema(spec: SchemaSpec): JsonSchemaObject {
   const properties: Record<string, unknown> = {}
@@ -269,6 +272,9 @@ function checkSpec(spec: SchemaSpec, value: unknown, path: string): string[] {
  * keys are allowed (no `additionalProperties: false`); `default` is not
  * applied; an `object`/`array` prop without `properties`/`items` only
  * type-checks; `enum` is membership (strings only).
+ * @param spec - the declared parameter schema to validate against.
+ * @param args - the model-generated arguments, however malformed.
+ * @returns the violation messages in declaration order; empty means valid.
  */
 export function validateArgs(spec: SchemaSpec, args: unknown): string[] {
   return checkSpec(spec, args, '')
@@ -340,6 +346,13 @@ export interface DefineToolOptions<S extends SchemaSpec> {
  * Raw JSON-Schema tool definitions (from MCP servers) are still accepted
  * by `ToolRegistry.register()` directly — `defineTool` is sugar for
  * first-party plugin authors.
+ * @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).
  */
 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/tests/json-schema.spec.ts

@@ -0,0 +1,304 @@
+import { describe, expect, it } from 'vitest'
+import {
+  assertSupportedOutputSchema,
+  OutputSchemaError,
+  validateStructuredValue,
+  type StructuredOutputSchema,
+} from '../src/json-schema.ts'
+
+/** Assert-and-narrow helper: the asserted schema, typed. */
+function asserted(schema: unknown): StructuredOutputSchema {
+  assertSupportedOutputSchema(schema)
+  return schema
+}
+
+/** The violations OutputSchemaError carries for a bad schema (throws if it passes). */
+function violationsOf(schema: unknown): string[] {
+  try {
+    assertSupportedOutputSchema(schema)
+  } catch (error: unknown) {
+    if (error instanceof OutputSchemaError) return error.violations
+    throw error
+  }
+  throw new Error('expected the schema to be rejected')
+}
+
+describe('assertSupportedOutputSchema', () => {
+  it('accepts a representative subset schema (all supported keywords)', () => {
+    const schema = asserted({
+      type: 'object',
+      description: 'a finding',
+      title: 'Finding',
+      properties: {
+        file: { type: 'string', description: 'path' },
+        line: { type: 'integer' },
+        severity: { type: 'string', enum: ['low', 'high'] },
+        kind: { type: 'string', const: 'bug' },
+        score: { type: 'number' },
+        confirmed: { type: 'boolean' },
+        parent: { type: 'null' },
+        tags: { type: 'array', items: { type: 'string' } },
+        nested: {
+          type: 'object',
+          properties: { x: { type: 'number', default: 3, examples: [1, 2] } },
+          additionalProperties: false,
+        },
+        anything: { type: 'array' },
+      },
+      required: ['file', 'line'],
+      additionalProperties: true,
+    })
+    expect(schema.type).toBe('object')
+  })
+
+  it('rejects a non-object root (scalar/array-rooted schemas)', () => {
+    expect(violationsOf({ type: 'string' })).toEqual(['schema.type must be "object" (structured output is object-rooted)'])
+    expect(violationsOf({ type: 'array', items: { type: 'string' } }))
+      .toContain('schema.type must be "object" (structured output is object-rooted)')
+  })
+
+  it('rejects non-object schema nodes and missing/unknown type', () => {
+    expect(violationsOf('nope')).toEqual(['schema must be a schema object'])
+    expect(violationsOf(null)).toEqual(['schema must be a schema object'])
+    expect(violationsOf([])).toEqual(['schema must be a schema object'])
+    expect(violationsOf({})).toEqual(['schema.type must be one of object/array/string/number/integer/boolean/null'])
+    expect(violationsOf({ type: 'tuple' })[0]).toMatch(/type must be one of/)
+    expect(violationsOf({ type: 'object', properties: { a: 'str' } })).toEqual(['schema.properties.a must be a schema object'])
+  })
+
+  it('rejects type ARRAYS with a dedicated message', () => {
+    expect(violationsOf({ type: ['string', 'null'] }))
+      .toEqual(['schema.type must be a single type string (type arrays are not supported)'])
+  })
+
+  it('rejects unsupported constraint keywords loudly (never accepted-then-ignored)', () => {
+    for (const keyword of ['oneOf', 'anyOf', 'allOf', 'not', 'pattern', 'minimum', 'maxLength', '$ref']) {
+      const bad = violationsOf({ type: 'object', [keyword]: [] })
+      expect(bad.some(v => v.includes(`schema.${keyword} is not a supported keyword`))).toBe(true)
+    }
+  })
+
+  it('reports EVERY violation, not just the first', () => {
+    const bad = violationsOf({
+      type: 'object',
+      pattern: 'x',
+      properties: { a: { type: 'weird' }, b: { type: 'string', minimum: 1 } },
+    })
+    expect(bad.length).toBe(3)
+  })
+
+  it('rejects keywords on the wrong type (items on object, properties on string, enum on object)', () => {
+    expect(violationsOf({ type: 'object', items: { type: 'string' } }))
+      .toEqual(['schema.items is not supported on type "object"'])
+    expect(violationsOf({ type: 'object', properties: { a: { type: 'string', properties: {} } } }))
+      .toEqual(['schema.properties.a.properties is not supported on type "string"'])
+    expect(violationsOf({ type: 'object', enum: [1] }))
+      .toEqual(['schema.enum is not supported on type "object"'])
+    expect(violationsOf({ type: 'object', properties: { a: { type: 'array', const: 1 } } }))
+      .toEqual(['schema.properties.a.const is not supported on type "array"'])
+  })
+
+  it('validates required: must be string[] naming declared properties', () => {
+    expect(violationsOf({ type: 'object', required: 'file' }))
+      .toEqual(['schema.required must be an array of strings'])
+    expect(violationsOf({ type: 'object', required: [1] }))
+      .toEqual(['schema.required must be an array of strings'])
+    expect(violationsOf({ type: 'object', properties: { a: { type: 'string' } }, required: ['b'] }))
+      .toEqual(['schema.required names "b" which is not in properties'])
+    expect(violationsOf({ type: 'object', required: ['a'] }))
+      .toEqual(['schema.required names "a" which is not in properties'])
+  })
+
+  it('validates additionalProperties must be boolean and enum/const must be scalars', () => {
+    expect(violationsOf({ type: 'object', additionalProperties: {} }))
+      .toEqual(['schema.additionalProperties must be a boolean'])
+    expect(violationsOf({ type: 'object', properties: { a: { type: 'string', enum: [] } } }))
+      .toEqual(['schema.properties.a.enum must be a non-empty array of scalars'])
+    expect(violationsOf({ type: 'object', properties: { a: { type: 'string', enum: [{}] } } }))
+      .toEqual(['schema.properties.a.enum must be a non-empty array of scalars'])
+    expect(violationsOf({ type: 'object', properties: { a: { type: 'string', enum: 'x' } } }))
+      .toEqual(['schema.properties.a.enum must be a non-empty array of scalars'])
+    expect(violationsOf({ type: 'object', properties: { a: { type: 'number', enum: [Number.NaN] } } }))
+      .toEqual(['schema.properties.a.enum must be a non-empty array of scalars'])
+    expect(violationsOf({ type: 'object', properties: { a: { type: 'string', const: {} } } }))
+      .toEqual(['schema.properties.a.const must be a scalar'])
+  })
+
+  it('rejects non-string description/title and non-JSON annotation payloads', () => {
+    expect(violationsOf({ type: 'object', description: 7 }))
+      .toEqual(['schema.description must be a string'])
+    expect(violationsOf({ type: 'object', title: 7 }))
+      .toEqual(['schema.title must be a string'])
+    expect(violationsOf({ type: 'object', default: () => 1 }))
+      .toEqual(['schema.default annotation must be JSON data'])
+    expect(violationsOf({ type: 'object', examples: [undefined] }))
+      .toEqual(['schema.examples annotation must be JSON data'])
+    expect(violationsOf({ type: 'object', examples: [Number.POSITIVE_INFINITY] }))
+      .toEqual(['schema.examples annotation must be JSON data'])
+    // A cyclic annotation payload is caught by the JSON-data walk.
+    const cyclicAnnotation: Record<string, unknown> = {}
+    cyclicAnnotation.self = cyclicAnnotation
+    expect(violationsOf({ type: 'object', default: cyclicAnnotation }))
+      .toEqual(['schema.default annotation must be JSON data'])
+    // Object/array annotations that ARE JSON data pass.
+    asserted({ type: 'object', default: { a: [1, 'x', null, true] } })
+  })
+
+  it('rejects a circular schema instead of recursing forever', () => {
+    const node: Record<string, unknown> = { type: 'object' }
+    node.properties = { self: node }
+    expect(violationsOf(node)).toEqual(['schema.properties.self is circular'])
+  })
+
+  it('accepts the same subschema object reused in two SIBLING positions (a DAG, not a cycle)', () => {
+    const leaf = { type: 'string' }
+    asserted({ type: 'object', properties: { a: leaf, b: leaf } })
+  })
+
+  it('required cannot be satisfied by INHERITED names — `toString` is not a declared property', () => {
+    // `'toString' in {}` is true via Object.prototype; the declared-property
+    // contract must be an own-property check.
+    expect(violationsOf({ type: 'object', properties: {}, required: ['toString'] }))
+      .toEqual(['schema.required names "toString" which is not in properties'])
+  })
+
+  it('rejects exotic host objects where the subset expects plain JSON structure', () => {
+    // A Map as `properties` has no own enumerable entries: structurally it
+    // would read as "no properties" and serialize to {} — lossy, not loud.
+    expect(violationsOf({ type: 'object', properties: new Map() }))
+      .toEqual(['schema.properties must be an object of schemas'])
+    // A Date node is not a schema object even though Object.values(date) is [].
+    expect(violationsOf({ type: 'object', properties: { at: new Date(0) } }))
+      .toEqual(['schema.properties.at must be a schema object'])
+  })
+
+  it('rejects exotic annotation payloads that would serialize lossily', () => {
+    expect(violationsOf({ type: 'object', default: new Date(0) }))
+      .toEqual(['schema.default annotation must be JSON data'])
+    expect(violationsOf({ type: 'object', examples: [new Map()] }))
+      .toEqual(['schema.examples annotation must be JSON data'])
+  })
+})
+
+describe('validateStructuredValue', () => {
+  const schema = asserted({
+    type: 'object',
+    properties: {
+      file: { type: 'string' },
+      line: { type: 'integer' },
+      score: { type: 'number' },
+      confirmed: { type: 'boolean' },
+      parent: { type: 'null' },
+      severity: { type: 'string', enum: ['low', 'high'] },
+      kind: { type: 'string', const: 'bug' },
+      tags: { type: 'array', items: { type: 'string' } },
+      free: { type: 'array' },
+      nested: { type: 'object', properties: { x: { type: 'number' } }, required: ['x'], additionalProperties: false },
+    },
+    required: ['file'],
+  })
+
+  it('accepts a fully valid value (empty violations)', () => {
+    expect(validateStructuredValue(schema, {
+      file: 'a.ts', line: 3, score: 0.5, confirmed: true, parent: null,
+      severity: 'high', kind: 'bug', tags: ['x'], free: [1, { any: true }], nested: { x: 1 },
+    })).toEqual([])
+  })
+
+  it('reports missing required and wrong root type', () => {
+    expect(validateStructuredValue(schema, {})).toEqual(['missing required property "value.file"'])
+    expect(validateStructuredValue(schema, 'nope')).toEqual(['"value" must be an object'])
+    expect(validateStructuredValue(schema, [])).toEqual(['"value" must be an object'])
+  })
+
+  it('type-checks every scalar branch with path-qualified messages', () => {
+    expect(validateStructuredValue(schema, { file: 1 })).toEqual(['"value.file" must be a string'])
+    expect(validateStructuredValue(schema, { file: 'a', line: 1.5 })).toEqual(['"value.line" must be an integer'])
+    expect(validateStructuredValue(schema, { file: 'a', line: 'x' })).toEqual(['"value.line" must be an integer'])
+    expect(validateStructuredValue(schema, { file: 'a', score: 'x' })).toEqual(['"value.score" must be a finite number'])
+    expect(validateStructuredValue(schema, { file: 'a', score: Number.NaN })).toEqual(['"value.score" must be a finite number'])
+    expect(validateStructuredValue(schema, { file: 'a', confirmed: 'yes' })).toEqual(['"value.confirmed" must be a boolean'])
+    expect(validateStructuredValue(schema, { file: 'a', parent: 0 })).toEqual(['"value.parent" must be null'])
+  })
+
+  it('enforces enum membership and const equality', () => {
+    expect(validateStructuredValue(schema, { file: 'a', severity: 'mid' }))
+      .toEqual(['"value.severity" must be one of ["low","high"]'])
+    expect(validateStructuredValue(schema, { file: 'a', kind: 'feature' }))
+      .toEqual(['"value.kind" must be "bug"'])
+  })
+
+  it('checks arrays per index; an items-less array accepts anything', () => {
+    expect(validateStructuredValue(schema, { file: 'a', tags: 'x' })).toEqual(['"value.tags" must be an array'])
+    expect(validateStructuredValue(schema, { file: 'a', tags: ['ok', 2] })).toEqual(['"value.tags[1]" must be a string'])
+    expect(validateStructuredValue(schema, { file: 'a', free: [{ deep: [1] }, null] })).toEqual([])
+  })
+
+  it('recurses into nested objects: required + additionalProperties: false', () => {
+    expect(validateStructuredValue(schema, { file: 'a', nested: {} }))
+      .toEqual(['missing required property "value.nested.x"'])
+    expect(validateStructuredValue(schema, { file: 'a', nested: { x: 1, y: 2 } }))
+      .toEqual(['"value.nested.y" is not a declared property (additionalProperties: false)'])
+    expect(validateStructuredValue(schema, { file: 'a', nested: 3 }))
+      .toEqual(['"value.nested" must be an object'])
+  })
+
+  it('a required key present-but-undefined counts as missing', () => {
+    expect(validateStructuredValue(schema, { file: undefined })).toEqual(['missing required property "value.file"'])
+  })
+
+  it('inherited properties satisfy nothing: required, additionalProperties, and recursion are own-property only', () => {
+    // required: ['toString'] must NOT be satisfied by Object.prototype.toString.
+    expect(validateStructuredValue(
+      asserted({ type: 'object', properties: { toString: { type: 'string' } }, required: ['toString'] }),
+      {},
+    )).toEqual(['missing required property "value.toString"'])
+    // additionalProperties: false must flag an OWN `toString` key even though
+    // `'toString' in properties` is true via the prototype.
+    expect(validateStructuredValue(
+      asserted({ type: 'object', additionalProperties: false }),
+      { toString: 1 },
+    )).toEqual(['"value.toString" is not a declared property (additionalProperties: false)'])
+    // A declared property the value does NOT carry must not be validated
+    // against the value's INHERITED member (constructor is a function on
+    // every plain object's prototype, not a carried property).
+    expect(validateStructuredValue(
+      asserted({ type: 'object', properties: { constructor: { type: 'string' } } }),
+      {},
+    )).toEqual([])
+  })
+
+  it('a non-plain object value is not an object in the JSON sense', () => {
+    expect(validateStructuredValue(asserted({ type: 'object' }), new Date(0)))
+      .toEqual(['"value" must be an object'])
+  })
+
+  it('collects multiple violations across branches in one pass', () => {
+    expect(validateStructuredValue(schema, { line: 'x', severity: 'mid' })).toEqual([
+      'missing required property "value.file"',
+      '"value.line" must be an integer',
+      '"value.severity" must be one of ["low","high"]',
+    ])
+  })
+
+  it('null-typed const/enum work through the scalar path', () => {
+    const nullish = asserted({ type: 'object', properties: { a: { type: 'null', const: null } } })
+    expect(validateStructuredValue(nullish, { a: null })).toEqual([])
+  })
+
+  it('rejects a non-object properties value in the schema walk', () => {
+    expect(violationsOf({ type: 'object', properties: [] }))
+      .toEqual(['schema.properties must be an object of schemas'])
+  })
+
+  it('an object schema without properties/required only type-checks its value', () => {
+    const bare = asserted({ type: 'object' })
+    expect(validateStructuredValue(bare, { any: ['thing'] })).toEqual([])
+    expect(validateStructuredValue(bare, 7)).toEqual(['"value" must be an object'])
+  })
+
+  it('validateStructuredValue throws on a type the assert would never let through (assertNever backstop)', () => {
+    const forged = { type: 'tuple' } as unknown as StructuredOutputSchema
+    expect(() => validateStructuredValue(forged, 1)).toThrow(/tuple/)
+  })
+})

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

@@ -129,6 +129,9 @@ export interface LocalDirEntry {
  * 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.
+ * @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.
  */
 export async function resolveLocalTarget(cwd: string, path: string): Promise<LocalTarget> {
   if (path.trim().length === 0) throw new FsError('file_path must be a non-empty string', 'FS_NOT_FOUND')
@@ -165,7 +168,11 @@ export async function resolveLocalTarget(cwd: string, path: string): Promise<Loc
   }
 }
 
-/** Probe a path for its version, mode, type, and size. Null if absent. */
+/**
+ * Probe a path for its version, mode, type, and size. Null if absent.
+ * @param absolutePath - the path to stat (typically a target key; symlinks are followed).
+ * @returns the metadata, or null when the path — or a parent segment — does not exist.
+ */
 export async function probe(absolutePath: string): Promise<PathInfo | null> {
   try {
     const info = await stat(absolutePath)
@@ -200,6 +207,9 @@ async function resolveListedChildTarget(parent: LocalTarget, name: string): Prom
  * List direct children of a directory in stable name order. Each child includes
  * a resolved target plus stat metadata when still available; file contents are
  * never read.
+ * @param target - the resolved directory to list; a missing or non-directory target throws.
+ * @param signal - aborts the listing, checked between children (`FS_ABORTED`).
+ * @returns one entry per direct child, sorted by name.
  */
 export async function listDirectory(target: LocalTarget, signal?: AbortSignal): Promise<LocalDirEntry[]> {
   throwIfAborted(signal, 'list')
@@ -290,6 +300,9 @@ async function statRegularFile(target: LocalTarget, verb: 'read', signal?: Abort
 /**
  * Read a whole regular UTF-8 text file into a single decoded string. Rejects
  * non-regular files, invalid UTF-8, and NUL-byte binary samples.
+ * @param target - the resolved file to read.
+ * @param signal - aborts the read (`FS_ABORTED`).
+ * @returns the full decoded text, byte-for-byte (no normalization).
  */
 export async function readWholeText(target: LocalTarget, signal?: AbortSignal): Promise<string> {
   await statRegularFile(target, 'read', signal)
@@ -305,6 +318,9 @@ export async function readWholeText(target: LocalTarget, signal?: AbortSignal):
  * Stream a whole regular UTF-8 text file as decoded text chunks. Same text
  * semantics as {@link readWholeText} (regular-file check, binary/NUL rejection,
  * cross-chunk UTF-8 decoding), but never holds the whole file in memory.
+ * @param target - the resolved file to stream.
+ * @param signal - aborts the stream, including between chunks (`FS_ABORTED`).
+ * @returns decoded text chunks in file order; chunk boundaries carry no meaning.
  */
 export async function* streamWholeText(target: LocalTarget, signal?: AbortSignal): AsyncIterable<string> {
   await statRegularFile(target, 'read', signal)
@@ -352,6 +368,11 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
  * (`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.
+ * @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 internals - test seam for pinning temp names and observing the staged file.
  */
 export async function writeFileAtomic(
   absolutePath: string,
@@ -409,6 +430,12 @@ export async function writeFileAtomic(
 /** Line ending style detected before LF normalization. */
 export type LineEndings = 'LF' | 'CRLF'
 
+/**
+ * Collapse CRLF to LF — the canonical in-memory form every edit/diff basis
+ * uses. Lone `\r` bytes (not followed by `\n`) are left untouched.
+ * @param content - decoded text in whatever line-ending style the file had.
+ * @returns the text with every `\r\n` pair replaced by `\n`.
+ */
 function normalizeLineEndings(content: string): string {
   return content.replaceAll('\r\n', '\n')
 }
@@ -420,6 +447,14 @@ function detectLineEndings(raw: string): LineEndings {
   return crlfCount > lfCount ? 'CRLF' : 'LF'
 }
 
+/**
+ * Convert LF-normalized content back to the line-ending style detected at read
+ * time, for write-back. `LF` returns the content unchanged; `CRLF` re-normalizes
+ * first so an already-CRLF sequence is never doubled to `\r\r\n`.
+ * @param content - the LF-normalized (edited) text.
+ * @param lineEndings - the original file's style, as detected by {@link readForEdit}.
+ * @returns the text in the original file's line-ending style.
+ */
 function restoreLineEndings(content: string, lineEndings: LineEndings): string {
   return lineEndings === 'LF' ? content : normalizeLineEndings(content).split('\n').join('\r\n')
 }
@@ -438,6 +473,10 @@ function countOccurrences(content: string, needle: string): number {
 /**
  * Read and decode a file for editing: rejects binaries, returns LF-normalized
  * content plus the original line-ending style for write-back.
+ * @param absolutePath - the file to read (typically a target key).
+ * @param displayPath - the caller-facing path used in error messages.
+ * @param signal - aborts the read (`FS_ABORTED`).
+ * @returns the LF-normalized content and the detected style to restore on write-back.
  */
 export async function readForEdit(
   absolutePath: string,
@@ -459,6 +498,9 @@ export async function readForEdit(
  * 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).
+ * @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.
  */
 export async function readTextForDiff(absolutePath: string, signal?: AbortSignal): Promise<string | null> {
   const buffer = await readFileAbortable(absolutePath, 'read', signal)
@@ -477,6 +519,12 @@ export async function readTextForDiff(absolutePath: string, signal?: AbortSignal
  * `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.
+ * @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 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.
+ * @returns the edited LF-normalized content plus how many occurrences were replaced.
  */
 export function applyLiteralEdit(
   content: string,

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

@@ -73,6 +73,7 @@ export class LocalFileSystem extends FileSystem {
     cwd: z.string().default(process.cwd()),
   })
 
+  /** Validated config (schemastery applied the defaults before construction). */
   readonly config: ResolvedConfig
   /** Test seam forwarded to fsio (force streaming path, pin temp names). */
   internals: FsIoInternals = {}

packages/fs/fs/src/types.ts

@@ -29,7 +29,12 @@ import type { Branded } from '@deepseek-ai/dsh-brand'
  */
 export type FsTargetKey = Branded<'FsTargetKey'>
 
-/** Brand a string as an {@link FsTargetKey}. */
+/**
+ * Brand a string as an {@link FsTargetKey}. For backend use only — a consumer
+ * never manufactures a key, it receives one from `resolve()`.
+ * @param key - the backend's raw key string (the local backend passes a realpath).
+ * @returns the same string, branded; no validation is performed.
+ */
 export function FsTargetKey(key: string): FsTargetKey {
   return key as FsTargetKey
 }
@@ -42,7 +47,12 @@ export function FsTargetKey(key: string): FsTargetKey {
  */
 export type FsVersion = Branded<'FsVersion'>
 
-/** Brand a string as an {@link FsVersion}. */
+/**
+ * Brand a string as an {@link FsVersion}. For backend use only — a consumer
+ * never manufactures a version, it receives one from `stat`/write/edit outcomes.
+ * @param v - the backend's raw version string (the local backend derives it from mtime+size).
+ * @returns the same string, branded; no validation is performed.
+ */
 export function FsVersion(v: string): FsVersion {
   return v as FsVersion
 }

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

@@ -40,6 +40,10 @@ export type FsDiffMeta = { diffs: FileDiff[] }
  * (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 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.
  */
 export function computeHunkDiffs(path: string, before: string, after: string): FileDiff[] {
   const patch = structuredPatch('', '', before, after, undefined, undefined, { context: DIFF_CONTEXT })
@@ -83,6 +87,8 @@ function isFileDiff(value: unknown): value is FileDiff {
  * 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.
  */
 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

@@ -29,7 +29,13 @@ interface EditInput {
   replaceAll: boolean
 }
 
-/** Validate value constraints the schema DSL can't express. */
+/**
+ * Validate value constraints the schema DSL can't express: a non-blank
+ * `file_path`, a non-empty `old_string`, and `old_string !== new_string`
+ * (an equal pair would be a guaranteed no-op edit).
+ * @param args - the schema-validated raw tool arguments.
+ * @returns the camelCased input with `replace_all` defaulted to false.
+ */
 export function parseEditArgs(args: { file_path: string; old_string: string; new_string: string; replace_all?: boolean }): EditInput {
   if (args.file_path.trim().length === 0) throw new Error('file_path must be a non-empty string')
   if (args.old_string.length === 0) throw new Error('old_string must be a non-empty string')
@@ -42,14 +48,22 @@ export function parseEditArgs(args: { file_path: string; old_string: string; new
   }
 }
 
-/** Format an edit success (single-match or replace-all) as a Claude-style model-facing message. */
+/**
+ * Format an edit success (single-match or replace-all) as a Claude-style model-facing message.
+ * @param displayPath - the backend-resolved path shown to the model.
+ * @param replaceAll - selects the all-occurrences wording over the single-replacement one.
+ * @returns the confirmation sentence the model sees as the tool result.
+ */
 export function formatEditOutput(displayPath: string, replaceAll: boolean): string {
   return replaceAll
     ? `The file ${displayPath} has been updated. All occurrences were successfully replaced.`
     : `The file ${displayPath} has been updated successfully.`
 }
 
-/** Register the `edit` tool and its system-prompt guidance. */
+/**
+ * Register the `edit` tool and its system-prompt guidance.
+ * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
+ */
 export function applyEditTool(ctx: Context): void {
   ctx.systemPrompt.section({
     name: 'tool:edit',

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

@@ -119,6 +119,10 @@ function finish(acc: WindowAccumulator, request: ReadWindow, displayPath: string
  * 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.
+ * @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.
+ * @returns the numbered window lines, the total line count seen, and the byte-cap truncation flag.
  */
 export async function buildWindow(
   chunks: AsyncIterable<string> | Iterable<string>,
@@ -156,7 +160,12 @@ export async function buildWindow(
   return finish(acc, request, displayPath)
 }
 
-/** Format a read outcome as one OpenCode-style line-numbered text block body. */
+/**
+ * Format a read outcome as one OpenCode-style line-numbered text block body.
+ * @param displayPath - the backend-resolved path rendered in the envelope's `<path>` element.
+ * @param outcome - the windowed read to render.
+ * @returns the model-facing envelope: numbered lines plus a continuation or end-of-file footer.
+ */
 export function formatReadOutput(displayPath: string, outcome: FileReadOutcome): string {
   const endLine = outcome.lines.at(-1)?.number ?? Math.max(0, outcome.offset - 1)
   let footer: string

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

@@ -58,7 +58,12 @@ function parsePositiveInteger(value: number, name: string): number {
   return value
 }
 
-/** Validate value constraints the schema DSL can't express. `maxLimit` is the deployment's line cap. */
+/**
+ * Validate value constraints the schema DSL can't express. `maxLimit` is the deployment's line cap.
+ * @param args - the schema-validated raw tool arguments; `offset`/`limit` must be positive integers when given.
+ * @param maxLimit - the configured line cap: both the default `limit` and the largest one accepted.
+ * @returns the validated input with `offset` defaulted to 1 and `limit` to `maxLimit`.
+ */
 export function parseReadArgs(args: { file_path: string; offset?: number; limit?: number }, maxLimit: number): ReadInput {
   if (args.file_path.trim().length === 0) throw new Error('file_path must be a non-empty string')
   const offset = args.offset === undefined ? 1 : parsePositiveInteger(args.offset, 'offset')
@@ -67,7 +72,11 @@ export function parseReadArgs(args: { file_path: string; offset?: number; limit?
   return { filePath: args.file_path, offset, limit }
 }
 
-/** Register the `read` tool and its system-prompt guidance. */
+/**
+ * Register the `read` tool and its system-prompt guidance.
+ * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
+ * @param caps - the deployment's resolved read caps (plugin config after defaulting).
+ */
 export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
   ctx.systemPrompt.section({
     name: 'tool:read',

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

@@ -18,7 +18,11 @@
 
 import type { ToolExecution } from '@deepseek-ai/dsh-tools'
 
-/** The session workspace cwd for this call, or `undefined` when none applies. */
+/**
+ * The session workspace cwd for this call, or `undefined` when none applies.
+ * @param exec - the tool-execution context; only its optional `agent` is read.
+ * @returns the calling agent's session cwd, or undefined for a non-agent caller (the backend then applies its own default).
+ */
 export function sessionCwd(exec: ToolExecution): string | undefined {
   return exec.agent?.session.header.cwd
 }

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

@@ -21,13 +21,23 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 import { computeHunkDiffs, diffsFromMeta, type FsDiffMeta } from './diff.ts'
 import { sessionCwd } from './session-cwd.ts'
 
-/** Validate value constraints the schema DSL can't express. */
+/**
+ * Validate value constraints the schema DSL can't express: only a non-blank
+ * `file_path` — an empty `content` is legitimate (it writes an empty file).
+ * @param args - the schema-validated raw tool arguments.
+ * @returns the camelCased input; `content` passes through untouched.
+ */
 export function parseWriteArgs(args: { file_path: string; content: string }): { filePath: string; content: string } {
   if (args.file_path.trim().length === 0) throw new Error('file_path must be a non-empty string')
   return { filePath: args.file_path, content: args.content }
 }
 
-/** Format a write outcome as one model-facing text block body. */
+/**
+ * Format a write outcome as one model-facing text block body.
+ * @param displayPath - the backend-resolved path rendered in the envelope's `<path>` element.
+ * @param outcome - the write outcome; its `operation` selects the Created/Updated wording.
+ * @returns the model-facing confirmation envelope (no file content is echoed back).
+ */
 export function formatWriteOutput(displayPath: string, outcome: FsWriteOutcome): string {
   const verb = outcome.operation === 'create' ? 'Created' : 'Updated'
   return `<path>${displayPath}</path>
@@ -37,7 +47,10 @@ ${verb} file
 </content>`
 }
 
-/** Register the `write` tool and its system-prompt guidance. */
+/**
+ * Register the `write` tool and its system-prompt guidance.
+ * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
+ */
 export function applyWriteTool(ctx: Context): void {
   ctx.systemPrompt.section({
     name: 'tool:write',

packages/hooks/hook-protocol/src/codec.ts

@@ -75,6 +75,12 @@ function permissionDecisionOf(value: string | undefined): HookOutput['decision']
  * (`decision`/`reason`/`continue`/`stopReason`/`systemMessage`)
  * are unaffected. Omit `expectedEventName` (or pass a matching one) to apply the
  * block as-is — a caller that doesn't key by event opts out of the check.
+ *
+ * @param exitCode - the process exit code; `undefined` when the hook could not be spawned at all.
+ * @param stdout - the captured stdout stream; consulted for structured JSON only on a 0 exit.
+ * @param stderr - the captured stderr stream; becomes the blocking `reason` on exit 2.
+ * @param expectedEventName - the event the hook is firing for; omit to apply a `hookSpecificOutput` block as-is.
+ * @returns the dialect-neutral decoded outcome.
  */
 export function parseHookOutput(exitCode: number | undefined, stdout: string, stderr: string, expectedEventName?: string): HookOutput {
   const trimmedErr = stderr.trim()

packages/hooks/hook-protocol/src/events.ts

@@ -66,6 +66,9 @@ export const DEFAULT_STDERR_SUMMARY_MAX_CHARS = 500
  * `undefined` when empty, cut at `maxChars` with an ellipsis when over. The
  * bound is a parameter — like `runHook`'s `defaultTimeoutMs`, each bridge owns
  * the config default and passes it in.
+ * @param stderr - the hook's raw captured stderr.
+ * @param maxChars - the character cap for the summary (the bridge's config value).
+ * @returns the trimmed, capped summary, or `undefined` when stderr is blank.
  */
 export function summarizeStderr(stderr: string, maxChars: number): string | undefined {
   const t = stderr.trim()
@@ -73,7 +76,11 @@ export function summarizeStderr(stderr: string, maxChars: number): string | unde
   return t.length > maxChars ? t.slice(0, maxChars) + '…' : t
 }
 
-/** Append a `hook/invoked` provenance event to `session`. */
+/**
+ * Append a `hook/invoked` provenance event to `session`.
+ * @param session - the session whose open turn records the event.
+ * @param invocation - the invocation identity; an absent `matcher` is omitted from the payload.
+ */
 export function appendHookInvoked(session: Session, invocation: HookInvocation): void {
   session.append('hook/invoked', {
     turn: invocation.turn,
@@ -91,6 +98,8 @@ export function appendHookInvoked(session: Session, invocation: HookInvocation):
  * else `'pass'`; `stderrSummary` is the trimmed stderr truncated to
  * `record.stderrSummaryMaxChars` characters (omitted when empty); `exitCode`
  * is omitted when the hook never ran.
+ * @param session - the session whose open turn records the event.
+ * @param record - the outcome to record: the decoded output plus the summary cap and duration.
  */
 export function appendHookResult(session: Session, record: HookResultRecord): void {
   const { output } = record

packages/hooks/hook-protocol/src/matcher.ts

@@ -34,6 +34,10 @@ const CLAUDE_LITERAL = /^[A-Za-z0-9_|]+$/
  * pattern exact-matches the query (splitting `|` into alternatives); every other
  * `claude` pattern and ALL `codex` patterns are tested as an unanchored regex.
  * An invalid regex matches nothing (never throws).
+ * @param matcher - the configured pattern; absent/empty/`'*'` are the match-all sentinels.
+ * @param query - the candidate value (a tool name, a session source, …).
+ * @param mode - the dialect deciding literal-vs-regex interpretation of the pattern.
+ * @returns `true` when the pattern selects the query; `false` on a non-match or an invalid regex.
  */
 export function matchesMatcher(matcher: string | undefined, query: string, mode: MatcherMode): boolean {
   if (isMatchAll(matcher)) return true

packages/hooks/hook-protocol/src/merge.ts

@@ -71,6 +71,8 @@ function decisionForRank(maxRank: number): MergedDecision {
  * into one {@link MergedHookOutcome} by the precedence rules above. An empty list
  * yields a neutral outcome (`decision: 'none'`, no stop, empty context) — the
  * caller treats that as "no hook had anything to say".
+ * @param outputs - every matched hook's decoded output, in hook order.
+ * @returns the single folded outcome the bridge maps onto its seam.
  */
 export function mergeHookOutputs(outputs: HookOutput[]): MergedHookOutcome {
   let maxRank = 0

packages/hooks/hook-protocol/src/runner.ts

@@ -70,6 +70,11 @@ export interface RunHookResult {
  * `exitCode: undefined`, so the caller's merge logic treats it as a
  * non-blocking error rather than crashing the turn. `now` is injected for
  * testable durations.
+ * @param bash - the executor seam the command runs through.
+ * @param hook - the configured command; its `timeoutSec` (wire unit: seconds) overrides the default timeout.
+ * @param options - the invocation's payload, env, cwd, signal, stdin framing, and default timeout.
+ * @param now - millisecond clock used for the reported duration.
+ * @returns the decoded output plus the run's wall-clock duration.
  */
 export async function runHook(
   bash: BashExecutor,

packages/hooks/hooks-claude/src/config.ts

@@ -43,7 +43,12 @@ function asObject(value: unknown): Record<string, unknown> | undefined {
     : undefined
 }
 
-/** Apply `${CLAUDE_PLUGIN_ROOT}` / `${CLAUDE_PROJECT_DIR}` substitution to a command string. */
+/**
+ * Apply `${CLAUDE_PLUGIN_ROOT}` / `${CLAUDE_PROJECT_DIR}` substitution to a command string.
+ * @param command - the raw command from config.
+ * @param vars - the substitution values; a token whose variable is unset stays verbatim.
+ * @returns the command with every occurrence of each set token replaced.
+ */
 export function substituteCommand(command: string, vars: SubstitutionVars): string {
   let out = command
   if (vars.pluginRoot !== undefined) out = out.split('${CLAUDE_PLUGIN_ROOT}').join(vars.pluginRoot)
@@ -57,6 +62,9 @@ export function substituteCommand(command: string, vars: SubstitutionVars): stri
  * Non-command hooks and malformed entries are dropped (recorded in `skipped` /
  * silently ignored) rather than throwing — a bad hook config must not crash boot.
  * `vars` are substituted into every surviving `command`.
+ * @param raw - the parsed JSON config: a settings object with a `hooks` key, or the bare event map.
+ * @param vars - substitution values applied to every surviving `command` (defaults to none).
+ * @returns the runnable per-event groups plus the skipped non-command hooks.
  */
 export function parseClaudeConfig(raw: unknown, vars: SubstitutionVars = {}): ParsedClaudeConfig {
   const config: ClaudeHookConfig = {}

packages/hooks/hooks-codex/src/config.ts

@@ -41,6 +41,8 @@ function asObject(value: unknown): Record<string, unknown> | undefined {
  * `type !== 'command'` and `async: true` command hooks are skipped (recorded in
  * `skipped`). Malformed entries are ignored rather than thrown — a bad config
  * must not crash boot. No command substitution (Codex does none).
+ * @param raw - the parsed JSON config: a `{ hooks: … }` wrapper or the bare event map.
+ * @returns the runnable per-event groups plus the skipped hooks with their reasons.
  */
 export function parseCodexConfig(raw: unknown): ParsedCodexConfig {
   const config: CodexHookConfig = {}

packages/llm/llm-deepseek/src/adapter.ts

@@ -13,7 +13,9 @@ import { parseSse } from './sse.ts'
 import { translate } from './translate.ts'
 import type { WireError } from './types.ts'
 
+/** Constructor options for {@link DeepSeekAdapter}; the plugin's `apply` resolves them from Config + environment. */
 export interface DeepSeekAdapterOptions {
+  /** Bearer token sent in the `authorization` header on every request. */
   apiKey: string
   /** Endpoint base; `/chat/completions` is appended. */
   baseURL: string
@@ -21,7 +23,11 @@ export interface DeepSeekAdapterOptions {
   defaults?: RequestDefaults
 }
 
-/** Map an HTTP status to a stable LlmError code. */
+/**
+ * Map an HTTP status to a stable LlmError code.
+ * @param status - status of a non-2xx provider response.
+ * @returns `AUTH` (401/403), `RATE_LIMIT` (429), `INVALID_REQUEST` (400), `SERVER` (5xx), or `HTTP_<status>` for anything else.
+ */
 export function httpErrorCode(status: number): string {
   if (status === 401 || status === 403) return 'AUTH'
   if (status === 429) return 'RATE_LIMIT'

packages/llm/llm-deepseek/src/index.ts

@@ -34,6 +34,12 @@ export type * from './types.ts'
 export const name = 'llm-deepseek'
 export const inject = ['llm']
 
+/**
+ * Plugin config, validated by the same-named schemastery schema. Every field
+ * is optional in yml: credentials/endpoint fall back to the environment (a
+ * missing API key fails plugin load, not the first call), and omitted
+ * thinking fields send nothing on the wire, so the provider default applies.
+ */
 export interface Config {
   /** API key; falls back to $DEEPSEEK_API_KEY. Required one way or the other. */
   apiKey?: string

packages/llm/llm-deepseek/src/serialize.ts

@@ -66,6 +66,8 @@ function serializeAssistant(message: Message): WireMessage {
  * `{role: 'tool'}` messages; the harness puts each tool result in its own
  * user-role message, so a mixed user message contributes its text first and
  * its tool results as separate wire messages after.
+ * @param messages - the harness conversation, in order.
+ * @returns the wire messages; order preserved, each tool result expanded into its own entry.
  */
 export function serializeMessages(messages: Message[]): WireMessage[] {
   const wire: WireMessage[] = []
@@ -97,7 +99,14 @@ export function serializeMessages(messages: Message[]): WireMessage[] {
   return wire
 }
 
-/** Build the full wire request. */
+/**
+ * Build the full wire request. Always streaming (`stream: true`, usage
+ * reporting on); optional fields are omitted rather than sent as null, so
+ * provider defaults apply.
+ * @param options - the harness request (model, history, system, tools, sampling).
+ * @param defaults - adapter-level thinking defaults; undefined fields put nothing on the wire.
+ * @returns the chat-completions request body.
+ */
 export function serializeRequest(options: GenerateOptions, defaults: RequestDefaults = {}): WireRequest {
   const messages: WireMessage[] = []
   if (options.system !== undefined) {

packages/llm/llm-deepseek/src/sse.ts

@@ -37,6 +37,8 @@ function eventData(block: string): string | undefined {
  * Parse a byte stream into SSE data payloads. Yields `[DONE]` as the final
  * value and returns; throws `LlmError('STREAM_CLOSED')` when the stream ends
  * without it (truncated response — the model call cannot be trusted).
+ * @param stream - raw SSE bytes; reads may split anywhere, including mid-UTF-8 sequence.
+ * @returns each event's data payload in arrival order, the `[DONE]` sentinel last.
  */
 export async function* parseSse(stream: AsyncIterable<Uint8Array>): AsyncGenerator<string> {
   const decoder = new TextDecoder()

packages/llm/llm-deepseek/src/translate.ts

@@ -29,7 +29,11 @@ interface OpenBlock {
   name?: string
 }
 
-/** Map the wire finish_reason vocabulary to the harness FinishReason. */
+/**
+ * Map the wire finish_reason vocabulary to the harness FinishReason.
+ * @param reason - the wire `finish_reason` string.
+ * @returns the mapped reason; unrecognized values (content_filter, …) become `{kind: 'error'}` with the uppercased value as `code`.
+ */
 export function mapFinishReason(reason: string): FinishReason {
   switch (reason) {
     case 'stop': return { kind: 'stop' }
@@ -46,6 +50,8 @@ export function mapFinishReason(reason: string): FinishReason {
  * (`prompt_tokens = prompt_cache_hit_tokens + prompt_cache_miss_tokens`,
  * api/create-chat-completion); the harness TokenUsage convention is
  * DISJOINT counts, so cache reads are subtracted out of `inputTokens`.
+ * @param usage - wire usage from the finish chunk or the trailing usage-only chunk.
+ * @returns disjoint harness counts; cache/reasoning fields present only when the wire reported them.
  */
 export function mapUsage(usage: WireUsage): TokenUsage {
   const cacheRead = usage.prompt_tokens_details?.cached_tokens ?? usage.prompt_cache_hit_tokens
@@ -75,6 +81,8 @@ function closeBlock(block: OpenBlock): ContentBlock {
 /**
  * Consume SSE data payloads (ending with `[DONE]`) and yield StreamChunks.
  * Malformed JSON payloads abort the stream with `MALFORMED_RESPONSE`.
+ * @param payloads - SSE data payloads from {@link parseSse}, `[DONE]`-terminated.
+ * @returns deltas as they arrive; `block-end`s, `usage`, and `finish` are all deferred to the `[DONE]` sentinel.
  */
 export async function* translate(payloads: AsyncIterable<string>): AsyncGenerator<StreamChunk> {
   let nextIndex = 0

packages/llm/llm-deepseek/src/types.ts

@@ -48,12 +48,18 @@ export interface WireToolMessage {
   content: string
 }
 
+/** One entry of the request `messages` array, discriminated on `role`. */
 export type WireMessage =
   | WireSystemMessage
   | WireUserMessage
   | WireAssistantMessage
   | WireToolMessage
 
+/**
+ * Assistant-role history message. The harness replays `content: ""` (never
+ * null) on tool-call-only turns — some gateways reject null — and sends null
+ * only when the turn carried neither text nor tool calls.
+ */
 export interface WireAssistantMessage {
   role: 'assistant'
   content: string | null
@@ -66,12 +72,14 @@ export interface WireAssistantMessage {
   tool_calls?: WireToolCall[]
 }
 
+/** A completed tool call replayed on an assistant history message; `arguments` is the raw JSON string. */
 export interface WireToolCall {
   id: string
   type: 'function'
   function: { name: string; arguments: string }
 }
 
+/** One entry of the request `tools` array; `parameters` is a JSON Schema object. */
 export interface WireTool {
   type: 'function'
   function: {
@@ -88,11 +96,13 @@ export interface WireChunk {
   usage?: WireUsage | null
 }
 
+/** One streamed choice (requests always ask for a single one); `finish_reason` is non-null only on its terminal chunk. */
 export interface WireChoice {
   delta?: WireDelta
   finish_reason?: string | null
 }
 
+/** The incremental content of one streamed choice; any subset of fields may be present per chunk. */
 export interface WireDelta {
   role?: string
   /** Visible text. Null/empty on reasoning/tool-call chunks. */
@@ -105,6 +115,7 @@ export interface WireDelta {
   tool_calls?: WireToolCallDelta[]
 }
 
+/** A streamed fragment of one tool call; fragments sharing an `index` concatenate into one call. */
 export interface WireToolCallDelta {
   /** Disambiguates parallel tool calls; stable across a call's deltas. */
   index: number
@@ -119,6 +130,13 @@ export interface WireToolCallDelta {
   }
 }
 
+/**
+ * Wire token accounting. `prompt_tokens` INCLUDES cache hits (it equals
+ * `prompt_cache_hit_tokens + prompt_cache_miss_tokens`); `mapUsage` subtracts
+ * them to keep the harness convention of disjoint counts.
+ * `prompt_tokens_details.cached_tokens` is the OpenAI-compat spelling of the
+ * hit count.
+ */
 export interface WireUsage {
   prompt_tokens: number
   completion_tokens: number

packages/llm/llm-pi-ai/src/adapter.ts

@@ -21,14 +21,22 @@ import { toPiContext, toStreamChunks } from './convert.ts'
 /** Reasoning levels surfaced by this adapter (DeepSeek wire: high|max). */
 export type PiAiReasoning = 'off' | 'high' | 'xhigh'
 
+/** Constructor options for {@link PiAiAdapter}; the plugin's `apply` resolves them from Config + environment. */
 export interface PiAiAdapterOptions {
+  /** Bearer token pi-ai sends on every request. */
   apiKey: string
+  /** Endpoint base; `/chat/completions` is appended. */
   baseURL: string
   /** Thinking level applied to every request ('off' disables thinking). */
   reasoning?: PiAiReasoning | undefined
 }
 
-/** Build the inline pi-ai model descriptor for one DeepSeek model name. */
+/**
+ * Build the inline pi-ai model descriptor for one DeepSeek model name.
+ * @param modelId - harness model name; sent verbatim on the wire.
+ * @param options - adapter options; only `baseURL` is read here (key and reasoning apply per request, not per descriptor).
+ * @returns a descriptor with every DeepSeek compat flag explicit — pi-ai's URL-based auto-detection is never relied on.
+ */
 export function buildModel(modelId: string, options: PiAiAdapterOptions): Model<'openai-completions'> {
   return {
     id: modelId,

packages/llm/llm-pi-ai/src/convert.ts

@@ -55,6 +55,8 @@ function parseArguments(raw: string): Record<string, unknown> {
  * NAME (pi-ai's `toolName`), which the harness doesn't carry on the result
  * block — it is recovered from the preceding assistant tool-call with the
  * same id.
+ * @param options - the harness request; `options.system` maps to pi-ai's single `systemPrompt` slot.
+ * @returns the pi-ai context; `tools` is omitted entirely when the request declares none.
  */
 export function toPiContext(options: GenerateOptions): PiContext {
   const toolNames = new Map<CallId, string>()
@@ -159,7 +161,11 @@ function emptyPiUsage(): PiUsage {
   }
 }
 
-/** Map pi-ai usage (reasoning folded into output by pi-ai). */
+/**
+ * Map pi-ai usage (reasoning folded into output by pi-ai).
+ * @param usage - cumulative usage from the terminal pi-ai event.
+ * @returns harness counts; cache fields appear only when non-zero (pi-ai reports zeros, not absence).
+ */
 export function mapUsage(usage: PiUsage): TokenUsage {
   return {
     inputTokens: usage.input,
@@ -177,7 +183,11 @@ function classifyPiAiError(message: string): string {
   return 'PI_AI_ERROR'
 }
 
-/** Map a terminal pi-ai event to the harness finish reason. */
+/**
+ * Map a terminal pi-ai event to the harness finish reason.
+ * @param message - the assistant message carried by the `done` or `error` event.
+ * @returns the harness reason; `error` yields `{kind: 'error'}` with a code classified from the error text.
+ */
 export function mapStopReason(message: AssistantMessage): FinishReason {
   switch (message.stopReason) {
     case 'stop': return { kind: 'stop' }
@@ -195,6 +205,9 @@ export function mapStopReason(message: AssistantMessage): FinishReason {
  * Translate the pi-ai event stream into StreamChunks. pi-ai never throws
  * mid-stream — failures arrive as `error` events, which become error/aborted
  * `finish` chunks (the harness protocol's other error-delivery style).
+ * @param events - one assistant turn's pi-ai event stream.
+ * @returns the harness chunks, ending with `usage` then `finish`; throws
+ *   `LlmError` (`STREAM_CLOSED`) if the source ends without a terminal event.
  */
 export async function* toStreamChunks(events: AsyncIterable<AssistantMessageEvent>): AsyncGenerator<StreamChunk> {
   // pi-ai contentIndex ↔ our block index map 1:1 (both count blocks from 0

packages/llm/llm-pi-ai/src/index.ts

@@ -29,6 +29,11 @@ export { mapStopReason, mapUsage, toPiContext, toStreamChunks } from './convert.
 export const name = 'llm-pi-ai'
 export const inject = ['llm']
 
+/**
+ * Plugin config, validated by the same-named schemastery schema. Every field
+ * is optional in yml: credentials/endpoint fall back to the environment (a
+ * missing API key fails plugin load, not the first call).
+ */
 export interface Config {
   /** API key; falls back to $DEEPSEEK_API_KEY. Required one way or the other. */
   apiKey?: string

packages/llm/llm/src/assembler.ts

@@ -40,6 +40,8 @@ export class BlockAssembler {
   /**
    * Feed one chunk. Returns the completed block when the chunk closes one
    * (an explicit `block-end`), otherwise undefined.
+   * @param chunk - the next raw chunk, in stream order.
+   * @returns the authoritative block from the first `block-end` at its index; undefined for every other chunk.
    */
   push(chunk: StreamChunk): ContentBlock | undefined {
     switch (chunk.type) {
@@ -123,20 +125,29 @@ export class BlockAssembler {
     return partial
   }
 
-  /** Assemble all blocks seen so far, in stream order. */
+  /**
+   * Assemble all blocks seen so far, in stream order.
+   * @returns one block per seen index; an open block assembles from its
+   *   accumulated deltas (an unknown block type never closed by `block-end` throws).
+   */
   blocks(): ContentBlock[] {
     return this.order.map(index => this.assemble(this.mustGet(index), index))
   }
 
+  /** Usage from the `usage` chunk; undefined until one arrives. */
   get usage(): TokenUsage | undefined {
     return this._usage
   }
 
+  /** Finish reason from the `finish` chunk; `{kind: 'stop'}` when the stream ended without one. */
   get finish(): FinishReason {
     return this._finish ?? { kind: 'stop' }
   }
 
-  /** The assembled assistant message. */
+  /**
+   * The assembled assistant message.
+   * @returns an assistant-role message over `blocks()` (same open-block assembly rules).
+   */
   message(): Message {
     return { role: 'assistant', content: this.blocks() }
   }

packages/llm/llm/src/attribution.ts

@@ -54,6 +54,8 @@ export const APP_IDENTITY: AppIdentity = {
  * The standard `User-Agent` value: `product/version (+url)`. The
  * parenthesized `+url` comment is the conventional self-identification form
  * (RFC 9110 §10.1.5 product + comment syntax).
+ * @param identity - the identity to render; defaults to {@link APP_IDENTITY}.
+ * @returns the ready-to-send header value.
  */
 export function userAgent(identity: AppIdentity = APP_IDENTITY): string {
   return `${identity.product}/${identity.version} (+${identity.url})`
@@ -63,6 +65,8 @@ export function userAgent(identity: AppIdentity = APP_IDENTITY): string {
  * Build the attribution headers an adapter must send on every provider
  * request. Header names are lowercase (HTTP field names are case-insensitive
  * on the wire).
+ * @param identity - the identity to send; defaults to {@link APP_IDENTITY} — omission cannot suppress attribution.
+ * @returns headers to merge into the provider request (currently just `user-agent`).
  */
 export function attributionHeaders(
   identity: AppIdentity = APP_IDENTITY,

packages/llm/llm/src/brand.ts

@@ -17,7 +17,11 @@ import type { Branded } from '@deepseek-ai/dsh-brand'
  */
 export type CallId = Branded<'CallId'>
 
-/** Brand a string as a {@link CallId}. */
+/**
+ * Brand a string as a {@link CallId}.
+ * @param id - the provider-issued (or synthesized) call id.
+ * @returns the same string, branded; no validation is performed.
+ */
 export function CallId(id: string): CallId {
   return id as CallId
 }

packages/llm/llm/src/error.ts

@@ -18,6 +18,7 @@
  * `ErrorOptions`. `name` defaults to the subclass constructor name.
  */
 export class HarnessError extends Error {
+  /** Stable machine-routable failure class (e.g. `RATE_LIMIT`); route on this, never by parsing `message`. */
   readonly code: string
 
   constructor(message: string, code: string, options?: ErrorOptions) {
@@ -27,7 +28,11 @@ export class HarnessError extends Error {
   }
 }
 
-/** Narrow an arbitrary thrown value to a HarnessError (for `instanceof` at seams). */
+/**
+ * Narrow an arbitrary thrown value to a HarnessError (for `instanceof` at seams).
+ * @param value - the caught value (`unknown` in catch clauses).
+ * @returns true only for real instances; duck-typed or cross-realm errors do not narrow.
+ */
 export function isHarnessError(value: unknown): value is HarnessError {
   return value instanceof HarnessError
 }

packages/llm/llm/src/index.ts

@@ -73,7 +73,11 @@ export class LlmError extends HarnessError {
  * same value to the wire.
  */
 export abstract class LlmAdapter {
-  /** Stream one model call as raw chunks. The only required method. */
+  /**
+   * Stream one model call as raw chunks. The only required method.
+   * @param options - the fully-assembled request; implementations must honor `options.signal`.
+   * @returns the chunk stream, obeying the adapter contract documented on `StreamChunk`.
+   */
   abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 }
 

packages/llm/llm/src/never.ts

@@ -26,6 +26,9 @@
  * variant was added without updating the switch (compile error at the call
  * site — the desired outcome) or a value escaped its type (runtime throw
  * with diagnostics — the safety net).
+ * @param value - the impossible value; typed `never` so an unhandled variant fails compilation at the call site.
+ * @param context - optional label (e.g. the switch site) prefixed into the throw message.
+ * @returns never — it always throws, with the offending value JSON-rendered in the message.
  */
 export function assertNever(value: never, context?: string): never {
   // JSON.stringify is typed string but returns undefined for undefined input;

packages/llm/llm/src/types.ts

@@ -70,7 +70,9 @@ export interface ContentBlockMap {
   'tool-result': ToolResultBlock
 }
 
+/** The block `type` tag vocabulary; widens as plugins merge new shapes into {@link ContentBlockMap}. */
 export type ContentBlockType = keyof ContentBlockMap
+/** Any known content block, derived from {@link ContentBlockMap}; switch on `type` and fall through unknowns (merge-extensible). */
 export type ContentBlock = ContentBlockMap[ContentBlockType]
 
 /** A single message in a conversation history. */
@@ -88,6 +90,7 @@ export interface MessageSourceMap {
   plugin: { kind: 'plugin'; plugin: string }
 }
 
+/** Any known message source, derived from {@link MessageSourceMap}; switch on `kind` and fall through unknowns (merge-extensible). */
 export type MessageSource = MessageSourceMap[keyof MessageSourceMap]
 
 /**
@@ -102,6 +105,7 @@ export interface FinishReasonMap {
   'error': { kind: 'error'; message: string; code?: string }
 }
 
+/** Any known finish reason, derived from {@link FinishReasonMap}; switch on `kind` and fall through unknowns (merge-extensible). */
 export type FinishReason = FinishReasonMap[keyof FinishReasonMap]
 
 /**

packages/session-persistence/session-persistence-jsonl/src/format.ts

@@ -27,7 +27,11 @@ export interface HeaderLine {
   seedLength?: number
 }
 
-/** Build the header line object from a {@link SessionHeader}. */
+/**
+ * Build the header line object from a {@link SessionHeader}.
+ * @param header - the immutable session metadata to serialize.
+ * @returns the `type: 'session'`-tagged line object, absent optional fields omitted (never null).
+ */
 export function toHeaderLine(header: SessionHeader): HeaderLine {
   return {
     type: 'session',
@@ -40,7 +44,11 @@ export function toHeaderLine(header: SessionHeader): HeaderLine {
   }
 }
 
-/** Parse a header line back into a {@link SessionHeader}. */
+/**
+ * Parse a header line back into a {@link SessionHeader}.
+ * @param line - the shape-checked first line of a log (see the `isHeaderLine` guard).
+ * @returns the header, absent optional fields omitted.
+ */
 export function fromHeaderLine(line: HeaderLine): SessionHeader {
   return {
     version: line.version,
@@ -77,6 +85,8 @@ function isHeaderLine(value: unknown): value is HeaderLine {
  * `Buffer.from(…, 'utf8')` would do, breaking injectivity). `.` is in the safe
  * set for readability but the whole-segment tokens `.`/`..` are escaped so they
  * can never traverse.
+ * @param raw - the string to encode; must be non-empty (throws on `''`).
+ * @returns the escaped single path segment, decodable back to `raw`.
  */
 export function encodeSegment(raw: string): string {
   if (raw.length === 0) throw new Error('cannot encode an empty path segment')
@@ -97,9 +107,12 @@ export function encodeSegment(raw: string): string {
 
 /**
  * The directory a session's files live in: the configured root, then a per-cwd
- * subdirectory so sessions group by project. The cwd subdir is a stable hash
- * (short, collision-resistant, filesystem-safe) plus an encoded suffix for
- * readability; sessions without a cwd go in a shared `_no-cwd` bucket.
+ * subdirectory so sessions group by project. The cwd subdir is a stable hash of
+ * the cwd (short, collision-resistant, filesystem-safe); sessions without a
+ * cwd go in a shared `_no-cwd` bucket.
+ * @param root - the backend's session root directory.
+ * @param cwd - the session's project directory; `undefined` selects the shared `_no-cwd` bucket.
+ * @returns the per-cwd bucket directory path under `root`.
  */
 export function sessionDir(root: string, cwd: string | undefined): string {
   if (cwd === undefined) return join(root, '_no-cwd')
@@ -107,12 +120,22 @@ export function sessionDir(root: string, cwd: string | undefined): string {
   return join(root, `cwd-${hash}`)
 }
 
-/** The append-only event-log file path for a session. */
+/**
+ * The append-only event-log file path for a session.
+ * @param root - the backend's session root directory.
+ * @param cwd - the session's project directory (picks the per-cwd bucket; `undefined` → `_no-cwd`).
+ * @param id - the session id, path-encoded via {@link encodeSegment} before filesystem use.
+ * @returns the session's `.jsonl` log file path.
+ */
 export function logPath(root: string, cwd: string | undefined, id: SessionId): string {
   return join(sessionDir(root, cwd), `${encodeSegment(id)}.jsonl`)
 }
 
-/** Serialize one event as a JSONL line (no trailing newline). */
+/**
+ * Serialize one event as a JSONL line (no trailing newline).
+ * @param event - the event to serialize verbatim.
+ * @returns the event's single-line JSON text; the writer adds the newline.
+ */
 export function eventLine(event: SessionEvent): string {
   return JSON.stringify(event)
 }
@@ -135,6 +158,9 @@ export function eventLine(event: SessionEvent): string {
  * This relies on the session-log invariant that every event lives inside a turn
  * (`Session.append` enforces it): only the final turn can be open, so the
  * preserved tail is at most one unclosed turn.
+ * @param buffer - the raw bytes of the log file (header line first).
+ * @returns the header, the preserved event prefix, and `committedBytes` — the
+ *   byte offset the next append truncates any torn tail to.
  */
 export function scanLog(buffer: Buffer): { meta: SessionHeader; events: SessionEvent[]; committedBytes: number } {
   const text = buffer.toString('utf8')
@@ -239,6 +265,8 @@ export function scanLog(buffer: Buffer): { meta: SessionHeader; events: SessionE
  * `undefined` if it is missing/not a header. Used by `list()` to read session
  * metadata WITHOUT parsing the whole log: a session picker scales with the
  * number of sessions, not the total size of every conversation.
+ * @param firstLine - the first line of a log file (without its trailing newline).
+ * @returns the parsed header, or `undefined` when the line is not a well-formed session header.
  */
 export function parseHeaderMeta(firstLine: string): SessionHeader | undefined {
   let parsed: unknown

packages/session-persistence/session-persistence-jsonl/src/index.ts

@@ -31,6 +31,7 @@ import {
   encodeSegment, eventLine, logPath, parseHeaderMeta, scanLog, sessionDir, toHeaderLine,
 } from './format.ts'
 
+/** Plugin config: where the JSONL backend keeps its session logs (`root` is required — no default). */
 export interface Config {
   /**
    * Root directory for all session files. Required (no default): a default of

packages/session-persistence/session-persistence-sqlite/README.md

@@ -8,7 +8,7 @@ A SQLite durable session-persistence backend — a second `SessionPersistence` i
 
 Each `SessionEvent` maps 1:1 onto a row in an `events` table `(session_id, seq, type, time, data, source_event_seqs, surface_op)` — `data` is the event payload as JSON text, so the row shape is the event verbatim (including `assistant/chunk`, keeping `seq` contiguous). The two `TEXT` columns `source_event_seqs` and `surface_op` are nullable; they store the event's optional surface-metadata fields (see [session surface](../../../docs/rfc/implemented/architecture/2026-06-18-session-surface.md)). Out-of-log metadata (`SessionHeader`) lives in a `sessions` row. A `sessions` row is written only by the first `append` — its existence is the lazy-materialization signal (`list` reports exactly the sessions that have a row), so no separate column is needed.
 
-The repo targets Node ≥ 24 (the root `engines` field), which includes the stable `node:sqlite` module. The database opens with `foreign_keys = ON` (so `ON DELETE CASCADE` drops a session's events with its row) and the configured `journal_mode` (default `wal`; pick a rollback-journal mode like `delete` on filesystems where WAL's shared-memory files do not work, e.g. network mounts). The table-layout version is stored in `PRAGMA user_version` and checked on open: a fresh database is stamped with the current `SCHEMA_VERSION`; a database written by any other, incompatible build (a non-current `user_version`, older or newer) is rejected rather than opened against an unknown layout — there is no migration (unreleased software).
+The repo's `engines.node` is `^22.19.0 || >=24.0.0` (Node 22.19+ or 24+), matching the LTS floor required by the installed Pi adapter dependency; `node:sqlite` itself ships without the `--experimental-sqlite` flag from Node 22.13 (LTS) and 23.4 / 24 (Current) on. The range deliberately excludes Node 23 because that line is non-LTS/EOL and still has flagged runtime features before 23.6. The database opens with `foreign_keys = ON` (so `ON DELETE CASCADE` drops a session's events with its row) and the configured `journal_mode` (default `wal`; pick a rollback-journal mode like `delete` on filesystems where WAL's shared-memory files do not work, e.g. network mounts). The table-layout version is stored in `PRAGMA user_version` and checked on open: a fresh database is stamped with the current `SCHEMA_VERSION`; a database written by any other, incompatible build (a non-current `user_version`, older or newer) is rejected rather than opened against an unknown layout — there is no migration (unreleased software).
 
 ## Contract semantics over rows
 

packages/session-persistence/session-persistence-sqlite/src/schema.ts

@@ -76,6 +76,9 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
  * is the merged layout carrying every column; bumping past the collided v3
  * makes the version check reject both sibling v3 databases instead of opening
  * one against columns it does not have.
+ * @param path - the SQLite database file to open (created when absent).
+ * @param journalMode - the journal pragma to apply — a closed in-code union, validated by the plugin Config.
+ * @returns the open handle with pragmas applied and both tables ensured.
  */
 export function openDatabase(path: string, journalMode: JournalMode): DatabaseSync {
   const db = new DatabaseSync(path)
@@ -120,7 +123,11 @@ export function openDatabase(path: string, journalMode: JournalMode): DatabaseSy
   return db
 }
 
-/** Reconstruct the {@link SessionHeader} from a `sessions` row. */
+/**
+ * Reconstruct the {@link SessionHeader} from a `sessions` row.
+ * @param row - the `sessions` table row.
+ * @returns the header, `NULL` columns mapped to omitted optional fields.
+ */
 export function rowToMeta(row: SessionRow): SessionHeader {
   return {
     version: row.version,
@@ -132,7 +139,12 @@ export function rowToMeta(row: SessionRow): SessionHeader {
   }
 }
 
-/** Reconstruct a {@link SessionEvent} from an `events` row (parses `data`). */
+/**
+ * Reconstruct a {@link SessionEvent} from an `events` row (parses `data`).
+ * @param row - the `events` table row; `data` and the surface columns hold JSON text.
+ * @returns the reconstructed event; throws when a JSON column fails to parse
+ *   ({@link scanRows} treats that as a hole, not corruption, in the tail).
+ */
 export function rowToEvent(row: EventRow): SessionEvent {
   // Surface-metadata fields are conditional on the event type in the type
   // system; spread them so each variant gets only the fields it declares.
@@ -172,6 +184,9 @@ export function rowToEvent(row: EventRow): SessionEvent {
  * This relies on the session-log invariant that every event lives inside a turn
  * (`Session.append` enforces it): only the final turn can be open, so the
  * preserved tail is at most one unclosed turn.
+ * @param rows - one session's event rows, ordered by seq ascending.
+ * @returns the preserved event prefix, plus `tornFrom` — the seq the physical
+ *   delete starts at — when a torn tail exists.
  */
 export function scanRows(rows: readonly EventRow[]): { preserved: SessionEvent[]; tornFrom?: number } {
   // Pass 1: parse each row's data; a row whose data is not valid JSON is a hole.

packages/session-persistence/session-persistence/src/coordinator.ts

@@ -186,6 +186,7 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   /**
    * Register a new session's metadata (lazy: no physical write until the first
    * {@link append}). Rejects if the id is already tracked or already persisted.
+   * @param meta - the immutable header (id, version, cwd, lineage) to record; snapshotted at call time.
    */
   create(meta: SessionHeader): Promise<void> {
     // Snapshot the metadata at call time: the op runs later (behind the
@@ -216,6 +217,8 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   /**
    * Durably persist a batch of events. Honors the append-only and contiguous-seq
    * contracts; rejects non-JSON-serializable `event.data`.
+   * @param id - the session the batch belongs to.
+   * @param events - the contiguous batch to persist, in seq order; deep-cloned at call time.
    */
   async append(id: SessionId, events: readonly SessionEvent[]): Promise<void> {
     // Validate serializability BEFORE cloning so a bad event surfaces the typed
@@ -252,6 +255,8 @@ export class PersistenceCoordinator<TornMarker = unknown> {
    * Reload a session: its {@link SessionHeader} plus the event log up to the last
    * durable checkpoint, with any interrupted final turn durably closed (synthetic
    * boundary events) during load.
+   * @param id - the persisted session to reload.
+   * @returns the header plus the event log, ending on a balanced `turn/end`.
    */
   load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
     return this.serialize(id, () => this.loadCore(id))

packages/session-persistence/session-persistence/src/index.ts

@@ -45,6 +45,9 @@ declare module 'cordis' {
  *
  * The comparison includes the full event payload, not just seq/type/time, so a
  * mutated seed cannot be grafted onto a durable log with the same envelope.
+ * @param seed - the live session's creation-time event snapshot.
+ * @param prefix - the persisted prefix the seed must reproduce.
+ * @returns `true` when the prefix fits within the seed and every event matches by JSON text.
  */
 export function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly SessionEvent[]): boolean {
   return prefix.length <= seed.length
@@ -58,6 +61,7 @@ export function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly
  * Reject non-JSON-serializable event data before a backend serializes a batch.
  * Live session appends already enforce this; persistence append paths also
  * accept replay/fork batches that may bypass a live session instance.
+ * @param events - the batch to validate; throws naming the offending event's type and seq.
  */
 export function assertSerializable(events: readonly SessionEvent[]): void {
   for (const event of events) {

packages/subagent/subagent-acp/src/run.ts

@@ -121,7 +121,12 @@ export const DEFAULT_DISPOSE_GRACE_MS = 3_000
  */
 export const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i
 
-/** The ambient env minus credential-shaped vars, plus the spec's explicit env. */
+/**
+ * The ambient env minus credential-shaped vars, plus the spec's explicit env.
+ * @param extra - explicit vars layered on top AFTER the scrub, so a
+ * credential-shaped name supplied deliberately still reaches the child.
+ * @returns the environment to spawn the child with.
+ */
 export function buildChildEnv(extra: Record<string, string>): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = {}
   for (const [key, value] of Object.entries(process.env)) {
@@ -130,7 +135,12 @@ export function buildChildEnv(extra: Record<string, string>): NodeJS.ProcessEnv
   return { ...env, ...extra }
 }
 
-/** Map an ACP {@link StopReason} to a harness {@link SubagentStopReason}. */
+/**
+ * Map an ACP {@link StopReason} to a harness {@link SubagentStopReason}.
+ * @param reason - the terminal reason from the child's `session/prompt` response.
+ * @returns the harness equivalent; `max_turn_requests` and any unknown future
+ * variant map to `error`, so an unclean stop is never reported as `completed`.
+ */
 export function acpStopReason(reason: StopReason): SubagentStopReason {
   switch (reason) {
     case 'end_turn':
@@ -155,12 +165,20 @@ export function acpStopReason(reason: StopReason): SubagentStopReason {
   }
 }
 
-/** Collect the text of an ACP content block (non-text blocks contribute nothing). */
+/**
+ * Collect the text of an ACP content block (non-text blocks contribute nothing).
+ * @param content - the content block off a streamed `agent_message_chunk`.
+ * @returns the block's text, or `''` for a non-text block.
+ */
 export function acpContentText(content: AcpContentBlock): string {
   return content.type === 'text' ? content.text : ''
 }
 
-/** Translate the harness prompt blocks into ACP prompt blocks (text only). */
+/**
+ * Translate the harness prompt blocks into ACP prompt blocks (text only).
+ * @param prompt - the harness prompt; non-text blocks are dropped.
+ * @returns the ACP text blocks, in order.
+ */
 export function toAcpPrompt(prompt: ContentBlock[]): AcpContentBlock[] {
   const blocks: AcpContentBlock[] = []
   for (const block of prompt) {
@@ -206,6 +224,11 @@ function exitsWithin(child: ChildProcess, ms: number): Promise<boolean> {
  * failure (a spawn/transport/RPC error resolves with `stopReason: 'error'`), per
  * the seam contract. `cancel()` sends `session/cancel`; `dispose()` kills the
  * subprocess and awaits its exit (quiescent teardown).
+ * @param request - the start request; the driver consumes `prompt` and `signal`
+ * (an already-aborted signal yields an inert `aborted` run with no spawn).
+ * @param spec - the resolved spawn spec: command/args/cwd, env, permission
+ * policy, dispose graces, and the optional error sink.
+ * @returns the live run handle for the child subprocess.
  */
 export function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpec): SubagentRun {
   const id = AgentId(randomUUID())