From 4dee9a8d9bc5bbce52dee79bd24ab2523a7f1309 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 8 Jul 2026 20:31:41 +0800
Subject: [PATCH 01/48] docs: propose background subagent tasks

---
 docs/rfc/INDEX.md                             |  1 +
 .../2026-07-08-background-subagent-tasks.md   | 98 +++++++++++++++++++
 2 files changed, 99 insertions(+)
 create mode 100644 docs/rfc/proposed/feature/2026-07-08-background-subagent-tasks.md

diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md
index d6d0ce747b..5f0da6a7ff 100644
--- a/docs/rfc/INDEX.md
+++ b/docs/rfc/INDEX.md
@@ -13,6 +13,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Code Mode — the model writes TypeScript against the tool registry](proposed/feature/2026-06-15-code-mode.md) | 2026-06-15 |
 | [Pre-tool input rewrite — a consistent design](proposed/feature/2026-06-30-pre-tool-input-rewrite.md) | 2026-06-30 |
 | [Claude Code and Codex subagent backends (out-of-process delegation to external coding agents)](proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md) | 2026-07-07 |
+| [Background subagent tasks](proposed/feature/2026-07-08-background-subagent-tasks.md) | 2026-07-08 |
 | [Repeat-tool-call guard plugin](proposed/feature/2026-07-08-repeat-tool-guard.md) | 2026-07-08 |
 
 ### Simplification
diff --git a/docs/rfc/proposed/feature/2026-07-08-background-subagent-tasks.md b/docs/rfc/proposed/feature/2026-07-08-background-subagent-tasks.md
new file mode 100644
index 0000000000..7c1fe99624
--- /dev/null
+++ b/docs/rfc/proposed/feature/2026-07-08-background-subagent-tasks.md
@@ -0,0 +1,98 @@
+# RFC: Background subagent tasks
+
+Status: proposed
+
+## Problem
+
+The subagent seam ([the seam RFC](../../implemented/feature/2026-06-21-subagent-capability-seam.md)) exposes `start() -> SubagentRun`, and the model-facing `dsh-tool-subagent` consumer collects that run synchronously: the parent turn blocks until the child returns one final result. That shape is simple and transport-neutral, but it makes slow delegation expensive for the parent. A model that wants two independent investigations must either run them serially or hold the parent step open for the entire child duration.
+
+The harness already has one background-task precedent in bash. Bash has task ids, owner-token checks, output polling, stop, completion notifications, and prompt guidance. Subagents need the same user-facing habit, but not by copying bash's process-output semantics: a subagent does not expose an incremental stdout stream, and its child session remains the home for internal steps. The parent needs to start a child, keep working, later wait for or read the final answer, and stop the task when it is no longer relevant.
+
+The design also has two lifecycle constraints that the synchronous cut does not face. First, a background subagent can outlive the tool call that started it, so the tool-call abort signal must not stay wired to the child after the id is returned. Second, a completion notice can only be injected into a live owner agent: once an ACP session closes or an agent handle is disposed, `agent.inject()` cannot append to that session. The feature must therefore define whether background subagents survive owner disposal.
+
+## Proposal
+
+Add a background mode to the existing model-facing subagent tools and add three companion tools: `subagent_wait`, `subagent_output`, and `subagent_stop`. The background task registry lives in `@deepseek-ai/dsh-subagent`, keyed by branded task ids and owner tokens, while `@deepseek-ai/dsh-tool-subagent` owns the model-facing schemas, text rendering, completion notice injection, and prompt guidance.
+
+`dsh-tool-subagent` becomes a single multi-tool consumer plugin instead of one plugin instance per provider. Its config maps model-facing tool names to provider names, so one plugin instance can register `subagent`, `subagent_fork`, and any deployment-specific aliases such as `subagent_acp`, plus the shared background control tools. Providers remain named implementations on `ctx.subagents`: `spawn`, `fork`, `acp`, or future backends. This keeps provider implementation and model-facing exposure separate while avoiding a failure mode where one `subagent` tool exposes `run_in_background` but the companion wait/output/stop tools were never loaded.
+
+The background task is scoped to the owner session, not durable across session closure. A background subagent starts only from a model-driven call with `exec.agent`; the service stores the caller's `session.header.id` as the owner token. `subagent_output`, `subagent_wait`, and `subagent_stop` compare that stored token with the caller's session id and reject cross-session access. When the owner agent is disposed, the service cancels any running background subagent tasks for that owner and discards their retained snapshots after quiescence. Completion notices are best-effort: if the owner agent is still registered, `dsh-tool-subagent` injects a short `context/message`; if the owner is gone, no notice is written.
+
+## Tool surface
+
+Each configured delegation tool may expose `run_in_background?: boolean`. The deployment can disable background mode per tool; a disabled tool does not include the parameter in its schema. A foreground call keeps the synchronous semantics: it waits for `run.result`, returns final text on `completed`, maps non-clean terminal stop reasons to an errored tool result, and disposes the run in `finally`.
+
+A background call validates that a parent agent exists, starts the provider run through `ctx.subagents`, registers a task, and returns `started background subagent task <task_id>`. It checks an already-aborted tool signal before starting, but after the id is returned it does not keep the tool-call signal connected to `run.cancel()`. The parent step may finish while the child continues.
+
+`subagent_output` is a non-blocking status read for a background subagent task. While the task is `running` or `stopping`, it returns only a status line. Once terminal, it returns the final text output or error message plus the terminal status. Reading output is idempotent and does not consume the result; v1 deliberately exposes no incremental transcript cursor because the child session remains the detailed trace.
+
+`subagent_wait` waits for a task to become terminal, bounded by a defaulted and capped timeout from `dsh-tool-subagent` config. A wait timeout returns `running` and leaves the child alive. Aborting the wait call cancels only the wait, not the background task.
+
+`subagent_stop` requests cancellation of a running or stopping task and returns immediately. The task registry remains responsible for observing the run settle, recording the terminal state, and disposing the run. Calling stop on an already-terminal task reports that terminal state rather than failing.
+
+## Runtime task model
+
+`@deepseek-ai/dsh-subagent` adds a runtime-global task registry to `SubagentService`. Task ids and owner tokens are branded types. A task snapshot records the task id, provider name, child run id, owner token, status, started/finished timestamps, final output, and error message. The status vocabulary is `running`, `stopping`, and the existing terminal `SubagentStopReason` values (`completed`, `aborted`, `error`, `max-tokens`, `refusal`, plus merge-extensible provider values).
+
+The registry owns task settlement. It attaches one continuation to `run.result`; on success it stores the final output and stop reason, on rejection it stores `error`, and in both cases it disposes the run and notifies task-done listeners. Listener failures are contained and logged so one consumer cannot starve cleanup.
+
+The registry is runtime-global because `ctx.subagents` is a service shared by all live agents in the Cordis context. Session isolation is therefore explicit owner-token authorization, not an assumption about separate service instances. This mirrors the bash background-task fence: predictable ids are safe only when read/stop operations check the caller's owner token.
+
+Owner disposal is a hard lifecycle boundary. `SubagentService` listens to `agent/disposed`, finds tasks owned by that agent's session id, and cancels running tasks. It does not attempt to persist unfinished task state, resume children, or inject into disposed sessions. A future durable job system can extend this boundary, but this feature intentionally keeps background subagents tied to live sessions.
+
+## Model guidance
+
+`dsh-tool-subagent` registers a system-prompt section that teaches the background-task habit:
+
+- Keep track of every task id returned by a background subagent call.
+- Do not produce a final answer while a relevant background subagent is still running.
+- While waiting, continue independent exploration or use other tools when useful.
+- Before summarizing or handing work back, call `subagent_wait` or `subagent_output` to collect finished tasks.
+- Call `subagent_stop` for a background task that is no longer needed.
+- End without collecting a task only when its result is irrelevant or the task was explicitly stopped.
+
+This prompt guidance is not the enforcement boundary. Runtime enforcement is owner-token authorization and cancellation on owner disposal. The guidance keeps ordinary model behavior from accidentally abandoning relevant work while still allowing explicit stop or irrelevance.
+
+## Relationship to generic long-running tools
+
+The generic long-running tool runtime RFC ([Extract a generic long-running tool runtime](../../proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md)) remains the larger direction for shared task ids, owner tokens, cancellation, completion notices, and presentation. Background subagents should not block on that extraction because subagents have a narrower result model than bash: no incremental stdout, no spill files, and no process exit markers. The implementation should keep the subagent registry small and shaped so it can later migrate into a generic runtime without changing the model-facing `run_in_background`, `subagent_wait`, `subagent_output`, and `subagent_stop` contract.
+
+## Alternatives considered
+
+### Why not keep one `dsh-tool-subagent` instance per provider?
+
+The existing one-instance-per-provider shape makes aliasing simple, but companion tools become ambiguous. If each instance registers `subagent_wait`, duplicate tool names collide. If only one instance registers them, deployments can accidentally expose `run_in_background` without the tools required to collect or stop the task. A single multi-tool consumer config keeps provider selection in deployment config and makes the background control plane atomic.
+
+### Why not put wait/output/stop in a separate plugin?
+
+A separate plugin has the same half-loaded failure mode: `subagent` could advertise background mode while the control tools are absent. The control tools are part of the model-facing subagent contract, so they should be registered by the same consumer plugin that adds `run_in_background`.
+
+### Why not let background subagents survive owner session closure?
+
+Survival after owner closure requires durable task state, child-session recovery, a way to surface late results into a reopened session, and policy for tasks whose owning client never returns. The current agent runtime unregisters disposed agents, and `agent.inject()` intentionally rejects disposed targets. Tying background tasks to live owner sessions makes the v1 lifecycle explicit and avoids orphaned child agents.
+
+### Why not skip owner-token checks because ACP sessions are isolated?
+
+ACP sessions isolate their logs and agents, but services such as `ctx.agents`, `ctx.tools`, and `ctx.subagents` are shared within the runtime. A background-task id is a global resource handle. Without an owner check, another live session in the same runtime could guess or receive a task id and read or stop it.
+
+### Why not expose incremental subagent transcript output?
+
+The child session is already the trace for internal reasoning, tool calls, and intermediate messages. Streaming that transcript into the parent would blur the parent/child log boundary that makes in-process and ACP providers equivalent. The first background surface returns status and final output only; richer observation belongs to UI/session tooling or a separate observation RFC.
+
+## Acceptance criteria
+
+- A deployment config can expose `subagent` and `subagent_fork` from one `dsh-tool-subagent` instance while binding them to different providers.
+- A configured delegation tool exposes `run_in_background` only when that tool enables background mode.
+- A background call returns a task id immediately and the parent can continue using other tools before collecting the result.
+- `subagent_output`, `subagent_wait`, and `subagent_stop` enforce owner-token access and reject cross-session task ids.
+- A task that finishes while the owner agent is live injects a durable completion notice into the owner session; a task whose owner is disposed does not throw while trying to notify.
+- Disposing the owner agent cancels all of that owner's running background subagent tasks and reaches quiescence without leaking child agents.
+- Snapshot coverage proves the changed tool schemas and the completion-notice path; unit coverage pins foreground compatibility, background settlement, timeout, stop, owner isolation, and owner-disposal cleanup.
+
+## Risks
+
+The multi-tool config reshapes how deployments expose provider aliases, so examples and generated tool catalogs must move together with the implementation. The pre-release policy allows this churn, but the migration must update every shipped config in one change.
+
+The prompt guidance can reduce abandoned tasks but cannot force a model to collect every background result. Runtime cleanup on owner disposal is the hard stop; a future planner or guard could enforce "no final answer with relevant running tasks" more strongly if the prompt proves insufficient.
+
+The task registry duplicates some concepts named by the generic long-running-tool RFC. Keeping the subagent registry final-output-only and service-local limits that duplication, but a later generic runtime extraction will still need a careful migration.

From e7e382f9d1b499313c8d62d25e068b252798c90b Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Wed, 8 Jul 2026 21:16:56 +0800
Subject: [PATCH 02/48] docs: require awaited subagent owner cleanup

---
 .../feature/2026-07-08-background-subagent-tasks.md  | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/rfc/proposed/feature/2026-07-08-background-subagent-tasks.md b/docs/rfc/proposed/feature/2026-07-08-background-subagent-tasks.md
index 7c1fe99624..97e8ce1ddb 100644
--- a/docs/rfc/proposed/feature/2026-07-08-background-subagent-tasks.md
+++ b/docs/rfc/proposed/feature/2026-07-08-background-subagent-tasks.md
@@ -16,7 +16,7 @@ Add a background mode to the existing model-facing subagent tools and add three
 
 `dsh-tool-subagent` becomes a single multi-tool consumer plugin instead of one plugin instance per provider. Its config maps model-facing tool names to provider names, so one plugin instance can register `subagent`, `subagent_fork`, and any deployment-specific aliases such as `subagent_acp`, plus the shared background control tools. Providers remain named implementations on `ctx.subagents`: `spawn`, `fork`, `acp`, or future backends. This keeps provider implementation and model-facing exposure separate while avoiding a failure mode where one `subagent` tool exposes `run_in_background` but the companion wait/output/stop tools were never loaded.
 
-The background task is scoped to the owner session, not durable across session closure. A background subagent starts only from a model-driven call with `exec.agent`; the service stores the caller's `session.header.id` as the owner token. `subagent_output`, `subagent_wait`, and `subagent_stop` compare that stored token with the caller's session id and reject cross-session access. When the owner agent is disposed, the service cancels any running background subagent tasks for that owner and discards their retained snapshots after quiescence. Completion notices are best-effort: if the owner agent is still registered, `dsh-tool-subagent` injects a short `context/message`; if the owner is gone, no notice is written.
+The background task is scoped to the owner session, not durable across session closure. A background subagent starts only from a model-driven call with `exec.agent`; the service stores the caller's `session.header.id` as the owner token. `subagent_output`, `subagent_wait`, and `subagent_stop` compare that stored token with the caller's session id and reject cross-session access. When the owner agent is disposed, an awaited owner-cleanup path cancels any running background subagent tasks for that owner and waits for their settlement/dispose before the owner handle reports quiescence. Completion notices are best-effort: if the owner agent is still registered, `dsh-tool-subagent` injects a short `context/message`; if the owner is gone, no notice is written.
 
 ## Tool surface
 
@@ -38,7 +38,7 @@ The registry owns task settlement. It attaches one continuation to `run.result`;
 
 The registry is runtime-global because `ctx.subagents` is a service shared by all live agents in the Cordis context. Session isolation is therefore explicit owner-token authorization, not an assumption about separate service instances. This mirrors the bash background-task fence: predictable ids are safe only when read/stop operations check the caller's owner token.
 
-Owner disposal is a hard lifecycle boundary. `SubagentService` listens to `agent/disposed`, finds tasks owned by that agent's session id, and cancels running tasks. It does not attempt to persist unfinished task state, resume children, or inject into disposed sessions. A future durable job system can extend this boundary, but this feature intentionally keeps background subagents tied to live sessions.
+Owner disposal is a hard lifecycle boundary, but `agent/disposed` alone is not the cleanup mechanism. The current agent registry emits `agent/disposed` synchronously after removing the agent, and `AgentHandle.dispose()` does not await asynchronous listener work. This feature therefore also adds an awaited owner-cleanup seam: background task registration attaches an owner-scoped disposer that runs in the owning agent's disposal chain before that handle resolves. That disposer finds tasks owned by the agent's session id, requests cancellation, waits for each task's settlement path to record the terminal snapshot, and awaits `run.dispose()`. The existing `agent/disposed` event may still be used as a best-effort notification/fallback, but it must not be the path that promises child quiescence. The service does not attempt to persist unfinished task state, resume children, or inject into disposed sessions. A future durable job system can extend this boundary, but this feature intentionally keeps background subagents tied to live sessions.
 
 ## Model guidance
 
@@ -51,7 +51,7 @@ Owner disposal is a hard lifecycle boundary. `SubagentService` listens to `agent
 - Call `subagent_stop` for a background task that is no longer needed.
 - End without collecting a task only when its result is irrelevant or the task was explicitly stopped.
 
-This prompt guidance is not the enforcement boundary. Runtime enforcement is owner-token authorization and cancellation on owner disposal. The guidance keeps ordinary model behavior from accidentally abandoning relevant work while still allowing explicit stop or irrelevance.
+This prompt guidance is not the enforcement boundary. Runtime enforcement is owner-token authorization and the awaited owner-cleanup path. The guidance keeps ordinary model behavior from accidentally abandoning relevant work while still allowing explicit stop or irrelevance.
 
 ## Relationship to generic long-running tools
 
@@ -69,7 +69,7 @@ A separate plugin has the same half-loaded failure mode: `subagent` could advert
 
 ### Why not let background subagents survive owner session closure?
 
-Survival after owner closure requires durable task state, child-session recovery, a way to surface late results into a reopened session, and policy for tasks whose owning client never returns. The current agent runtime unregisters disposed agents, and `agent.inject()` intentionally rejects disposed targets. Tying background tasks to live owner sessions makes the v1 lifecycle explicit and avoids orphaned child agents.
+Survival after owner closure requires durable task state, child-session recovery, a way to surface late results into a reopened session, and policy for tasks whose owning client never returns. The current agent runtime unregisters disposed agents, and `agent.inject()` intentionally rejects disposed targets. Tying background tasks to an awaited owner-cleanup path makes the v1 lifecycle explicit and avoids orphaned child agents.
 
 ### Why not skip owner-token checks because ACP sessions are isolated?
 
@@ -86,13 +86,13 @@ The child session is already the trace for internal reasoning, tool calls, and i
 - A background call returns a task id immediately and the parent can continue using other tools before collecting the result.
 - `subagent_output`, `subagent_wait`, and `subagent_stop` enforce owner-token access and reject cross-session task ids.
 - A task that finishes while the owner agent is live injects a durable completion notice into the owner session; a task whose owner is disposed does not throw while trying to notify.
-- Disposing the owner agent cancels all of that owner's running background subagent tasks and reaches quiescence without leaking child agents.
+- Disposing the owner agent runs an awaited owner-cleanup path that cancels all of that owner's running background subagent tasks and reaches quiescence without leaking child agents; tests prove `agent/disposed` alone is not relied on for this guarantee.
 - Snapshot coverage proves the changed tool schemas and the completion-notice path; unit coverage pins foreground compatibility, background settlement, timeout, stop, owner isolation, and owner-disposal cleanup.
 
 ## Risks
 
 The multi-tool config reshapes how deployments expose provider aliases, so examples and generated tool catalogs must move together with the implementation. The pre-release policy allows this churn, but the migration must update every shipped config in one change.
 
-The prompt guidance can reduce abandoned tasks but cannot force a model to collect every background result. Runtime cleanup on owner disposal is the hard stop; a future planner or guard could enforce "no final answer with relevant running tasks" more strongly if the prompt proves insufficient.
+The prompt guidance can reduce abandoned tasks but cannot force a model to collect every background result. Runtime cleanup through the awaited owner-disposal path is the hard stop; a future planner or guard could enforce "no final answer with relevant running tasks" more strongly if the prompt proves insufficient.
 
 The task registry duplicates some concepts named by the generic long-running-tool RFC. Keeping the subagent registry final-output-only and service-local limits that duplication, but a later generic runtime extraction will still need a careful migration.

From 184e164091d462cefc9dfe309c0e85d46ca6e231 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 9 Jul 2026 21:22:54 +0800
Subject: [PATCH 03/48] feat(tasks): background task runtime, generic task_*
 control tools, bash/subagent producers

One shared ctx.tasks registry (branded <kind>-N ids, owner-fenced
read/kill/wait/list, attachSurface misconfiguration fence, reported-flag
notice dedup, atomic register) + dsh-tool-tasks (task_output/task_list/
task_kill, completion-notice injection, background prompt habit).
Producers opt in via their own enableRunInBackground config: bash
(stream kind; seam slimmed to resolve/run/start returning a BashProcess
handle, bash_output/bash_kill deleted) and subagent (final-output kind;
done settles after run.dispose()). Owner disposal drains tasks through
the new awaited ctx.agents.onCleanup seam in the loop's disposal chain.
Both RFCs moved to implemented/; docs, catalogs, snapshots re-pinned.
---
 docs/architecture.md                          |   4 +-
 docs/capability-seams.md                      |   8 +
 docs/config-catalog.md                        |  51 +-
 docs/cookbook/adding-a-tool.md                |   4 +-
 docs/cordis-catalog/events.md                 |   8 +-
 docs/cordis-catalog/services.md               |  43 +-
 docs/core-data-structures/bash.md             |  65 +-
 docs/core-data-structures/core.md             |   7 +-
 docs/core-data-structures/tasks.md            | 126 +++
 docs/event-producer-consumer.md               |   8 +-
 docs/module-graph.md                          |  22 +-
 docs/rfc/INDEX.md                             |   4 +-
 ...06-20-generic-long-running-tool-runtime.md | 171 +++++
 .../2026-07-08-background-subagent-tasks.md   |  62 ++
 ...06-20-generic-long-running-tool-runtime.md |  41 -
 .../2026-07-08-background-subagent-tasks.md   |  98 ---
 ...2026-06-20-drop-bash-output-spill-files.md |   2 +-
 docs/tool-catalog.md                          | 128 ++--
 .../tests/snapshots/text-turn/session.jsonl   |  72 +-
 examples/coding-agent/README.md               |   4 +-
 examples/coding-agent/cordis.yml              |   3 +-
 packages/README.md                            |   1 +
 packages/bash/README.md                       |   4 +-
 packages/bash/bash-local/README.md            |   2 +-
 packages/bash/bash-local/src/index.ts         | 157 ++--
 .../bash/bash-local/tests/executor.spec.ts    | 346 ++++-----
 packages/bash/bash/README.md                  |  18 +-
 packages/bash/bash/package.json               |   2 -
 packages/bash/bash/src/index.ts               | 136 +---
 packages/bash/bash/src/types.ts               | 123 ++-
 packages/bash/bash/tests/service.spec.ts      | 151 +---
 packages/bash/bash/tsconfig.json              |   3 -
 packages/bash/tool-bash/README.md             |  36 +-
 packages/bash/tool-bash/package.json          |   6 +
 packages/bash/tool-bash/src/index.ts          | 286 +++----
 .../bash/tool-bash/tests/integration.spec.ts  |  76 +-
 packages/bash/tool-bash/tests/tools.spec.ts   | 715 +++++++-----------
 packages/bash/tool-bash/tsconfig.json         |   6 +
 packages/core/agent-core/README.md            |   2 +-
 packages/core/agent-core/package.json         |   4 +
 packages/core/agent-core/src/index.ts         |   7 +-
 .../core/agent-core/tests/agent-core.spec.ts  |   4 +-
 packages/core/agent-core/tsconfig.json        |   6 +
 packages/core/agent-loop/README.md            |   2 +-
 packages/core/agent-loop/src/index.ts         |  11 +-
 .../agent-loop/tests/cleanup-drain.spec.ts    |  57 ++
 packages/core/agent/README.md                 |   5 +-
 packages/core/agent/src/index.ts              |  68 ++
 packages/core/agent/tests/agent.spec.ts       | 125 ++-
 .../core/tools/tests/gen-tool-catalog.spec.ts |   2 +-
 .../hooks/hook-protocol/tests/runner.spec.ts  |   1 -
 packages/subagent/subagent/README.md          |   2 +-
 packages/subagent/subagent/src/index.ts       |  15 +-
 packages/subagent/tool-subagent/README.md     |   9 +-
 packages/subagent/tool-subagent/package.json  |   5 +-
 packages/subagent/tool-subagent/src/index.ts  | 125 ++-
 .../tool-subagent/tests/tool-subagent.spec.ts | 192 ++++-
 packages/subagent/tool-subagent/tsconfig.json |   3 +
 packages/tasks/README.md                      |  10 +
 packages/tasks/tasks/README.md                |  25 +
 packages/tasks/tasks/package.json             |  35 +
 packages/tasks/tasks/src/index.ts             | 457 +++++++++++
 packages/tasks/tasks/src/types.ts             | 155 ++++
 packages/tasks/tasks/tests/tasks.spec.ts      | 465 ++++++++++++
 packages/tasks/tasks/tsconfig.json            |  24 +
 packages/tasks/tool-tasks/README.md           |  24 +
 packages/tasks/tool-tasks/package.json        |  43 ++
 packages/tasks/tool-tasks/src/index.ts        | 183 +++++
 .../tasks/tool-tasks/tests/tool-tasks.spec.ts | 306 ++++++++
 packages/tasks/tool-tasks/tsconfig.json       |  33 +
 packages/ui/acp-agent/tests/acp-agent.spec.ts |   4 +-
 packages/ui/acp/README.md                     |   2 +-
 .../ui/stdio-agent/tests/stdio-agent.spec.ts  |   4 +-
 packages/util/README.md                       |   2 +-
 packages/util/brand/README.md                 |   4 +-
 pnpm-lock.yaml                                |  68 +-
 scripts/doc-budgets.manifest.json             |   4 +-
 scripts/gen-doc-graphs.ts                     |   9 +
 scripts/gen-tool-catalog.ts                   |  21 +-
 scripts/type-equiv.manifest.json              |   9 +-
 tsconfig.base.json                            |   1 +
 tsconfig.build.json                           |   2 +
 tsconfig.json                                 |   2 +
 83 files changed, 3909 insertions(+), 1627 deletions(-)
 create mode 100644 docs/core-data-structures/tasks.md
 create mode 100644 docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
 create mode 100644 docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md
 delete mode 100644 docs/rfc/proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md
 delete mode 100644 docs/rfc/proposed/feature/2026-07-08-background-subagent-tasks.md
 create mode 100644 packages/core/agent-loop/tests/cleanup-drain.spec.ts
 create mode 100644 packages/tasks/README.md
 create mode 100644 packages/tasks/tasks/README.md
 create mode 100644 packages/tasks/tasks/package.json
 create mode 100644 packages/tasks/tasks/src/index.ts
 create mode 100644 packages/tasks/tasks/src/types.ts
 create mode 100644 packages/tasks/tasks/tests/tasks.spec.ts
 create mode 100644 packages/tasks/tasks/tsconfig.json
 create mode 100644 packages/tasks/tool-tasks/README.md
 create mode 100644 packages/tasks/tool-tasks/package.json
 create mode 100644 packages/tasks/tool-tasks/src/index.ts
 create mode 100644 packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
 create mode 100644 packages/tasks/tool-tasks/tsconfig.json

diff --git a/docs/architecture.md b/docs/architecture.md
index 02dac4a2dd..eaeb86d913 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -31,6 +31,7 @@ The default distribution is a composition, not a hierarchy. `packages/core/` is
 | `ctx.web` | [`web/`](../packages/web/README.md) | search/fetch provider registries |
 | `ctx.compact` | [`compact/`](../packages/compact/README.md) | session-surface compaction |
 | `ctx.subagents` | [`subagent/`](../packages/subagent/README.md) | named delegation providers |
+| `ctx.tasks` | [`tasks/`](../packages/tasks/README.md) | background task registry + generic `task_*` control tools |
 | `ctx.sessionPersistence` | [`session-persistence/`](../packages/session-persistence/README.md) | durable storage for session logs |
 
 ## Event Surface
@@ -101,7 +102,7 @@ Every session event is turn-enclosed. Reloading a crashed session preserves the
 
 ### Agent Handles
 
-`ctx.agents` owns live agents and returns an `AgentHandle { agent, dispose() }`. `Agent` is the surface other plugins drive: `send()` queues work, `steer()` injects mid-turn content, `inject()` appends context and opens a one-shot injection turn when idle, `cancel()` is the public stop primitive, and `whenIdle()` observes quiescence. Lifecycle owners tear down with `await dispose()`.
+`ctx.agents` owns live agents and returns an `AgentHandle { agent, dispose() }`. `Agent` is the surface other plugins drive: `send()` queues work, `steer()` injects mid-turn content, `inject()` appends context and opens a one-shot injection turn when idle, `cancel()` is the public stop primitive, and `whenIdle()` observes quiescence. Lifecycle owners tear down with `await dispose()`, whose chain also awaits every `ctx.agents.onCleanup` registration — the seam tying resources (background tasks) to the owner's quiescence.
 
 ## State And Model Surface
 
@@ -140,6 +141,7 @@ New behavior should attach to a documented seam; changing the shipped loop requi
 | Add a model provider | register an adapter on `ctx.llm` |
 | Add a model-facing capability | register a tool on `ctx.tools`; schemas flow into prompt assembly |
 | Add command execution | implement and register a `ctx.bash` backend |
+| Add a long-running/background capability | register the work on `ctx.tasks`; the generic `task_*` tools collect/stop it |
 | Add filesystem access or policy | implement a `ctx.fs` provider or listen on `fs/*` policy events |
 | Intercept prompts, requests, tool use, or continuation | listen on the relevant `agent/*` or `tools/*` waterfall |
 | Add UI or editor integration | drive `ctx.agents` and render from `session/event` |
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 339954c00f..54a271423e 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -56,6 +56,9 @@ flowchart LR
   pkg_subagent_fork["subagent-fork"]
   pkg_subagent_acp["subagent-acp"]
   pkg_subagent_mock["subagent-mock"]
+  pkg_tasks["tasks"]
+  svc_tasks["ctx.tasks<br/>Background task registry"]
+  pkg_tool_tasks["tool-tasks"]
   pkg_web["web"]
   svc_web["ctx.web<br/>Web access provider registry"]
   pkg_web_search_exa["web-search-exa"]
@@ -85,6 +88,7 @@ flowchart LR
   pkg_subagent_mock --> svc_subagents
   pkg_subagent_spawn --> svc_subagents
   pkg_system_prompt --> svc_systemPrompt
+  pkg_tasks --> svc_tasks
   pkg_tools --> svc_tools
   pkg_web --> svc_web
   pkg_web_fetch_local --> svc_web
@@ -116,6 +120,9 @@ flowchart LR
   svc_systemPrompt --> pkg_tool_fs
   svc_systemPrompt --> pkg_tool_web
   svc_systemPrompt --> pkg_tools
+  svc_tasks --> pkg_tool_bash
+  svc_tasks --> pkg_tool_subagent
+  svc_tasks --> pkg_tool_tasks
   svc_tools --> pkg_acp
   svc_tools --> pkg_agent_loop
   svc_tools --> pkg_tool_bash
@@ -141,6 +148,7 @@ flowchart LR
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-policy contributes observed-state checks through the fs/* event gate. |
 | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend currently consumes the pre-step event directly; a model-facing compact tool remains deferred. |
 | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-mock`](../packages/support/subagent-mock) | [`tool-subagent`](../packages/subagent/tool-subagent) | - | Providers implement transports; tool-subagent exposes one configured provider as a model-facing tool name. |
+| `ctx.tasks` | `core` | [`tasks`](../packages/tasks/tasks) | - | [`tool-bash`](../packages/bash/tool-bash), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (tool-bash background commands, tool-subagent background delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it. |
 | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. |
 
 Maintenance mode: hybrid: services are discovered from Cordis declarations; interface/implementation/consumer roles are classified in `scripts/gen-doc-graphs.ts` with a completeness guard.
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index e55066101f..f59260810f 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -83,7 +83,7 @@ export interface Config {
 
 Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt)
 
-Source: [`packages/core/agent-core/src/index.ts:69`](../packages/core/agent-core/src/index.ts)
+Source: [`packages/core/agent-core/src/index.ts:72`](../packages/core/agent-core/src/index.ts)
 
 ## `@deepseek-ai/dsh-agent-loop`
 
@@ -139,7 +139,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/bash/bash-local/src/index.ts:28`](../packages/bash/bash-local/src/index.ts)
+Source: [`packages/bash/bash-local/src/index.ts:29`](../packages/bash/bash-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-compact-basic`
 
@@ -602,6 +602,25 @@ export interface Config {
 
 Source: [`packages/core/system-prompt/src/index.ts:179`](../packages/core/system-prompt/src/index.ts)
 
+## `@deepseek-ai/dsh-tool-bash`
+
+Requires: `tools` · `bash` · `systemPrompt`
+
+```ts config-catalog
+/** Config: whether the model may background commands (the producer-opt-in flag). */
+export interface Config {
+  /**
+   * Expose `run_in_background` in the bash schema (default true). Disabled,
+   * the parameter is absent entirely — schema and capability never disagree.
+   * Backgrounding also needs the `ctx.tasks` runtime at call time; a missing
+   * one fails the call loud with the load-these-packages message.
+   */
+  enableRunInBackground?: boolean
+}
+```
+
+Source: [`packages/bash/tool-bash/src/index.ts:43`](../packages/bash/tool-bash/src/index.ts)
+
 ## `@deepseek-ai/dsh-tool-fs`
 
 Requires: `tools` · `fs` · `systemPrompt`
@@ -639,6 +658,14 @@ export interface Config {
    * `{ provider: 'acp', toolName: 'subagent_acp' }`.
    */
   toolName?: string
+  /**
+   * Expose `run_in_background` in this instance's schema (default true).
+   * Disabled, the parameter is absent entirely — schema and capability never
+   * disagree; delegation through this instance stays strictly synchronous.
+   * Backgrounding also needs the `ctx.tasks` runtime at call time; a missing
+   * one fails the call loud with the load-these-packages message.
+   */
+  enableRunInBackground?: boolean
   /**
    * Default per-child agent options (model) applied to every spawned child.
    * Omitted fields fall back to the child loop's own defaults. There is no
@@ -651,7 +678,23 @@ export interface Config {
 
 Depends on: [`AgentOptions`](../packages/core/agent/src/index.ts)
 
-Source: [`packages/subagent/tool-subagent/src/index.ts:44`](../packages/subagent/tool-subagent/src/index.ts)
+Source: [`packages/subagent/tool-subagent/src/index.ts:56`](../packages/subagent/tool-subagent/src/index.ts)
+
+## `@deepseek-ai/dsh-tool-tasks`
+
+Requires: `tools` · `tasks` · `systemPrompt`
+
+```ts config-catalog
+/** Config: the `task_output` wait bounds (defaulted, capped — never hardcoded). */
+export interface Config {
+  /** Wait duration applied when `task_output` sets `wait` without `timeout_ms` (default 30s). */
+  waitTimeoutMs?: number
+  /** Hard cap on any single wait; a larger model-supplied `timeout_ms` is clamped down to it (default 10min). */
+  maxWaitTimeoutMs?: number
+}
+```
+
+Source: [`packages/tasks/tool-tasks/src/index.ts:34`](../packages/tasks/tool-tasks/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-web`
 
@@ -793,7 +836,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-llm` ([`packages/llm/llm/src/index.ts`](../packages/llm/llm/src/index.ts))
 - `@deepseek-ai/dsh-session` ([`packages/core/session/src/index.ts`](../packages/core/session/src/index.ts))
 - `@deepseek-ai/dsh-subagent` ([`packages/subagent/subagent/src/index.ts`](../packages/subagent/subagent/src/index.ts))
-- `@deepseek-ai/dsh-tool-bash` — requires `tools` · `bash` · `systemPrompt` ([`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts))
+- `@deepseek-ai/dsh-tasks` ([`packages/tasks/tasks/src/index.ts`](../packages/tasks/tasks/src/index.ts))
 - `@deepseek-ai/dsh-tool-todo` — requires `tools` ([`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/index.ts))
 - `@deepseek-ai/dsh-tools` — requires `systemPrompt` ([`packages/core/tools/src/index.ts`](../packages/core/tools/src/index.ts))
 
diff --git a/docs/cookbook/adding-a-tool.md b/docs/cookbook/adding-a-tool.md
index 9180d88489..ba89caf387 100644
--- a/docs/cookbook/adding-a-tool.md
+++ b/docs/cookbook/adding-a-tool.md
@@ -41,9 +41,7 @@ Registration is effect-based: disposing the plugin fiber unregisters the tool (w
 
 ## Long-running work
 
-Follow tool-bash's background pattern: a `run_in_background` flag returns a task id immediately; companion tools poll incrementally and kill; completion notices arrive via `agent.inject()`. Bound buffers and spill full output to disk so nothing is silently lost.
-
-> TODO: each tool reimplements this background pattern by hand today. At some point we need a generic long-running-tool layer that handles task ids, incremental polling, kill, and completion notices uniformly.
+Register the running work with the shared task runtime instead of inventing a task protocol: gate a `run_in_background` parameter behind your plugin's own defaulted `enableRunInBackground`-style config, start the work, and hand it to `ctx.tasks.register({ kind, label, owner: exec.agent, cancel, done, readOutput? })` (`@deepseek-ai/dsh-tasks`). The runtime issues the `<kind>-N` id, fences access to the owning session, cancels-and-awaits your task when the owner disposes, and the generic `task_output`/`task_list`/`task_kill` tools plus the completion notice come from `@deepseek-ai/dsh-tool-tasks` — your tool returns `started background task <id>` and is done. Your producer keeps its execution concerns: `done` must settle at quiescence (resources released), and a stream-kind `readOutput` owns its own truncation/spill formatting (bound buffers, spill full output to disk so nothing is silently lost — see tool-bash's `renderProcessRead`). Do NOT wire `exec.signal` to the background work after the id is returned; check `exec.signal?.aborted` once before starting, then leave cancellation to `task_kill` and owner cleanup. **A failed `register()` must not orphan the work**: `register()` is atomic (a throw — the no-control-surface fence, a bad owner — mutates no registry state), so wrap it in try/catch, cancel the just-started work, AWAIT its quiescence, and rethrow — the model never learns an id, so nothing else could ever collect or kill what you started (tool-bash's `proc.kill(); await proc.done` and tool-subagent's `run.cancel(); await done` are the templates).
 
 ## Permissions / sandboxing
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 8d776a75ef..ed6e7dad33 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -243,7 +243,7 @@ A subagent run settled — emitted when SubagentRun.result resolves (any stop re
 'subagent/end'(info: SubagentRunEndInfo): void
 ```
 
-Source: [`packages/subagent/subagent/src/index.ts:98`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:99`](../../packages/subagent/subagent/src/index.ts)
 
 ### `subagent/provider-added` — emit
 
@@ -253,7 +253,7 @@ A provider became resolvable in the SubagentService registry. Consumers that der
 'subagent/provider-added'(provider: SubagentProvider): void
 ```
 
-Source: [`packages/subagent/subagent/src/index.ts:72`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:73`](../../packages/subagent/subagent/src/index.ts)
 
 ### `subagent/provider-removed` — emit
 
@@ -263,7 +263,7 @@ A provider left the registry (its plugin's fiber was disposed — an unload or a
 'subagent/provider-removed'(name: string): void
 ```
 
-Source: [`packages/subagent/subagent/src/index.ts:83`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:84`](../../packages/subagent/subagent/src/index.ts)
 
 ### `subagent/start` — emit
 
@@ -273,7 +273,7 @@ A subagent run started — emitted after the provider is resolved and its capabi
 'subagent/start'(info: SubagentRunInfo): void
 ```
 
-Source: [`packages/subagent/subagent/src/index.ts:91`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:92`](../../packages/subagent/subagent/src/index.ts)
 
 ## `system-prompt/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 26126c4481..42179d4bd3 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -33,12 +33,14 @@ create(options: CreateAgentOptions): AgentHandle
 async resume(options: ResumeAgentOptions): Promise<AgentHandle>
 register(agent: Agent): () => void
 get(id: AgentId): Agent | undefined
+onCleanup(agentId: AgentId, cleanup: () => Promise<void>): () => void
+async drainCleanups(agentId: AgentId): Promise<void>
 list(): Agent[]
 ```
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/index.ts:117`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:124`](../../packages/core/agent/src/index.ts)
 
 ## `ctx.bash` — `BashExecutor` (abstract seam)
 
@@ -47,25 +49,19 @@ Abstract bash execution service. Subclass, implement the abstract methods, and l
 Semantics every implementation must honor:
 
 - run REJECTS only for infrastructure failures (unusable workdir, missing shell, pre-aborted signal). Nonzero exits, timeout kills, and abort kills RESOLVE with a descriptive BashRunResult — reporting a failed command is the tool layer's job, not an exception.
-- start returns immediately; no timeout applies to background tasks (callers stop them via kill or the spec's AbortSignal). Completion must fire the onTaskDone listeners exactly once per task, and must NOT fire after the service is disposed.
-- readOutput is incremental: consecutive reads never re-deliver output. Implementations bound their buffers; reads that lost data flag `lossy` and point at full-stream spill files when available.
-- Disposal kills every running task and awaits their exit (no orphan processes survive `fiber.dispose()`).
+- start returns immediately; no timeout applies to background processes (callers stop them via BashProcess.kill or the spec's AbortSignal). The handle's `done` settles at process close and never rejects (a spawn failure settles as `killed` with the error readable on stderr).
+- BashProcess.readOutput is incremental: consecutive reads never re-deliver output. Implementations bound their buffers; reads that lost data flag `lossy` and point at full-stream spill files when available.
+- Disposal kills every running background process and awaits their exit (no orphan processes survive `fiber.dispose()`).
 
 ```ts cordis-catalog
 abstract resolve(request: BashExecRequest): BashExecSpec
 abstract run(spec: BashExecSpec): Promise<BashRunResult>
-abstract start(spec: BashExecSpec): BashTask
-abstract get(id: BashTaskId): BashTask | undefined
-abstract ownerOf(id: BashTaskId): OwnerToken | undefined
-abstract list(): BashTask[]
-abstract readOutput(id: BashTaskId): BashTaskRead
-abstract kill(id: BashTaskId): boolean
-onTaskDone(listener: BashTaskListener): () => void
+abstract start(spec: BashExecSpec): BashProcess
 ```
 
-Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md) · [BashTask](../core-data-structures/bash.md) · [BashTaskRead](../core-data-structures/bash.md)
+Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md)
 
-Source: [`packages/bash/bash/src/index.ts:59`](../../packages/bash/bash/src/index.ts)
+Source: [`packages/bash/bash/src/index.ts:65`](../../packages/bash/bash/src/index.ts)
 
 ## `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
 
@@ -196,7 +192,7 @@ list(): string[]
 start(name: string, request: SubagentStartRequest): SubagentRun
 ```
 
-Source: [`packages/subagent/subagent/src/index.ts:144`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:145`](../../packages/subagent/subagent/src/index.ts)
 
 ## `ctx.systemPrompt` — `SystemPrompt`
 
@@ -211,6 +207,25 @@ async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
 
 Source: [`packages/core/system-prompt/src/index.ts:291`](../../packages/core/system-prompt/src/index.ts)
 
+## `ctx.tasks` — `TaskService`
+
+The `tasks` service: the runtime-global background task registry. See the module doc for the ownership, isolation, and lifecycle contracts.
+
+```ts cordis-catalog
+register(registration: TaskRegistration): TaskId
+list(caller?: Agent): TaskSnapshot[]
+get(id: TaskId, caller?: Agent): TaskSnapshot
+read(id: TaskId, caller?: Agent): TaskRead
+kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-terminal'
+async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
+onTaskDone(listener: TaskDoneListener): () => void
+attachSurface(name: string): () => void
+```
+
+Types: [Agent](../core-data-structures/core.md)
+
+Source: [`packages/tasks/tasks/src/index.ts:84`](../../packages/tasks/tasks/src/index.ts)
+
 ## `ctx.tools` — `ToolRegistry`
 
 Tool registry (`ctx.tools`): tool plugins register definitions; the agent loop executes calls through the `tools/pre-execute` → dispatch → `tools/post-execute` pipeline. The registry contributes its schemas into the system-prompt assembly.
diff --git a/docs/core-data-structures/bash.md b/docs/core-data-structures/bash.md
index 273ba5ebe8..ffa83cd22a 100644
--- a/docs/core-data-structures/bash.md
+++ b/docs/core-data-structures/bash.md
@@ -1,6 +1,6 @@
 # Bash Executor
 
-The bash execution seam — the canonical [capability seam](../rfc/implemented/architecture/2026-06-13-capability-seams.md) example, split across three packages: interface ([dsh-bash](../../packages/bash/bash), `ctx.bash`), implementation ([dsh-bash-local](../../packages/bash/bash-local), local subprocesses), and consumer ([dsh-tool-bash](../../packages/bash/tool-bash), the `bash`/`bash_output`/`bash_kill` tool schemas). Bash is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A sandboxed, containerized, or remote backend is a sibling package implementing the same interface.
+The bash execution seam — the canonical [capability seam](../rfc/implemented/architecture/2026-06-13-capability-seams.md) example, split across three packages: interface ([dsh-bash](../../packages/bash/bash), `ctx.bash`), implementation ([dsh-bash-local](../../packages/bash/bash-local), local subprocesses), and consumer ([dsh-tool-bash](../../packages/bash/tool-bash), the `bash` tool schema). Bash is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A sandboxed, containerized, or remote backend is a sibling package implementing the same interface.
 
 Source: [`packages/bash/bash/src/types.ts`](../../packages/bash/bash/src/types.ts)
 
@@ -35,15 +35,6 @@ interface BashExecRequest {
    * uses shell syntax like `FOO=bar cmd`).
    */
   env?: Record<string, string> | undefined
-  /**
-   * Opaque OWNER token for a background task — the consumer's isolation key
-   * (the tool layer passes the owning agent's `session.header.id`). The
-   * executor stores it on the task and exposes it via {@link BashExecutor.ownerOf};
-   * the executor itself NEVER interprets it (no access policy lives in the
-   * seam — that is the consumer's job). Absent for foreground runs and for an
-   * ownerless background start (a non-agent caller).
-   */
-  owner?: OwnerToken | undefined
 }
 ```
 
@@ -56,10 +47,10 @@ interface BashExecSpec {
   signal?: AbortSignal | undefined
   /**
    * Bytes to write to the command's stdin (then close it), carried through
-   * verbatim from {@link BashExecRequest.stdin}. OPTIONAL on the resolved spec
-   * (unlike `owner`): it has no config default, so a missing one means "no
-   * stdin" — the safe, ordinary case — not a silent footgun, so it stays a
-   * plain optional rather than required-but-nullable (see the request field).
+   * verbatim from {@link BashExecRequest.stdin}. OPTIONAL on the resolved spec:
+   * it has no config default, so a missing one means "no stdin" — the safe,
+   * ordinary case — not a silent footgun, so it stays a plain optional rather
+   * than required-but-nullable (see the request field).
    */
   stdin?: string | undefined
   /**
@@ -70,23 +61,12 @@ interface BashExecSpec {
    * config default, absent means "no extra env".
    */
   env?: Record<string, string> | undefined
-  /**
-   * Opaque owner token, REQUIRED-but-nullable (mirrors `workdir`/`timeoutMs`
-   * being required on the resolved spec): {@link BashExecutor.resolve} carries
-   * the request's `owner` through, defaulting a missing one to `undefined`. A
-   * required field makes a forgotten owner a VISIBLE `undefined` rather than a
-   * silently-absent property that yields an unowned (cross-session-readable)
-   * task. `start()` stores it; `run()` (foreground) ignores it.
-   */
-  owner: OwnerToken | undefined
 }
 ```
 
-The `owner` token is the isolation key: the executor stores it but never interprets it (access policy is the consumer's job), so a background task started by one agent isn't readable cross-session. A required-but-nullable field makes a forgotten owner a visible `undefined` rather than a silently-unowned task.
+The seam is deliberately **task-free**: no task ids, no owner tokens, no polling protocol. Background-task semantics (ids, cross-session isolation, collect/stop tools, completion notices) live in the generic `ctx.tasks` runtime ([dsh-tasks](../../packages/tasks/tasks)); the tool layer adapts a `BashProcess` handle into a task registration, so a sandboxed or remote executor inherits no session or registry dependency.
 
-`stdin` and `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload on stdin and its `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` env. The model-facing `dsh-tool-bash` tool does not expose them as parameters — its request is built from `command`/`workdir`/`timeoutMs`/`signal`/`owner` only — because a model already has equivalent power through shell syntax (`FOO=bar cmd`, a heredoc), so duplicating them as tool params would be redundant. This is NOT a security boundary: the credential scrub in `dsh-bash-local` is what stops the harness's ambient secrets reaching a spawned command, and it works regardless of these fields (a model cannot read a value the scrub removed, and tool-call args are static JSON, never shell-evaluated). A guard test asserts the tool doesn't forward model `env`/`stdin` — to catch a future `...args` spread, not to defend a trust wall. `env` is merged AFTER the scrub so an explicit caller entry (a value it already holds) wins even on a credential-shaped name. See [the bash-stdin-env RFC](../rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
-
-Both ids the seam handles are [branded](core.md) (zero-cost `string` brands, the same machinery as `SessionId`/`AgentId`): `BashTaskId` (a tracked background task, generated `bash-N` by the local executor) and `OwnerToken` (the opaque isolation key). `OwnerToken` is deliberately a DISTINCT brand from `SessionId`, not an alias: the bash seam is a capability seam that must not know what an owner token *means*, so it never imports `dsh-session`'s vocabulary — the `dsh-tool-bash` consumer is the single boundary that casts the owning agent's `SessionId` into an `OwnerToken`. Branding both stops a raw `string` (or a `BashTaskId` where an `OwnerToken` is expected, or vice versa) from slipping through the type checker on the model-facing `task_id` path.
+`stdin` and `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload on stdin and its `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` env. The model-facing `dsh-tool-bash` tool does not expose them as parameters — its request is built from `command`/`workdir`/`timeoutMs`/`signal` only — because a model already has equivalent power through shell syntax (`FOO=bar cmd`, a heredoc), so duplicating them as tool params would be redundant. This is NOT a security boundary: the credential scrub in `dsh-bash-local` is what stops the harness's ambient secrets reaching a spawned command, and it works regardless of these fields (a model cannot read a value the scrub removed, and tool-call args are static JSON, never shell-evaluated). A guard test asserts the tool doesn't forward model `env`/`stdin` — to catch a future `...args` spread, not to defend a trust wall. `env` is merged AFTER the scrub so an explicit caller entry (a value it already holds) wins even on a credential-shaped name. See [the bash-stdin-env RFC](../rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
 
 ## Foreground runs: `BashRunResult`
 
@@ -122,29 +102,40 @@ interface CollectedOutput {
 }
 ```
 
-## Background tasks: `BashTask`
+## Background processes: `BashProcess`
 
-A long-running command started with `start()` is tracked as a `BashTask`. `BashTaskStatus` is `'running' | 'completed' | 'killed'`; `done` resolves when the underlying process closes and never rejects.
+A long-running command started with `start()` returns a `BashProcess` **handle** — the only access path (no executor-level id lookup). `BashProcessStatus` is `'running' | 'completed' | 'killed'`; `done` resolves when the underlying process closes and never rejects (a spawn failure settles as `killed` with the error readable on stderr). Reads stay valid after exit: the remaining buffered output is still consumable through the handle.
 
 ```ts type-equiv
-interface BashTask {
-  readonly id: BashTaskId
+interface BashProcess {
+  /** The command line this process runs. */
   readonly command: string
-  status: BashTaskStatus
+  /** Process lifecycle state (settled exactly once). */
+  status: BashProcessStatus
   /** Exit code once finished (null = killed by signal / still running). */
   exitCode: number | null
   /** Terminating signal name, when signal-killed. */
   signal: NodeJS.Signals | null
-  /** Resolves when the underlying process closes (never rejects). */
+  /** Resolves when the underlying process closes (never rejects — a spawn failure settles as `killed` with the error on stderr). */
   readonly done: Promise<void>
+  /**
+   * Read output produced since the previous read (consuming — consecutive
+   * reads never re-deliver). Reads that lost data flag `lossy` and point at
+   * full-stream spill files when available.
+   */
+  readOutput(): BashProcessRead
+  /**
+   * Kill the process group. Returns false when it had already finished
+   * (no-op); idempotent.
+   */
+  kill(): boolean
 }
 ```
 
-`readOutput()` returns an incremental `BashTaskRead` — the output produced since the previous read, with a `lossy` flag when truncation dropped unread bytes:
+`readOutput()` returns an incremental `BashProcessRead` — the output produced since the previous read, with a `lossy` flag when truncation dropped unread bytes:
 
 ```ts type-equiv
-interface BashTaskRead {
-  task: BashTask
+interface BashProcessRead {
   /** Output produced since the previous read (stderr in a marked section). */
   delta: string
   /** True when truncation dropped unread bytes the delta cannot include. */
@@ -158,4 +149,4 @@ interface BashTaskRead {
 
 ## The service
 
-`BashExecutor` (`ctx.bash`, abstract — defined in [`packages/bash/bash/src/index.ts`](../../packages/bash/bash/src/index.ts)) mirrors the `LlmService`/`LlmAdapter` split: `resolve` (request → spec), `run` (foreground), `start` (background), `get`/`ownerOf`/`list`/`readOutput`/`kill`, and `onTaskDone` (a `BashTaskListener` completion callback). Spawned commands get a **scrubbed env** (dropping `*KEY*`/`*SECRET*`/`*TOKEN*`) and spill files use a private 0700 dir with random names and owner-only opens — model output never gets the ambient environment or a predictable path. The implementation that provides all this is `dsh-bash-local`; the model-facing `bash`/`bash_output`/`bash_kill` schemas that call it are in `dsh-tool-bash` (and present as terminals via the [tool-presentation vocabulary](tools.md#tool-presentation-ui-vocabulary)).
+`BashExecutor` (`ctx.bash`, abstract — defined in [`packages/bash/bash/src/index.ts`](../../packages/bash/bash/src/index.ts)) mirrors the `LlmService`/`LlmAdapter` split and is exactly three methods: `resolve` (request → spec), `run` (foreground), `start` (background, returning the `BashProcess` handle). Spawned commands get a **scrubbed env** (dropping `*KEY*`/`*SECRET*`/`*TOKEN*`) and spill files use a private 0700 dir with random names and owner-only opens — model output never gets the ambient environment or a predictable path. The implementation that provides all this is `dsh-bash-local`; the model-facing `bash` schema that calls it is in `dsh-tool-bash` (background runs register with [`ctx.tasks`](../../packages/tasks/README.md) and are collected via the generic `task_output`/`task_kill`), presenting as terminals via the [tool-presentation vocabulary](tools.md#tool-presentation-ui-vocabulary).
diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md
index 615c222d94..91667a304e 100644
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -19,7 +19,8 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnTrigger`/`TurnEndReason`, `deriveMessages()`, the turn-enclosure invariant |
 | [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` |
 | [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, the `tools/pre-execute`/`tools/post-execute` pipeline |
-| [bash.md](bash.md) | the bash executor seam: `BashExecRequest`/`Spec`, `BashRunResult`, background `BashTask`s |
+| [bash.md](bash.md) | the bash executor seam: `BashExecRequest`/`Spec`, `BashRunResult`, the background `BashProcess` handle |
+| [tasks.md](tasks.md) | the background task runtime: `TaskId`, `TaskRegistration`, `TaskOutcome`, `TaskSnapshot`/`TaskRead`, owner isolation, the control-tool surface |
 | [code-runtime.md](code-runtime.md) | the code-execution seam: `CodeRunRequest`/`Result`, binding namespaces, captured logs, the `CodeRunFailure` taxonomy |
 | [filesystem.md](filesystem.md) | the filesystem seam: `FsTarget`, read/write/edit outcomes, observed-file state, `FsErrorCode` |
 | [compaction.md](compaction.md) | the compaction seam: the `compact/*` session events, `CompactionResult`, the `CompactService` interface |
@@ -68,7 +69,7 @@ Two large discriminated unions are the ones consumers `switch` over most: **`Str
 
 IDs that cross package boundaries are **branded** — structurally strings, but non-interchangeable at the type level (an `AgentId` can't be passed where a `CallId` is expected). Construction goes through a per-type factory; comparison, logging, and JSON behave as ordinary strings.
 
-The `Branded<B>` primitive lives in its own type-only package, [dsh-brand](../../packages/util/brand) (no runtime code, no harness-package dependency), so any package can brand the ids it owns without depending on an unrelated capability package (e.g. dsh-bash brands `BashTaskId`/`OwnerToken` via dsh-brand alone, never pulling in dsh-llm).
+The `Branded<B>` primitive lives in its own type-only package, [dsh-brand](../../packages/util/brand) (no runtime code, no harness-package dependency), so any package can brand the ids it owns without depending on an unrelated capability package (e.g. dsh-tasks brands `TaskId` via dsh-brand alone, never pulling in dsh-llm).
 
 Source: [`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index.ts)
 
@@ -76,7 +77,7 @@ Source: [`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index
 type Branded<B extends string> = string & { readonly [BRAND]: B }
 ```
 
-The three core IDs: `CallId` (correlates a tool call with its result; dsh-llm), `SessionId` (dsh-session), `AgentId` (dsh-agent). Each is `Branded<'CallId'>` etc. plus a same-named factory function. Capability seams brand their own ids too — see `BashTaskId`/`OwnerToken` in [bash.md](bash.md).
+The three core IDs: `CallId` (correlates a tool call with its result; dsh-llm), `SessionId` (dsh-session), `AgentId` (dsh-agent). Each is `Branded<'CallId'>` etc. plus a same-named factory function. Capability seams brand their own ids too — see `TaskId` in [tasks.md](tasks.md).
 
 ## Content blocks and messages
 
diff --git a/docs/core-data-structures/tasks.md b/docs/core-data-structures/tasks.md
new file mode 100644
index 0000000000..f229e402ee
--- /dev/null
+++ b/docs/core-data-structures/tasks.md
@@ -0,0 +1,126 @@
+# Background Task Runtime
+
+The shared background-task vocabulary — what a producer (`dsh-tool-bash`, `dsh-tool-subagent`, any future long-running tool) hands to `ctx.tasks.register()` and what consumers (the `task_output`/`task_list`/`task_kill` tools, completion-notice injection) get back. The runtime is ONE concrete service ([dsh-tasks](../../packages/tasks/tasks), `ctx.tasks`), not an interface/implementation seam pair — see [the runtime RFC](../rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) for the decision and [the tasks group README](../../packages/tasks/README.md) for the package split.
+
+Source: [`packages/tasks/tasks/src/types.ts`](../../packages/tasks/tasks/src/types.ts)
+
+## Ids and status
+
+`TaskId` is [branded](core.md#branded-ids) (`Branded<'TaskId'>` + a same-named factory), generated by the registry as `<kind>-N` with a per-kind counter (`bash-1`, `subagent-1`) — kind-prefixed so transcripts stay self-describing, sequential because the owner fence (not id secrecy) is the isolation boundary. `TaskStatus` is generic and CLOSED: `'running' | 'stopping' | 'completed' | 'killed' | 'failed'` — kind-specific meaning (exit codes, stop reasons) rides in `TaskSnapshot.detail`, so the registry never learns process or agent semantics.
+
+## The producer contract: `TaskRegistration`
+
+A producer starts its work, then hands the running work over. The producer stays the owner of its execution concerns (process streams, child agents); the registry owns ids, isolation, status, and completion fan-out. The optional `readOutput` marks a STREAM kind — the method presence is the capability, mirroring `SubagentRun.sendMessage`.
+
+```ts type-equiv
+interface TaskRegistration {
+  /** Producer kind — also the id prefix (`bash`, `subagent`, …). Non-empty. */
+  kind: string
+  /** One-line model-facing label (the command; the delegation description). */
+  label: string
+  /**
+   * The spawning agent. Its `session.header.id` becomes the task's owner
+   * token (read/kill/wait/list are fenced to that session), and its disposal
+   * cancels and awaits the task through the `ctx.agents.onCleanup` seam.
+   * `undefined` registers an UNOWNED task: open to any caller, alive until the
+   * tasks service disposes.
+   */
+  owner?: Agent | undefined
+  /**
+   * Request termination. Idempotent, synchronous, and must lead to
+   * {@link done} settling; a throw propagates to the killer (fail loud — a
+   * cancel that cannot even be requested is a producer bug). The optional
+   * reason is `task_kill`'s logged reason, forwarded verbatim.
+   */
+  cancel(reason?: string): void
+  /**
+   * Settles with the terminal outcome at QUIESCENCE — after the producer has
+   * released the task's resources (process exited, child agent disposed) —
+   * not merely when the work finished. Must never reject; a rejection is
+   * contained as a `failed` outcome and logged as a producer contract
+   * violation.
+   */
+  done: Promise<TaskOutcome>
+  /**
+   * OPTIONAL incremental read (stream kinds): everything produced since the
+   * previous call, formatted by the producer (truncation/spill notices
+   * included). Consecutive calls never re-deliver output; the registry keeps
+   * ONE consuming cursor per task, so v1's single intended reader is the
+   * owning model. Absence marks a final-output-only kind (the method presence
+   * IS the capability).
+   */
+  readOutput?(): string
+}
+```
+
+`register()` is ATOMIC: a throw (the no-control-surface fence, an owner-cleanup attach failure) mutates no registry state, so the producer cancels and awaits its just-started work and rethrows — background work never runs without a collectable id.
+
+```ts type-equiv
+interface TaskOutcome {
+  /** How the task ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
+  status: 'completed' | 'killed' | 'failed'
+  /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
+  detail?: string
+  /**
+   * Final output for FINAL-OUTPUT-ONLY kinds (no {@link TaskRegistration.readOutput}),
+   * read idempotently after the task settles. Stream kinds leave it unset —
+   * their output is consumed incrementally through `readOutput`.
+   */
+  output?: string
+}
+```
+
+## What consumers see: `TaskSnapshot` and `TaskRead`
+
+Snapshots are fresh projections, never live registry state. `reported` is the notice-suppression flag: the completion-notice injector (`dsh-tool-tasks`) skips a task whose terminal state the model already saw.
+
+```ts type-equiv
+interface TaskSnapshot {
+  /** The registry-issued id (`<kind>-N`). */
+  id: TaskId
+  /** The producer kind the task was registered with. */
+  kind: string
+  /** The producer-supplied one-line label. */
+  label: string
+  /**
+   * The owner's session id (`session.header.id`), for surfaces that must
+   * reach the owning agent (the completion-notice injector); absent for
+   * unowned tasks. Session ids are runtime-shared identifiers, not secrets —
+   * the read/kill/wait/list FENCE is what isolation rests on.
+   */
+  ownerSession?: string
+  /** Current lifecycle state. */
+  status: TaskStatus
+  /** Kind-specific status detail, present once the producer supplied one (usually terminal). */
+  detail?: string
+  /** Epoch ms when the task was registered. */
+  startedAt: number
+  /** Epoch ms when the task settled; absent while `running`/`stopping`. */
+  finishedAt?: number
+  /**
+   * True once the terminal state has been (or is being) reported to the owner
+   * through an explicit surface response — a `kill` call, or a `read`/`wait`
+   * that returned the terminal state (including a wait pending at settlement).
+   * Completion-notice surfaces suppress their notice when set, so the model
+   * never gets a redundant "finished" for a task it just collected or killed.
+   */
+  reported: boolean
+}
+```
+
+```ts type-equiv
+interface TaskRead {
+  /**
+   * Stream kinds: the consuming delta since the previous read. Final-output
+   * kinds: empty while live, the terminal {@link TaskOutcome.output} (or
+   * empty) once settled — idempotent, never consumed.
+   */
+  text: string
+  /** The task's state at read time. */
+  snapshot: TaskSnapshot
+}
+```
+
+## The service
+
+`TaskService` (`ctx.tasks` — [`packages/tasks/tasks/src/index.ts`](../../packages/tasks/tasks/src/index.ts)): `register` (atomic, fenced by `attachSurface`), non-consuming `get`/`list` (caller-scoped — owned-by-caller plus unowned only), `read` (consuming for stream kinds), `kill` (producer `cancel` first; a throw leaves the task untouched), `wait` (bounded, abort cancels the wait only), and `onTaskDone` (a `TaskDoneListener` per settlement, effect-scoped, contained). Every read/kill/wait/get compares the task's owner session with the caller's and rejects a foreign one. Owned tasks are cancelled and awaited when their owning agent disposes (the `ctx.agents.onCleanup` seam); the model-facing surface over all of this is [dsh-tool-tasks](../../packages/tasks/tool-tasks/README.md).
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index c10d7caa52..8aef863ee0 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -25,10 +25,10 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:39`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`invariants`](../packages/support/invariants), [`session-persistence`](../packages/session-persistence/session-persistence) |
 | `session/event` | `emit` | [`packages/core/session/src/index.ts:47`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`emit`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio-agent`](../packages/ui/stdio-agent) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:57`](../packages/core/session/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`parallel`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
-| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:98`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
-| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:72`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:83`](../packages/subagent/subagent/src/index.ts) | - | [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `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) |
+| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:99`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
+| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:73`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:84`](../packages/subagent/subagent/src/index.ts) | - | [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:92`](../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:97`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 5e043d22d4..e7f77dce7a 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -82,6 +82,10 @@ flowchart TD
   subgraph group_code_runtime["packages/code-runtime"]
     pkg_code_runtime["code-runtime"]
   end
+  subgraph group_tasks["packages/tasks"]
+    pkg_tasks["tasks"]
+    pkg_tool_tasks["tool-tasks"]
+  end
   pkg_llm --> pkg_brand
   pkg_bash --> pkg_brand
   pkg_llm_deepseek --> pkg_llm
@@ -124,6 +128,8 @@ flowchart TD
   pkg_invariants --> pkg_agent
   pkg_invariants --> pkg_llm
   pkg_invariants --> pkg_session
+  pkg_tasks --> pkg_agent
+  pkg_tasks --> pkg_brand
   pkg_agent_loop --> pkg_agent
   pkg_agent_loop --> pkg_llm
   pkg_agent_loop --> pkg_session
@@ -134,6 +140,7 @@ flowchart TD
   pkg_tool_bash --> pkg_bash
   pkg_tool_bash --> pkg_llm
   pkg_tool_bash --> pkg_system_prompt
+  pkg_tool_bash --> pkg_tasks
   pkg_tool_bash --> pkg_tools
   pkg_tool_fs --> pkg_fs
   pkg_tool_fs --> pkg_llm
@@ -160,13 +167,19 @@ flowchart TD
   pkg_acp --> pkg_session
   pkg_acp --> pkg_session_persistence
   pkg_acp --> pkg_tools
+  pkg_tool_tasks --> pkg_agent
+  pkg_tool_tasks --> pkg_system_prompt
+  pkg_tool_tasks --> pkg_tasks
+  pkg_tool_tasks --> pkg_tools
   pkg_agent_core --> pkg_agent
   pkg_agent_core --> pkg_agent_loop
   pkg_agent_core --> pkg_invariants
   pkg_agent_core --> pkg_llm
   pkg_agent_core --> pkg_session
   pkg_agent_core --> pkg_system_prompt
+  pkg_agent_core --> pkg_tasks
   pkg_agent_core --> pkg_tool_bash
+  pkg_agent_core --> pkg_tool_tasks
   pkg_agent_core --> pkg_tools
   pkg_subagent_acp --> pkg_agent
   pkg_subagent_acp --> pkg_llm
@@ -180,6 +193,7 @@ flowchart TD
   pkg_tool_subagent --> pkg_agent
   pkg_tool_subagent --> pkg_llm
   pkg_tool_subagent --> pkg_subagent
+  pkg_tool_subagent --> pkg_tasks
   pkg_tool_subagent --> pkg_tools
   pkg_hooks_claude --> pkg_agent
   pkg_hooks_claude --> pkg_hook_protocol
@@ -239,18 +253,20 @@ flowchart TD
 | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
 | [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
 | [`invariants`](../packages/support/invariants) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`tools`](../packages/core/tools) |
 | [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
 | [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) |
-| [`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) |
+| [`tool-tasks`](../packages/tasks/tool-tasks) | `tasks` | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`agent-core`](../packages/core/agent-core) | `core` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tool-bash`](../packages/bash/tool-bash), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools) |
 | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) |
 | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`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) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md
index 5f0da6a7ff..8b09679f36 100644
--- a/docs/rfc/INDEX.md
+++ b/docs/rfc/INDEX.md
@@ -13,7 +13,6 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Code Mode — the model writes TypeScript against the tool registry](proposed/feature/2026-06-15-code-mode.md) | 2026-06-15 |
 | [Pre-tool input rewrite — a consistent design](proposed/feature/2026-06-30-pre-tool-input-rewrite.md) | 2026-06-30 |
 | [Claude Code and Codex subagent backends (out-of-process delegation to external coding agents)](proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md) | 2026-07-07 |
-| [Background subagent tasks](proposed/feature/2026-07-08-background-subagent-tasks.md) | 2026-07-08 |
 | [Repeat-tool-call guard plugin](proposed/feature/2026-07-08-repeat-tool-guard.md) | 2026-07-08 |
 
 ### Simplification
@@ -28,7 +27,6 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | Title | First proposed |
 |---|---|
 | [Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern)](proposed/architecture/2026-06-16-typed-event-schemas.md) | 2026-06-16 |
-| [Extract a generic long-running tool runtime](proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md) | 2026-06-20 |
 
 ### Process
 
@@ -64,6 +62,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [SessionStore fork API](implemented/feature/2026-06-30-session-store-fork-api.md) | 2026-06-30 |
 | [Subagent lifecycle enrichment — lastAssistantMessage (observe-only)](implemented/feature/2026-06-30-subagent-observe-enrich.md) | 2026-06-30 |
 | [Explicit model-facing tool order](implemented/feature/2026-07-06-explicit-tool-order.md) | 2026-07-06 |
+| [Background subagent tasks](implemented/feature/2026-07-08-background-subagent-tasks.md) | 2026-07-08 |
 
 ### Simplification
 
@@ -111,6 +110,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Shared persistence write coordinator](implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md) | 2026-06-18 |
 | [Branded IDs everywhere they belong](implemented/architecture/2026-06-20-branded-ids.md) | 2026-06-20 |
 | [Extract example apps into packages](implemented/architecture/2026-06-20-extract-example-app-packages.md) | 2026-06-20 |
+| [The background task runtime (`ctx.tasks`) and the generic task control tools](implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) | 2026-06-20 |
 | [Reorganize packages into a modular hierarchy](implemented/architecture/2026-06-20-package-hierarchy.md) | 2026-06-20 |
 | [Mandatory `User-Agent` attribution for provider requests](implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md) | 2026-06-21 |
 | [Web capability seam - stable tools over multiple providers](implemented/architecture/2026-06-24-web-capability-seam.md) | 2026-06-24 |
diff --git a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
new file mode 100644
index 0000000000..a049df012f
--- /dev/null
+++ b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -0,0 +1,171 @@
+# RFC: The background task runtime (`ctx.tasks`) and the generic task control tools
+
+Status: implemented
+
+## Problem
+
+The bash capability seam supports both foreground commands and long-running background tasks. Background support was large: the abstract executor exposed `start`, `get`, `ownerOf`, `list`, `readOutput`, `kill`, and `onTaskDone`; the local executor tracked tasks, incremental reads, owner tokens, process cleanup, and completion listeners; the model saw three tools (`bash`, `bash_output`, `bash_kill`); the tool plugin injected completion notices back into the owning agent's session. The local executor fenced task access behind owner tokens because predictable global task ids are a cross-session read/kill hazard.
+
+The [tool cookbook](../../../cookbook/adding-a-tool.md) already pointed at the real design smell: background bash is really generic long-running-tool infrastructure living inside one tool. The pressure stopped being hypothetical with [background subagent tasks](../feature/2026-07-08-background-subagent-tasks.md), which needs the same task ids, owner isolation, polling, stop, completion notices, and prompt guidance, and whose first draft answered by cloning the protocol under new names (`subagent_wait`, `subagent_output`, `subagent_stop`) and reshaping `dsh-tool-subagent` into a multi-tool plugin solely so the cloned companion tools would not collide across instances. Every future long-running capability (dev servers, watchers, remote jobs) would clone it again, and the model would learn a new collect/stop habit per capability.
+
+The surveyed peer products converged on the opposite shape. Claude Code exposes one `TaskOutput`/`TaskStop` pair spanning seven task kinds (background shells, subagents, remote sessions, …), with its earlier per-capability `BashOutput`/`KillShell` names kept only as aliases; Kimi Code's `BackgroundManager` runs process, agent, and pending-question kinds behind the same two tools and a ~5-method producer interface; DeepSeek-Reasonix serves bash and delegation from one session-scoped jobs manager; OpenCode's `BackgroundJob` registry is kind-agnostic by construction. The lesson is that the task registry, the control tools, and the notification path are one capability, and the producers (bash, subagents) are plugins into it.
+
+## Decision
+
+The `tasks/` package group owns background-task semantics once, and bash and subagents are producers:
+
+- `@deepseek-ai/dsh-tasks` — the task registry service (`ctx.tasks`): branded task ids, owner-scoped authorization, status snapshots, incremental/final output reads, cancellation, wait-for-terminal, completion listeners, and the awaited owner-cleanup path.
+- `@deepseek-ai/dsh-tool-tasks` — the model-facing control surface: `task_output`, `task_list`, `task_kill`, the completion-notice injection into the owning session, and the system-prompt section that teaches the background-task habit.
+
+Producers register running work into `ctx.tasks` and stay owners of their execution concerns: `dsh-tool-bash`'s `run_in_background` path registers the process it started (incremental stdout, spill formatting, kill), and `dsh-tool-subagent`'s background mode ([the feature RFC](../feature/2026-07-08-background-subagent-tasks.md)) registers the child run (final output only, cancel + dispose). The bash seam carries no registry: `bash_output`/`bash_kill` no longer exist (the generic tools replaced them), and the subagent companion tools were never created. The `dsh-agent-core` bundle loads the pair, so every shipped deployment has the control surface.
+
+The registry is a CONCRETE service, not an interface/implementation seam pair: there is exactly one sensible in-process implementation today, and the capability-seam convention says not to split preemptively. The pre-release stance lets a later durable/remote job system extract an interface when a second backend actually exists.
+
+## Task model
+
+`dsh-tasks` owns the vocabulary ([data-structure catalog](../../../core-data-structures/tasks.md)). `TaskId` is branded, generated by the registry as `<kind>-N` with a per-kind counter (`bash-1`, `subagent-1`) — the kind prefix keeps ids self-describing in transcripts and preserves the pre-runtime `bash-N` shape. Ids are runtime-global and predictable, so every access is authorized (below).
+
+A producer registers a task with:
+
+```ts ignore-check
+interface TaskRegistration {
+  /** Producer kind — also the id prefix ('bash', 'subagent', …). */
+  kind: string
+  /** One-line model-facing label (the command; the delegation description). */
+  label: string
+  /** The spawning agent; undefined = unowned (open access, dies with the service). */
+  owner?: Agent
+  /** Request termination; idempotent; must lead to `done` settling. The optional reason is `task_kill`'s logged reason, forwarded. */
+  cancel(reason?: string): void
+  /** Settles at QUIESCENCE — after the producer has released the task's resources. Never rejects. */
+  done: Promise<TaskOutcome>
+  /** OPTIONAL incremental read (stream kinds). Consecutive calls never re-deliver output; the producer owns truncation/spill formatting. Absence = final-output-only kind. */
+  readOutput?(): string
+}
+
+interface TaskOutcome {
+  status: 'completed' | 'killed' | 'failed'
+  /** Kind-specific detail rendered into the status line ('exit code: 3', 'max-tokens'). */
+  detail?: string
+  /** Final output for final-only kinds; read idempotently after the task settles. */
+  output?: string
+}
+```
+
+The task status vocabulary is generic and closed: `running`, `stopping` (cancel requested, not yet settled), and the three terminal values above. Kind-specific meaning rides in `detail`, so the registry never learns process or agent semantics — the method presence (`readOutput`) is the capability, mirroring `SubagentRun.sendMessage`.
+
+The registry attaches ONE continuation to `done`: record the terminal snapshot, then notify task-done listeners with per-listener containment (the guarantee the bash seam's `notifyTaskDone` used to give its own listener set). `done` settling at quiescence — not merely at completion — is what makes owner cleanup and service disposal awaitable without a second completion surface; this resolves the old seam's duplication of a per-task `done` promise AND a global `onTaskDone` registry by making the promise the producer contract and the listener registry the consumer surface.
+
+Registrations are NOT effect-scoped to the registering fiber: a task belongs to its owning agent and its producing backend, not to the tool plugin whose call started it, so an HMR reload of `dsh-tool-bash` or `dsh-tool-tasks` never orphans or kills a running task (the same argument that used to keep bash ownership in the executor). The registry's own disposal cancels every live task and awaits settlement — no orphans survive `fiber.dispose()`.
+
+## Authorization and the service surface
+
+Cross-session isolation lives IN the runtime so every consumer gets the same rule for free: read/kill/wait/get take the caller (`Agent | undefined`), and a task whose owner session differs from the caller's session is rejected (`!== undefined` comparison — an unowned task is open, a no-agent caller cannot match an owned task). `list(caller)` returns only the caller-visible tasks (owned-by-caller or unowned) — a global listing would leak other sessions' labels. Owner identity is `session.header.id`, the canonical id every other subsystem keys on; because both sides of the comparison come from live `Agent`s, the freestanding `OwnerToken` brand the bash seam used to carry became internal state rather than a seam type.
+
+```ts ignore-check
+class TaskService extends Service {           // ctx.tasks
+  register(reg: TaskRegistration): TaskId     // throws when no control surface is attached; ATOMIC — a throw mutates nothing
+  get(id: TaskId, caller?: Agent): TaskSnapshot            // non-consuming; throws: unknown id, foreign owner
+  list(caller?: Agent): TaskSnapshot[]                     // caller-visible only
+  read(id: TaskId, caller?: Agent): TaskRead               // delta (stream kinds, consuming) or final output (final kinds, idempotent) + snapshot
+  kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-terminal'
+  wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
+  onTaskDone(listener: (snapshot: TaskSnapshot) => void): () => void   // effect-scoped, contained, never fires after dispose
+  attachSurface(name: string): () => void     // the misconfiguration fence, below
+}
+```
+
+`TaskSnapshot` is the read-only projection: id, kind, label, owner session, status, detail, started/finished timestamps, and the `reported` notice-suppression flag (below). `wait` resolves with the terminal snapshot, or with the still-`running` snapshot on timeout; aborting the wait cancels only the wait.
+
+**Misconfiguration fails loud**: a deployment that loads a background-capable producer without any control surface would let the model start tasks it can never read or stop — the half-loaded failure mode the subagent RFC's first draft reshaped a whole plugin to avoid. The fence is `attachSurface()`: `dsh-tool-tasks` attaches (effect-scoped) on load, and `register()` throws `background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)` when none is attached — the earliest self-contained moment, since concurrent plugin start makes a load-time check racy. The registry stays ignorant of tool names; a deployment with a custom (non-model) surface attaches its own.
+
+## The model-facing control tools
+
+`dsh-tool-tasks` registers three kind-agnostic tools (ACP render intent: `generic` cards, `kind: 'execute'` for kill and `'read'` for output/list, no `locations`):
+
+- `task_output(task_id, wait?, timeout_ms?)` — non-blocking by default: stream kinds return output produced since the previous read, final kinds return only a status line while running and the final output once terminal; every response ends with the status line (`[status: running]`, `[status: completed, exit code: 0]`, `[status: failed, max-tokens]` — generic status + producer detail). `wait: true` blocks until the task settles or the timeout expires (config: defaulted `waitTimeoutMs`, capped `maxWaitTimeoutMs`); a timed-out wait returns `[status: running]` and leaves the task alive. Polling-by-default preserves the established bash habit; `wait` is what a parent uses when it is genuinely blocked on a subagent's answer.
+- `task_list()` — the caller's tasks, one line each: `<id> [<kind>] <status> — <label>`; `(no background tasks)` when empty. Most peers make listing a human-only surface (`/tasks` panels) and only Gemini CLI ships a model-facing list; DSH keeps it model-facing because the harness is an SDK with no guaranteed user UI — a deployment may have no `/tasks` equivalent — and a caller-scoped list is one cheap registry read.
+- `task_kill(task_id, reason?)` — requests cancellation and returns immediately (`requested cancellation of task <id>`); the optional `reason` lands in the logged tool args and is forwarded to the producer's `cancel` where the underlying seam accepts one (`SubagentRun.cancel(reason)`). Killing an already-terminal task reports its terminal status rather than failing; a producer `cancel` that throws fails the call loud and leaves the task untouched (still `running`, notice not suppressed).
+
+`task_output`'s read cursor is task-scoped and CONSUMING for stream kinds: the registry keeps one cursor per task, and a read returns everything produced since the previous read, exactly like the old `bash_output`. v1's intended reader is the owning model — the owner fence already makes it the only model-facing one — so a non-consuming observation surface (a UI tailing a task, multiple concurrent readers) is deliberately out of scope; when one is needed, it extends the registry with a cursor/snapshot read API rather than changing `task_output`, because two consumers sharing the consuming cursor would silently eat each other's output.
+
+One system-prompt section (order 106, next to `tool:bash`) teaches the cross-call habit the per-tool descriptions cannot: track every returned task id; you are notified in-session when a task finishes, so do not busy-poll or sleep on one — keep working on independent steps and do not duplicate a running task's work; do not produce a final answer while a relevant task still runs — call `task_output` (with `wait` when blocked) to collect it first; `task_kill` tasks that stopped mattering. The do-not-poll and do-not-duplicate sentences are near-verbatim convergent across Claude Code, Kimi Code, and OpenCode — they are the two failure modes every peer engineered against.
+
+Completion notices stay durable context, not a wake-up (`agent.inject()` appends a logged `context/message` the next model request sees; it does not run the model): on `onTaskDone`, `dsh-tool-tasks` injects `background task <id> (<kind>: <label>) finished [status: …]. Read its output with task_output.` into the owning agent's session, with the same disposed-race containment `dsh-tool-bash` used to carry. Notices are deduplicated the way Claude Code and Kimi Code both learned to: a task the model explicitly killed, or whose terminal state a read/wait already returned (including a wait pending at the moment of settlement), is marked `reported` and its notice suppressed — never a redundant "finished" for work the model just collected or ended. The model-visible ⟺ logged invariant holds with no new session event type.
+
+## Producer opt-in and schema exposure
+
+Whether a producer tool offers `run_in_background` is that producer's own defaulted config: `enableRunInBackground?: boolean` on `dsh-tool-bash` and on each `dsh-tool-subagent` instance (both default `true` — bash keeps its always-exposed behavior, and a deployment disables either per instance from cordis.yml, no code edit). A disabled producer omits the parameter from its schema entirely, so schema and capability can never disagree. `ctx.tasks` plays no part in schema shaping — it never rewrites or decorates a producer's tool schema (Kimi Code regex-rewrites its bash description when background is disabled; config-owns-the-schema makes that trick unnecessary) — it only provides runtime registration. The two halves compose fail-loud: the producer's config decides what the model sees, and a background call that still reaches `register()` without a control surface throws the load-this-package error. `register()` is atomic (a throw mutates no registry state), and a producer whose registration fails cancels and awaits its just-started work before rethrowing — background work never runs without a collectable id.
+
+## The awaited owner-cleanup seam
+
+A background task must not outlive its owner: the subagent case leaks live child agents/sessions otherwise, and `agent/disposed` is emitted synchronously inside the disposal chain without awaiting listener work, so an emit listener cannot promise quiescence (the analysis in [the feature RFC](../feature/2026-07-08-background-subagent-tasks.md)). The runtime therefore needs a seam the owning agent's disposal chain actually awaits, and that seam belongs to `dsh-agent`, where every lifecycle consumer can reach it:
+
+- `AgentRegistry.onCleanup(agentId, cleanup: () => Promise<void>): () => void` — a per-agent cleanup registry (registrations are effects; the disposer unregisters).
+- The loop's composite disposal chain carries one link for it: after stop-and-drain and before unregister, `await ctx.agents.drainCleanups(agent.id)` runs every registered cleanup with per-cleanup containment (a throwing cleanup is logged and never starves later cleanups or the rest of the chain). This is a documented `dsh-agent-loop` change; running cleanups is part of the `AgentFactory` dispose contract so a replacement loop honors it too.
+
+`dsh-tasks` consumes the seam: the first task registered for an owner attaches one cleanup that cancels the owner's still-live tasks, awaits each task's `done` (quiescence), and drops the owner's snapshots. `AgentHandle.dispose()` thus resolves only after the owner's background children are actually gone, and the guarantee composes transitively: a background subagent that started background tasks of its own drains them when its child agent disposes inside the parent task's settlement path (the cascade OpenCode implements with explicit parent-chain walking falls out of the seam here). This is a deliberate behavior change for bash — a background bash task used to outlive its owning agent until service disposal — adopted for uniformity: an ownerless task is the sanctioned way to outlive an agent, and a future durable-job RFC is the way to outlive the runtime.
+
+## Bash migration
+
+`dsh-bash` keeps the execution contract and carries no registry. The seam is `resolve`, `run`, and `start`, where `start(spec)` returns a process handle — `BashProcess`: `{ command, status, exitCode, signal, done, readOutput(), kill() }` — instead of a registry entry: `get`/`ownerOf`/`list`/`onTaskDone`, the listener machinery, `BashTaskId`, `OwnerToken`, and the spec's `owner` field are gone (a consumer census found `get`/`list` reached only by test harnesses and `onTaskDone` single-consumer — `dsh-tool-bash`; the hook bridges consume `resolve`+`run` only). The local executor keeps an internal table of LIVE processes solely for its own disposal quiescence (entries leave on settlement). The foreground trusted-plugin path (`resolve` + `run` with `stdin`/`env`, used by the hook bridges) is untouched and never routes through the runtime; `BashExecSpec.timeoutMs` stays required-but-ignored by `start()` (shared-spec status quo, documented in the seam JSDoc); the credential-scrub duplication between the bash and ACP spawn sites is explicitly NOT this runtime's work — the registry never touches process spawning.
+
+`dsh-tool-bash` keeps the `bash` tool; the `run_in_background` path is `ctx.bash.start(...)` + `ctx.tasks.register({ kind: 'bash', label: command, owner: exec.agent, cancel, done, readOutput })`, where `done` maps the process exit to a `TaskOutcome` (`processOutcome`: `completed`/`killed` + exit-code/signal detail) and `readOutput` wraps the handle's incremental read with the spill/lossy formatting (`renderProcessRead`). The completion-notice listener left `dsh-tool-bash` entirely.
+
+## Subagent integration
+
+[Background subagent tasks](../feature/2026-07-08-background-subagent-tasks.md) rides this runtime; the headline consequence is that `dsh-tool-subagent` KEEPS its one-instance-per-provider shape — the multi-tool reshape existed only to keep cloned companion tools from colliding, and there are no companion tools to clone. Its background call starts the provider run, then registers `{ kind: 'subagent', label: description, owner: parent, cancel: run.cancel, done }` where `done` awaits `run.result`, awaits `run.dispose()` (quiescence), and maps the stop reason (`completed` → `completed`; `aborted` → `killed`; `error`/`max-tokens`/`refusal`/unknown → `failed` with the reason as detail) and the final text as `output`. No `readOutput` — the child session remains the detailed trace, exactly as that RFC argues.
+
+## Alternatives considered
+
+### Why not per-capability companion tools (`bash_output`/`bash_kill` + `subagent_wait`/`subagent_output`/`subagent_stop`)?
+
+That is the trajectory this RFC interrupted. Each capability re-implements ids, ownership, polling, stop, notices, and guidance; the model learns N collect/stop habits and the prompt carries N near-identical tool descriptions; `dsh-tool-subagent` needed a structural reshape purely to de-duplicate its clones. Claude Code walked this exact path — per-capability `BashOutput`/`KillShell` first, then a generalized `TaskOutput`/`TaskStop` spanning shells, agents, and remote sessions with the old names kept as deprecated aliases — and the pre-release stance let this repo land directly on the unified shape with no alias burden.
+
+### Why not an abstract `TaskRuntime` seam with swappable backends?
+
+There is one in-process implementation and no concrete second backend; the capability-seam rule is to split when the consumer and backend can actually evolve independently, not before. A durable/persistent job system is the plausible second backend, and it changes the lifecycle contract (survival across owner disposal) enough that its RFC should own the interface extraction.
+
+### Why not keep authorization in the consumers, as bash did?
+
+The bash split put policy in `dsh-tool-bash` so the executor seam stayed session-free — right for a seam that may be implemented remotely. The registry is harness-local infrastructure whose entire purpose includes the isolation fence; leaving the fence to each consumer means every future surface (model tools, a UI bridge, hook bridges) re-implements it or forgets it. Centralizing it is most of the reason the runtime exists.
+
+### Why not a `parallel`-mode `agent/cleanup` event instead of the keyed registry?
+
+An event fires for every agent at every disposal and every listener must filter; `Promise.all` rejection semantics need extra containment; and there is no disposer to make registrations effects. A keyed registry is targeted, contained, and disposable — and the loop already drains an ordered chain, so one more awaited link was the smaller change.
+
+### Why not blocking-by-default `task_output` (Claude Code's `block: true`)?
+
+The established bash habit is poll-between-work, and the guidance tells the model to keep doing independent work while tasks run; defaulting to block would silently serialize the parent on its slowest child. The explicit `wait: true` keeps blocking a deliberate act, and the wait/read/kill trio still lands within the three-tool surface.
+
+### Why not a separate `task_wait` tool?
+
+Waiting is never useful without reading the result afterwards; a separate tool doubles the calls and the schema surface for zero information. Folding it into `task_output` matches the only real usage pattern.
+
+### Why not a push-sink producer contract (`appendOutput`/`settle`), as Kimi Code's manager uses?
+
+A sink centralizes output buffering, truncation, and spill in the runtime, which is elegant when the runtime owns output storage. In this codebase those concerns already live — bounded, tested, spill-file-aware — inside `dsh-bash-local`, and keeping process concerns in the executor is the point of the bash seam. The pull contract (`readOutput()` returning a formatted delta) reuses that machinery as-is; a sink would relocate it for no v1 gain. If a durable backend later makes the runtime own output storage, the producer contract is the one seam to revisit.
+
+### Why not random task ids (Claude Code's per-kind `36^8` suffixes)?
+
+Peers with shared registries use unguessable ids as defense-in-depth against cross-session access and predictable-path attacks. Here the owner fence is the boundary — exactly as `dsh-tool-bash` documented for the old predictable `bash-N` — and the registry hands no filesystem paths derived from the id, so sequential per-kind counters keep transcripts readable and tests deterministic. Nothing prevents switching the generator later; the id is branded and opaque to consumers.
+
+### Why not foreground→background promotion?
+
+Claude Code, Kimi Code, and OpenCode all let a running foreground call be promoted to a background task (user action or an over-budget auto-detach). It is deliberately out of v1: promotion needs a UI/user channel the SDK does not prescribe, and it changes the foreground tools' result contracts. The registration-based design leaves the door open — a foreground execution is promotable by registering its already-running work mid-flight — and a follow-up RFC can add it without touching the model-facing control tools.
+
+### Why not new session events for task lifecycle?
+
+Everything model-visible already lands in the log: starts and reads are tool calls/results, notices are injected `context/message` events. A `task/*` session event would duplicate facts the log carries, and live registry state (`task_list`) is intentionally runtime state, exactly as bash's task table was.
+
+## Testing
+
+Unit coverage pins the registry lifecycle (register/read/kill/wait/list, owner isolation including no-agent callers, stream-vs-final read semantics, listener containment, notice suppression after an explicit kill or terminal read/wait, the `attachSurface` fence, register atomicity — a failed registration mutates nothing and burns no counter; a failed producer `cancel` leaves the task untouched — disposal quiescence, per-kind id counters), the `onCleanup` drain ordering + containment (including mid-drain registration), both producers' registration mapping plus their no-orphan guarantee (a failed `register()` kills/cancels and awaits the just-started work before rethrowing), and unchanged foreground bash/subagent behavior. Snapshot coverage pins the task tool schemas and the prompt section through the pinned-header fixture.
+
+## Consequences
+
+One background-task contract exists instead of a per-capability clone family: a background subagent and a background bash command coexist in one session under one id namespace, one listing, one notice format, and one guidance section, and the [tool cookbook](../../../cookbook/adding-a-tool.md) points long-running tools at `ctx.tasks`. The cost was a wide landing change — the bash seam lost its registry surface and every test tier moved with it, model-facing tool names churned (`bash_output`/`bash_kill` deleted), and the ACP snapshot pinned header was refreshed for the new schemas — sanctioned by the pre-release stance.
+
+Owner-scoped cleanup changed bash semantics: a task that previously outlived its agent now dies with it. Deployments that relied on fire-and-forget background commands start them unowned (a non-agent caller) or accept the new lifecycle; the uniformity was judged worth the change, and the durable-job direction remains open for real survival requirements.
+
+`wait` is the first blocking tool call whose duration is model-controlled; the config cap bounds it, but a model that serializes on `wait` loses the parallelism the feature exists for — prompt guidance mitigates, and a future continuation-policy guard can enforce. Recording live background-flow snapshot scenarios (a polled and killed background command, a completion-notice turn) and a with-key e2e background lifecycle require a `DEEPSEEK_API_KEY` re-record and remain named follow-up work. The runtime deliberately defers durable/cross-restart tasks, non-consuming observation cursors, and foreground→background promotion (see Alternatives).
diff --git a/docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md b/docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md
new file mode 100644
index 0000000000..0c9c7f884e
--- /dev/null
+++ b/docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md
@@ -0,0 +1,62 @@
+# RFC: Background subagent tasks
+
+Status: implemented
+
+## Problem
+
+The subagent seam ([the seam RFC](2026-06-21-subagent-capability-seam.md)) exposes `start() -> SubagentRun`, and the model-facing `dsh-tool-subagent` consumer collected that run synchronously only: the parent turn blocked until the child returned one final result. That shape is simple and transport-neutral, but it makes slow delegation expensive for the parent. A model that wants two independent investigations must either run them serially or hold the parent step open for the entire child duration.
+
+The harness already had one background-task precedent in bash: task ids, owner checks, output polling, stop, completion notifications, and prompt guidance. Subagents need the same user-facing habit, but not by copying bash's process-output semantics: a subagent does not expose an incremental stdout stream, and its child session remains the home for internal steps. The parent needs to start a child, keep working, later wait for or read the final answer, and stop the task when it is no longer relevant. An earlier draft of this RFC answered by cloning the bash protocol under subagent names (`subagent_wait`, `subagent_output`, `subagent_stop`) and reshaping `dsh-tool-subagent` into a multi-tool plugin so the clones would not collide across instances; [the background task runtime RFC](../architecture/2026-06-20-generic-long-running-tool-runtime.md) dissolved that duplication by extracting the registry and the control tools once, and this feature rides it.
+
+The design also has two lifecycle constraints that the synchronous path does not face. First, a background subagent can outlive the tool call that started it, so the tool-call abort signal must not stay wired to the child after the id is returned. Second, a completion notice can only be injected into a live owner agent: once an ACP session closes or an agent handle is disposed, `agent.inject()` cannot append to that session. The feature must therefore define whether background subagents survive owner disposal.
+
+## Decision
+
+Each `dsh-tool-subagent` instance may expose `run_in_background?: boolean`, gated per instance by its defaulted `enableRunInBackground` config flag (default `true`; a disabled instance omits the parameter from its schema — the producer-opt-in shape [the runtime RFC](../architecture/2026-06-20-generic-long-running-tool-runtime.md) pins: the producer's config owns the schema, `ctx.tasks` only provides runtime registration). The plugin keeps its one-instance-per-provider shape — provider selection stays deployment config (`subagent` on `spawn`, `subagent_fork` on `fork`, …), and there are no subagent-specific companion tools to collide: collection, listing, and cancellation are the generic `task_output`/`task_list`/`task_kill` tools from `@deepseek-ai/dsh-tool-tasks`.
+
+A foreground call keeps the synchronous semantics: it waits for `run.result`, returns final text on `completed`, maps non-clean terminal stop reasons to an errored tool result, and disposes the run in `finally`.
+
+A background call validates that a parent agent exists, checks an already-aborted tool signal before starting, starts the provider run through `ctx.subagents`, registers the run with `ctx.tasks`, and returns `started background subagent task <task_id>`. After the id is returned the tool-call signal is NOT connected to `run.cancel()` — the parent step may finish while the child continues; cancellation belongs to `task_kill` and the owner-cleanup path. A registration that throws (the no-control-surface fence) does not orphan the child: the producer cancels the run, awaits its `done` (which settles only after `run.dispose()`), and rethrows — the model never learns an id for work that is not actually tracked. `ctx.tasks.register()` supplies the runtime guarantees this feature needs and this RFC does not implement: kind-prefixed branded task ids, owner-scoped access (the parent agent is the owner; another session's agent cannot read or kill the task), the loud no-control-surface failure, completion-notice injection, and the generic prompt guidance.
+
+The registration maps the seam vocabulary onto the runtime's:
+
+- `kind: 'subagent'`, `label`: the model's `description` argument, `owner`: the parent agent.
+- `cancel`: `run.cancel(reason)` — the runtime forwards `task_kill`'s optional logged `reason`; the task shows as `stopping` until settlement.
+- `done` (`settleRun`): awaits `run.result`, then awaits `run.dispose()` (child quiescence — `done` must not settle before the child agent/session is released), then maps the stop reason (`runOutcome`): `completed` → `completed` with the final text as `output`; `aborted` → `killed`; `error`, `max-tokens`, `refusal`, and unknown merge-extensible reasons → `failed` with the reason as `detail`. A rejected `run.result` (infrastructure fault) still disposes and settles `failed`.
+- No `readOutput`: a subagent task is final-output-only. While it runs, `task_output` returns only the status line; once terminal it returns the final text (or failure detail) idempotently. The child session remains the detailed trace; v1 deliberately exposes no incremental transcript cursor.
+
+## Lifecycle
+
+The background task is scoped to the owner session, not durable across session closure. The runtime's awaited owner-cleanup path (the `AgentRegistry.onCleanup` seam, owned by [the runtime RFC](../architecture/2026-06-20-generic-long-running-tool-runtime.md)) cancels the owner's running tasks on agent disposal and awaits each task's `done` before `AgentHandle.dispose()` resolves; because this registration's `done` settles only after `run.dispose()`, owner disposal reaches child quiescence without leaking child agents or sessions. `agent/disposed` alone is not the mechanism — the registry emits it synchronously without awaiting listener work, which is exactly why the awaited seam exists. Completion notices are best-effort by the runtime's rule: a live owner gets the injected notice; a disposed owner drops it without throwing.
+
+## Model guidance
+
+The background-task habit (track ids, do not finish while a relevant task runs, collect with `task_output`, kill what stopped mattering) is the generic `dsh-tool-tasks` prompt section — one habit for bash and subagents alike, which is the point of the shared runtime. `dsh-tool-subagent` adds only the wording on its own tool: the description and the `run_in_background` parameter say the call returns a task id immediately and the final answer is collected with `task_output` (with `wait: true` when genuinely blocked on it). Runtime enforcement remains owner authorization and the awaited owner-cleanup path, not the prompt.
+
+## Alternatives considered
+
+### Why not subagent-specific `subagent_wait`/`subagent_output`/`subagent_stop` tools?
+
+The earlier draft of this RFC. The clones duplicate the bash protocol, teach the model a second collect/stop habit, and force a structural reshape of `dsh-tool-subagent` (one multi-tool instance instead of one instance per provider) purely so the companion tools register once. The generic runtime provides the same operations kind-agnostically, keeps this plugin's shape untouched, and its `attachSurface` fence covers the half-loaded deployment failure the reshape was defending against. The reshape was dropped with the clones.
+
+### Why not let background subagents survive owner session closure?
+
+Survival after owner closure requires durable task state, child-session recovery, a way to surface late results into a reopened session, and policy for tasks whose owning client never returns. The agent runtime unregisters disposed agents, and `agent.inject()` intentionally rejects disposed targets. Scoping tasks to the owner and cleaning up through the awaited path makes the v1 lifecycle explicit and avoids orphaned child agents; a durable job system is the runtime RFC's named future direction, not this feature.
+
+### Why not skip owner checks because ACP sessions are isolated?
+
+ACP sessions isolate their logs and agents, but services such as `ctx.agents`, `ctx.tools`, and `ctx.tasks` are shared within the runtime, and task ids are global, predictable resource handles. The runtime enforces the owner fence for every task kind; this RFC merely notes that subagent tasks inherit it.
+
+### Why not expose incremental subagent transcript output?
+
+The child session is already the trace for internal reasoning, tool calls, and intermediate messages. Streaming that transcript into the parent would blur the parent/child log boundary that makes in-process and ACP providers equivalent. The first background surface returns status and final output only; richer observation belongs to UI/session tooling or a separate observation RFC.
+
+## Testing
+
+Unit coverage pins the stop-reason → outcome mapping (`runOutcome`, including unknown merge-extensible reasons), `settleRun`'s dispose-before-report on both result paths, the detached-signal contract (a pre-aborted signal refuses to start; a returned id is never wired to the tool signal), background settlement collected through the real `task_output`/`task_kill` tools, the no-orphan rollback when `register()` throws, per-instance schema gating (`enableRunInBackground: false` omits the parameter and the background wording), and the loud failure when the tasks runtime is absent. Snapshot coverage pins the changed `subagent`/`subagent_fork` schemas through the pinned-header fixture; recording a live background-delegation transcript requires a `DEEPSEEK_API_KEY` re-record and remains named follow-up work.
+
+## Consequences
+
+Slow delegation no longer holds the parent step open: the model fans out background children, keeps working, and collects with the same three control tools it already uses for bash — no new habit, no schema clones, and `dsh-tool-subagent`'s per-provider shape survived unchanged. The feature's usability depends on the tasks pair being loaded; the runtime's `register()` fence turns a missing control surface into a loud, actionable error rather than a silent dead end, and the `dsh-agent-core` bundle ships the pair so every stock deployment has it.
+
+The prompt guidance reduces abandoned tasks but cannot force a model to collect every background result. Runtime cleanup through the awaited owner-disposal path is the hard stop; a future planner or guard could enforce "no final answer with relevant running tasks" more strongly if the prompt proves insufficient. A background child outliving its starting tool call means a misbehaving child consumes tokens until collected, killed, or owner-disposed; `task_list` keeps it visible, and setting `enableRunInBackground: false` per instance keeps a deployment's delegation strictly synchronous.
diff --git a/docs/rfc/proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md b/docs/rfc/proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md
deleted file mode 100644
index f4ebe921b5..0000000000
--- a/docs/rfc/proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# RFC: Extract a generic long-running tool runtime
-
-Status: proposed
-
-## Problem
-
-The bash capability seam supports both foreground commands and long-running background tasks. Background support is large: the abstract executor exposes `start`, `get`, `ownerOf`, `list`, `readOutput`, `kill`, and `onTaskDone`; the local executor tracks tasks, incremental reads, owner tokens, process cleanup, and completion listeners; the model sees three tools (`bash`, `bash_output`, `bash_kill`); the tool plugin injects completion notices back into the owning agent's session. The local executor fences task access behind owner tokens because predictable global task ids are a cross-session read/kill hazard.
-
-The [tool cookbook](../../../cookbook/adding-a-tool.md) already points at the real design smell: background bash is really generic long-running-tool infrastructure living inside one tool. If future tools need background execution, polling, kill, ownership, and completion notices, those semantics should not be hidden in `dsh-bash`.
-
-## Proposal
-
-Move long-running task semantics above bash into a tool-agnostic runtime. Bash remains able to run background commands, but it stops owning the general concepts of task ids, ownership tokens, polling, cancellation, completion notifications, and model-facing "read/kill this task" commands.
-
-The runtime should own:
-
-- Stable task ids and owner tokens keyed to the calling session/agent.
-- Registration of a long-running task with a producer for incremental output and a completion promise.
-- Generic read/cancel/list operations with the same cross-session authorization rule for every tool.
-- Completion notification injection into the owning session.
-- Presentation hooks for pending/running/completed task state, with bash supplying only command-specific labels and output formatting.
-
-`dsh-bash` then keeps the bash-specific execution contract: resolve a request into a command spec, run a foreground command, or start a process and hand its streams/process handle to the generic runtime. `dsh-tool-bash` keeps the model-facing command tool, but the follow-up operations become generic long-running-tool operations or a shared utility that bash registers with, rather than bespoke `bash_output`/`bash_kill` plumbing.
-
-## Current seam consumption
-
-A consumer census of the surface the runtime would carve up. Production has two seam consumers: `packages/bash/tool-bash/src/index.ts` consumes `resolve`, `run`, `start`, `ownerOf`, `readOutput`, `kill`, and `onTaskDone`; and the hook bridges — via `dsh-hook-protocol`'s `runHook` (`packages/hooks/hook-protocol/src/runner.ts`) — consume `resolve` + `run` only, a foreground-only trusted-plugin caller that sets the seam's `stdin`/`env` fields, so the background machinery stays single-consumer (which sharpens the extraction premise). `get()`/`list()` have test-harness consumers only — they were removed once and reverted on the merits (the implementation note in [prune dead methods from the persistence seam](../../implemented/simplification/2026-06-20-prune-dead-seam-methods.md) records the test-migration cost dwarfing the surface removed). The per-task `BashTask.done` promise has no consumer through the public seam either (`dsh-tool-bash` completes via `onTaskDone`), but it is production-load-bearing INSIDE the implementation: `dsh-bash-local`'s disposal awaits it to reach quiescence. The seam therefore exposes two public completion representations — the per-task promise and the global `onTaskDone` listener registry — and the shipped consumers use only the latter: the runtime should pick exactly one public completion surface and record which. Two shape facts for the split to dissolve or preserve deliberately: `BashExecSpec.timeoutMs` is required but ignored by `start()` (documented in the seam JSDoc itself), and `stdin`/`env` ride the shared spec for the foreground trusted-plugin path — the carve-up must keep a plain in-process foreground `resolve`+`run` path carrying them, so hook execution is never forced through the long-running runtime. Adjacent blast radius: the credential scrub is duplicated between the two production spawn sites (`packages/bash/bash-local/src/run.ts` and `packages/subagent/subagent-acp/src/run.ts`); if the runtime absorbs spawn-env policy, collapsing that duplication is its work too.
-
-## Acceptance criteria
-
-- The bash-specific packages no longer define the generic task registry, owner-token authorization, polling, cancellation, or completion-notification machinery.
-- A shared long-running-task service or tool layer owns those semantics and is documented as the path for any future background-capable tool.
-- Bash background behavior remains available through the shared layer, with tests proving cross-session isolation still holds.
-- ACP and snapshot fixtures render background bash through the shared task vocabulary, not through bash-only lifecycle semantics.
-- The [tool cookbook](../../../cookbook/adding-a-tool.md) points long-running tools at the shared runtime instead of telling each tool to invent its own task protocol.
-
-## Risks
-
-The bash package loses local ownership of an already-working background-task implementation, and the implementing PR may temporarily churn model-facing tool names or transcript presentation. That churn is worthwhile if it leaves one background-task contract instead of making every future long-running tool clone bash's private protocol.
-
-<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
diff --git a/docs/rfc/proposed/feature/2026-07-08-background-subagent-tasks.md b/docs/rfc/proposed/feature/2026-07-08-background-subagent-tasks.md
deleted file mode 100644
index 97e8ce1ddb..0000000000
--- a/docs/rfc/proposed/feature/2026-07-08-background-subagent-tasks.md
+++ /dev/null
@@ -1,98 +0,0 @@
-# RFC: Background subagent tasks
-
-Status: proposed
-
-## Problem
-
-The subagent seam ([the seam RFC](../../implemented/feature/2026-06-21-subagent-capability-seam.md)) exposes `start() -> SubagentRun`, and the model-facing `dsh-tool-subagent` consumer collects that run synchronously: the parent turn blocks until the child returns one final result. That shape is simple and transport-neutral, but it makes slow delegation expensive for the parent. A model that wants two independent investigations must either run them serially or hold the parent step open for the entire child duration.
-
-The harness already has one background-task precedent in bash. Bash has task ids, owner-token checks, output polling, stop, completion notifications, and prompt guidance. Subagents need the same user-facing habit, but not by copying bash's process-output semantics: a subagent does not expose an incremental stdout stream, and its child session remains the home for internal steps. The parent needs to start a child, keep working, later wait for or read the final answer, and stop the task when it is no longer relevant.
-
-The design also has two lifecycle constraints that the synchronous cut does not face. First, a background subagent can outlive the tool call that started it, so the tool-call abort signal must not stay wired to the child after the id is returned. Second, a completion notice can only be injected into a live owner agent: once an ACP session closes or an agent handle is disposed, `agent.inject()` cannot append to that session. The feature must therefore define whether background subagents survive owner disposal.
-
-## Proposal
-
-Add a background mode to the existing model-facing subagent tools and add three companion tools: `subagent_wait`, `subagent_output`, and `subagent_stop`. The background task registry lives in `@deepseek-ai/dsh-subagent`, keyed by branded task ids and owner tokens, while `@deepseek-ai/dsh-tool-subagent` owns the model-facing schemas, text rendering, completion notice injection, and prompt guidance.
-
-`dsh-tool-subagent` becomes a single multi-tool consumer plugin instead of one plugin instance per provider. Its config maps model-facing tool names to provider names, so one plugin instance can register `subagent`, `subagent_fork`, and any deployment-specific aliases such as `subagent_acp`, plus the shared background control tools. Providers remain named implementations on `ctx.subagents`: `spawn`, `fork`, `acp`, or future backends. This keeps provider implementation and model-facing exposure separate while avoiding a failure mode where one `subagent` tool exposes `run_in_background` but the companion wait/output/stop tools were never loaded.
-
-The background task is scoped to the owner session, not durable across session closure. A background subagent starts only from a model-driven call with `exec.agent`; the service stores the caller's `session.header.id` as the owner token. `subagent_output`, `subagent_wait`, and `subagent_stop` compare that stored token with the caller's session id and reject cross-session access. When the owner agent is disposed, an awaited owner-cleanup path cancels any running background subagent tasks for that owner and waits for their settlement/dispose before the owner handle reports quiescence. Completion notices are best-effort: if the owner agent is still registered, `dsh-tool-subagent` injects a short `context/message`; if the owner is gone, no notice is written.
-
-## Tool surface
-
-Each configured delegation tool may expose `run_in_background?: boolean`. The deployment can disable background mode per tool; a disabled tool does not include the parameter in its schema. A foreground call keeps the synchronous semantics: it waits for `run.result`, returns final text on `completed`, maps non-clean terminal stop reasons to an errored tool result, and disposes the run in `finally`.
-
-A background call validates that a parent agent exists, starts the provider run through `ctx.subagents`, registers a task, and returns `started background subagent task <task_id>`. It checks an already-aborted tool signal before starting, but after the id is returned it does not keep the tool-call signal connected to `run.cancel()`. The parent step may finish while the child continues.
-
-`subagent_output` is a non-blocking status read for a background subagent task. While the task is `running` or `stopping`, it returns only a status line. Once terminal, it returns the final text output or error message plus the terminal status. Reading output is idempotent and does not consume the result; v1 deliberately exposes no incremental transcript cursor because the child session remains the detailed trace.
-
-`subagent_wait` waits for a task to become terminal, bounded by a defaulted and capped timeout from `dsh-tool-subagent` config. A wait timeout returns `running` and leaves the child alive. Aborting the wait call cancels only the wait, not the background task.
-
-`subagent_stop` requests cancellation of a running or stopping task and returns immediately. The task registry remains responsible for observing the run settle, recording the terminal state, and disposing the run. Calling stop on an already-terminal task reports that terminal state rather than failing.
-
-## Runtime task model
-
-`@deepseek-ai/dsh-subagent` adds a runtime-global task registry to `SubagentService`. Task ids and owner tokens are branded types. A task snapshot records the task id, provider name, child run id, owner token, status, started/finished timestamps, final output, and error message. The status vocabulary is `running`, `stopping`, and the existing terminal `SubagentStopReason` values (`completed`, `aborted`, `error`, `max-tokens`, `refusal`, plus merge-extensible provider values).
-
-The registry owns task settlement. It attaches one continuation to `run.result`; on success it stores the final output and stop reason, on rejection it stores `error`, and in both cases it disposes the run and notifies task-done listeners. Listener failures are contained and logged so one consumer cannot starve cleanup.
-
-The registry is runtime-global because `ctx.subagents` is a service shared by all live agents in the Cordis context. Session isolation is therefore explicit owner-token authorization, not an assumption about separate service instances. This mirrors the bash background-task fence: predictable ids are safe only when read/stop operations check the caller's owner token.
-
-Owner disposal is a hard lifecycle boundary, but `agent/disposed` alone is not the cleanup mechanism. The current agent registry emits `agent/disposed` synchronously after removing the agent, and `AgentHandle.dispose()` does not await asynchronous listener work. This feature therefore also adds an awaited owner-cleanup seam: background task registration attaches an owner-scoped disposer that runs in the owning agent's disposal chain before that handle resolves. That disposer finds tasks owned by the agent's session id, requests cancellation, waits for each task's settlement path to record the terminal snapshot, and awaits `run.dispose()`. The existing `agent/disposed` event may still be used as a best-effort notification/fallback, but it must not be the path that promises child quiescence. The service does not attempt to persist unfinished task state, resume children, or inject into disposed sessions. A future durable job system can extend this boundary, but this feature intentionally keeps background subagents tied to live sessions.
-
-## Model guidance
-
-`dsh-tool-subagent` registers a system-prompt section that teaches the background-task habit:
-
-- Keep track of every task id returned by a background subagent call.
-- Do not produce a final answer while a relevant background subagent is still running.
-- While waiting, continue independent exploration or use other tools when useful.
-- Before summarizing or handing work back, call `subagent_wait` or `subagent_output` to collect finished tasks.
-- Call `subagent_stop` for a background task that is no longer needed.
-- End without collecting a task only when its result is irrelevant or the task was explicitly stopped.
-
-This prompt guidance is not the enforcement boundary. Runtime enforcement is owner-token authorization and the awaited owner-cleanup path. The guidance keeps ordinary model behavior from accidentally abandoning relevant work while still allowing explicit stop or irrelevance.
-
-## Relationship to generic long-running tools
-
-The generic long-running tool runtime RFC ([Extract a generic long-running tool runtime](../../proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md)) remains the larger direction for shared task ids, owner tokens, cancellation, completion notices, and presentation. Background subagents should not block on that extraction because subagents have a narrower result model than bash: no incremental stdout, no spill files, and no process exit markers. The implementation should keep the subagent registry small and shaped so it can later migrate into a generic runtime without changing the model-facing `run_in_background`, `subagent_wait`, `subagent_output`, and `subagent_stop` contract.
-
-## Alternatives considered
-
-### Why not keep one `dsh-tool-subagent` instance per provider?
-
-The existing one-instance-per-provider shape makes aliasing simple, but companion tools become ambiguous. If each instance registers `subagent_wait`, duplicate tool names collide. If only one instance registers them, deployments can accidentally expose `run_in_background` without the tools required to collect or stop the task. A single multi-tool consumer config keeps provider selection in deployment config and makes the background control plane atomic.
-
-### Why not put wait/output/stop in a separate plugin?
-
-A separate plugin has the same half-loaded failure mode: `subagent` could advertise background mode while the control tools are absent. The control tools are part of the model-facing subagent contract, so they should be registered by the same consumer plugin that adds `run_in_background`.
-
-### Why not let background subagents survive owner session closure?
-
-Survival after owner closure requires durable task state, child-session recovery, a way to surface late results into a reopened session, and policy for tasks whose owning client never returns. The current agent runtime unregisters disposed agents, and `agent.inject()` intentionally rejects disposed targets. Tying background tasks to an awaited owner-cleanup path makes the v1 lifecycle explicit and avoids orphaned child agents.
-
-### Why not skip owner-token checks because ACP sessions are isolated?
-
-ACP sessions isolate their logs and agents, but services such as `ctx.agents`, `ctx.tools`, and `ctx.subagents` are shared within the runtime. A background-task id is a global resource handle. Without an owner check, another live session in the same runtime could guess or receive a task id and read or stop it.
-
-### Why not expose incremental subagent transcript output?
-
-The child session is already the trace for internal reasoning, tool calls, and intermediate messages. Streaming that transcript into the parent would blur the parent/child log boundary that makes in-process and ACP providers equivalent. The first background surface returns status and final output only; richer observation belongs to UI/session tooling or a separate observation RFC.
-
-## Acceptance criteria
-
-- A deployment config can expose `subagent` and `subagent_fork` from one `dsh-tool-subagent` instance while binding them to different providers.
-- A configured delegation tool exposes `run_in_background` only when that tool enables background mode.
-- A background call returns a task id immediately and the parent can continue using other tools before collecting the result.
-- `subagent_output`, `subagent_wait`, and `subagent_stop` enforce owner-token access and reject cross-session task ids.
-- A task that finishes while the owner agent is live injects a durable completion notice into the owner session; a task whose owner is disposed does not throw while trying to notify.
-- Disposing the owner agent runs an awaited owner-cleanup path that cancels all of that owner's running background subagent tasks and reaches quiescence without leaking child agents; tests prove `agent/disposed` alone is not relied on for this guarantee.
-- Snapshot coverage proves the changed tool schemas and the completion-notice path; unit coverage pins foreground compatibility, background settlement, timeout, stop, owner isolation, and owner-disposal cleanup.
-
-## Risks
-
-The multi-tool config reshapes how deployments expose provider aliases, so examples and generated tool catalogs must move together with the implementation. The pre-release policy allows this churn, but the migration must update every shipped config in one change.
-
-The prompt guidance can reduce abandoned tasks but cannot force a model to collect every background result. Runtime cleanup through the awaited owner-disposal path is the hard stop; a future planner or guard could enforce "no final answer with relevant running tasks" more strongly if the prompt proves insufficient.
-
-The task registry duplicates some concepts named by the generic long-running-tool RFC. Keeping the subagent registry final-output-only and service-local limits that duplication, but a later generic runtime extraction will still need a careful migration.
diff --git a/docs/rfc/rejected/simplification/2026-06-20-drop-bash-output-spill-files.md b/docs/rfc/rejected/simplification/2026-06-20-drop-bash-output-spill-files.md
index 0a13d90f1b..859bd6f23d 100644
--- a/docs/rfc/rejected/simplification/2026-06-20-drop-bash-output-spill-files.md
+++ b/docs/rfc/rejected/simplification/2026-06-20-drop-bash-output-spill-files.md
@@ -12,7 +12,7 @@ This solves a real problem, but in a narrow and leaky way. A spill path is a pro
 
 Keep tail truncation, drop full-output spill files. A bash result contains the bounded tail plus a clear truncation marker; no path is emitted. If users need full-output recovery, add a generic artifact/blob service with explicit ownership, cleanup, and UI rendering, then let bash attach large outputs to that service.
 
-This proposal can land independently of [a generic long-running tool runtime](../../proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md). If background tasks stay, `bash_output` should still report that output was dropped, but without advertising a spill path.
+This proposal can land independently of [a generic long-running tool runtime](../../implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md). If background tasks stay, `bash_output` should still report that output was dropped, but without advertising a spill path.
 
 ## Acceptance criteria
 
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index a621d3299d..477df191db 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -15,9 +15,10 @@ This table connects model-visible tool names to the plugin package and service s
 
 | Tool package | Model-visible names | Requires | Writes / affects | Shipped aliases | Deployment note |
 | --- | --- | --- | --- | --- | --- |
-| `@deepseek-ai/dsh-tool-bash` | `bash`, `bash_kill`, `bash_output` | `ctx.tools`, `ctx.bash` | `tool/call`, `tool/result`, `context/message via agent.inject() for background completion notices` | - | The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam. |
+| `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`, `ctx.bash`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.tasks` runtime and is collected/stopped through the `task_*` tools from `@deepseek-ai/dsh-tool-tasks`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled. |
 | `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. |
 | `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. |
+| `@deepseek-ai/dsh-tool-tasks` | `task_kill`, `task_list`, `task_output` | `ctx.tools`, `ctx.tasks`, `ctx.systemPrompt` | `tool/call`, `tool/result`, `context/message via agent.inject() for background completion notices` | - | The kind-agnostic background-task control surface: a background bash command and a background subagent are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers' `ctx.tasks.register()`. |
 | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist or ACP plan. |
 | `@deepseek-ai/dsh-tool-web` | `web_fetch`, `web_search` | `ctx.tools`, `ctx.web`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | web_search and web_fetch keep provider selection behind ctx.web so model-visible schemas stay stable across backend swaps. |
 
@@ -25,7 +26,7 @@ This table connects model-visible tool names to the plugin package and service s
 
 ### `bash`
 
-Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.
+Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.
 
 ```json
 {
@@ -49,7 +50,7 @@ Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs
     },
     "run_in_background": {
       "type": "boolean",
-      "description": "Run in the background and return a task id immediately. No timeout applies."
+      "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."
     }
   },
   "required": [
@@ -61,49 +62,7 @@ Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs
 
 Source: [`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts)
 
-### `bash_kill`
-
-Ask the executor to kill a running background bash task by task id.
-
-```json
-{
-  "type": "object",
-  "properties": {
-    "task_id": {
-      "type": "string",
-      "description": "Task id returned by the bash tool."
-    }
-  },
-  "required": [
-    "task_id"
-  ]
-}
-```
-
-Source: [`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts)
-
-### `bash_output`
-
-Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.
-
-```json
-{
-  "type": "object",
-  "properties": {
-    "task_id": {
-      "type": "string",
-      "description": "Task id returned by the bash tool."
-    }
-  },
-  "required": [
-    "task_id"
-  ]
-}
-```
-
-Source: [`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/index.ts)
-
-The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam.
+The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.tasks` runtime and is collected/stopped through the `task_*` tools from `@deepseek-ai/dsh-tool-tasks`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled.
 
 ## `@deepseek-ai/dsh-tool-fs`
 
@@ -203,7 +162,7 @@ The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `
 
 ### `subagent`
 
-Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.
+Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.
 
 ```json
 {
@@ -216,6 +175,10 @@ Delegate a self-contained task to a subagent (a separate agent that works in its
     "prompt": {
       "type": "string",
       "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+    },
+    "run_in_background": {
+      "type": "boolean",
+      "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
     }
   },
   "required": [
@@ -229,6 +192,77 @@ Source: [`packages/subagent/tool-subagent/src/index.ts`](../packages/subagent/to
 
 The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`.
 
+## `@deepseek-ai/dsh-tool-tasks`
+
+### `task_kill`
+
+Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "description": "Task id returned by the tool that started the background work."
+    },
+    "reason": {
+      "type": "string",
+      "description": "Optional short reason, recorded in the log and forwarded to the task."
+    }
+  },
+  "required": [
+    "task_id"
+  ]
+}
+```
+
+Source: [`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
+
+### `task_list`
+
+List your background tasks (running and finished) with their ids, kinds, and statuses.
+
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+
+Source: [`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
+
+### `task_output`
+
+Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "description": "Task id returned by the tool that started the background work."
+    },
+    "wait": {
+      "type": "boolean",
+      "description": "Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."
+    },
+    "timeout_ms": {
+      "type": "number",
+      "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."
+    }
+  },
+  "required": [
+    "task_id"
+  ]
+}
+```
+
+Source: [`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
+
+The kind-agnostic background-task control surface: a background bash command and a background subagent are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers' `ctx.tasks.register()`.
+
 ## `@deepseek-ai/dsh-tool-todo`
 
 ### `todo_write`
diff --git a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl
index 2a71c46b18..efb5bd317a 100644
--- a/examples/acp-agent/tests/snapshots/text-turn/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/text-turn/session.jsonl
@@ -1,36 +1,36 @@
-{"type":"session","version":0,"id":"a407f6bc-310c-4c0e-ad8b-4ffdf1b544b1","createdAt":1783279329590,"cwd":"/tmp/acp-snap-cwd-q0sbE9"}
-{"type":"turn/start","seq":0,"time":1783279329596,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
-{"type":"user/message","seq":1,"time":1783279329596,"data":{"content":[{"type":"text","text":"Reply with exactly the word: PONG. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"}
-{"type":"step/start","seq":2,"time":1783279329598,"data":{"turn":1,"step":1}}
-{"type":"request/header","seq":3,"time":1783279329598,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /tmp/acp-snap-cwd-q0sbE9.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately. No timeout applies."}},"required":["command","description"]}},{"name":"bash_kill","description":"Ask the executor to kill a running background bash task by task id.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"bash_output","description":"Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the bash tool."}},"required":["task_id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."}},"required":["description","prompt"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
-{"type":"assistant/chunk","seq":4,"time":1783279330062,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
-{"type":"assistant/chunk","seq":5,"time":1783279330062,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
-{"type":"assistant/chunk","seq":6,"time":1783279330154,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
-{"type":"assistant/chunk","seq":7,"time":1783279330183,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}}
-{"type":"assistant/chunk","seq":8,"time":1783279330183,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
-{"type":"assistant/chunk","seq":9,"time":1783279330183,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
-{"type":"assistant/chunk","seq":10,"time":1783279330184,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}}
-{"type":"assistant/chunk","seq":11,"time":1783279330184,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
-{"type":"assistant/chunk","seq":12,"time":1783279330184,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}}
-{"type":"assistant/chunk","seq":13,"time":1783279330210,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
-{"type":"assistant/chunk","seq":14,"time":1783279330211,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" word"}}}
-{"type":"assistant/chunk","seq":15,"time":1783279330211,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
-{"type":"assistant/chunk","seq":16,"time":1783279330211,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"P"}}}
-{"type":"assistant/chunk","seq":17,"time":1783279330211,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONG"}}}
-{"type":"assistant/chunk","seq":18,"time":1783279330211,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
-{"type":"assistant/chunk","seq":19,"time":1783279330238,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
-{"type":"assistant/chunk","seq":20,"time":1783279330238,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" not"}}}
-{"type":"assistant/chunk","seq":21,"time":1783279330239,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" use"}}}
-{"type":"assistant/chunk","seq":22,"time":1783279330239,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" any"}}}
-{"type":"assistant/chunk","seq":23,"time":1783279330239,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}}
-{"type":"assistant/chunk","seq":24,"time":1783279330239,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
-{"type":"assistant/chunk","seq":25,"time":1783279330268,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":26,"time":1783279330268,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"P"}}}
-{"type":"assistant/chunk","seq":27,"time":1783279330268,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"ONG"}}}
-{"type":"assistant/chunk","seq":28,"time":1783279330269,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly the word \"PONG\" and not use any tools."}}}}
-{"type":"assistant/chunk","seq":29,"time":1783279330269,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"PONG"}}}}
-{"type":"assistant/chunk","seq":30,"time":1783279330269,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2095,"outputTokens":23,"cacheReadTokens":0,"reasoningTokens":20}}}}
-{"type":"assistant/chunk","seq":31,"time":1783279330269,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":32,"time":1783279330271,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to reply with exactly the word \"PONG\" and not use any tools."},{"type":"text","text":"PONG"}],"usage":{"inputTokens":2095,"outputTokens":23,"cacheReadTokens":0,"reasoningTokens":20}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31],"surfaceOp":"append"}
-{"type":"step/end","seq":33,"time":1783279330271,"data":{"turn":1,"step":1}}
-{"type":"turn/end","seq":34,"time":1783279330271,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"session","version":0,"id":"10267d34-6c0c-4e0c-8a2d-57644c57d0d5","createdAt":1783597843469,"cwd":"/var/folders/_g/59jgff8x2gqd39f5vy1wnbfc0000gn/T/acp-snap-cwd-YUSqHr"}
+{"type":"turn/start","seq":0,"time":1783597843471,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1783597843471,"data":{"content":[{"type":"text","text":"Reply with exactly the word: PONG. Do not use any tools."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1783597843472,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1783597843472,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are a coding assistant powered by the deepseek-v4-flash model. Your working\ndirectory is /var/folders/_g/59jgff8x2gqd39f5vy1wnbfc0000gn/T/acp-snap-cwd-YUSqHr.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1783597843472,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":5,"time":1783597843472,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}}
+{"type":"assistant/chunk","seq":6,"time":1783597843472,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}}
+{"type":"assistant/chunk","seq":7,"time":1783597843472,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" wants"}}}
+{"type":"assistant/chunk","seq":8,"time":1783597843472,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" me"}}}
+{"type":"assistant/chunk","seq":9,"time":1783597843472,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" to"}}}
+{"type":"assistant/chunk","seq":10,"time":1783597843472,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" reply"}}}
+{"type":"assistant/chunk","seq":11,"time":1783597843472,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" with"}}}
+{"type":"assistant/chunk","seq":12,"time":1783597843472,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" exactly"}}}
+{"type":"assistant/chunk","seq":13,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" the"}}}
+{"type":"assistant/chunk","seq":14,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" word"}}}
+{"type":"assistant/chunk","seq":15,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" \""}}}
+{"type":"assistant/chunk","seq":16,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"P"}}}
+{"type":"assistant/chunk","seq":17,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"ONG"}}}
+{"type":"assistant/chunk","seq":18,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"\""}}}
+{"type":"assistant/chunk","seq":19,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" and"}}}
+{"type":"assistant/chunk","seq":20,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" not"}}}
+{"type":"assistant/chunk","seq":21,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" use"}}}
+{"type":"assistant/chunk","seq":22,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" any"}}}
+{"type":"assistant/chunk","seq":23,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" tools"}}}
+{"type":"assistant/chunk","seq":24,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":25,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":26,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"P"}}}
+{"type":"assistant/chunk","seq":27,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":1,"text":"ONG"}}}
+{"type":"assistant/chunk","seq":28,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly the word \"PONG\" and not use any tools."}}}}
+{"type":"assistant/chunk","seq":29,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"PONG"}}}}
+{"type":"assistant/chunk","seq":30,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2095,"outputTokens":23,"cacheReadTokens":0,"reasoningTokens":20}}}}
+{"type":"assistant/chunk","seq":31,"time":1783597843473,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":32,"time":1783597843473,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to reply with exactly the word \"PONG\" and not use any tools."},{"type":"text","text":"PONG"}],"usage":{"inputTokens":2095,"outputTokens":23,"cacheReadTokens":0,"reasoningTokens":20}},"sourceEventSeqs":[4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31],"surfaceOp":"append"}
+{"type":"step/end","seq":33,"time":1783597843473,"data":{"turn":1,"step":1}}
+{"type":"turn/end","seq":34,"time":1783597843473,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/coding-agent/README.md b/examples/coding-agent/README.md
index 4b15d2dc5a..6b2467a608 100644
--- a/examples/coding-agent/README.md
+++ b/examples/coding-agent/README.md
@@ -11,7 +11,7 @@ The REPL agent demo wiring: DeepSeek V4 + the `read`/`write`/`edit` filesystem t
 pnpm run demo:repl
 ```
 
-Type a coding task. The agent works through the `read`/`write`/`edit` filesystem tools for ordinary file operations and `bash` (+ `bash_output` / `bash_kill` for background tasks) for shell commands, searches, and test runs, each in a fresh `bash -c` (the system prompt tells the model to pass `workdir` instead of `cd`). Both the fs tools and bash resolve relative paths against the session workspace. It can also delegate with `subagent`/`subagent_fork` and track multi-step work with `todo_write` (a whole-list task tracker rendered as a checklist). Reasoning streams dimmed; tool calls/results render inline.
+Type a coding task. The agent works through the `read`/`write`/`edit` filesystem tools for ordinary file operations and `bash` (+ the generic `task_output` / `task_list` / `task_kill` for background tasks) for shell commands, searches, and test runs, each in a fresh `bash -c` (the system prompt tells the model to pass `workdir` instead of `cd`). Both the fs tools and bash resolve relative paths against the session workspace. It can also delegate with `subagent`/`subagent_fork` and track multi-step work with `todo_write` (a whole-list task tracker rendered as a checklist). Reasoning streams dimmed; tool calls/results render inline.
 
 ```
 > fix the failing test in /path/to/project
@@ -39,7 +39,7 @@ This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads
 |---|---|
 | `hmr` (`@cordisjs/plugin-hmr`) | the dev/demo edit-reload loop — a **leaf** entry (not baked into the app) because it is Loader-only and needs `node --expose-internals`, which `demo:repl` passes |
 | `llm-deepseek` | real `LlmAdapter` via config (`!!js process.env.…` secrets); swap one line to `@deepseek-ai/dsh-llm-pi-ai` for the library-backed twin |
-| `bash` (`dsh-bash-local`) | the executor implementation — the swappable half of the bash seam. The model-facing `bash`/`bash_output`/`bash_kill` tool schemas (`tool-bash`) come from `agent-core`, so only the executor is a leaf choice |
+| `bash` (`dsh-bash-local`) | the executor implementation — the swappable half of the bash seam. The model-facing `bash` schema (`tool-bash`) and the `task_*` control tools (`tool-tasks`) come from `agent-core`, so only the executor is a leaf choice |
 | `stdio-agent` (`@deepseek-ai/dsh-stdio-agent`) | the app bundle: the agent-core spine + console logger + JSONL persistence + readline UI + a pre-created `main` agent. Its config carries the model, system prompt, `persistenceRoot` (`./.sessions`), and `resumeSessionId` — so persistence and the agent are configured here, not wired as separate leaf plugins |
 | `subagent`, `subagent-spawn`, `subagent-fork` | the subagent provider registry plus the two in-process backends: a fresh child and a child seeded with the parent's completed-turn prefix |
 | `tool-subagent`, `tool-subagent-fork` | two model-facing `dsh-tool-subagent` loads, each bound to a different provider and exposed under a distinct tool name (`subagent`, `subagent_fork`) |
diff --git a/examples/coding-agent/cordis.yml b/examples/coding-agent/cordis.yml
index 0439262e33..a0d17b425b 100644
--- a/examples/coding-agent/cordis.yml
+++ b/examples/coding-agent/cordis.yml
@@ -2,7 +2,8 @@
 # backends — the DeepSeek adapter and the local bash executor — plus `hmr` for
 # the dev/demo reload loop, then the stdio chat app (@deepseek-ai/dsh-stdio-
 # agent), which bundles the whole agent-core spine (timer, llm, sessions,
-# system-prompt, tools, agents, invariants, tool-bash, agent-loop), the console
+# system-prompt, tools, agents, tasks + the task_* control tools, invariants,
+# tool-bash, agent-loop), the console
 # logger, JSONL persistence, the readline UI, and a pre-created `main` agent.
 #
 # `hmr` is a leaf entry (not baked into dsh-stdio-agent): it is a Loader-only
diff --git a/packages/README.md b/packages/README.md
index da75f740e8..91691eaceb 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -15,6 +15,7 @@ Packages are grouped by modular role at `packages/<group>/<pkg>/`. The group dir
 | [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools | Product — stable surface |
 | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface |
 | [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry seam and the model-facing delegation tool | Product — stable surface |
+| [`tasks/`](tasks/README.md) | Background task family: the `ctx.tasks` registry + the generic `task_*` control tools | Product — stable surface |
 | [`web/`](web/README.md) | Web capability family: the abstract seam, search/fetch provider impls, and the model-facing web tools | Product — stable surface |
 | [`todo/`](todo/README.md) | Todo/planning family: the model-facing `todo_write` tool (whole-list task tracking on the session log) | Product — stable surface |
 | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
diff --git a/packages/bash/README.md b/packages/bash/README.md
index 9a9dba88d5..d68aa1c700 100644
--- a/packages/bash/README.md
+++ b/packages/bash/README.md
@@ -6,6 +6,6 @@ The canonical three-package capability seam (see [capability seams](../../docs/r
 |---|---|---|
 | `bash/` | Abstract bash executor seam (interface + vocabulary) | `ctx.bash` |
 | `bash-local/` | Local-subprocess `BashExecutor` implementation | (registers `ctx.bash`) |
-| `tool-bash/` | Model-facing `bash`/`bash_output`/`bash_kill` tool schemas | (registers on `ctx.tools`) |
+| `tool-bash/` | Model-facing `bash` tool schema | (registers on `ctx.tools`) |
 
-The interface lives at `bash/bash/`. A sandboxed executor would replace `bash-local` without touching the interface or the tool — the split is what makes that possible.
+The interface lives at `bash/bash/`. A sandboxed executor would replace `bash-local` without touching the interface or the tool — the split is what makes that possible. Background runs are generic tasks, not bash-private state: `tool-bash` registers a started `BashProcess` handle with the [`ctx.tasks` registry](../tasks/README.md), whose `task_*` tools collect and stop it.
diff --git a/packages/bash/bash-local/README.md b/packages/bash/bash-local/README.md
index dec29ce93b..b97dba3f25 100644
--- a/packages/bash/bash-local/README.md
+++ b/packages/bash/bash-local/README.md
@@ -23,7 +23,7 @@ Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi;
 - **Process-group kills with escalation** — children are spawned `detached` (own process group); kills send SIGTERM to the group, then SIGKILL after the `graceMs` grace (default 3s — OpenCode's escalation; pipelines and subshells die with the parent). ESRCH is tolerated; daemons that re-parent away from the group can still survive — same caveat as the surveyed tools.
 - **Tail-keep truncation + spill files** — output beyond `maxOutputBytes` keeps the in-memory TAIL (errors/results cluster at the end — pi/OpenCode rationale) while the FULL stream is appended to a temp file whose path is reported when available. If the final spill close reports a delayed writeback failure, the executor still returns the tail but withholds the path rather than advertising a possibly incomplete file.
 - **Model-friendly env + credential scrub** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`), then `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` (Codex's hardcoded set) so pagers and ANSI color don't garble results. This scrub is the security control that keeps the harness's *ambient* credentials out of a spawned command. A spec's `env` is merged LAST (after the scrub), so a caller's explicit entry — a value it already holds — wins even on a credential-shaped name. The spec's `stdin`, when supplied, is written to the child and closed; with none supplied, fd 0 is `/dev/null` — the exact pre-seam default, so a command that probes stdin's file type is unaffected. Both `env`/`stdin` are set by in-process plugins (the hooks bridges); the model-facing tool doesn't expose them. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
-- **Background tasks** — `start()` returns immediately, no timeout applies (Claude Code detaches timeouts when backgrounding), `readOutput()` is incremental with whole-stream byte offsets, and disposal kills everything. The spec's opaque `owner` token is stored on the tracked task and returned by `ownerOf(id)` — the executor never interprets it (the consumer's access policy does), and because it lives with the task here it survives a `tool-bash` HMR reload.
+- **Background processes** — `start()` returns a live `BashProcess` handle immediately, no timeout applies (Claude Code detaches timeouts when backgrounding), the handle's `readOutput()` is incremental with whole-stream byte offsets, and disposal kills every running process and awaits its exit. Everything task-shaped (ids, ownership, polling, notices) lives in the generic [`ctx.tasks` runtime](../../tasks/tasks/README.md), which the tool layer registers the handle with — this executor never sees a session or a registry.
 
 ## Sandboxing
 
diff --git a/packages/bash/bash-local/src/index.ts b/packages/bash/bash-local/src/index.ts
index cdac3985b8..a4707e1c83 100644
--- a/packages/bash/bash-local/src/index.ts
+++ b/packages/bash/bash-local/src/index.ts
@@ -2,7 +2,8 @@
  * `LocalBashExecutor`: the local-subprocess implementation of the
  * `@deepseek-ai/dsh-bash` executor seam. Spawns `bash -c` per call in its
  * own process group (see `./run.ts` for the plumbing and the agent-tool
- * survey notes), tracks background tasks, and kills everything on dispose.
+ * survey notes), tracks live background processes for disposal quiescence
+ * ONLY (task semantics live in `ctx.tasks`), and kills everything on dispose.
  *
  * TODO(permissions/sandbox): execution policy does NOT belong here — use
  * the `tools/pre-execute` deny/ask gate (see docs/architecture.md
@@ -16,8 +17,8 @@
 
 import { Context } from 'cordis'
 import z from 'schemastery'
-import { BashExecutor, BashTaskId } from '@deepseek-ai/dsh-bash'
-import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskRead, OwnerToken } from '@deepseek-ai/dsh-bash'
+import { BashExecutor } from '@deepseek-ai/dsh-bash'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashProcessRead, BashRunResult } from '@deepseek-ai/dsh-bash'
 import { DEFAULT_GRACE_MS, runBash } from './run.ts'
 import type { RunInternals, RunningBash } from './run.ts'
 
@@ -47,15 +48,6 @@ function assertPositiveFinite(name: string, value: number): void {
   }
 }
 
-interface TrackedTask extends BashTask {
-  running: RunningBash
-  /** Whole-stream byte offsets already delivered via {@link LocalBashExecutor.readOutput}. */
-  stdoutOffset: number
-  stderrOffset: number
-  /** Opaque owner token from the {@link BashExecSpec} (the consumer's isolation key). */
-  owner: OwnerToken | undefined
-}
-
 /**
  * Local-subprocess bash executor. Defaults follow the agent-tool survey
  * consensus: 120s default / 600s max timeout (Claude Code, OpenCode), 64KB
@@ -71,8 +63,12 @@ export class LocalBashExecutor extends BashExecutor {
     graceMs: z.number().default(DEFAULT_GRACE_MS),
   })
 
-  private tasks = new Map<BashTaskId, TrackedTask>()
-  private nextTaskId = 1
+  /**
+   * Live background processes, tracked for DISPOSAL only: an entry leaves
+   * the map the moment its process settles (callers keep reading through
+   * their own {@link BashProcess} handle — the buffers live on it).
+   */
+  private live = new Map<BashProcess, RunningBash>()
   /** Test seam: spill knobs forwarded to runBash. */
   internals: RunInternals = {}
 
@@ -91,17 +87,14 @@ export class LocalBashExecutor extends BashExecutor {
     ctx.effect(() => async () => {
       // Kill every live process group and WAIT for the processes to close so
       // nothing outlives the fiber (HMR safety) — a TERM-trapping child is
-      // held until the SIGKILL escalation lands. The base class already
-      // silenced listeners, so these kills complete without notices.
+      // held until the SIGKILL escalation lands.
       const pending: Promise<void>[] = []
-      for (const task of this.tasks.values()) {
-        if (task.status === 'running') {
-          task.status = 'killed'
-          task.running.kill()
-          pending.push(task.done)
-        }
+      for (const [proc, running] of this.live) {
+        proc.status = 'killed'
+        running.kill()
+        pending.push(proc.done)
       }
-      this.tasks.clear()
+      this.live.clear()
       await Promise.all(pending)
     }, 'local bash teardown')
   }
@@ -125,9 +118,6 @@ export class LocalBashExecutor extends BashExecutor {
       // means none). env merges AFTER the scrub in run.ts.
       ...request.stdin !== undefined ? { stdin: request.stdin } : {},
       ...request.env !== undefined ? { env: request.env } : {},
-      // Carry the owner through verbatim (required-but-nullable on the spec):
-      // the executor never interprets it — the consumer's access policy does.
-      owner: request.owner,
     }
   }
 
@@ -145,12 +135,12 @@ export class LocalBashExecutor extends BashExecutor {
     return { ...outcome, timeoutMs: spec.timeoutMs }
   }
 
-  start(spec: BashExecSpec): BashTask {
-    // No timeout for background tasks (matches Claude Code, which detaches
-    // the timeout when backgrounding); callers stop tasks via kill() — or
-    // via spec.signal, which the seam contract honors for background runs
-    // too (runBash wires it to the group kill). spec.timeoutMs is ignored
-    // here by design.
+  start(spec: BashExecSpec): BashProcess {
+    // No timeout for background processes (matches Claude Code, which
+    // detaches the timeout when backgrounding); callers stop them via the
+    // handle's kill() — or via spec.signal, which the seam contract honors
+    // for background runs too (runBash wires it to the group kill).
+    // spec.timeoutMs is ignored here by design.
     const running = runBash({
       command: spec.command,
       cwd: spec.workdir,
@@ -162,79 +152,54 @@ export class LocalBashExecutor extends BashExecutor {
       env: spec.env,
     }, this.internals)
 
-    const id = BashTaskId(`bash-${this.nextTaskId++}`)
-    const task: TrackedTask = {
-      id,
+    let stdoutOffset = 0
+    let stderrOffset = 0
+    const proc: BashProcess = {
       command: spec.command,
       status: 'running',
       exitCode: null,
       signal: null,
-      owner: spec.owner,
-      running,
-      stdoutOffset: 0,
-      stderrOffset: 0,
       done: running.done.then((outcome) => {
-        // Abort-killed tasks report as killed, not completed.
-        if (task.status === 'running') task.status = outcome.aborted ? 'killed' : 'completed'
-        task.exitCode = outcome.exitCode
-        task.signal = outcome.signal
-        this.notifyTaskDone(task)
+        // Abort-killed processes report as killed, not completed.
+        if (proc.status === 'running') proc.status = outcome.aborted ? 'killed' : 'completed'
+        proc.exitCode = outcome.exitCode
+        proc.signal = outcome.signal
+        this.live.delete(proc)
       }, (error: unknown) => {
-        // Spawn-level failure (bad workdir, …): the task never ran. String()
+        // Spawn-level failure (bad workdir, …): the process never ran. The
+        // error is surfaced through the read path, not a rejection. String()
         // suffices — runBash only rejects with Error instances.
-        task.status = 'killed'
-        task.running.stderr.push(Buffer.from(`spawn failed: ${String(error)}`))
-        this.notifyTaskDone(task)
+        proc.status = 'killed'
+        running.stderr.push(Buffer.from(`spawn failed: ${String(error)}`))
+        this.live.delete(proc)
       }),
+      readOutput: (): BashProcessRead => {
+        const out = running.stdout.readFrom(stdoutOffset)
+        const err = running.stderr.readFrom(stderrOffset)
+        stdoutOffset = out.nextOffset
+        stderrOffset = err.nextOffset
+
+        // Single newline between sections: stdout chunks usually end with one
+        // already; add it only when missing.
+        const separator = out.text.length > 0 && !out.text.endsWith('\n') ? '\n' : ''
+        const delta = out.text
+          + (err.text.length > 0 ? `${separator}[stderr]\n${err.text}` : '')
+        return {
+          delta,
+          lossy: out.lossy || err.lossy,
+          ...out.spillPath !== undefined ? { stdoutSpillPath: out.spillPath } : {},
+          ...err.spillPath !== undefined ? { stderrSpillPath: err.spillPath } : {},
+        }
+      },
+      kill: (): boolean => {
+        if (proc.status !== 'running') return false
+        proc.status = 'killed'
+        running.kill()
+        return true
+      },
     }
-    this.tasks.set(id, task)
-    return task
-  }
-
-  get(id: BashTaskId): BashTask | undefined {
-    return this.tasks.get(id)
-  }
-
-  ownerOf(id: BashTaskId): OwnerToken | undefined {
-    // Unknown id and known-but-ownerless both read as undefined — the consumer
-    // treats undefined as "open" and a truly unknown id fails at readOutput/kill.
-    return this.tasks.get(id)?.owner
-  }
-
-  list(): BashTask[] {
-    return [...this.tasks.values()]
-  }
-
-  readOutput(id: BashTaskId): BashTaskRead {
-    const task = this.tasks.get(id)
-    if (!task) throw new Error(`unknown bash task "${id}"`)
-
-    const out = task.running.stdout.readFrom(task.stdoutOffset)
-    const err = task.running.stderr.readFrom(task.stderrOffset)
-    task.stdoutOffset = out.nextOffset
-    task.stderrOffset = err.nextOffset
-
-    // Single newline between sections: stdout chunks usually end with one
-    // already; add it only when missing.
-    const separator = out.text.length > 0 && !out.text.endsWith('\n') ? '\n' : ''
-    const delta = out.text
-      + (err.text.length > 0 ? `${separator}[stderr]\n${err.text}` : '')
-    return {
-      task,
-      delta,
-      lossy: out.lossy || err.lossy,
-      ...out.spillPath !== undefined ? { stdoutSpillPath: out.spillPath } : {},
-      ...err.spillPath !== undefined ? { stderrSpillPath: err.spillPath } : {},
-    }
-  }
-
-  kill(id: BashTaskId): boolean {
-    const task = this.tasks.get(id)
-    if (!task) throw new Error(`unknown bash task "${id}"`)
-    if (task.status !== 'running') return false
-    task.status = 'killed'
-    task.running.kill()
-    return true
+    this.live.set(proc, running)
+    return proc
   }
 }
 
diff --git a/packages/bash/bash-local/tests/executor.spec.ts b/packages/bash/bash-local/tests/executor.spec.ts
index ce89b2a0ae..c860b88706 100644
--- a/packages/bash/bash-local/tests/executor.spec.ts
+++ b/packages/bash/bash-local/tests/executor.spec.ts
@@ -1,11 +1,10 @@
 import { mkdtempSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
-import { BashTaskId } from '@deepseek-ai/dsh-bash'
-import type { BashTaskRead } from '@deepseek-ai/dsh-bash'
+import type { BashProcess } from '@deepseek-ai/dsh-bash'
 
 const spillDir = mkdtempSync(join(tmpdir(), 'dsh-bash-exec-spec-'))
 
@@ -18,34 +17,20 @@ async function setup(config: ConstructorParameters<typeof LocalBashExecutor>[1]
   return { ctx, bash }
 }
 
-/** Poll until a pid no longer exists. */
-async function waitGone(pid: number, timeoutMs = 5_000): Promise<void> {
+/**
+ * Poll a handle's consuming readOutput until the ACCUMULATED delta contains
+ * `expected`; returns the accumulation (reads never re-deliver, so the caller
+ * gets everything produced up to the match).
+ */
+async function readUntil(proc: BashProcess, expected: string, timeoutMs = 5_000): Promise<string> {
   const deadline = Date.now() + timeoutMs
+  let all = ''
   while (Date.now() < deadline) {
-    try {
-      process.kill(pid, 0)
-    } catch {
-      return
-    }
+    all += proc.readOutput().delta
+    if (all.includes(expected)) return all
     await new Promise(resolve => setTimeout(resolve, 20))
   }
-  throw new Error(`pid ${pid} still alive after ${timeoutMs}ms`)
-}
-
-async function readUntil(
-  bash: LocalBashExecutor,
-  id: BashTaskId,
-  expected: string,
-  timeoutMs = 5_000,
-): Promise<BashTaskRead> {
-  const deadline = Date.now() + timeoutMs
-  let last: BashTaskRead | undefined
-  while (Date.now() < deadline) {
-    last = bash.readOutput(id)
-    if (last.delta.includes(expected)) return last
-    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(`process output did not include ${JSON.stringify(expected)}; accumulated ${JSON.stringify(all)}`)
 }
 
 describe('LocalBashExecutor.run', () => {
@@ -88,15 +73,6 @@ describe('LocalBashExecutor.run', () => {
     expect(() => bash.resolve({ command: 'true', timeoutMs: -1 })).toThrow(/request\.timeoutMs/)
   })
 
-  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))
-    bash.kill(task.id)
-    await task.done
-    expect(task.signal).toBe('SIGKILL')
-  })
-
   it('per-call timeout takes precedence under the cap and kills on expiry', async () => {
     const { bash } = await setup({ timeoutMs: 60_000 })
     const result = await bash.run(bash.resolve({ command: 'sleep 60', timeoutMs: 100 }))
@@ -136,229 +112,175 @@ describe('LocalBashExecutor.run', () => {
   })
 })
 
-describe('LocalBashExecutor background tasks', () => {
-  it('start returns immediately with a registered running task', async () => {
+describe('LocalBashExecutor.start (background process handles)', () => {
+  it('start returns immediately with a running handle that settles as completed', async () => {
     const { bash } = await setup()
     const before = Date.now()
-    const task = bash.start(bash.resolve({ command: 'sleep 0.2; echo done' }))
+    const proc = bash.start(bash.resolve({ command: 'sleep 0.2; echo done' }))
     expect(Date.now() - before).toBeLessThan(150)
-    expect(task.status).toBe('running')
-    expect(bash.get(task.id)).toBe(task)
-    expect(bash.list()).toContain(task)
-    await task.done
-    expect(task.status).toBe('completed')
-    expect(task.exitCode).toBe(0)
+    expect(proc.command).toBe('sleep 0.2; echo done')
+    expect(proc.status).toBe('running')
+    await proc.done
+    expect(proc.status).toBe('completed')
+    expect(proc.exitCode).toBe(0)
   })
 
-  it('assigns sequential ids', async () => {
+  it('threads stdin and extra env into a background process', async () => {
     const { bash } = await setup()
-    const first = bash.start(bash.resolve({ command: 'true' }))
-    const second = bash.start(bash.resolve({ command: 'true' }))
-    expect(first.id).toBe('bash-1')
-    expect(second.id).toBe('bash-2')
-    await Promise.all([first.done, second.done])
-  })
-
-  it('threads stdin and extra env into a background task', async () => {
-    const { bash } = await setup()
-    const task = bash.start(bash.resolve({
+    const proc = bash.start(bash.resolve({
       command: 'cat; echo "[$DSH_BG_VAR]"',
       stdin: 'bg-stdin\n',
       env: { DSH_BG_VAR: 'bg-env' },
     }))
-    const read = await readUntil(bash, task.id, '[bg-env]')
-    expect(read.delta).toContain('bg-stdin')
-    await task.done
-    expect(task.exitCode).toBe(0)
+    const output = await readUntil(proc, '[bg-env]')
+    expect(output).toContain('bg-stdin')
+    await proc.done
+    expect(proc.exitCode).toBe(0)
   })
 
-  it('readOutput returns increments without re-delivery', async () => {
+  it('readOutput is consuming: increments are never re-delivered, and reads stay valid after exit', async () => {
     const { bash } = await setup()
-    const task = bash.start(bash.resolve({ command: 'echo first; sleep 1; echo second' }))
-    const first = await readUntil(bash, task.id, 'first\n')
-    expect(first.delta).toBe('first\n')
-    expect(first.lossy).toBe(false)
-    await task.done
-    const second = bash.readOutput(task.id)
+    const proc = bash.start(bash.resolve({ command: 'echo first; sleep 1; echo second' }))
+    const first = await readUntil(proc, 'first\n')
+    expect(first).toBe('first\n')
+    await proc.done
+    // Read-after-exit returns the remaining buffered output — once.
+    const second = proc.readOutput()
     expect(second.delta).toBe('second\n')
-    const third = bash.readOutput(task.id)
-    expect(third.delta).toBe('')
+    expect(second.lossy).toBe(false)
+    expect(proc.readOutput().delta).toBe('')
   })
 
   it('readOutput marks stderr sections', async () => {
     const { bash } = await setup()
-    const task = bash.start(bash.resolve({ command: 'echo out; echo err >&2' }))
-    await task.done
-    const read = bash.readOutput(task.id)
-    expect(read.delta).toBe('out\n[stderr]\nerr\n')
+    const proc = bash.start(bash.resolve({ command: 'echo out; echo err >&2' }))
+    await proc.done
+    expect(proc.readOutput().delta).toBe('out\n[stderr]\nerr\n')
   })
 
   it('readOutput reports stderr-only deltas without a leading newline', async () => {
     const { bash } = await setup()
-    const task = bash.start(bash.resolve({ command: 'echo err >&2' }))
-    await task.done
-    expect(bash.readOutput(task.id).delta).toBe('[stderr]\nerr\n')
+    const proc = bash.start(bash.resolve({ command: 'echo err >&2' }))
+    await proc.done
+    expect(proc.readOutput().delta).toBe('[stderr]\nerr\n')
   })
 
-  it('readOutput flags lossy reads and reports spill paths', async () => {
+  it('readOutput adds a separator only when stdout lacks a trailing newline', async () => {
+    const { bash } = await setup()
+    const proc = bash.start(bash.resolve({ command: 'printf out; echo err >&2' }))
+    await proc.done
+    expect(proc.readOutput().delta).toBe('out\n[stderr]\nerr\n')
+  })
+
+  it('readOutput flags lossy reads and reports stdout spill paths', async () => {
     const { bash } = await setup({ maxOutputBytes: 100 })
-    const task = bash.start(bash.resolve({ command: 'for i in $(seq 1 100); do printf "line-%04d\\n" $i; done' }))
-    await task.done
-    const read = bash.readOutput(task.id)
+    const proc = bash.start(bash.resolve({ command: 'for i in $(seq 1 100); do printf "line-%04d\\n" $i; done' }))
+    await proc.done
+    const read = proc.readOutput()
     // Window slid past offset 0 → lossy, spill path points at the full stream.
     expect(read.lossy).toBe(true)
     expect(read.stdoutSpillPath).toBeDefined()
   })
 
-  it('readOutput throws for unknown ids', async () => {
-    const { bash } = await setup()
-    expect(() => bash.readOutput(BashTaskId('nope'))).toThrow(/unknown bash task "nope"/)
-  })
-
-  it('kill terminates the process group and reports status killed', async () => {
-    const { bash } = await setup()
-    const task = bash.start(bash.resolve({ command: 'sleep 60' }))
-    expect(bash.kill(task.id)).toBe(true)
-    await task.done
-    expect(task.status).toBe('killed')
-    expect(task.signal).toBe('SIGTERM')
-  })
-
-  it('kill returns false for finished tasks and throws for unknown ids', async () => {
-    const { bash } = await setup()
-    const task = bash.start(bash.resolve({ command: 'true' }))
-    await task.done
-    expect(bash.kill(task.id)).toBe(false)
-    expect(() => bash.kill(BashTaskId('nope'))).toThrow(/unknown bash task "nope"/)
-  })
-
-  it('notifies onTaskDone listeners on completion', async () => {
-    const { bash } = await setup()
-    const seen: [string, string][] = []
-    bash.onTaskDone(task => void seen.push([task.id, task.status]))
-    const task = bash.start(bash.resolve({ command: 'true' }))
-    await task.done
-    expect(seen).toEqual([[task.id, 'completed']])
-  })
-
-  it('notifies onTaskDone for killed tasks too', async () => {
-    const { bash } = await setup()
-    const listener = vi.fn()
-    bash.onTaskDone(listener)
-    const task = bash.start(bash.resolve({ command: 'sleep 60' }))
-    bash.kill(task.id)
-    await task.done
-    expect(listener).toHaveBeenCalledWith(task)
-    expect(task.status).toBe('killed')
-  })
-
-  it('marks tasks killed when the background spawn itself fails', async () => {
-    const { bash } = await setup()
-    const listener = vi.fn()
-    bash.onTaskDone(listener)
-    const task = bash.start(bash.resolve({ command: 'true', workdir: '/nonexistent-dsh' }))
-    await task.done
-    expect(task.status).toBe('killed')
-    expect(listener).toHaveBeenCalledWith(task)
-    expect(bash.readOutput(task.id).delta).toContain('spawn failed')
-  })
-
-  it('readOutput adds a separator only when stdout lacks a trailing newline', async () => {
-    const { bash } = await setup()
-    const task = bash.start(bash.resolve({ command: 'printf out; echo err >&2' }))
-    await task.done
-    expect(bash.readOutput(task.id).delta).toBe('out\n[stderr]\nerr\n')
-  })
-
   it('readOutput reports stderr spill paths', async () => {
     const { bash } = await setup({ maxOutputBytes: 100 })
-    const task = bash.start(bash.resolve({ command: 'for i in $(seq 1 100); do printf "line-%04d\\n" $i >&2; done' }))
-    await task.done
-    const read = bash.readOutput(task.id)
+    const proc = bash.start(bash.resolve({ command: 'for i in $(seq 1 100); do printf "line-%04d\\n" $i >&2; done' }))
+    await proc.done
+    const read = proc.readOutput()
     expect(read.lossy).toBe(true)
     expect(read.stderrSpillPath).toBeDefined()
     expect(read.delta).toContain('[stderr]')
   })
 
-  it('disposing with already-finished tasks only kills the running ones', async () => {
+  it('kill() terminates the process group: true once, false after settlement', async () => {
+    const { bash } = await setup()
+    const proc = bash.start(bash.resolve({ command: 'sleep 60' }))
+    expect(proc.kill()).toBe(true)
+    await proc.done
+    expect(proc.status).toBe('killed')
+    expect(proc.signal).toBe('SIGTERM')
+    expect(proc.kill()).toBe(false)
+  })
+
+  it('kill() returns false for a naturally completed process', async () => {
+    const { bash } = await setup()
+    const proc = bash.start(bash.resolve({ command: 'true' }))
+    await proc.done
+    expect(proc.status).toBe('completed')
+    expect(proc.kill()).toBe(false)
+  })
+
+  it('kill escalation uses the configured graceMs (a TERM-trapping process dies by SIGKILL)', async () => {
+    const { bash } = await setup() // setup pins graceMs: 200 via config
+    // The child echoes AFTER arming the trap, so waiting for the marker
+    // guarantees SIGTERM is already ignored when the kill lands (a fixed sleep
+    // is load-flaky: a slow spawn would take the SIGTERM before the trap).
+    const proc = bash.start(bash.resolve({ command: 'trap \'\' TERM; echo armed; sleep 60' }))
+    await readUntil(proc, 'armed')
+    proc.kill()
+    await proc.done
+    expect(proc.status).toBe('killed')
+    expect(proc.signal).toBe('SIGKILL')
+  })
+
+  it('a spec.signal abort settles the handle as killed, not completed', async () => {
+    const { bash } = await setup()
+    const controller = new AbortController()
+    const proc = bash.start(bash.resolve({ command: 'sleep 60', signal: controller.signal }))
+    controller.abort()
+    await proc.done
+    expect(proc.status).toBe('killed')
+    expect(proc.signal).toBe('SIGTERM')
+  })
+
+  it('a background spawn failure settles as killed with the error readable on stderr', async () => {
+    const { bash } = await setup()
+    const proc = bash.start(bash.resolve({ command: 'true', workdir: '/nonexistent-dsh' }))
+    // done resolves (never rejects) even though the process never ran.
+    await expect(proc.done).resolves.toBeUndefined()
+    expect(proc.status).toBe('killed')
+    expect(proc.readOutput().delta).toContain('spawn failed:')
+  })
+})
+
+describe('LocalBashExecutor disposal', () => {
+  it('disposing the fiber kills running processes and AWAITS their exit (no orphans, SIGKILL escalation included)', async () => {
     const ctx = new Context()
     const fiber = await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
     const bash = ctx.bash as LocalBashExecutor
     bash.internals = { spillDir }
 
-    const finished = bash.start(bash.resolve({ command: 'true' }))
+    // The child prints its own pid ($$ = the detached bash group leader) so
+    // the test can probe liveness through the public read surface alone.
+    const proc = bash.start(bash.resolve({ command: 'trap \'\' TERM; echo $$; sleep 60' }))
+    const pid = Number((await readUntil(proc, '\n')).trim())
+    expect(Number.isInteger(pid) && pid > 0).toBe(true)
+
+    await fiber.dispose()
+    // Disposal itself waited: the pid must already be gone, no grace left —
+    // even for a TERM-trapping child held until the SIGKILL escalation landed.
+    expect(() => process.kill(pid, 0)).toThrow()
+    expect(proc.status).toBe('killed')
+    await proc.done
+  })
+
+  it('settled processes already left the live map: dispose does not touch them', async () => {
+    const ctx = new Context()
+    const fiber = await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
+    const bash = ctx.bash as LocalBashExecutor
+    bash.internals = { spillDir }
+
+    const finished = bash.start(bash.resolve({ command: 'echo done' }))
     await finished.done
+    expect(finished.status).toBe('completed')
     const running = bash.start(bash.resolve({ command: 'sleep 60' }))
 
     await fiber.dispose()
-    await running.done
+    // The teardown marks every LIVE entry killed; a settled process had
+    // already left the map, so its status stays completed.
     expect(finished.status).toBe('completed')
+    expect(running.status).toBe('killed')
+    await running.done
     expect(running.signal).toBe('SIGTERM')
-    expect(bash.list()).toEqual([])
-  })
-
-  it('disposing the executor fiber kills running tasks (no orphans)', async () => {
-    const ctx = new Context()
-    const fiber = await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
-    const bash = ctx.bash as LocalBashExecutor
-    bash.internals = { spillDir }
-    const listener = vi.fn()
-    bash.onTaskDone(listener)
-
-    const task = bash.start(bash.resolve({ command: 'sleep 60' }))
-    const running = bash.get(task.id)!
-    await new Promise(resolve => setTimeout(resolve, 50))
-
-    // Grab the pid before dispose clears the registry.
-    const pid = (running as unknown as { running: { pid: number } }).running.pid
-    await fiber.dispose()
-    await waitGone(pid)
-    expect(bash.list()).toEqual([])
-    // Listener silenced by base-class teardown — no late notifications.
-    expect(listener).not.toHaveBeenCalled()
-  })
-})
-
-describe('review fixes: lifecycle hardening', () => {
-  it('start honors a pre-aborted or later-aborted AbortSignal', async () => {
-    const { bash } = await setup()
-    const controller = new AbortController()
-    const task = bash.start(bash.resolve({ command: 'sleep 60', signal: controller.signal }))
-    controller.abort()
-    await task.done
-    expect(task.status).toBe('killed')
-    expect(task.signal).toBe('SIGTERM')
-  })
-
-  it('a throwing onTaskDone listener does not reject task.done or starve later listeners', async () => {
-    const { bash } = await setup()
-    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
-    const second = vi.fn()
-    try {
-      bash.onTaskDone(() => { throw new Error('listener bug') })
-      bash.onTaskDone(second)
-      const task = bash.start(bash.resolve({ command: 'true' }))
-      await expect(task.done).resolves.toBeUndefined()
-      expect(second).toHaveBeenCalledWith(task)
-      expect(errorSpy).toHaveBeenCalled()
-    } finally {
-      errorSpy.mockRestore()
-    }
-  })
-
-  it('dispose AWAITS a TERM-trapping process (SIGKILL escalation included)', async () => {
-    const ctx = new Context()
-    const fiber = await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
-    const bash = ctx.bash as LocalBashExecutor
-    bash.internals = { spillDir }
-
-    const task = bash.start(bash.resolve({ command: 'trap \'\' TERM; sleep 60' }))
-    await new Promise(resolve => setTimeout(resolve, 100))
-    const pid = (task as unknown as { running: { pid: number } }).running.pid
-
-    await fiber.dispose()
-    // Disposal itself waited: the pid must already be gone, no grace left.
-    expect(() => process.kill(pid, 0)).toThrow()
-    expect(task.status).toBe('killed')
   })
 })
diff --git a/packages/bash/bash/README.md b/packages/bash/bash/README.md
index 39318ae371..d297dad506 100644
--- a/packages/bash/bash/README.md
+++ b/packages/bash/bash/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-bash
 
-The **bash executor seam**: an abstract `BashExecutor` service (`ctx.bash`) defining WHAT a bash backend does — run commands, manage background tasks — without saying HOW.
+The **bash executor seam**: an abstract `BashExecutor` service (`ctx.bash`) defining WHAT a bash backend does — run foreground commands, start background processes — without saying HOW.
 
 This package is one third of the bash capability, split so each concern can evolve (and be swapped) independently:
 
@@ -8,7 +8,7 @@ This package is one third of the bash capability, split so each concern can evol
 |---|---|
 | `@deepseek-ai/dsh-bash` (this) | the interface: abstract service + vocabulary types |
 | `@deepseek-ai/dsh-bash-local` | an implementation: local subprocesses |
-| `@deepseek-ai/dsh-tool-bash` | the model-facing tool schemas over `ctx.bash` |
+| `@deepseek-ai/dsh-tool-bash` | the model-facing tool schema over `ctx.bash` |
 
 The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool survey: pi hides execution behind a `BashOperations` interface (local shell / SSH / VM backends), Codex behind an exec-server protocol. A future sandboxed, containerized, or remote executor implements this interface and the tool schemas don't change.
 
@@ -16,18 +16,14 @@ The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool su
 
 | Member | Semantics |
 |---|---|
+| `resolve(request)` | Fill a caller's `BashExecRequest` (optional `workdir`/`timeoutMs`) into a fully-resolved `BashExecSpec` from the implementation's config defaults and caps — the explicit defaulting step consumers call before `run`/`start`. |
 | `run(spec)` | Foreground execution. Resolves when the command finishes. **Rejects only for infrastructure failures** (unusable workdir, missing shell, pre-aborted signal); nonzero exits, timeout kills, and abort kills resolve with a descriptive `BashRunResult`. |
-| `start(spec)` | Background execution. Returns a `BashTask` handle immediately; **no timeout applies** (stop tasks via `kill`). |
-| `get(id)` / `list()` | Task lookup. |
-| `ownerOf(id)` | The opaque OWNER token recorded for a background task at `start` (from the spec's `owner`), or `undefined` for an unknown id OR a known-but-ownerless task. The executor stores/returns it verbatim and NEVER interprets it — the access POLICY lives in the consumer (`dsh-tool-bash`), which compares `ownerOf(id)` to the caller's token. Storing ownership here (disposed with the executor's fiber) is what makes it survive a consumer HMR reload. |
-| `readOutput(id)` | **Incremental** output read — consecutive reads never re-deliver. Reads that lost data to buffer bounds flag `lossy` and point at full-stream spill files. Throws for unknown ids. |
-| `kill(id)` | Kill a running task. Returns `false` when it already finished; throws for unknown ids. |
-| `onTaskDone(listener)` | Completion listener (effect-based, disposer returned). Fires exactly once per task; never after the service is disposed. |
+| `start(spec)` | Background execution. Returns a `BashProcess` handle immediately; **no timeout applies** (stop the process via the handle's `kill()` or the spec's AbortSignal). |
 
-Implementations subclass `BashExecutor`, implement the abstract methods, and call `notifyTaskDone(task)` on background completion. Disposal must kill every running task (no orphan processes) — see the HMR-safety tests.
+The seam is deliberately TASK-FREE: `start()` hands back only the `BashProcess` handle — `command`, `status`, `exitCode`/`signal`, a never-rejecting `done` quiescence promise, a consuming incremental `readOutput()` (reads that lost data to buffer bounds flag `lossy` and point at full-stream spill files; reads stay valid after exit), and an idempotent `kill()`. Task ids, cross-session isolation, polling tools, and completion notices are the generic [`ctx.tasks` runtime](../../tasks/tasks/README.md)'s job — the tool layer adapts the handle into a task registration — which keeps a remote/sandbox executor free of any session or registry dependency. Disposal must kill every running background process and await its exit (no orphan processes) — see the HMR-safety tests.
 
 ## Vocabulary
 
-`BashExecRequest` (command, workdir?, timeoutMs?, signal?, stdin?, env?, owner?) resolves to `BashExecSpec` (command, workdir, timeoutMs, signal?, stdin?, env?, owner) before execution; `owner` is optional on the request and **required-but-nullable** (`OwnerToken | undefined`) on the resolved spec, so a forgotten owner is a visible `undefined` rather than a silently-absent property. The task id (`BashTaskId`) and the `owner` token (`OwnerToken`) are [branded](../../util/brand) — `OwnerToken` is a DISTINCT brand from `SessionId` (the seam never imports `dsh-session`; the `dsh-tool-bash` consumer is the single boundary that casts its `SessionId` into one). `run()` returns `BashRunResult` (exitCode, signal, timedOut, aborted, timeoutMs, stdout/stderr as `CollectedOutput`) and `start()`/`readOutput()` use `BashTask`/`BashTaskRead` for the background side. See `src/types.ts` for the full contracts.
+`BashExecRequest` (command, workdir?, timeoutMs?, signal?, stdin?, env?) resolves to `BashExecSpec` (command, workdir, timeoutMs, signal?, stdin?, env?) before execution. `run()` returns `BashRunResult` (exitCode, signal, timedOut, aborted, timeoutMs, stdout/stderr as `CollectedOutput`) and `start()` returns `BashProcess`, whose `readOutput()` yields a `BashProcessRead`. See `src/types.ts` for the full contracts.
 
-`stdin` and `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload on stdin and its `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` env. The model-facing `dsh-tool-bash` tool does not expose them as parameters — a model already has equivalent power through shell syntax (`FOO=bar cmd`, a heredoc), so they would be redundant tool params. This is not a security boundary: the implementation's credential scrub (not these fields) is what keeps the harness's ambient secrets out of a spawned command. They are plain optionals on the resolved spec (unlike `owner`'s required-but-nullable): a missing one means "none", the safe default. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
+`stdin` and `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload on stdin and its `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` env. The model-facing `dsh-tool-bash` tool does not expose them as parameters — a model already has equivalent power through shell syntax (`FOO=bar cmd`, a heredoc), so they would be redundant tool params. This is not a security boundary: the implementation's credential scrub (not these fields) is what keeps the harness's ambient secrets out of a spawned command. They are plain optionals on the resolved spec: a missing one means "none", the safe default. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
diff --git a/packages/bash/bash/package.json b/packages/bash/bash/package.json
index f1bc43c2b4..865de7b643 100644
--- a/packages/bash/bash/package.json
+++ b/packages/bash/bash/package.json
@@ -22,11 +22,9 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-brand": "workspace:^",
     "cordis": "^4.0.0-rc.6"
   }
 }
diff --git a/packages/bash/bash/src/index.ts b/packages/bash/bash/src/index.ts
index b629f10e4d..af0d032965 100644
--- a/packages/bash/bash/src/index.ts
+++ b/packages/bash/bash/src/index.ts
@@ -1,31 +1,36 @@
 /**
  * The bash executor seam (`ctx.bash`): an abstract service defining WHAT a
- * bash backend does — run commands, manage background tasks — without saying
- * HOW. Implementations subclass {@link BashExecutor} and register themselves
- * as the `bash` service; `@deepseek-ai/dsh-bash-local` (local subprocesses)
- * is the first. Future implementations swap in sandboxes, containers, or
- * remote exec servers without touching the tool schemas that consume them
- * (`@deepseek-ai/dsh-tool-bash`).
+ * bash backend does — run foreground commands, start background processes —
+ * without saying HOW. Implementations subclass {@link BashExecutor} and
+ * register themselves as the `bash` service; `@deepseek-ai/dsh-bash-local`
+ * (local subprocesses) is the first. Future implementations swap in
+ * sandboxes, containers, or remote exec servers without touching the tool
+ * schemas that consume them (`@deepseek-ai/dsh-tool-bash`).
  *
  * The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the
  * surveyed agents: pi hides execution behind a `BashOperations` interface
  * (local shell / SSH / VM backends), Codex behind an exec-server protocol.
  *
+ * The seam is deliberately TASK-FREE: `start()` hands back a
+ * {@link BashProcess} handle (incremental reads, kill, a quiescence promise)
+ * and nothing else. Task ids, owner isolation, polling tools, and completion
+ * notices are the generic `ctx.tasks` runtime's job (`@deepseek-ai/dsh-tasks`)
+ * — the tool layer adapts the handle into a task registration. This keeps a
+ * remote/sandbox executor free of any session or registry dependency.
+ *
  * @module @deepseek-ai/dsh-bash
  */
 
 import { Context, Service } from 'cordis'
-import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskId, BashTaskListener, BashTaskRead, OwnerToken } from './types.ts'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from './types.ts'
 
-export { BashTaskId, OwnerToken } from './types.ts'
 export type {
   BashExecRequest,
   BashExecSpec,
+  BashProcess,
+  BashProcessRead,
+  BashProcessStatus,
   BashRunResult,
-  BashTask,
-  BashTaskListener,
-  BashTaskRead,
-  BashTaskStatus,
   CollectedOutput,
 } from './types.ts'
 
@@ -47,27 +52,19 @@ declare module 'cordis' {
  *   abort kills RESOLVE with a descriptive {@link BashRunResult} — reporting
  *   a failed command is the tool layer's job, not an exception.
  * - {@link start} returns immediately; no timeout applies to background
- *   tasks (callers stop them via {@link kill} or the spec's AbortSignal).
- *   Completion must fire the {@link onTaskDone} listeners exactly once per
- *   task, and must NOT fire after the service is disposed.
- * - {@link readOutput} is incremental: consecutive reads never re-deliver
- *   output. Implementations bound their buffers; reads that lost data flag
- *   `lossy` and point at full-stream spill files when available.
- * - Disposal kills every running task and awaits their exit (no orphan
- *   processes survive `fiber.dispose()`).
+ *   processes (callers stop them via {@link BashProcess.kill} or the spec's
+ *   AbortSignal). The handle's `done` settles at process close and never
+ *   rejects (a spawn failure settles as `killed` with the error readable on
+ *   stderr).
+ * - {@link BashProcess.readOutput} is incremental: consecutive reads never
+ *   re-deliver output. Implementations bound their buffers; reads that lost
+ *   data flag `lossy` and point at full-stream spill files when available.
+ * - Disposal kills every running background process and awaits their exit
+ *   (no orphan processes survive `fiber.dispose()`).
  */
 export abstract class BashExecutor extends Service {
-  private listeners = new Set<BashTaskListener>()
-  private listenersClosed = false
-
   constructor(ctx: Context) {
     super(ctx, 'bash')
-    ctx.effect(() => () => {
-      // Close the listener registry before subclass teardown so late task
-      // completions (e.g. from kills issued during dispose) stay silent.
-      this.listenersClosed = true
-      this.listeners.clear()
-    }, 'bash listener teardown')
   }
 
   /**
@@ -92,86 +89,11 @@ export abstract class BashExecutor extends Service {
   abstract run(spec: BashExecSpec): Promise<BashRunResult>
 
   /**
-   * Start a background task and return its handle immediately.
+   * Start a background process and return its handle immediately.
    * @param spec - a resolved spec from {@link resolve}, never a raw request.
-   * @returns the live task handle; completion fires {@link onTaskDone}.
+   * @returns the live process handle (reads, kill, quiescence promise).
    */
-  abstract start(spec: BashExecSpec): BashTask
-
-  /**
-   * Look up a background task by id.
-   * @param id - the task id to look up.
-   * @returns the tracked task, or undefined for an id this executor never issued.
-   */
-  abstract get(id: BashTaskId): BashTask | undefined
-
-  /**
-   * The opaque OWNER token recorded for a background task at {@link start}
-   * (from the {@link BashExecSpec}'s `owner`), or `undefined` for an unknown id
-   * OR a known-but-ownerless task. The executor stores and returns the token
-   * verbatim — it never interprets it; the access POLICY (who may read/kill a
-   * task) lives in the consumer (`@deepseek-ai/dsh-tool-bash`), which compares
-   * `ownerOf(id)` to the caller's token. Collapsing unknown-id and
-   * known-but-unowned into the same `undefined` is fine: the consumer's access
-   * gate treats `undefined` as "open", and a genuinely unknown id then fails
-   * loudly at the subsequent {@link readOutput}/{@link kill} ("unknown task").
-   * Storing ownership in the executor (disposed with ITS fiber) — not in the
-   * tool plugin — is what makes ownership survive a `tool-bash` HMR reload.
-   * @param id - the background task id to look up ownership for.
-   * @returns the token recorded at start, verbatim; undefined for an unknown
-   *   id or a known-but-ownerless task.
-   */
-  abstract ownerOf(id: BashTaskId): OwnerToken | undefined
-
-  /**
-   * All tracked background tasks (insertion order).
-   * @returns every task this executor started, running or finished.
-   */
-  abstract list(): BashTask[]
-
-  /**
-   * Read output produced since the previous read. Throws for unknown ids.
-   * @param id - the task to read from.
-   * @returns the incremental read; consecutive reads never re-deliver output.
-   */
-  abstract readOutput(id: BashTaskId): BashTaskRead
-
-  /**
-   * Kill a running background task. Returns false when it had already
-   * finished (no-op). Throws for unknown ids.
-   * @param id - the task to kill.
-   * @returns true when this call killed it, false when it had already finished.
-   */
-  abstract kill(id: BashTaskId): boolean
-
-  /**
-   * Register a background-task completion listener (disposed with the
-   * calling fiber). Listeners never fire after this service is disposed.
-   * @param listener - called exactly once per task completion.
-   * @returns the disposer that unregisters the listener.
-   */
-  onTaskDone(listener: BashTaskListener): () => void {
-    const dispose = this.ctx.effect(() => {
-      this.listeners.add(listener)
-      return () => this.listeners.delete(listener)
-    }, 'bash.onTaskDone()')
-    return () => void dispose()
-  }
-
-  /** For implementations: notify listeners that `task` completed. Listener
-   * exceptions are contained (logged) — one bad listener must not reject
-   * `BashTask.done` or starve the listeners after it. */
-  protected notifyTaskDone(task: BashTask): void {
-    if (this.listenersClosed) return
-    for (const listener of this.listeners) {
-      try {
-        listener(task)
-      } catch (error: unknown) {
-        // Listener bugs are reported, never propagated into task.done.
-        console.error('bash onTaskDone listener threw:', error)
-      }
-    }
-  }
+  abstract start(spec: BashExecSpec): BashProcess
 }
 
 export default BashExecutor
diff --git a/packages/bash/bash/src/types.ts b/packages/bash/bash/src/types.ts
index 4715ace318..c5031fdcee 100644
--- a/packages/bash/bash/src/types.ts
+++ b/packages/bash/bash/src/types.ts
@@ -3,43 +3,15 @@
  * service lives in `./index.ts`, implementations in sibling packages
  * (`@deepseek-ai/dsh-bash-local` first).
  *
+ * Background TASK semantics (ids, ownership, polling protocol, completion
+ * listeners) deliberately do NOT live here: the seam starts a background
+ * PROCESS and returns a {@link BashProcess} handle; the caller (the tool
+ * layer) registers that handle with the generic `ctx.tasks` runtime
+ * (`@deepseek-ai/dsh-tasks`), which owns everything task-shaped.
+ *
  * @module dsh-bash/types
  */
 
-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}.
- * @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
-}
-
-/**
- * A background task's opaque isolation key — the CONSUMER's owner identity, not
- * the bash seam's. The executor stores and returns it verbatim and never
- * interprets it; the access policy lives in the consumer (`dsh-tool-bash`),
- * which is the single boundary that casts its own id vocabulary into one. A
- * DISTINCT brand (not a `SessionId` alias) keeps the seam decoupled — a
- * sandboxed/remote executor inherits no session dependency.
- */
-export type OwnerToken = Branded<'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
-}
-
 /**
  * A caller's execution REQUEST: `workdir` and `timeoutMs` are optional and
  * filled by {@link BashExecutor.resolve} from the implementation's config.
@@ -72,15 +44,6 @@ export interface BashExecRequest {
    * uses shell syntax like `FOO=bar cmd`).
    */
   env?: Record<string, string> | undefined
-  /**
-   * Opaque OWNER token for a background task — the consumer's isolation key
-   * (the tool layer passes the owning agent's `session.header.id`). The
-   * executor stores it on the task and exposes it via {@link BashExecutor.ownerOf};
-   * the executor itself NEVER interprets it (no access policy lives in the
-   * seam — that is the consumer's job). Absent for foreground runs and for an
-   * ownerless background start (a non-agent caller).
-   */
-  owner?: OwnerToken | undefined
 }
 
 /**
@@ -88,7 +51,7 @@ export interface BashExecRequest {
  * {@link BashExecutor.start} act on. `workdir` and `timeoutMs` are REQUIRED:
  * defaulting and capping already happened in {@link BashExecutor.resolve}, so
  * the executor never hides a `?? config` fallback (explicit > implicit). For
- * background tasks, `start()` ignores `timeoutMs` (background runs have no
+ * background processes, `start()` ignores `timeoutMs` (background runs have no
  * timeout) — the field is still required because the type is shared.
  */
 export interface BashExecSpec {
@@ -99,10 +62,10 @@ export interface BashExecSpec {
   signal?: AbortSignal | undefined
   /**
    * Bytes to write to the command's stdin (then close it), carried through
-   * verbatim from {@link BashExecRequest.stdin}. OPTIONAL on the resolved spec
-   * (unlike `owner`): it has no config default, so a missing one means "no
-   * stdin" — the safe, ordinary case — not a silent footgun, so it stays a
-   * plain optional rather than required-but-nullable (see the request field).
+   * verbatim from {@link BashExecRequest.stdin}. OPTIONAL on the resolved spec:
+   * it has no config default, so a missing one means "no stdin" — the safe,
+   * ordinary case — not a silent footgun, so it stays a plain optional rather
+   * than required-but-nullable (see the request field).
    */
   stdin?: string | undefined
   /**
@@ -113,15 +76,6 @@ export interface BashExecSpec {
    * config default, absent means "no extra env".
    */
   env?: Record<string, string> | undefined
-  /**
-   * Opaque owner token, REQUIRED-but-nullable (mirrors `workdir`/`timeoutMs`
-   * being required on the resolved spec): {@link BashExecutor.resolve} carries
-   * the request's `owner` through, defaulting a missing one to `undefined`. A
-   * required field makes a forgotten owner a VISIBLE `undefined` rather than a
-   * silently-absent property that yields an unowned (cross-session-readable)
-   * task. `start()` stores it; `run()` (foreground) ignores it.
-   */
-  owner: OwnerToken | undefined
 }
 
 /** One captured stream: the (possibly truncated) text plus recovery info. */
@@ -150,25 +104,11 @@ export interface BashRunResult {
   stderr: CollectedOutput
 }
 
-/** Lifecycle of a background task. */
-export type BashTaskStatus = 'running' | 'completed' | 'killed'
+/** Lifecycle of a background process. */
+export type BashProcessStatus = 'running' | 'completed' | 'killed'
 
-/** A tracked background task handle. */
-export interface BashTask {
-  readonly id: BashTaskId
-  readonly command: string
-  status: BashTaskStatus
-  /** Exit code once finished (null = killed by signal / still running). */
-  exitCode: number | null
-  /** Terminating signal name, when signal-killed. */
-  signal: NodeJS.Signals | null
-  /** Resolves when the underlying process closes (never rejects). */
-  readonly done: Promise<void>
-}
-
-/** One incremental {@link BashExecutor.readOutput} read. */
-export interface BashTaskRead {
-  task: BashTask
+/** One incremental {@link BashProcess.readOutput} read. */
+export interface BashProcessRead {
   /** Output produced since the previous read (stderr in a marked section). */
   delta: string
   /** True when truncation dropped unread bytes the delta cannot include. */
@@ -179,5 +119,34 @@ export interface BashTaskRead {
   stderrSpillPath?: string
 }
 
-/** Completion callback for background tasks. */
-export type BashTaskListener = (task: BashTask) => void
+/**
+ * A live background process handle, returned by {@link BashExecutor.start}.
+ * The HANDLE is the only access path (no executor-level id lookup): the
+ * caller holds it, adapts it into a `ctx.tasks` registration, or drops it.
+ * Reads stay valid after the process exits (the remaining buffered output is
+ * still consumable); the executor's own disposal kills every running process
+ * and awaits {@link done}.
+ */
+export interface BashProcess {
+  /** The command line this process runs. */
+  readonly command: string
+  /** Process lifecycle state (settled exactly once). */
+  status: BashProcessStatus
+  /** Exit code once finished (null = killed by signal / still running). */
+  exitCode: number | null
+  /** Terminating signal name, when signal-killed. */
+  signal: NodeJS.Signals | null
+  /** Resolves when the underlying process closes (never rejects — a spawn failure settles as `killed` with the error on stderr). */
+  readonly done: Promise<void>
+  /**
+   * Read output produced since the previous read (consuming — consecutive
+   * reads never re-deliver). Reads that lost data flag `lossy` and point at
+   * full-stream spill files when available.
+   */
+  readOutput(): BashProcessRead
+  /**
+   * Kill the process group. Returns false when it had already finished
+   * (no-op); idempotent.
+   */
+  kill(): boolean
+}
diff --git a/packages/bash/bash/tests/service.spec.ts b/packages/bash/bash/tests/service.spec.ts
index 81530843ed..e1ab24da84 100644
--- a/packages/bash/bash/tests/service.spec.ts
+++ b/packages/bash/bash/tests/service.spec.ts
@@ -1,145 +1,78 @@
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import { BashExecutor, BashTaskId, OwnerToken } from '@deepseek-ai/dsh-bash'
-import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskRead } from '@deepseek-ai/dsh-bash'
+import { BashExecutor } from '@deepseek-ai/dsh-bash'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashProcessRead, BashRunResult } from '@deepseek-ai/dsh-bash'
 
-/** Minimal concrete executor: records calls, lets tests drive completions. */
+/**
+ * Minimal concrete executor: canned foreground results, a hand-built process
+ * handle. The seam is TASK-FREE (start returns a {@link BashProcess} handle;
+ * task semantics live in `ctx.tasks`), so this stub is all an implementation
+ * owes the abstract class.
+ */
 class StubExecutor extends BashExecutor {
-  tasks = new Map<BashTaskId, BashTask>()
-  private owners = new Map<BashTaskId, OwnerToken | undefined>()
-
   resolve(request: BashExecRequest): BashExecSpec {
     return {
       command: request.command,
       workdir: request.workdir ?? '/stub',
       timeoutMs: request.timeoutMs ?? 1000,
       ...request.signal ? { signal: request.signal } : {},
-      owner: request.owner,
     }
   }
 
-  async run(_spec: BashExecSpec): Promise<BashRunResult> {
+  async run(spec: BashExecSpec): Promise<BashRunResult> {
     return {
       exitCode: 0,
       signal: null,
       timedOut: false,
       aborted: false,
-      timeoutMs: 1000,
+      timeoutMs: spec.timeoutMs,
       stdout: { text: 'ok', truncated: false },
       stderr: { text: '', truncated: false },
     }
   }
 
-  start(spec: BashExecSpec): BashTask {
-    const task: BashTask = {
-      id: BashTaskId(`stub-${this.tasks.size + 1}`),
+  start(spec: BashExecSpec): BashProcess {
+    const proc: BashProcess = {
       command: spec.command,
       status: 'running',
       exitCode: null,
       signal: null,
       done: Promise.resolve(),
+      readOutput: (): BashProcessRead => ({ delta: '', lossy: false }),
+      kill: (): boolean => {
+        if (proc.status !== 'running') return false
+        proc.status = 'killed'
+        return true
+      },
     }
-    this.tasks.set(task.id, task)
-    this.owners.set(task.id, spec.owner)
-    return task
+    return proc
   }
-
-  get(id: BashTaskId): BashTask | undefined {
-    return this.tasks.get(id)
-  }
-
-  ownerOf(id: BashTaskId): OwnerToken | undefined {
-    return this.owners.get(id)
-  }
-
-  list(): BashTask[] {
-    return [...this.tasks.values()]
-  }
-
-  readOutput(id: BashTaskId): BashTaskRead {
-    const task = this.tasks.get(id)
-    if (!task) throw new Error(`unknown bash task "${id}"`)
-    return { task, delta: '', lossy: false }
-  }
-
-  kill(id: BashTaskId): boolean {
-    const task = this.tasks.get(id)
-    if (!task) throw new Error(`unknown bash task "${id}"`)
-    if (task.status !== 'running') return false
-    task.status = 'killed'
-    return true
-  }
-
-  /** Expose the protected notifier for tests. */
-  fire(task: BashTask): void {
-    this.notifyTaskDone(task)
-  }
-}
-
-async function setup() {
-  const ctx = new Context()
-  await ctx.plugin(StubExecutor)
-  // ctx.bash resolves to the registered implementation.
-  const bash = ctx.bash as StubExecutor
-  return { ctx, bash }
 }
 
 describe('BashExecutor service seam', () => {
-  it('registers as ctx.bash and serves the abstract API', async () => {
-    const { bash } = await setup()
-    const task = bash.start(bash.resolve({ command: 'sleep 1' }))
-    expect(bash.get(task.id)).toBe(task)
-    expect(bash.list()).toEqual([task])
-    expect(bash.kill(task.id)).toBe(true)
-    expect(bash.kill(task.id)).toBe(false)
-    const result = await bash.run(bash.resolve({ command: 'true' }))
-    expect(result.exitCode).toBe(0)
-  })
-
-  it('onTaskDone delivers completions to registered listeners', async () => {
-    const { bash } = await setup()
-    const seen: string[] = []
-    bash.onTaskDone(task => void seen.push(task.id))
-    const task = bash.start(bash.resolve({ command: 'x' }))
-    bash.fire(task)
-    expect(seen).toEqual([task.id])
-  })
-
-  it('onTaskDone disposer unsubscribes the listener', async () => {
-    const { bash } = await setup()
-    const listener = vi.fn()
-    const dispose = bash.onTaskDone(listener)
-    dispose()
-    bash.fire(bash.start(bash.resolve({ command: 'x' })))
-    expect(listener).not.toHaveBeenCalled()
-  })
-
-  it('listeners registered from a fiber are removed on dispose (HMR safety)', async () => {
-    const { ctx, bash } = await setup()
-    const listener = vi.fn()
-    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
-      inner.bash.onTaskDone(listener)
-    }, { inject: ['bash'] }))
-    bash.fire(bash.start(bash.resolve({ command: 'one' })))
-    expect(listener).toHaveBeenCalledTimes(1)
-
-    await fiber.dispose()
-    bash.fire(bash.start(bash.resolve({ command: 'two' })))
-    expect(listener).toHaveBeenCalledTimes(1)
-  })
-
-  it('silences listeners once the service fiber is disposed', async () => {
+  it('a concrete subclass registers as ctx.bash and serves the abstract API', async () => {
     const ctx = new Context()
-    const fiber = await ctx.plugin(Object.assign(async (inner: Context) => {
-      await inner.plugin(StubExecutor)
-    }, {}))
-    const bash = ctx.bash as StubExecutor
-    const listener = vi.fn()
-    bash.onTaskDone(listener)
-    const task = bash.start(bash.resolve({ command: 'x' }))
+    await ctx.plugin(StubExecutor)
+    const spec = ctx.bash.resolve({ command: 'echo hi' })
+    expect(spec).toEqual({ command: 'echo hi', workdir: '/stub', timeoutMs: 1000 })
 
-    await fiber.dispose()
-    bash.fire(task)
-    expect(listener).not.toHaveBeenCalled()
+    const result = await ctx.bash.run(spec)
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout.text).toBe('ok')
+
+    const proc = ctx.bash.start(spec)
+    expect(proc.command).toBe('echo hi')
+    expect(proc.status).toBe('running')
+    expect(proc.readOutput()).toEqual({ delta: '', lossy: false })
+    expect(proc.kill()).toBe(true)
+    expect(proc.kill()).toBe(false) // already settled → no-op
+    await proc.done
+  })
+
+  it('loading a second implementation throws (one bash service per context — cordis standard)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(StubExecutor)
+    class SecondExecutor extends StubExecutor {}
+    await expect(ctx.plugin(SecondExecutor)).rejects.toThrow(/service "bash" has been registered/)
   })
 })
diff --git a/packages/bash/bash/tsconfig.json b/packages/bash/bash/tsconfig.json
index 342f636170..754725418e 100644
--- a/packages/bash/bash/tsconfig.json
+++ b/packages/bash/bash/tsconfig.json
@@ -13,9 +13,6 @@
     },
     {
       "path": "../../../vendor/cordis"
-    },
-    {
-      "path": "../../util/brand"
     }
   ]
 }
diff --git a/packages/bash/tool-bash/README.md b/packages/bash/tool-bash/README.md
index eabb9298aa..44bc2f1b35 100644
--- a/packages/bash/tool-bash/README.md
+++ b/packages/bash/tool-bash/README.md
@@ -1,14 +1,18 @@
 # @deepseek-ai/dsh-tool-bash
 
-The model-facing bash tools — `bash`, `bash_output`, `bash_kill` — registered over the `ctx.bash` executor seam (`@deepseek-ai/dsh-bash`). Pure schema + text shaping; every process concern lives behind the seam, so sandboxed or remote executor implementations swap in without changing what the model sees.
+The model-facing `bash` tool, registered over the `ctx.bash` executor seam (`@deepseek-ai/dsh-bash`). Pure schema + text shaping; every process concern lives behind the seam, so sandboxed or remote executor implementations swap in without changing what the model sees. Background runs are generic tasks: the tool registers the started process with `ctx.tasks` (`@deepseek-ai/dsh-tasks`), and the model collects/stops them through the shared `task_output`/`task_list`/`task_kill` tools (`@deepseek-ai/dsh-tool-tasks`) — this package registers no companion tools of its own.
 
-Requires a loaded executor implementation (e.g. `@deepseek-ai/dsh-bash-local`); the plugin stays pending until `ctx.bash` exists (`inject: ['tools', 'bash', 'systemPrompt']`).
+Requires a loaded executor implementation (e.g. `@deepseek-ai/dsh-bash-local`); the plugin stays pending until `ctx.bash` exists (`inject: ['tools', 'bash', 'systemPrompt']`). The `ctx.tasks` runtime is looked up at call time: a background call without it fails loud (`background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks`).
 
 The plugin also contributes the `tool:bash` prompt section (order 105) — the cross-call habit the per-tool descriptions cannot carry: check the `[exit code: N]` marker on every result and investigate failures before moving on.
 
-## Tools
+## Config
 
-### `bash`
+| key | default | meaning |
+|---|---|---|
+| `enableRunInBackground` | `true` | Expose `run_in_background` in the schema. Disabled, the parameter is absent entirely (schema and capability never disagree) and the description says background execution is unavailable. |
+
+## The `bash` tool
 
 | Arg | Type | Notes |
 |---|---|---|
@@ -16,35 +20,23 @@ The plugin also contributes the `tool:bash` prompt section (order 105) — the c
 | `description` | string (required) | One-line, active-voice summary of the command (5-10 words), for UI/log display only — no effect on execution. |
 | `timeoutMs` | number | Timeout override in milliseconds. The executor applies its configured default and cap. |
 | `workdir` | string | Working directory for this call. Defaults to the calling agent's session cwd (`session.header.cwd`) so each session runs in its own workspace; a relative `workdir` is resolved against that session cwd. |
-| `run_in_background` | boolean | Return a task id immediately; no timeout applies. |
+| `run_in_background` | boolean | Return a task id immediately; no timeout applies. Present only when `enableRunInBackground` allows. |
 
 `command`, `workdir`, and `timeoutMs` are resolved against the executor's config defaults via `ctx.bash.resolve()` before execution, so the executor seam (`BashExecSpec`) receives explicit `workdir`/`timeoutMs` values. The workdir default is applied in the tool layer (from the calling agent's `session.header.cwd`) BEFORE `resolve()` — the per-session cwd must come from `exec.agent`, since N sessions share one executor; only when no session cwd is available does the executor fall back to its own config / `process.cwd()`.
 
-Result text: stdout, then a `[stderr]` section, then status markers — `[timed out after Nms]` whenever the executor's timer fired (reported independently of how the process ended, so a command that traps SIGTERM and exits 0 still shows it), `[killed by signal: …]` for a signal death, `[exit code: N]` for a non-zero exit (reported, **not** `isError`: the model decides how to react), and `[output truncated; full output: <path>]` when the tail was kept and a safe spill file is available. If the executor knows output was dropped but cannot safely advertise a complete spill file, the path is reported as `(unavailable)`. Only infrastructure failures (spawn errors, aborts) surface as `isError` results.
+Foreground result text: stdout, then a `[stderr]` section, then status markers — `[timed out after Nms]` whenever the executor's timer fired (reported independently of how the process ended, so a command that traps SIGTERM and exits 0 still shows it), `[killed by signal: …]` for a signal death, `[exit code: N]` for a non-zero exit (reported, **not** `isError`: the model decides how to react), and `[output truncated; full output: <path>]` when the tail was kept and a safe spill file is available. If the executor knows output was dropped but cannot safely advertise a complete spill file, the path is reported as `(unavailable)`. Only infrastructure failures (spawn errors, aborts) surface as `isError` results.
 
-### `bash_output`
+## Background runs as tasks
 
-`task_id` → output produced **since the previous `bash_output` call** plus a status line (`running` / `completed, exit code: N` / `killed`). Reads that lost data to buffer bounds say so and point at the full-output spill file when one is safely available, otherwise `(unavailable)`.
-
-### `bash_kill`
-
-`task_id` → ask the executor to kill the background task. The concrete executor decides how to signal or stop the process; killing an already-finished task is a reported no-op, and unknown ids are errors.
-
-### Task ownership (cross-session isolation)
-
-The owning agent's session token (`session.header.id`) is stamped onto the task at spawn — passed to the executor via `resolve({ …, owner })` and stored ON THE TASK inside the executor (the `dsh-bash` `ownerOf(id)` seam), **not** in a plugin-local map. `bash_output`/`bash_kill` compare `ctx.bash.ownerOf(id)` to the caller's token (`session.header.id`) with `!== undefined` semantics and reject a task owned by a *different* session with `task <id> belongs to another session` (a task started with no agent — a non-loop caller — has no owner token and is open to anyone; a call with no `exec.agent` cannot access an owned task). Task ids are global and predictable, so under multi-session ACP this token check is the fence that stops one session's agent from reading or killing another session's background task. Because ownership lives on the task in the executor (disposed with the `dsh-bash` fiber), it **survives an independent `tool-bash` HMR reload** — closing the old plugin-local-map gap where a reload orphaned pre-reload tasks. (The `onTaskDone` listener is still effect-scoped to this plugin's `apply`, so a completion landing during the reload gap still drops its one notice — the pre-existing reload-gap drop — but the ownership fence itself is HMR-proof.)
+A `run_in_background` call refuses an already-aborted `exec.signal`, starts the process through the seam, registers `{ kind: 'bash', label: command, owner: exec.agent, cancel, done, readOutput }` with `ctx.tasks`, and returns `started background task <id>`. The tool-call signal is deliberately NOT wired to the process after that — the parent step may end while the command runs; cancellation belongs to `task_kill` and the runtime's owner-disposal cleanup. The producer mapping is exported for tests: `processOutcome` (a killed process → `killed` with the signal as detail; everything else → `completed` with `exit code: N` — a nonzero exit is reported, not failed) and `renderProcessRead` (the incremental delta, plus a `[some output was dropped from memory; full output: …]` notice with spill paths on lossy reads). Ownership, isolation, listing, polling, waiting, kill semantics, and completion notices are all the task runtime's — see [`packages/tasks`](../../tasks/README.md).
 
 ## UI presentation
 
-These tools own how their calls render in a UI (an editor's tool-call card) via the `dsh-tools` `presentCall`/`presentResult` seam, each returning a `card`-tagged render intent — a UI never special-cases tool names. A FOREGROUND `bash` run declares a **terminal card**: `presentCall` returns `{ card: 'terminal', title, description?, cwd? }` — the **title** is the exact `command` ("ls -la src"), the model-written `description` rides along (rendered ABOVE the card), and `cwd` comes from the model `workdir` when given (absolute as-is, relative for the UI bridge to resolve against the session cwd; else left for the bridge to fill from the session cwd) — and `presentResult` returns `{ card: 'terminal', title?, output?, exitCode?, signal? }` carrying the raw output plus the parsed `exitCode`/`signal`, so a capable client (Zed) renders a terminal card with an exit-status pill. The result carries the raw `output`; the bridge DERIVES the ` ```console ` fenced fallback for a no-terminal-capability UI (the tool no longer encodes the fences itself), so the model-facing result text stays unfenced. A `run_in_background` call is NOT a terminal (it returns a task id immediately and never streams a terminal — poll with `bash_output`) and instead returns a **generic card** (`{ card: 'generic', title, kind: 'execute', rawInput: command, content: [description] }`); an `isError` result (spawn failure / abort) likewise returns a `generic` result view with no exit pill (there is no real process exit). `bash_output`/`bash_kill` return a `generic` card with a task-scoped title ("Read output from background task bash-3" / "Kill background task bash-3") and the task id as rawInput. These methods are pure/display-only (they also run on `session/load` replay), and a malformed/older logged arg shape falls back to a generic presentation rather than throwing. See `packages/core/tools` ("Tool-owned UI presentation") and `packages/ui/acp` ("Terminal card" / "Tool-call presentation").
-
-## Background completion notices
-
-When a background task finishes, a short notice is injected into the owning agent's session (`agent.inject()`, source `{kind: 'plugin', plugin: 'tool-bash'}`). The owning agent is found by its session token: the listener reads `ctx.bash.ownerOf(task.id)` and scans `ctx.get('agents')?.list()` for an agent whose `session.header.id` matches (read via `ctx.get` — `onTaskDone` runs on the bash fiber, a foreign fiber, so the `ctx.agents` proxy would throw). If no live agent carries that token — e.g. the owning session disconnected and its agent was disposed while the task ran on — the notice is dropped cleanly. Injection is **durable context for the next model request, not a wake-up** — an idle agent stays idle until something sends a message. That's why the tool descriptions tell the model to poll with `bash_output`.
+These tools own how their calls render in a UI (an editor's tool-call card) via the `dsh-tools` `presentCall`/`presentResult` seam, each returning a `card`-tagged render intent — a UI never special-cases tool names. A FOREGROUND `bash` run declares a **terminal card**: `presentCall` returns `{ card: 'terminal', title, description?, cwd? }` — the **title** is the exact `command` ("ls -la src"), the model-written `description` rides along (rendered ABOVE the card), and `cwd` comes from the model `workdir` when given (absolute as-is, relative for the UI bridge to resolve against the session cwd; else left for the bridge to fill from the session cwd) — and `presentResult` returns `{ card: 'terminal', title?, output?, exitCode?, signal? }` carrying the raw output plus the parsed `exitCode`/`signal`, so a capable client (Zed) renders a terminal card with an exit-status pill. The result carries the raw `output`; the bridge DERIVES the ` ```console ` fenced fallback for a no-terminal-capability UI (the tool no longer encodes the fences itself), so the model-facing result text stays unfenced. A `run_in_background` call is NOT a terminal (it returns a task id immediately and never streams a terminal — its output is read via `task_output`) and instead returns a **generic card** (`{ card: 'generic', title, kind: 'execute', rawInput: command, content: [description] }`); an `isError` result (spawn failure / abort) likewise returns a `generic` result view with no exit pill (there is no real process exit). These methods are pure/display-only (they also run on `session/load` replay), and a malformed/older logged arg shape falls back to a generic presentation rather than throwing. See `packages/core/tools` ("Tool-owned UI presentation") and `packages/ui/acp` ("Terminal card" / "Tool-call presentation").
 
 ## The tool builds its request from named args only
 
-The `BashExecRequest` seam carries optional `stdin` and `env`, used by the hooks bridges to feed a hook command its JSON payload and `CLAUDE_*` env. This tool does **not** expose them as parameters: its request is built from `command`/`workdir`/`timeoutMs`/`signal`/`owner` only, so a model that includes `env` or `stdin` keys in its tool arguments has them ignored. This is not a trust boundary — a model already has equivalent power through shell syntax (`FOO=bar cmd`, a heredoc), and the real defense against leaking the harness's ambient secrets is `dsh-bash-local`'s credential scrub, which works regardless. A regression guard drives the real tool with those extra args and asserts the resulting request carries neither field — its job is to catch a future refactor that blindly spreads `...args` into the request (which would silently forward model input into the post-scrub `env` merge), not to defend a wall. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
+The `BashExecRequest` seam carries optional `stdin` and `env`, used by the hooks bridges to feed a hook command its JSON payload and `CLAUDE_*` env. This tool does **not** expose them as parameters: its request is built from `command`/`workdir`/`timeoutMs`/`signal` only, so a model that includes `env` or `stdin` keys in its tool arguments has them ignored. This is not a trust boundary — a model already has equivalent power through shell syntax (`FOO=bar cmd`, a heredoc), and the real defense against leaking the harness's ambient secrets is `dsh-bash-local`'s credential scrub, which works regardless. A regression guard drives the real tool with those extra args and asserts the resulting request carries neither field — its job is to catch a future refactor that blindly spreads `...args` into the request (which would silently forward model input into the post-scrub `env` merge), not to defend a wall. See [the bash-stdin-env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md).
 
 ## Permissions
 
diff --git a/packages/bash/tool-bash/package.json b/packages/bash/tool-bash/package.json
index d8836d6a21..728f29a7ca 100644
--- a/packages/bash/tool-bash/package.json
+++ b/packages/bash/tool-bash/package.json
@@ -26,9 +26,13 @@
     "@deepseek-ai/dsh-bash": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "@deepseek-ai/dsh-tasks": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
@@ -37,6 +41,8 @@
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tasks": "workspace:^",
+    "@deepseek-ai/dsh-tool-tasks": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "cordis": "^4.0.0-rc.6"
   }
diff --git a/packages/bash/tool-bash/src/index.ts b/packages/bash/tool-bash/src/index.ts
index d4a3105165..bb02b67b00 100644
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -1,34 +1,22 @@
 /**
- * The model-facing bash tools: `bash`, `bash_output`, `bash_kill`. Pure
- * schema + text shaping — every process concern lives behind the `ctx.bash`
- * executor seam (`@deepseek-ai/dsh-bash`), so sandbox/permission/remote
- * executor implementations swap in without touching what the model sees.
+ * The model-facing `bash` tool. Pure schema + text shaping — every process
+ * concern lives behind the `ctx.bash` executor seam (`@deepseek-ai/dsh-bash`),
+ * so sandbox/permission/remote executor implementations swap in without
+ * touching what the model sees.
  *
- * Background notifications: when a background task completes, a short notice
- * is injected into the owning agent's session (`agent.inject()` — the
- * documented context seam). Injection is durable context for the NEXT model
- * request, not a wake-up: an idle agent stays idle until something sends a
- * message, which is why the tool descriptions tell the model to poll with
- * `bash_output`.
+ * Background runs are TASKS, not bash-private state: `run_in_background`
+ * starts a process through the seam and registers its handle with the generic
+ * `ctx.tasks` runtime (`@deepseek-ai/dsh-tasks`), which owns the id, the
+ * owner fence, the completion notice, and the model-facing collect/stop
+ * tools (`task_output`/`task_list`/`task_kill` from
+ * `@deepseek-ai/dsh-tool-tasks`). Whether the parameter is exposed at all is
+ * THIS plugin's `enableRunInBackground` config (default on) — the registry
+ * never rewrites a producer's schema.
  *
- * Task ownership: a background task's OWNER is an opaque token — the owning
- * agent's `session.header.id` — passed to the executor at spawn
- * (`resolve({ …, owner })`) and stored ON THE TASK inside the executor
- * (`@deepseek-ai/dsh-bash`'s `ownerOf(id)` seam), NOT in a plugin-local map.
- * `bash_output`/`bash_kill` compare `ctx.bash.ownerOf(id)` to the caller's token
- * and reject a task owned by a DIFFERENT session (`owner !== undefined && owner
- * !== caller`); an unowned task (no token — started by a non-agent caller) is
- * open to anyone. Task ids are global and predictable (`bash-1`, …); under
- * multi-session ACP (RFC 011) this token check is the fence that stops one
- * session's agent from reading or killing another session's background task.
- *
- * Storing the token on the task in the EXECUTOR (disposed with the `dsh-bash`
- * fiber), rather than in this plugin, is what makes ownership survive a
- * `tool-bash` HMR reload — a reload that reset a plugin-local map would orphan
- * a task spawned before it. (The `onTaskDone` listener is still effect-scoped
- * to this plugin's `apply`, so a
- * completion landing during the reload gap still drops its one notice — the
- * pre-existing reload-gap drop — but the ownership fence itself is HMR-proof.)
+ * The tool-call abort signal is deliberately NOT wired to a background
+ * process: after the task id is returned the parent step may end while the
+ * work continues; cancellation belongs to `task_kill` and the owner-disposal
+ * cleanup. A signal already aborted before the call refuses to start.
  *
  * TODO(permissions): commands run with the executor's full authority. The
  * permission/sandbox seam is the `tools/pre-execute` waterfall (deny/ask) plus
@@ -39,17 +27,33 @@
  */
 
 import type { Context } from 'cordis'
+import z from 'schemastery'
 import { isAbsolute, resolve as resolvePath } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView, TerminalCallView, ToolResult, ToolResultView } from '@deepseek-ai/dsh-tools'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-system-prompt'
-import { BashTaskId, OwnerToken } from '@deepseek-ai/dsh-bash'
-import type { BashRunResult, BashTask, CollectedOutput } from '@deepseek-ai/dsh-bash'
+import type {} from '@deepseek-ai/dsh-tasks'
+import type { BashProcess, BashProcessRead, BashRunResult, CollectedOutput } from '@deepseek-ai/dsh-bash'
 
 export const name = 'tool-bash'
 export const inject = ['tools', 'bash', 'systemPrompt']
 
+/** Config: whether the model may background commands (the producer-opt-in flag). */
+export interface Config {
+  /**
+   * Expose `run_in_background` in the bash schema (default true). Disabled,
+   * the parameter is absent entirely — schema and capability never disagree.
+   * Backgrounding also needs the `ctx.tasks` runtime at call time; a missing
+   * one fails the call loud with the load-these-packages message.
+   */
+  enableRunInBackground?: boolean
+}
+
+export const Config: z<Config> = z.object({
+  enableRunInBackground: z.boolean().default(true),
+})
+
 /**
  * Validate the constraints the SchemaSpec can't express. `defineTool` now
  * validates parsed args against the SchemaSpec before `execute` runs (the
@@ -76,18 +80,6 @@ function validateBashArgs(args: {
   }
 }
 
-/**
- * Reject an empty `task_id`. Type and presence are guaranteed by the
- * SchemaSpec validation (the arg-validation RFC); only the non-empty constraint, which the
- * DSL can't express, is left to check here.
- */
-function validateTaskId(value: string): BashTaskId {
-  if (value.length === 0) {
-    throw new Error(`invalid task_id: expected a string, got ${JSON.stringify(value)}`)
-  }
-  return BashTaskId(value)
-}
-
 /** Append the truncation notice (with the full-output spill path) to a stream's text. */
 function streamText(output: CollectedOutput): string {
   if (!output.truncated) return output.text
@@ -131,6 +123,39 @@ export function renderResult(result: BashRunResult): string {
   return body + markers.join('\n')
 }
 
+/**
+ * Shape one background-process read into the `task_output` delta the model
+ * sees: the incremental delta, plus the lossy-read notice (with full-stream
+ * spill paths) when in-memory truncation dropped unread bytes. Empty-delta
+ * rendering (`(no new output)`) is the control surface's job, not this
+ * producer's. Exported for tests.
+ * @param read - one incremental read from the process handle.
+ * @returns the delta text with any loss notice appended.
+ */
+export function renderProcessRead(read: BashProcessRead): string {
+  if (!read.lossy) return read.delta
+  const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((p): p is string => p !== undefined)
+  const notice = `[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(', ') : '(unavailable)'}]`
+  if (read.delta.length === 0) return notice
+  return `${read.delta}${read.delta.endsWith('\n') ? '' : '\n'}${notice}`
+}
+
+/**
+ * Map a settled background process onto the generic task-outcome vocabulary:
+ * `killed` stays `killed` (detail: the signal when one is known), everything
+ * else is `completed` with the exit code as detail — a nonzero exit is
+ * REPORTED, not failed, exactly like the foreground rendering. Exported for
+ * tests.
+ * @param proc - the settled process handle.
+ * @returns the outcome for the `ctx.tasks` registration.
+ */
+export function processOutcome(proc: BashProcess): { status: 'completed' | 'killed'; detail: string } {
+  if (proc.status === 'killed') {
+    return { status: 'killed', detail: proc.signal !== null ? `signal: ${proc.signal}` : 'killed before exit' }
+  }
+  return { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` }
+}
+
 // ---------------------------------------------------------------------------
 // UI presentation (tool-owned). These shape how a UI (e.g. the ACP bridge)
 // renders a bash call's pending and completed states. They are display-only and
@@ -153,7 +178,7 @@ export function renderResult(result: BashRunResult): string {
  * `terminal` marks the call so a capable UI renders a TERMINAL card — but ONLY a
  * FOREGROUND run is a terminal: a `run_in_background` call returns a task id
  * immediately (it never streams a terminal; its output is polled via
- * `bash_output`), so it is NOT marked terminal and renders as an ordinary
+ * `task_output`), so it is NOT marked terminal and renders as an ordinary
  * execute card. For a foreground run the `terminal.cwd` (header) is the model
  * `workdir` when given — ABSOLUTE as-is, RELATIVE for the UI bridge to resolve
  * against the session cwd; when omitted the bridge fills the session workspace
@@ -253,11 +278,6 @@ function parseExitStatus(text: string): { exitCode: number } | { signal: string
   return { exitCode: 0 }
 }
 
-/** Pending-state presentation for `bash_output`/`bash_kill` (background-task tools). */
-function presentTaskCall(verb: string, args: { task_id: string }): GenericCallView {
-  return { card: 'generic', title: `${verb} background task ${args.task_id}`, kind: 'execute', rawInput: args.task_id }
-}
-
 /**
  * Resolve the working directory for a bash call. Precedence: an explicit model
  * `workdir` wins; otherwise default to the calling agent's session cwd
@@ -278,18 +298,11 @@ function resolveWorkdir(modelWorkdir: string | undefined, exec: { agent?: Agent
   return modelWorkdir
 }
 
-/** Status line for background task reads. */
-function statusLine(task: BashTask): string {
-  switch (task.status) {
-    case 'running': return '[status: running]'
-    case 'killed': return `[status: killed${task.signal !== null ? ` by ${task.signal}` : ''}]`
-    case 'completed': return `[status: completed, exit code: ${task.exitCode ?? 0}]`
-  }
-}
+export function apply(ctx: Context, config: Config): void {
+  const backgroundEnabled = config.enableRunInBackground ?? true
 
-export function apply(ctx: Context): void {
-  // The bash tools' cross-call HABIT, which the per-tool descriptions cannot
-  // carry (they describe one call each): the exit-code marker is only useful
+  // The bash tool's cross-call HABIT, which the per-tool description cannot
+  // carry (it describes one call): the exit-code marker is only useful
   // if the model actually checks it every time.
   ctx.systemPrompt.section({
     name: 'tool:bash',
@@ -297,72 +310,16 @@ export function apply(ctx: Context): void {
     text: 'Check the [exit code: N] marker on every bash result; investigate failures before moving on.',
   })
 
-  /**
-   * The caller's owner TOKEN — the owning agent's `session.header.id`, or
-   * `undefined` for a non-agent caller. Read `session.header.id` (NOT
-   * `session.id`): every other subsystem keys off the header id (the ACP bridge,
-   * both persistence backends), and the sibling `resolveWorkdir` already reads
-   * `session.header.cwd`, so using `session.id` here would be the asymmetry smell
-   * the conventions flag. The two are equal in production, but the header is the
-   * canonical identity.
-   */
-  const callerToken = (exec: { agent?: Agent }): OwnerToken | undefined =>
-    exec.agent ? OwnerToken(exec.agent.session.header.id) : undefined
-
-  /**
-   * Authorize a `bash_output`/`bash_kill` call against the task's stored owner
-   * token. Rejects when the task HAS an owner and it differs from the caller's
-   * token — using `!== undefined` semantics, NOT truthiness, so an empty-string
-   * token is still a real owner (never treated as unowned). An unowned task
-   * (`ownerOf` returns `undefined`) is allowed; a truly unknown id is also
-   * `undefined` here and then fails loudly at the subsequent
-   * `readOutput`/`kill` ("unknown bash task"). The conservative no-agent caller
-   * (`callerToken` undefined) cannot match an owned task and is rejected.
-   */
-  const assertTaskAccess = (taskId: BashTaskId, exec: { agent?: Agent }): void => {
-    const owner = ctx.bash.ownerOf(taskId)
-    if (owner !== undefined && owner !== callerToken(exec)) {
-      throw new Error(`task ${taskId} belongs to another session`)
-    }
-  }
-
-  // Background completion → inject a notice into the owning agent's session.
-  // Find the live agent by its session id token via the agent registry, read
-  // opportunistically with `ctx.get('agents')` (NOT `ctx.agents`/static inject):
-  // this listener runs from `task.done.then` on the bash fiber — a foreign
-  // fiber — where the `ctx.agents` property proxy would throw through the
-  // traceable shadow; `ctx.get(name)` is the topology-independent lookup. No
-  // registry mounted (`undefined`) → drop the notice. Match on
-  // `agent.session.header.id`, NOT the registry key: a config agent's id differs
-  // from its session id, and the owner token IS the session id.
-  ctx.bash.onTaskDone((task) => {
-    const ownerToken = ctx.bash.ownerOf(task.id)
-    if (ownerToken === undefined) return
-    const agent = ctx.get('agents')?.list().find(a => OwnerToken(a.session.header.id) === ownerToken)
-    if (!agent) return
-    try {
-      agent.inject(
-        [{ type: 'text', text: `background bash task ${task.id} finished ${statusLine(task)}. Read its output with bash_output.` }],
-        { source: { kind: 'plugin', plugin: 'tool-bash' } },
-      )
-    } catch (error: unknown) {
-      // The ONE expected failure: the agent was disposed between task
-      // completion and this injection (ReactLoopAgent.inject throws
-      // `agent "<id>" is disposed`). That race is benign — drop the notice.
-      // Anything else is a real bug and must surface, not be swallowed.
-      if (error instanceof Error && error.message.includes('is disposed')) return
-      throw error
-    }
-  })
-
   ctx.tools.register(defineTool({
     name: 'bash',
     description: 'Execute a bash command (`bash -c`) and return its stdout/stderr. '
       + 'Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — '
       + 'pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. '
       + 'Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. '
-      + 'Set `run_in_background: true` for long-running commands: the call returns a task id immediately; '
-      + 'poll it with `bash_output` and stop it with `bash_kill`.',
+      + (backgroundEnabled
+        ? 'Set `run_in_background: true` for long-running commands: the call returns a task id immediately; '
+          + 'read its output with `task_output` and stop it with `task_kill`.'
+        : 'Background execution is not available; long-running commands must finish within the timeout.'),
     parameters: {
       command: { type: 'string', required: true, description: 'The bash command to execute.' },
       description: {
@@ -374,7 +331,9 @@ export function apply(ctx: Context): void {
       },
       timeoutMs: { type: 'number', description: 'Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry.' },
       workdir: { type: 'string', description: 'Working directory for this command. Defaults to the session workspace; a relative path is resolved against it.' },
-      run_in_background: { type: 'boolean', description: 'Run in the background and return a task id immediately. No timeout applies.' },
+      ...backgroundEnabled ? {
+        run_in_background: { type: 'boolean' as const, description: 'Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies.' },
+      } : {},
     },
     async execute(args, exec) {
       validateBashArgs(args)
@@ -389,65 +348,48 @@ export function apply(ctx: Context): void {
         command: args.command,
         ...workdir !== undefined ? { workdir } : {},
         ...args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {},
-        ...exec.signal ? { signal: exec.signal } : {},
       }
       if (args.run_in_background === true) {
-        // Stamp the owner token (the agent's session id) onto the spec so the
-        // executor stores it on the task — the isolation fence for bash_output/
-        // bash_kill. Foreground runs pass no owner (they finish inline; nothing
-        // to fence).
-        const task = ctx.bash.start(ctx.bash.resolve({ ...request, owner: callerToken(exec) }))
-        return [{ type: 'text', text: `started background task ${task.id}` }]
+        // The generic runtime owns everything task-shaped; without it a task
+        // id would be uncollectable — fail loud with the fix, not a dangle.
+        const tasks = ctx.get('tasks')
+        if (tasks === undefined) {
+          throw new Error('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
+        }
+        // A step already cancelled must not spawn; after the id is returned
+        // the tool-call signal is deliberately NOT wired to the process
+        // (cancellation belongs to task_kill / owner cleanup), so the check
+        // happens here, once, instead of passing the signal to start().
+        if (exec.signal?.aborted) throw new Error('command aborted')
+        const proc = ctx.bash.start(ctx.bash.resolve(request))
+        let id: string
+        try {
+          id = tasks.register({
+            kind: 'bash',
+            label: args.command,
+            ...exec.agent ? { owner: exec.agent } : {},
+            cancel: () => void proc.kill(),
+            done: proc.done.then(() => processOutcome(proc)),
+            readOutput: () => renderProcessRead(proc.readOutput()),
+          })
+        } catch (error: unknown) {
+          // A failed registration must not leak the just-started process: the
+          // model never received an id, so nothing could ever task_kill it.
+          // Kill, await quiescence, then fail the call with the real cause.
+          proc.kill()
+          await proc.done
+          throw error
+        }
+        return [{ type: 'text', text: `started background task ${id}` }]
       }
-      const result = await ctx.bash.run(ctx.bash.resolve(request))
+      const result = await ctx.bash.run(ctx.bash.resolve({
+        ...request,
+        ...exec.signal ? { signal: exec.signal } : {},
+      }))
       if (result.aborted) throw new Error('command aborted')
       return [{ type: 'text', text: renderResult(result) }]
     },
     presentCall: presentBashCall,
     presentResult: presentBashResult,
   }))
-
-  ctx.tools.register(defineTool({
-    name: 'bash_output',
-    description: 'Read new output from a background bash task started with `bash` + `run_in_background`. '
-      + 'Returns only output produced since the previous bash_output call, plus the task status. '
-      + 'Tasks keep running while you do other work; poll again later for more output.',
-    parameters: {
-      task_id: { type: 'string', required: true, description: 'Task id returned by the bash tool.' },
-    },
-    // execute is synchronous (registry reads + string shaping) but the
-    // ToolDefinition contract wants a Promise — hence resolve(), not async.
-    execute(args, exec) {
-      const id = validateTaskId(args.task_id)
-      assertTaskAccess(id, exec)
-      const read = ctx.bash.readOutput(id)
-      let text = read.delta.length > 0 ? read.delta : '(no new output)'
-      if (read.lossy) {
-        const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((p): p is string => p !== undefined)
-        const fullOutput = paths.length > 0 ? paths.join(', ') : '(unavailable)'
-        text += `\n[some output was dropped from memory; full output: ${fullOutput}]`
-      }
-      text += `\n${statusLine(read.task)}`
-      return Promise.resolve([{ type: 'text', text }])
-    },
-    presentCall: args => presentTaskCall('Read output from', args),
-  }))
-
-  ctx.tools.register(defineTool({
-    name: 'bash_kill',
-    description: 'Ask the executor to kill a running background bash task by task id.',
-    parameters: {
-      task_id: { type: 'string', required: true, description: 'Task id returned by the bash tool.' },
-    },
-    execute(args, exec) {
-      const id = validateTaskId(args.task_id)
-      assertTaskAccess(id, exec)
-      const killed = ctx.bash.kill(id)
-      return Promise.resolve([{
-        type: 'text',
-        text: killed ? `killed background task ${id}` : `task ${id} had already finished`,
-      }])
-    },
-    presentCall: args => presentTaskCall('Kill', args),
-  }))
 }
diff --git a/packages/bash/tool-bash/tests/integration.spec.ts b/packages/bash/tool-bash/tests/integration.spec.ts
index b3d6bb3f77..238176b8a6 100644
--- a/packages/bash/tool-bash/tests/integration.spec.ts
+++ b/packages/bash/tool-bash/tests/integration.spec.ts
@@ -7,15 +7,17 @@ import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
 import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import TaskService from '@deepseek-ai/dsh-tasks'
+import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
-import { BashTaskId } from '@deepseek-ai/dsh-bash'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 
 /**
  * Full-loop integration: a scripted mock model drives the REAL bash tool
  * through the agent loop, exercising the same seams a live model would
- * (tool/call + tool/result session events, agent.inject notifications).
+ * (tool/call + tool/result session events, the generic `ctx.tasks` runtime,
+ * agent.inject completion notices).
  */
 async function harness(adapter: MockAdapter) {
   const ctx = new Context()
@@ -25,6 +27,8 @@ async function harness(adapter: MockAdapter) {
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(TaskService)
+  await ctx.plugin(ToolTasks)
   await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000 })
   await ctx.plugin(ToolBash)
   ctx.llm.registerAdapter(['mock'], adapter)
@@ -67,6 +71,16 @@ function resultText(event: SessionEvent): string {
     .join('')
 }
 
+/** Poll until `predicate` holds (background settlement races turn end). */
+async function pollUntil(predicate: () => boolean, timeoutMs = 5_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    if (predicate()) return
+    await new Promise(resolve => setTimeout(resolve, 20))
+  }
+  throw new Error(`condition not met within ${timeoutMs}ms`)
+}
+
 describe('bash tool through the agent loop', () => {
   it('foreground: model calls bash, sees the result, replies', async () => {
     const adapter = new MockAdapter([
@@ -116,53 +130,41 @@ describe('bash tool through the agent loop', () => {
     expect(resultText(toolResult)).toContain('[exit code: 9]')
   })
 
-  it('background: start → poll → completion notice lands as context/message', async () => {
+  it('background: start ack → completion notice as context/message → task_output collects it', async () => {
+    // The task id is deterministic (a fresh TaskService counts per kind from 1),
+    // so the script can name `bash-1` without threading a generated id.
     const adapter = new MockAdapter([
       toolCallResponse('call-1', 'bash', { command: 'echo bg-ok', description: 'test command', run_in_background: true }),
-      toolCallResponse('call-2', 'bash_output', {}, undefined),
+      textResponse('Started it in the background.'),
+      toolCallResponse('call-2', 'task_output', { task_id: 'bash-1' }),
       textResponse('Background task finished.'),
     ])
-    // The second tool call needs the REAL task id from the first result;
-    // a tools/pre-execute listener rewrites the scripted arguments. (This uses
-    // the low-level capability to mutate `exec` before dispatch — the
-    // unadvertised mechanism behind a future first-class input-rewrite decision;
-    // here it is a test shim to thread the generated id, not a product feature.)
-    let taskId = ''
-
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('it-bg'), { model: 'mock' })
 
-    // Intercept the first tool result to capture the generated task id, then
-    // rewrite the second scripted call's arguments to use it.
-    ctx.on('session/event', (_session, event) => {
-      if (event.type === 'tool/result' && taskId === '') {
-        const match = /task (bash-\d+)/.exec(resultText(event))
-        if (match) taskId = match[1]!
-      }
-    })
-    ctx.on('tools/pre-execute', async (exec, next) => {
-      if (exec.name === 'bash_output') {
-        exec.arguments = { task_id: taskId }
-      }
-      return next()
-    })
-
     agent.send([{ type: 'text', text: 'run echo bg-ok in the background' }])
     await waitForIdle(ctx, agent)
 
-    // Wait for the background task itself (completion may race turn end).
-    const task = ctx.bash.get(BashTaskId(taskId))
-    if (!task) throw new Error(`task ${taskId} not registered`)
-    await task.done
+    const firstResult = findEvent(events(agent), 'tool/result')
+    expect(firstResult.data.isError).toBe(false)
+    expect(resultText(firstResult)).toBe('started background task bash-1')
 
-    const log = events(agent)
-    const firstResult = findEvent(log, 'tool/result')
-    expect(resultText(firstResult)).toBe(`started background task ${taskId}`)
-
-    const notice = findEvent(log, 'context/message')
+    // The task settles on its own; the tool-tasks notice listener injects a
+    // durable context/message into the owning agent's session (settlement may
+    // race turn end, so poll for it).
+    await pollUntil(() => events(agent).some(event => event.type === 'context/message'))
+    const notice = findEvent(events(agent), 'context/message')
     expect(notice.data.content.some(
-      block => block.type === 'text' && block.text.includes(`background bash task ${taskId} finished`),
+      block => block.type === 'text' && block.text.includes('background task bash-1 (bash: echo bg-ok) finished'),
     )).toBe(true)
-    expect(notice.data.source).toEqual({ kind: 'plugin', plugin: 'tool-bash' })
+    expect(notice.data.source).toEqual({ kind: 'plugin', plugin: 'tool-tasks' })
+
+    // The next turn collects the output through the generic task tool.
+    agent.send([{ type: 'text', text: 'collect it' }])
+    await waitForIdle(ctx, agent)
+    const readResult = findEvent(events(agent), 'tool/result', 'last')
+    expect(readResult.data.isError).toBe(false)
+    expect(resultText(readResult)).toContain('bg-ok')
+    expect(resultText(readResult)).toContain('[status: completed, exit code: 0]')
   })
 })
diff --git a/packages/bash/tool-bash/tests/tools.spec.ts b/packages/bash/tool-bash/tests/tools.spec.ts
index 7d4b34f74f..7aebb310c8 100644
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -1,21 +1,24 @@
 import { mkdtempSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
-import { BashExecutor, BashTaskId } from '@deepseek-ai/dsh-bash'
-import type { BashExecRequest, BashExecSpec, BashRunResult, BashTask, BashTaskRead, OwnerToken } from '@deepseek-ai/dsh-bash'
+import { BashExecutor } from '@deepseek-ai/dsh-bash'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashProcessRead, BashRunResult } from '@deepseek-ai/dsh-bash'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+import TaskService from '@deepseek-ai/dsh-tasks'
+import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
-import { renderResult } from '@deepseek-ai/dsh-tool-bash'
+import { processOutcome, renderProcessRead, renderResult } from '@deepseek-ai/dsh-tool-bash'
 
 const spillDir = mkdtempSync(join(tmpdir(), 'dsh-tool-bash-spec-'))
 
+/** Foreground-only harness: no task runtime (backgrounding fails loud here). */
 async function setup() {
   const ctx = new Context()
   await ctx.plugin(SystemPrompt)
@@ -27,39 +30,36 @@ async function setup() {
   return ctx
 }
 
+/** Full harness: the generic task runtime + its control surface, then the bash tool. */
+async function setupWithTasks() {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(TaskService)
+  await ctx.plugin(ToolTasks)
+  await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 })
+  ;(ctx.bash as LocalBashExecutor).internals = { spillDir }
+  await ctx.plugin(ToolBash)
+  return ctx
+}
+
 /**
- * Build a fake {@link Agent} whose session token is `sessionId`, REGISTER it in
- * `ctx.agents` (the completion-notice path finds the owning agent by scanning
- * the registry for a matching `session.header.id`), and return it. The returned
- * agent is also passed to `execute` as `exec.agent` so it owns the spawned task.
- * The registration disposer is tracked so {@link unregisterFakeAgents} can drop
- * it (simulating the owning session disconnecting before a task completes).
+ * Build a fake {@link Agent} whose session token is `sessionId` and REGISTER it
+ * in `ctx.agents` (an owned task registration attaches the awaited owner
+ * cleanup via `ctx.agents.onCleanup`, which requires a live registered agent).
+ * The agent id is deliberately DIFFERENT from the session token so a
+ * wrong-field match fails the test.
  */
-const fakeAgentDisposers = new Map<Context, (() => void)[]>()
-function registerFakeAgent(ctx: Context, sessionId: string, inject: (...args: unknown[]) => void): Agent {
-  // The registry KEY (agent.id) is deliberately DIFFERENT from the session
-  // token (session.header.id) — a config agent has `agentId !== sessionId`. The
-  // owner token IS the session id, so the notice path must find the agent by
-  // `session.header.id`, NOT the registry key. Using distinct values here makes
-  // the test fail if a regression matched on the wrong field (a same-value fake
-  // would pass either way — the "hits the line but not the scenario" trap).
-  const agent = { id: `agent-${sessionId}`, inject, session: { header: { version: 0, id: sessionId, createdAt: 0 } } } as unknown as Agent
-  const dispose = ctx.agents.register(agent)
-  const list = fakeAgentDisposers.get(ctx) ?? []
-  list.push(dispose)
-  fakeAgentDisposers.set(ctx, list)
+function registerFakeAgent(ctx: Context, sessionId: string): Agent {
+  const agent = { id: `agent-${sessionId}`, inject: () => {}, session: { header: { version: 0, id: sessionId, createdAt: 0 } } } as unknown as Agent
+  ctx.agents.register(agent)
   return agent
 }
 
-/** Unregister every fake agent in this ctx (simulate the owning session disconnecting). */
-function unregisterFakeAgents(ctx: Context): void {
-  for (const dispose of fakeAgentDisposers.get(ctx) ?? []) dispose()
-  fakeAgentDisposers.delete(ctx)
-}
-
 let callCounter = 0
-function call(ctx: Context, name: string, args: unknown) {
-  return ctx.tools.execute({ callId: CallId(`call-${++callCounter}`), name, arguments: args })
+function call(ctx: Context, name: string, args: unknown, agent?: Agent) {
+  return ctx.tools.execute({ callId: CallId(`call-${++callCounter}`), name, arguments: args, ...agent ? { agent } : {} })
 }
 
 function text(result: { content: { type: string; text?: string }[] }): string {
@@ -83,56 +83,6 @@ async function callUntilText(
   throw new Error(`${name} output did not include ${JSON.stringify(expected)}; last text was ${JSON.stringify(last !== undefined ? text(last) : '')}`)
 }
 
-class LossyReadBashExecutor extends BashExecutor {
-  private readonly task: BashTask = {
-    id: BashTaskId('bash-lossy'),
-    command: 'fake',
-    status: 'running',
-    exitCode: null,
-    signal: null,
-    done: Promise.resolve(),
-  }
-
-  resolve(request: BashExecRequest): BashExecSpec {
-    return {
-      command: request.command,
-      workdir: request.workdir ?? process.cwd(),
-      timeoutMs: request.timeoutMs ?? 0,
-      ...request.signal ? { signal: request.signal } : {},
-      owner: request.owner,
-    }
-  }
-
-  run(): Promise<BashRunResult> {
-    return Promise.reject(new Error('not used'))
-  }
-
-  start(): BashTask {
-    return this.task
-  }
-
-  get(id: BashTaskId): BashTask | undefined {
-    return id === this.task.id ? this.task : undefined
-  }
-
-  ownerOf(): OwnerToken | undefined {
-    return undefined
-  }
-
-  list(): BashTask[] {
-    return [this.task]
-  }
-
-  readOutput(id: BashTaskId): BashTaskRead {
-    if (id !== this.task.id) throw new Error(`unknown bash task "${id}"`)
-    return { task: this.task, delta: 'tail', lossy: true }
-  }
-
-  kill(): boolean {
-    return false
-  }
-}
-
 describe('bash tool', () => {
   it('returns stdout for a successful command', async () => {
     const ctx = await setup()
@@ -205,7 +155,7 @@ describe('bash tool', () => {
     expect(text(result)).toMatch(/ENOENT/)
   })
 
-  it('surfaces aborts as isError', async () => {
+  it('surfaces foreground aborts as isError', async () => {
     const ctx = await setup()
     const controller = new AbortController()
     const pending = ctx.tools.execute({
@@ -220,7 +170,7 @@ describe('bash tool', () => {
     expect(text(result)).toMatch(/aborted/)
   })
 
-  // Type and required-key violations are now rejected by the harness
+  // Type and required-key violations are rejected by the harness
   // (defineTool validates against the SchemaSpec — the arg-validation RFC) before execute.
   it.each([
     [{}, /missing required property "command"/],
@@ -250,15 +200,18 @@ describe('bash tool', () => {
     expect(text(result)).toMatch(pattern)
   })
 
-  it('registers all three schemas in the system prompt assembly', async () => {
+  it('registers the bash schema with run_in_background exposed by default', async () => {
     const ctx = await setup()
-    const names = ctx.tools.schemas().map(schema => schema.name)
-    expect(names).toEqual(['bash', 'bash_output', 'bash_kill'])
-    const bashSchema = ctx.tools.schemas()[0]!
+    const schemas = ctx.tools.schemas()
+    expect(schemas.map(schema => schema.name)).toEqual(['bash'])
+    const bashSchema = schemas[0]!
     expect(bashSchema.parameters).toMatchObject({
       type: 'object',
       required: ['command', 'description'],
     })
+    expect(Object.keys(bashSchema.parameters.properties as Record<string, unknown>))
+      .toContain('run_in_background')
+    expect(bashSchema.description).toContain('task_output')
   })
 
   it('contributes the exit-code habit as its prompt section (guidance the descriptions cannot carry)', async () => {
@@ -275,7 +228,7 @@ describe('bash tool', () => {
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(LocalBashExecutor, {})
     const fiber = await ctx.plugin(ToolBash)
-    expect(ctx.tools.schemas()).toHaveLength(3)
+    expect(ctx.tools.schemas()).toHaveLength(1)
     expect((await ctx.systemPrompt.assemble()).sections.map(s => s.name)).toEqual(['harness:identity', 'deployment:persona', 'tool:bash'])
     await fiber.dispose()
     expect(ctx.tools.schemas()).toHaveLength(0)
@@ -292,348 +245,274 @@ describe('bash tool', () => {
     expect(ctx.tools.schemas()).toHaveLength(0)
     await ctx.plugin(LocalBashExecutor, {})
     await new Promise(resolve => setTimeout(resolve, 0))
-    expect(ctx.tools.schemas()).toHaveLength(3)
-  })
-})
-
-describe('background tools', () => {
-  it('bash with run_in_background returns a task id immediately', async () => {
-    const ctx = await setup()
-    const result = await call(ctx, 'bash', { command: 'sleep 0.2; echo bg-done', description: 'test command', run_in_background: true })
-    expect(result.isError).toBe(false)
-    expect(text(result)).toMatch(/^started background task bash-\d+$/)
+    expect(ctx.tools.schemas()).toHaveLength(1)
   })
 
-  it('bash_output polls incrementally and reports status', async () => {
-    const ctx = await setup()
-    const started = await call(ctx, 'bash', { command: 'echo first; sleep 1; echo second', description: 'test command', run_in_background: true })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-
-    const first = await callUntilText(ctx, 'bash_output', { task_id: id }, 'first')
-    expect(text(first)).toContain('first')
-    expect(text(first)).toContain('[status: running]')
-
-    await ctx.bash.get(id)!.done
-    const second = await call(ctx, 'bash_output', { task_id: id })
-    expect(text(second)).toContain('second')
-    expect(text(second)).not.toContain('first')
-    expect(text(second)).toContain('[status: completed, exit code: 0]')
-
-    const third = await call(ctx, 'bash_output', { task_id: id })
-    expect(text(third)).toContain('(no new output)')
-  })
-
-  it('bash_output flags lossy reads with spill paths', async () => {
+  it('applies the built-in background default when apply() receives a bare config', async () => {
+    // Bypasses the schemastery defaults on purpose: apply() must stand on its
+    // own `?? true` fallback when embedded programmatically without the schema.
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
-    await ctx.plugin(LocalBashExecutor, { maxOutputBytes: 100, graceMs: 200 })
-    ;(ctx.bash as LocalBashExecutor).internals = { spillDir }
-    await ctx.plugin(ToolBash)
-
-    const started = await call(ctx, 'bash', { command: 'for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', description: 'test command', run_in_background: true })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-    await ctx.bash.get(id)!.done
-    const read = await call(ctx, 'bash_output', { task_id: id })
-    expect(text(read)).toContain('[some output was dropped from memory; full output: ')
-  })
-
-  it('bash_output reports unavailable when a lossy read has no safe spill path', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SystemPrompt)
-    await ctx.plugin(ToolRegistry)
-    await ctx.plugin(LossyReadBashExecutor)
-    await ctx.plugin(ToolBash)
-
-    const read = await call(ctx, 'bash_output', { task_id: 'bash-lossy' })
-    expect(text(read)).toBe('tail\n[some output was dropped from memory; full output: (unavailable)]\n[status: running]')
-  })
-
-  it('bash_kill stops a running task; repeat reports already-finished', async () => {
-    const ctx = await setup()
-    const started = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-
-    const killed = await call(ctx, 'bash_kill', { task_id: id })
-    expect(text(killed)).toBe(`killed background task ${id}`)
-    await ctx.bash.get(id)!.done
-
-    const again = await call(ctx, 'bash_kill', { task_id: id })
-    expect(text(again)).toBe(`task ${id} had already finished`)
-
-    const status = await call(ctx, 'bash_output', { task_id: id })
-    expect(text(status)).toContain('[status: killed by SIGTERM]')
-  })
-
-  it('unknown task ids are isError for both tools', async () => {
-    const ctx = await setup()
-    const read = await call(ctx, 'bash_output', { task_id: 'bash-999' })
-    expect(read.isError).toBe(true)
-    expect(text(read)).toMatch(/unknown bash task/)
-    const kill = await call(ctx, 'bash_kill', { task_id: 'bash-999' })
-    expect(kill.isError).toBe(true)
-  })
-
-  it.each([
-    ['bash_output', {}, /missing required property "task_id"/],
-    ['bash_output', { task_id: 9 }, /"task_id" must be a string/],
-    ['bash_kill', { task_id: '' }, /invalid task_id/],
-  ])('%s rejects invalid task_id %j', async (tool, args, pattern) => {
-    const ctx = await setup()
-    const result = await call(ctx, tool, args)
-    expect(result.isError).toBe(true)
-    expect(text(result)).toMatch(pattern)
-  })
-
-  it('injects a completion notice into the owning agent (found via the registry by session token)', async () => {
-    const ctx = await setup()
-    const inject = vi.fn()
-    // The notice path looks the agent up in ctx.agents by its session token, so
-    // the agent must be REGISTERED (not merely passed to execute). Mount a
-    // registry and register a fake whose session.header.id IS the owner token.
-    const agent = registerFakeAgent(ctx, 'bg', inject)
-
-    const started = await ctx.tools.execute({
-      callId: CallId('call-bg'),
-      name: 'bash',
-      arguments: { command: 'true', description: 'test command', run_in_background: true },
-      agent,
-    })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-    await ctx.bash.get(id)!.done
-
-    expect(inject).toHaveBeenCalledTimes(1)
-    const [content, options] = inject.mock.calls[0] as [
-      { type: string; text: string }[],
-      { source: { kind: string; plugin: string } },
-    ]
-    expect(content[0]!.text).toContain(`background bash task ${id} finished`)
-    expect(content[0]!.text).toContain('bash_output')
-    expect(options.source).toEqual({ kind: 'plugin', plugin: 'tool-bash' })
-  })
-
-  it('swallows ONLY the disposed-agent inject error', async () => {
-    const ctx = await setup()
-    const agent = registerFakeAgent(ctx, 'bg', () => { throw new Error('agent "x" is disposed') })
-
-    const started = await ctx.tools.execute({
-      callId: CallId('call-bg2'),
-      name: 'bash',
-      arguments: { command: 'true', description: 'test command', run_in_background: true },
-      agent,
-    })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-    await expect(ctx.bash.get(id)!.done).resolves.toBeUndefined()
-  })
-
-  it('rethrows a non-disposed inject failure (not blindly swallowed)', async () => {
-    const ctx = await setup()
-    // A real bug in inject (not the benign disposed race) must surface — the
-    // base-class notifier contains it (logs, does not reject task.done), but
-    // the listener itself must have thrown rather than silently eaten it.
-    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
-    try {
-      const agent = registerFakeAgent(ctx, 'bg', () => { throw new Error('unexpected inject bug') })
-
-      const started = await ctx.tools.execute({
-        callId: CallId('call-bg3'),
-        name: 'bash',
-        arguments: { command: 'true', description: 'test command', run_in_background: true },
-        agent,
-      })
-      const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-      await ctx.bash.get(id)!.done
-      // notifyTaskDone caught and logged the rethrown error.
-      expect(errorSpy).toHaveBeenCalled()
-      const logged = errorSpy.mock.calls.flat().some(arg => arg instanceof Error && arg.message === 'unexpected inject bug')
-      expect(logged).toBe(true)
-    } finally {
-      errorSpy.mockRestore()
-    }
-  })
-
-  it('drops the notice cleanly when the owning agent is gone from the registry by completion', async () => {
-    // A bash task (owned by the host-scoped bash-local fiber) can OUTLIVE its
-    // per-session agent — e.g. the ACP session disconnects and its AgentHandle
-    // disposes while the background task is still running. The owner token is
-    // still on the task, but no live agent carries it anymore, so the registry
-    // lookup finds nothing and the notice is dropped (no throw).
-    const ctx = await setup()
-    const inject = vi.fn()
-    const agent = registerFakeAgent(ctx, 'bg', inject)
-    const started = await ctx.tools.execute({
-      callId: CallId('call-bg4'),
-      name: 'bash',
-      arguments: { command: 'true', description: 'test command', run_in_background: true },
-      agent,
-    })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-    // Unregister the agent BEFORE the task completes (simulate disconnect).
-    unregisterFakeAgents(ctx)
-    await expect(ctx.bash.get(id)!.done).resolves.toBeUndefined()
-    expect(inject).not.toHaveBeenCalled()
-  })
-
-  it('does not notify when no agent owned the task', async () => {
-    const ctx = await setup()
-    const started = await call(ctx, 'bash', { command: 'true', description: 'test command', run_in_background: true })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-    await expect(ctx.bash.get(id)!.done).resolves.toBeUndefined()
+    await ctx.plugin(LocalBashExecutor, {})
+    ToolBash.apply(ctx, {})
+    const schema = ctx.tools.schemas()[0]!
+    expect(Object.keys(schema.parameters.properties as Record<string, unknown>))
+      .toContain('run_in_background')
   })
 })
 
-describe('background task ownership (cross-session isolation)', () => {
-  /** Run a tool on behalf of a specific agent (sets exec.agent). */
-  function callAs(ctx: Context, agent: import('@deepseek-ai/dsh-agent').Agent | undefined, name: string, args: unknown) {
-    return ctx.tools.execute({ callId: CallId(`own-${++callCounter}`), name, arguments: args, ...agent ? { agent } : {} })
-  }
-  // Ownership is by TOKEN (session.header.id), NOT agent object identity — so
-  // each agent needs a DISTINCT session id, else every fake yields the same
-  // token and the isolation tests pass for the wrong reason (all tasks owned by
-  // the same token). The impl reads `session.header.id`, so the fakes MUST carry
-  // it.
-  const fakeAgent = (sessionId: string) =>
-    ({ inject: () => undefined, session: { header: { version: 0, id: sessionId, createdAt: 0 } } }) as unknown as import('@deepseek-ai/dsh-agent').Agent
+describe('background execution through the task runtime', () => {
+  it('run_in_background acks with the task id, readable through the REAL task_output tool', async () => {
+    const ctx = await setupWithTasks()
+    const started = await call(ctx, 'bash', { command: 'echo bg-ok', description: 'test command', run_in_background: true })
+    expect(started.isError).toBe(false)
+    expect(text(started)).toBe('started background task bash-1')
 
-  it('rejects bash_output/bash_kill for a task owned by a DIFFERENT session token', async () => {
-    const ctx = await setup()
-    const a = fakeAgent('sess-a')
-    const b = fakeAgent('sess-b')
-    // Agent A starts a long-running background task.
-    const started = await callAs(ctx, a, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-
-    // Agent B (a different session token) cannot read or kill A's task.
-    const readByB = await callAs(ctx, b, 'bash_output', { task_id: id })
-    expect(readByB.isError).toBe(true)
-    expect(text(readByB)).toMatch(/belongs to another session/)
-    const killByB = await callAs(ctx, b, 'bash_kill', { task_id: id })
-    expect(killByB.isError).toBe(true)
-    expect(text(killByB)).toMatch(/belongs to another session/)
-
-    // The task is still running (B's kill did nothing) — A can still kill it.
-    const killByA = await callAs(ctx, a, 'bash_kill', { task_id: id })
-    expect(killByA.isError).toBe(false)
-    expect(text(killByA)).toBe(`killed background task ${id}`)
+    const read = await callUntilText(ctx, 'task_output', { task_id: 'bash-1' }, 'bg-ok')
+    expect(text(read)).toContain('bg-ok')
+    // A later read reports the terminal outcome in the generic status line.
+    const final = await callUntilText(ctx, 'task_output', { task_id: 'bash-1' }, '[status: completed, exit code: 0]')
+    expect(final.isError).toBe(false)
   })
 
-  it('a DIFFERENT Agent object with the SAME session token may access the task (ownership is by token, not object identity)', async () => {
-    // Ownership fences by session.header.id, NOT Agent object identity. Two
-    // distinct Agent objects sharing one session token (e.g. an agent re-created
-    // on the same session) are the SAME owner.
-    const ctx = await setup()
-    const a1 = fakeAgent('sess-shared')
-    const a2 = fakeAgent('sess-shared') // distinct object, same token
-    const started = await callAs(ctx, a1, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-    const readByA2 = await callAs(ctx, a2, 'bash_output', { task_id: id })
-    expect(readByA2.isError).toBe(false)
-    await callAs(ctx, a1, 'bash_kill', { task_id: id }) // cleanup
+  it('a running background task is killable through the REAL task_kill tool', async () => {
+    const ctx = await setupWithTasks()
+    await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
+
+    const killed = await call(ctx, 'task_kill', { task_id: 'bash-1' })
+    expect(text(killed)).toBe('requested cancellation of task bash-1')
+    // The cancel reached the process handle; the task settles as killed with
+    // the signal detail mapped by processOutcome.
+    const final = await call(ctx, 'task_output', { task_id: 'bash-1', wait: true })
+    expect(text(final)).toContain('[status: killed, signal: SIGTERM]')
   })
 
-  it('the no-agent (non-loop) caller cannot access an owned task', async () => {
-    const ctx = await setup()
-    const a = fakeAgent('sess-a')
-    const started = await callAs(ctx, a, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-    // A call with no exec.agent has no token → cannot prove ownership of an owned task.
-    const read = await callAs(ctx, undefined, 'bash_output', { task_id: id })
-    expect(read.isError).toBe(true)
-    expect(text(read)).toMatch(/belongs to another session/)
-    await callAs(ctx, a, 'bash_kill', { task_id: id }) // cleanup
-  })
+  it('a background task started by an agent is registered with that agent as owner', async () => {
+    // The fence SEMANTICS are pinned in dsh-tasks; this only pins that
+    // tool-bash forwards exec.agent as the registration's owner.
+    const ctx = await setupWithTasks()
+    const agent = registerFakeAgent(ctx, 'sess-owner')
+    const started = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true }, agent)
+    expect(text(started)).toBe('started background task bash-1')
 
-  it('an UNOWNED task (started with no agent) is accessible to anyone', async () => {
-    const ctx = await setup()
-    // Started by a non-loop caller (no exec.agent) → no owner token recorded.
-    const started = await callAs(ctx, undefined, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-    // Any agent (and the no-agent caller) may read/kill it.
-    const read = await callAs(ctx, fakeAgent('sess-x'), 'bash_output', { task_id: id })
-    expect(read.isError).toBe(false)
-    const killed = await callAs(ctx, undefined, 'bash_kill', { task_id: id })
+    const anon = await call(ctx, 'task_output', { task_id: 'bash-1' })
+    expect(anon.isError).toBe(true)
+    expect(text(anon)).toMatch(/belongs to another session/)
+
+    const killed = await call(ctx, 'task_kill', { task_id: 'bash-1' }, agent)
     expect(killed.isError).toBe(false)
+    await call(ctx, 'task_output', { task_id: 'bash-1', wait: true }, agent) // await settlement — no orphan
   })
 
-  it('the owner can still access its task AFTER it completes (owner token persists on the task)', async () => {
-    const ctx = await setup()
-    const a = fakeAgent('sess-a')
-    const b = fakeAgent('sess-b')
-    const started = await callAs(ctx, a, 'bash', { command: 'echo done', description: 'bg', run_in_background: true })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-    await ctx.bash.get(id)!.done
-    // Completion does NOT clear ownership: B is still rejected, A still allowed.
-    const readByB = await callAs(ctx, b, 'bash_output', { task_id: id })
-    expect(readByB.isError).toBe(true)
-    expect(text(readByB)).toMatch(/belongs to another session/)
-    const readByA = await callAs(ctx, a, 'bash_output', { task_id: id })
-    expect(readByA.isError).toBe(false)
+  it('fails loud when the task runtime is not loaded', async () => {
+    const ctx = await setup() // no TaskService / ToolTasks
+    const result = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
   })
 
-  it('ownership SURVIVES an independent tool-bash HMR reload (token lives on the executor)', async () => {
-    // The owner token lives on the TASK inside the executor (dsh-bash fiber), NOT
-    // in a tool-bash plugin-local map. So reloading ONLY tool-bash (executor +
-    // task survive) preserves ownership. This is the regression guard: a
-    // plugin-local map would make B accessible after reload, and this test would
-    // catch it.
+  it('a pre-aborted call refuses to start: isError, no process spawned', async () => {
+    class CountingStartExecutor extends BashExecutor {
+      starts = 0
+      resolve(request: BashExecRequest): BashExecSpec {
+        return { command: request.command, workdir: request.workdir ?? '/x', timeoutMs: request.timeoutMs ?? 0 }
+      }
+      run(): Promise<BashRunResult> { return Promise.reject(new Error('unused')) }
+      start(spec: BashExecSpec): BashProcess {
+        this.starts += 1
+        return {
+          command: spec.command,
+          status: 'completed',
+          exitCode: 0,
+          signal: null,
+          done: Promise.resolve(),
+          readOutput: () => ({ delta: '', lossy: false }),
+          kill: () => false,
+        }
+      }
+    }
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
-    await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 })
-    ;(ctx.bash as LocalBashExecutor).internals = { spillDir }
-    const fiber = await ctx.plugin(ToolBash)
-
-    const a = fakeAgent('sess-a')
-    const b = fakeAgent('sess-b')
-    const started = await callAs(ctx, a, 'bash', { command: 'sleep 60', description: 'bg', run_in_background: true })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-    // Before reload: B is rejected (A owns it).
-    expect((await callAs(ctx, b, 'bash_output', { task_id: id })).isError).toBe(true)
-
-    // Reload ONLY tool-bash; the executor and its running task (with its owner
-    // token) survive.
-    await fiber.dispose()
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(TaskService)
+    await ctx.plugin(ToolTasks)
+    await ctx.plugin(CountingStartExecutor)
     await ctx.plugin(ToolBash)
-    expect(ctx.bash.get(id)?.status).toBe('running')
-    expect(ctx.bash.ownerOf(id)).toBe('sess-a')
 
-    // After reload, ownership is INTACT → B is STILL rejected.
-    expect((await callAs(ctx, b, 'bash_output', { task_id: id })).isError).toBe(true)
-    await callAs(ctx, a, 'bash_kill', { task_id: id }) // cleanup
+    const controller = new AbortController()
+    controller.abort()
+    const result = await ctx.tools.execute({
+      callId: CallId('call-pre-aborted'),
+      name: 'bash',
+      arguments: { command: 'sleep 60', description: 'test command', run_in_background: true },
+      signal: controller.signal,
+    })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('command aborted')
+    expect((ctx.bash as CountingStartExecutor).starts).toBe(0)
+  })
+
+  it('a failed registration kills the just-started process (no orphan without an id)', async () => {
+    class LeakProbeExecutor extends BashExecutor {
+      kills = 0
+      resolve(request: BashExecRequest): BashExecSpec {
+        return { command: request.command, workdir: request.workdir ?? '/x', timeoutMs: request.timeoutMs ?? 0 }
+      }
+
+      run(): Promise<BashRunResult> { return Promise.reject(new Error('unused')) }
+      start(spec: BashExecSpec): BashProcess {
+        let close!: () => void
+        const done = new Promise<void>((res) => { close = res })
+        const proc: BashProcess = {
+          command: spec.command,
+          status: 'running',
+          exitCode: null,
+          signal: null,
+          done,
+          readOutput: () => ({ delta: '', lossy: false }),
+          kill: () => {
+            this.kills += 1
+            proc.status = 'killed'
+            close()
+            return true
+          },
+        }
+        return proc
+      }
+    }
+    // TaskService WITHOUT any control surface: register() throws AFTER the
+    // process already started — the producer must kill and await it.
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(TaskService)
+    await ctx.plugin(LeakProbeExecutor)
+    await ctx.plugin(ToolBash)
+
+    const result = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('no control surface is attached')
+    // The call resolved only after the kill landed (the catch awaits done).
+    expect((ctx.bash as LeakProbeExecutor).kills).toBe(1)
+  })
+
+  it('enableRunInBackground: false removes the parameter and flips the description', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(LocalBashExecutor, {})
+    await ctx.plugin(ToolBash, { enableRunInBackground: false })
+
+    const schema = ctx.tools.schemas().find(s => s.name === 'bash')!
+    expect(Object.keys(schema.parameters.properties as Record<string, unknown>))
+      .toEqual(['command', 'description', 'timeoutMs', 'workdir'])
+    expect(schema.description).toContain('Background execution is not available')
+    expect(schema.description).not.toContain('run_in_background')
+    // The registry-held definition agrees (schema and capability never disagree).
+    const parameters = ctx.tools.get('bash')!.parameters as { properties: Record<string, unknown> }
+    expect('run_in_background' in parameters.properties).toBe(false)
+  })
+})
+
+describe('renderProcessRead', () => {
+  const base: BashProcessRead = { delta: 'out\n', lossy: false }
+
+  it('returns the delta verbatim for a lossless read', () => {
+    expect(renderProcessRead(base)).toBe('out\n')
+    expect(renderProcessRead({ delta: '', lossy: false })).toBe('')
+  })
+
+  it('appends the loss notice with the available spill paths', () => {
+    expect(renderProcessRead({ ...base, lossy: true, stdoutSpillPath: '/spill/out.log' }))
+      .toBe('out\n[some output was dropped from memory; full output: /spill/out.log]')
+    expect(renderProcessRead({ ...base, lossy: true, stdoutSpillPath: '/spill/out.log', stderrSpillPath: '/spill/err.log' }))
+      .toBe('out\n[some output was dropped from memory; full output: /spill/out.log, /spill/err.log]')
+  })
+
+  it('reports (unavailable) when a lossy read has no safe spill path', () => {
+    expect(renderProcessRead({ ...base, lossy: true }))
+      .toBe('out\n[some output was dropped from memory; full output: (unavailable)]')
+  })
+
+  it('an empty lossy delta is the notice alone', () => {
+    expect(renderProcessRead({ delta: '', lossy: true, stderrSpillPath: '/spill/err.log' }))
+      .toBe('[some output was dropped from memory; full output: /spill/err.log]')
+  })
+
+  it('inserts the separating newline only when the delta lacks one', () => {
+    expect(renderProcessRead({ delta: 'tail', lossy: true }))
+      .toBe('tail\n[some output was dropped from memory; full output: (unavailable)]')
+    expect(renderProcessRead({ delta: 'tail\n', lossy: true }))
+      .toBe('tail\n[some output was dropped from memory; full output: (unavailable)]')
+  })
+})
+
+describe('processOutcome', () => {
+  function settled(over: Partial<BashProcess>): BashProcess {
+    return {
+      command: 'x',
+      status: 'completed',
+      exitCode: 0,
+      signal: null,
+      done: Promise.resolve(),
+      readOutput: () => ({ delta: '', lossy: false }),
+      kill: () => false,
+      ...over,
+    }
+  }
+
+  it('maps a signal-killed process to killed with the signal detail', () => {
+    expect(processOutcome(settled({ status: 'killed', signal: 'SIGTERM' })))
+      .toEqual({ status: 'killed', detail: 'signal: SIGTERM' })
+  })
+
+  it('maps a killed process without a recorded signal (kill raced exit / spawn failure)', () => {
+    expect(processOutcome(settled({ status: 'killed', exitCode: null })))
+      .toEqual({ status: 'killed', detail: 'killed before exit' })
+  })
+
+  it('maps a completed process to its exit code', () => {
+    expect(processOutcome(settled({ exitCode: 3 })))
+      .toEqual({ status: 'completed', detail: 'exit code: 3' })
+  })
+
+  it('defensively reads a null exit code as 0 (handle shapes from other executors)', () => {
+    expect(processOutcome(settled({ exitCode: null })))
+      .toEqual({ status: 'completed', detail: 'exit code: 0' })
   })
 })
 
 describe('session-cwd routing (per-session workdir)', () => {
-  function callAs(ctx: Context, agent: import('@deepseek-ai/dsh-agent').Agent | undefined, args: unknown) {
-    return ctx.tools.execute({ callId: CallId(`cwd-${++callCounter}`), name: 'bash', arguments: args, ...agent ? { agent } : {} })
-  }
   // An agent whose session header carries a cwd (what session/new records).
   const agentInCwd = (cwd: string) =>
-    ({ inject: () => undefined, session: { header: { version: 0, id: 'c', createdAt: 0, cwd } } }) as unknown as import('@deepseek-ai/dsh-agent').Agent
+    ({ inject: () => undefined, session: { header: { version: 0, id: 'c', createdAt: 0, cwd } } }) as unknown as Agent
 
   it('defaults bash to the agent\'s session cwd (not the server launch dir)', async () => {
     const ctx = await setup()
-    const result = await callAs(ctx, agentInCwd('/tmp'), { command: 'pwd', description: 'pwd' })
+    const result = await call(ctx, 'bash', { command: 'pwd', description: 'pwd' }, agentInCwd('/tmp'))
     expect(text(result).trim()).toMatch(/\/tmp$/)
   })
 
   it('an explicit absolute workdir overrides the session cwd', async () => {
     const ctx = await setup()
-    const result = await callAs(ctx, agentInCwd('/'), { command: 'pwd', description: 'pwd', workdir: '/tmp' })
+    const result = await call(ctx, 'bash', { command: 'pwd', description: 'pwd', workdir: '/tmp' }, agentInCwd('/'))
     expect(text(result).trim()).toMatch(/\/tmp$/)
   })
 
   it('a relative workdir is resolved against the session cwd', async () => {
     const ctx = await setup()
     // session cwd /usr + relative 'bin' → /usr/bin
-    const result = await callAs(ctx, agentInCwd('/usr'), { command: 'pwd', description: 'pwd', workdir: 'bin' })
+    const result = await call(ctx, 'bash', { command: 'pwd', description: 'pwd', workdir: 'bin' }, agentInCwd('/usr'))
     expect(text(result).trim()).toMatch(/\/usr\/bin$/)
   })
 
   it('two sessions with different cwds each run bash in their own dir', async () => {
     const ctx = await setup()
-    const inUsr = await callAs(ctx, agentInCwd('/usr'), { command: 'pwd', description: 'pwd' })
-    const inTmp = await callAs(ctx, agentInCwd('/tmp'), { command: 'pwd', description: 'pwd' })
+    const inUsr = await call(ctx, 'bash', { command: 'pwd', description: 'pwd' }, agentInCwd('/usr'))
+    const inTmp = await call(ctx, 'bash', { command: 'pwd', description: 'pwd' }, agentInCwd('/tmp'))
     expect(text(inUsr).trim()).toMatch(/\/usr$/)
     expect(text(inTmp).trim()).toMatch(/\/tmp$/)
   })
@@ -697,35 +576,6 @@ describe('renderResult', () => {
   })
 })
 
-describe('status lines', () => {
-  it('reports kills without a recorded signal (executor raced process exit)', async () => {
-    const ctx = await setup()
-    const started = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-    const task = ctx.bash.get(id)!
-
-    await call(ctx, 'bash_kill', { task_id: id })
-    await task.done
-    // Simulate the variant where the close event carried no signal.
-    task.signal = null
-    const read = await call(ctx, 'bash_output', { task_id: id })
-    expect(text(read)).toContain('[status: killed]')
-  })
-
-  it('reports completed tasks with a null exit code as exit 0', async () => {
-    const ctx = await setup()
-    const started = await call(ctx, 'bash', { command: 'true', description: 'test command', run_in_background: true })
-    const id = BashTaskId(/task (bash-\d+)/.exec(text(started))![1]!)
-    const task = ctx.bash.get(id)!
-    await task.done
-    // Defensive: completed tasks always carry an exit code in practice; the
-    // ?? 0 fallback covers task shapes from other executor implementations.
-    task.exitCode = null
-    const read = await call(ctx, 'bash_output', { task_id: id })
-    expect(text(read)).toContain('[status: completed, exit code: 0]')
-  })
-})
-
 describe('tool-owned UI presentation (presentCall / presentResult)', () => {
   it('bash presentCall: a foreground run is a terminal card (command title, description, workdir → cwd absolute or relative)', async () => {
     const ctx = await setup()
@@ -851,14 +701,6 @@ describe('tool-owned UI presentation (presentCall / presentResult)', () => {
     })).toBeUndefined()
   })
 
-  it('bash_output / bash_kill presentCall: a readable task-scoped title, task id as rawInput', async () => {
-    const ctx = await setup()
-    expect(ctx.tools.get('bash_output')!.presentCall!({ task_id: 'bash-3' }))
-      .toEqual({ card: 'generic', title: 'Read output from background task bash-3', kind: 'execute', rawInput: 'bash-3' })
-    expect(ctx.tools.get('bash_kill')!.presentCall!({ task_id: 'bash-3' }))
-      .toEqual({ card: 'generic', title: 'Kill background task bash-3', kind: 'execute', rawInput: 'bash-3' })
-  })
-
   it('presentCall validates softly: malformed args (missing required description) return undefined, never throw', async () => {
     const ctx = await setup()
     // defineTool wraps presentCall to soft-validate against the schema and fall
@@ -879,8 +721,8 @@ describe('the model-facing bash tool builds its request from named args only (no
    * future refactor that blindly forwards `...args` — which would silently thread
    * model input into the post-scrub `env` merge — NOT to defend a trust boundary
    * (the credential scrub in dsh-bash-local is the security control; see the
-   * bash-stdin-env RFC). Foreground `run()` returns a canned result; `start()` is
-   * unused here.
+   * bash-stdin-env RFC). Foreground `run()` returns a canned result; `start()`
+   * hands back an already-settled fake handle so the task registration completes.
    */
   class RecordingBashExecutor extends BashExecutor {
     readonly requests: BashExecRequest[] = []
@@ -893,7 +735,6 @@ describe('the model-facing bash tool builds its request from named args only (no
         ...request.signal ? { signal: request.signal } : {},
         ...request.stdin !== undefined ? { stdin: request.stdin } : {},
         ...request.env !== undefined ? { env: request.env } : {},
-        owner: request.owner,
       }
     }
     run(): Promise<BashRunResult> {
@@ -902,12 +743,17 @@ describe('the model-facing bash tool builds its request from named args only (no
         stdout: { text: 'ok', truncated: false }, stderr: { text: '', truncated: false },
       })
     }
-    start(): BashTask { throw new Error('unused') }
-    get(): BashTask | undefined { return undefined }
-    ownerOf(): OwnerToken | undefined { return undefined }
-    list(): BashTask[] { return [] }
-    readOutput(): BashTaskRead { throw new Error('unused') }
-    kill(): boolean { return false }
+    start(spec: BashExecSpec): BashProcess {
+      return {
+        command: spec.command,
+        status: 'completed',
+        exitCode: 0,
+        signal: null,
+        done: Promise.resolve(),
+        readOutput: () => ({ delta: '', lossy: false }),
+        kill: () => false,
+      }
+    }
   }
 
   async function setupRecording() {
@@ -915,6 +761,8 @@ describe('the model-facing bash tool builds its request from named args only (no
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
     await ctx.plugin(AgentRegistry)
+    await ctx.plugin(TaskService)
+    await ctx.plugin(ToolTasks)
     await ctx.plugin(RecordingBashExecutor)
     await ctx.plugin(ToolBash)
     return { ctx, bash: ctx.bash as RecordingBashExecutor }
@@ -947,9 +795,7 @@ describe('the model-facing bash tool builds its request from named args only (no
 
   it('a background bash call likewise carries no env/stdin', async () => {
     const { ctx, bash } = await setupRecording()
-    // start() throws in this recorder, but resolve() runs first and records the
-    // request — which is all this no-forward assertion needs.
-    await ctx.tools.execute({
+    const result = await ctx.tools.execute({
       callId: CallId('no-forward-2'),
       name: 'bash',
       arguments: {
@@ -960,13 +806,14 @@ describe('the model-facing bash tool builds its request from named args only (no
         stdin: 'x',
       },
     })
+    // The call really went down the background path (the recorder sees the real
+    // request the consumer built, so the absent env/stdin below is a real
+    // negative, not a recorder that drops everything).
+    expect(text(result)).toBe('started background task bash-1')
     expect(bash.requests).toHaveLength(1)
     const request = bash.requests[0]!
+    expect(request.command).toBe('sleep 1')
     expect('env' in request).toBe(false)
     expect('stdin' in request).toBe(false)
-    // The owner token IS set on a background call (the isolation fence) — proving
-    // the recorder sees the real request the consumer built, so the absent
-    // env/stdin above is a real negative, not a recorder that drops everything.
-    expect('owner' in request).toBe(true)
   })
 })
diff --git a/packages/bash/tool-bash/tsconfig.json b/packages/bash/tool-bash/tsconfig.json
index 89b10bfea8..020a3e253f 100644
--- a/packages/bash/tool-bash/tsconfig.json
+++ b/packages/bash/tool-bash/tsconfig.json
@@ -14,6 +14,9 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../../../vendor/schemastery"
+    },
     {
       "path": "../../llm/llm"
     },
@@ -25,6 +28,9 @@
     },
     {
       "path": "../../bash/bash"
+    },
+    {
+      "path": "../../tasks/tasks"
     }
   ]
 }
diff --git a/packages/core/agent-core/README.md b/packages/core/agent-core/README.md
index 3f2ff08c0e..76fb38df31 100644
--- a/packages/core/agent-core/README.md
+++ b/packages/core/agent-core/README.md
@@ -16,7 +16,7 @@ This is the package to read to see **the whole plugin tree at once** — the tea
 @deepseek-ai/dsh-tools            tool registry + tools/pre-execute/post-execute
 @deepseek-ai/dsh-agent            agent registry + agent/* event vocabulary
 @deepseek-ai/dsh-invariants       dev-mode event-contract assertions
-@deepseek-ai/dsh-tool-bash        the model-facing bash/bash_output/bash_kill schemas
+@deepseek-ai/dsh-tool-bash        the model-facing bash schema (background runs register with ctx.tasks)
 @deepseek-ai/dsh-agent-loop       THE concrete loop (gets the forwarded `agents`)
                                   (dsh-system-prompt gets the forwarded `persona`)
 ```
diff --git a/packages/core/agent-core/package.json b/packages/core/agent-core/package.json
index 5b1eed413a..35e4dd7015 100644
--- a/packages/core/agent-core/package.json
+++ b/packages/core/agent-core/package.json
@@ -29,7 +29,9 @@
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "@deepseek-ai/dsh-tasks": "^0.0.1",
     "@deepseek-ai/dsh-tool-bash": "^0.0.1",
+    "@deepseek-ai/dsh-tool-tasks": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
@@ -41,7 +43,9 @@
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tasks": "workspace:^",
     "@deepseek-ai/dsh-tool-bash": "workspace:^",
+    "@deepseek-ai/dsh-tool-tasks": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "cordis": "^4.0.0-rc.6"
   },
diff --git a/packages/core/agent-core/src/index.ts b/packages/core/agent-core/src/index.ts
index 785c8d1ff2..9a7892a8f1 100644
--- a/packages/core/agent-core/src/index.ts
+++ b/packages/core/agent-core/src/index.ts
@@ -3,7 +3,8 @@
  *
  * Loads the fixed set of services every harness agent needs — `timer`, the LLM
  * service, the session store, system-prompt assembly, the tool registry, the
- * agent registry, the dev-mode invariants, the model-facing `bash` tool
+ * agent registry, the background task registry + its `task_*` control tools,
+ * the dev-mode invariants, the model-facing `bash` tool
  * schemas, and the concrete `agent-loop` — and forwards the loop's `agents`
  * list as its OWN config (default `[]`), so each app supplies its own
  * pre-created agents.
@@ -50,8 +51,10 @@ import SessionStore from '@deepseek-ai/dsh-session'
 import SystemPrompt, { type Config as SystemPromptConfig } from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
+import TaskService from '@deepseek-ai/dsh-tasks'
 import * as invariants from '@deepseek-ai/dsh-invariants'
 import * as toolBash from '@deepseek-ai/dsh-tool-bash'
+import * as toolTasks from '@deepseek-ai/dsh-tool-tasks'
 import AgentLoop, { type Config as AgentLoopConfig } from '@deepseek-ai/dsh-agent-loop'
 
 export const name = 'agent-core'
@@ -103,7 +106,9 @@ export function apply(ctx: Context, config: Config): void {
   })
   ctx.plugin(ToolRegistry)
   ctx.plugin(AgentRegistry)
+  ctx.plugin(TaskService)
   ctx.plugin(invariants)
   ctx.plugin(toolBash)
+  ctx.plugin(toolTasks)
   ctx.plugin(AgentLoop, { agents: config.agents ?? [] })
 }
diff --git a/packages/core/agent-core/tests/agent-core.spec.ts b/packages/core/agent-core/tests/agent-core.spec.ts
index 818da77311..a6b52a7ffc 100644
--- a/packages/core/agent-core/tests/agent-core.spec.ts
+++ b/packages/core/agent-core/tests/agent-core.spec.ts
@@ -81,7 +81,9 @@ describe('dsh-agent-core bundle', () => {
       })
     }
     const assembly = await ctx.get('systemPrompt')!.assemble()
-    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha'])
+    // The rest-slot is lexicographic: the bundle's own task control tools
+    // (tool-tasks needs no executor, unlike the pending bash tool) follow alpha.
+    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'task_kill', 'task_list', 'task_output'])
     await ctx.fiber.dispose()
   })
 
diff --git a/packages/core/agent-core/tsconfig.json b/packages/core/agent-core/tsconfig.json
index 91e5ec894e..6dee8a53e1 100644
--- a/packages/core/agent-core/tsconfig.json
+++ b/packages/core/agent-core/tsconfig.json
@@ -40,6 +40,12 @@
     },
     {
       "path": "../../bash/tool-bash"
+    },
+    {
+      "path": "../../tasks/tasks"
+    },
+    {
+      "path": "../../tasks/tool-tasks"
     }
   ]
 }
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index ed651ca7f0..bae2d9447a 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -12,7 +12,7 @@ This is the only package in the harness that contains concrete loop logic. Every
 
 `AgentLoop` also implements the `AgentFactory` seam and registers itself via `ctx.agents.setFactory(this)`, so plugins create/resume agents through `ctx.agents` (the interface):
 
-- `ctx.agents.create({ agentId, sessionId, meta?, seed?, agentOptions? }): AgentHandle` — programmatic create on a caller-supplied `sessionId` (e.g. an ACP-generated id), NOT `${id}-session`; `meta` carries cwd/lineage/seed-boundary metadata and `seed` reconstructs a forked child prefix. Returns an [`AgentHandle`](../agent/README.md) — the owner disposes it to tear down exactly this agent (stop loop + await quiescence + unregister + remove session).
+- `ctx.agents.create({ agentId, sessionId, meta?, seed?, agentOptions? }): AgentHandle` — programmatic create on a caller-supplied `sessionId` (e.g. an ACP-generated id), NOT `${id}-session`; `meta` carries cwd/lineage/seed-boundary metadata and `seed` reconstructs a forked child prefix. Returns an [`AgentHandle`](../agent/README.md) — the owner disposes it to tear down exactly this agent (stop loop + await quiescence + drain the `ctx.agents.onCleanup` registrations + unregister + remove session).
 - `ctx.agents.resume({ agentId, resumeSessionId, agentOptions? }): Promise<AgentHandle>` — load a persisted session via `ctx.sessionPersistence` ([session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md)) and resume an agent on it. The live session id is the resumed id; turn numbering and derived history continue from the loaded log. Requires a session-persistence backend (NOT hard-injected — non-persistent demos still work; `resume` rejects with a clear error when persistence is absent). Returns an `AgentHandle`.
 
 The config-driven `ctx.agentLoop.create()` path keeps its agent owned by the loop fiber (it discards the handle) — only the programmatic factory callers (the ACP bridge and in-process subagent backends) hold a handle and own per-agent teardown.
diff --git a/packages/core/agent-loop/src/index.ts b/packages/core/agent-loop/src/index.ts
index e7e0e562d9..8bbf6a8216 100644
--- a/packages/core/agent-loop/src/index.ts
+++ b/packages/core/agent-loop/src/index.ts
@@ -274,11 +274,15 @@ export class AgentLoop extends Service implements AgentFactory {
    * chain — the runtime awaits each disposer's returned promise before the next:
    *
    *   yield session-detach   (disposed LAST  — detach onAppend + remove entry)
-   *   yield register         (disposed 2nd   — unregister)
+   *   yield register         (disposed 3rd   — unregister)
+   *   yield cleanup-drain    (disposed 2nd   — await ctx.agents.drainCleanups)
    *   yield stop-and-drain   (disposed FIRST — request loop stop, await agent.done)
    *
    * So on teardown: the loop is stopped and AWAITED to exit (its final
    * `session/flush` + `turn/end` fire through the still-attached `onAppend`),
+   * THEN the awaited per-agent cleanups drain (background tasks cancel and
+   * reach quiescence while the agent is STILL registered — a settling task's
+   * completion notice can still find it, and `agent/disposed` has not fired),
    * THEN the agent is unregistered, THEN the session is detached — capturing the
    * closing events before detach, whether the trigger is the handle's `dispose()`
    * OR a fiber unload. Rollback safety: each yield runs before the next mutation,
@@ -304,6 +308,11 @@ export class AgentLoop extends Service implements AgentFactory {
       yield this.ctx.sessions.enter(session)
       this.ctx.sessions.announce(session)
       yield this.ctx.agents.register(agent)
+      // Disposed 2nd (after stop-and-drain below, before unregister above):
+      // drain the awaited per-agent cleanups — the AgentFactory dispose
+      // contract that lets other plugins (ctx.tasks) tie resources to this
+      // agent's quiescence. drainCleanups contains rejections itself.
+      yield async () => { await this.ctx.agents.drainCleanups(agent.id) }
       // Fire AFTER register (a listener can ctx.agents.get(id) + inject()) and
       // BEFORE the loop's first turn. Contained: a throwing listener is logged,
       // never aborts construction (no open turn to balance here).
diff --git a/packages/core/agent-loop/tests/cleanup-drain.spec.ts b/packages/core/agent-loop/tests/cleanup-drain.spec.ts
new file mode 100644
index 0000000000..1894d73e1c
--- /dev/null
+++ b/packages/core/agent-loop/tests/cleanup-drain.spec.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { MockAdapter } from './mock-adapter.ts'
+
+async function harness() {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  ctx.llm.registerAdapter(['mock'], new MockAdapter([]))
+  return ctx
+}
+
+describe('agent disposal drains onCleanup registrations', () => {
+  it('awaits the cleanup after loop drain and before unregistration', async () => {
+    const ctx = await harness()
+    const handle = ctx.agents.create({ agentId: AgentId('owner'), sessionId: SessionId('owner-sess'), agentOptions: { model: 'mock' } })
+
+    const order: string[] = []
+    ctx.on('agent/disposed', () => void order.push('agent/disposed'))
+    let cleanupSettled = false
+    ctx.agents.onCleanup(handle.agent.id, async () => {
+      // The agent must STILL be registered while cleanups drain (a settling
+      // task's completion notice can still find it by session id).
+      order.push(`cleanup:registered=${ctx.agents.get(handle.agent.id) !== undefined}`)
+      await new Promise(r => setTimeout(r, 10))
+      cleanupSettled = true
+      order.push('cleanup:done')
+    })
+
+    await handle.dispose()
+    // dispose() resolves only after the cleanup settled (awaited, not fired).
+    expect(cleanupSettled).toBe(true)
+    expect(order).toEqual(['cleanup:registered=true', 'cleanup:done', 'agent/disposed'])
+  })
+
+  it('a rejecting cleanup never breaks the disposal chain', async () => {
+    const ctx = await harness()
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const handle = ctx.agents.create({ agentId: AgentId('owner'), sessionId: SessionId('owner-sess'), agentOptions: { model: 'mock' } })
+    ctx.agents.onCleanup(handle.agent.id, () => Promise.reject(new Error('drain boom')))
+
+    await expect(handle.dispose()).resolves.toBeUndefined()
+    expect(ctx.agents.get(handle.agent.id)).toBeUndefined()
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('drain boom'))
+  })
+})
diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md
index 9e15356ed0..01dec7deaa 100644
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -20,7 +20,10 @@ Agent *creation* is provided by whichever plugin implements `AgentFactory` (phas
 - `ctx.agents.create(options: CreateAgentOptions): AgentHandle` — construct, start, AND register a new agent on a caller-supplied `sessionId` (with optional `meta.cwd`/`meta.parentSession`/`meta.seedLength` and optional `seed` events for forked children). Distinct from `register` (which only records). Throws if no factory is registered.
 - `ctx.agents.resume(options: ResumeAgentOptions): Promise<AgentHandle>` — load a persisted session ([session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md)) and resume an agent on it. Async; rejects if no factory is registered, or if the factory finds session persistence unconfigured.
 
-`AgentHandle = { agent: Agent; dispose(): Promise<void> }`. The disposer is a **capability** — only the holder can tear this agent down. `dispose()` stops the loop, `await`s its exit (quiescence — NOT just the `disposed` status flip), unregisters the agent, and removes its session from the store, in an order that captures the loop's final `session/flush` before the session is detached. `ctx.agents.get(id)` still returns a bare `Agent` — the handle is only for the OWNER that created it. The ACP bridge and in-process subagent backends are production consumers; config-created agents are owned by the loop fiber and never need a handle.
+`AgentHandle = { agent: Agent; dispose(): Promise<void> }`. The disposer is a **capability** — only the holder can tear this agent down. `dispose()` stops the loop, `await`s its exit (quiescence — NOT just the `disposed` status flip), drains the registered per-agent cleanups, unregisters the agent, and removes its session from the store, in an order that captures the loop's final `session/flush` before the session is detached.
+
+- `ctx.agents.onCleanup(agentId, cleanup: () => Promise<void>): () => void` — register an AWAITED per-agent cleanup: the agent's disposal chain runs it (after loop drain, before unregistration) and `AgentHandle.dispose()` resolves only after it settles. The seam for resources that must not outlive their owner (`ctx.tasks` background tasks) — the `agent/disposed` EMIT cannot promise that, because emit listeners are not awaited. Throws for an unregistered agent id; effect-scoped.
+- `ctx.agents.drainCleanups(agentId): Promise<void>` — LIFECYCLE OWNERS ONLY: run and detach every registered cleanup (registration order, per-cleanup containment, loops so a cleanup registered mid-drain still runs). Part of the `AgentFactory` dispose contract — a replacement loop must call it in its disposal chain. `ctx.agents.get(id)` still returns a bare `Agent` — the handle is only for the OWNER that created it. The ACP bridge and in-process subagent backends are production consumers; config-created agents are owned by the loop fiber and never need a handle.
 
 ### Events
 
diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts
index 096555f925..3f173e330a 100644
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -88,6 +88,13 @@ export interface AgentHandle {
  * via {@link AgentRegistry.setFactory}. Kept on the `dsh-agent` interface so
  * consumers (e.g. the ACP bridge) program against `ctx.agents` without
  * depending on the concrete `dsh-agent-loop` package.
+ *
+ * Dispose contract: the handle's `dispose()` must, after draining the loop and
+ * BEFORE unregistering the agent, await
+ * {@link AgentRegistry.drainCleanups | ctx.agents.drainCleanups(agent.id)} —
+ * that is what makes {@link AgentRegistry.onCleanup} registrations an awaited
+ * quiescence guarantee for every plugin, whichever loop implementation is
+ * installed.
  */
 export interface AgentFactory {
   /**
@@ -117,6 +124,7 @@ const NO_FACTORY_MESSAGE = 'no agent factory registered (load an agent-loop plug
 export class AgentRegistry extends Service {
   private store = new Map<AgentId, Agent>()
   private factory: AgentFactory | undefined
+  private cleanups = new Map<AgentId, Set<() => Promise<void>>>()
 
   constructor(ctx: Context) {
     super(ctx, 'agents')
@@ -217,6 +225,66 @@ export class AgentRegistry extends Service {
     return this.store.get(id)
   }
 
+  /**
+   * Register an AWAITED per-agent cleanup: the agent's disposal chain runs it
+   * (via {@link drainCleanups}) after the loop has drained and before the agent
+   * unregisters, and `AgentHandle.dispose()` resolves only after it settles.
+   * This is the seam for resources that must not outlive their owning agent
+   * (e.g. `ctx.tasks` background tasks) — the `agent/disposed` EMIT cannot
+   * promise that, because emit listeners are not awaited. Throws for an agent
+   * id not currently registered: a cleanup attached to a dead agent would
+   * silently never run. Effect-scoped: disposed with the calling fiber.
+   * @param agentId - the LIVE agent whose disposal must await this cleanup.
+   * @param cleanup - awaited during disposal; a rejection is logged, never propagated.
+   * @returns the disposer that detaches the cleanup without running it.
+   */
+  onCleanup(agentId: AgentId, cleanup: () => Promise<void>): () => void {
+    const dispose = this.ctx.effect(() => {
+      if (!this.store.has(agentId)) {
+        throw new Error(`agent "${agentId}" is not registered (cleanup would never run)`)
+      }
+      let set = this.cleanups.get(agentId)
+      if (set === undefined) {
+        set = new Set()
+        this.cleanups.set(agentId, set)
+      }
+      set.add(cleanup)
+      return () => {
+        set.delete(cleanup)
+        // Guard the map removal with an identity check: after drainCleanups
+        // detached this set, the same id may map to a FRESH set (a cleanup
+        // registered mid-drain) that this stale disposer must not remove.
+        if (set.size === 0 && this.cleanups.get(agentId) === set) this.cleanups.delete(agentId)
+      }
+    }, 'agents.onCleanup()')
+    return () => void dispose()
+  }
+
+  /**
+   * Run and detach every cleanup registered for an agent (registration order,
+   * awaited sequentially, per-cleanup containment — a rejecting cleanup is
+   * logged and never starves the ones after it or the caller's disposal chain).
+   * For LIFECYCLE OWNERS ONLY: the agent factory's disposal chain calls this
+   * between loop drain and unregistration (part of the {@link AgentFactory}
+   * dispose contract); other plugins register via {@link onCleanup}, never
+   * drain. Loops until no cleanups remain, so one registered DURING the drain
+   * (from a settling task) still runs instead of leaking.
+   * @param agentId - the agent being disposed.
+   * @returns resolves when every registered cleanup has settled.
+   */
+  async drainCleanups(agentId: AgentId): Promise<void> {
+    for (let set = this.cleanups.get(agentId); set !== undefined; set = this.cleanups.get(agentId)) {
+      this.cleanups.delete(agentId)
+      for (const cleanup of set) {
+        try {
+          await cleanup()
+        } catch (error: unknown) {
+          this.ctx.logger.warn(`agent "${agentId}": disposal cleanup threw: ${String(error)}`)
+        }
+      }
+    }
+  }
+
   /**
    * All live agents, in registration order.
    * @returns a fresh array; mutating it does not affect the registry.
diff --git a/packages/core/agent/tests/agent.spec.ts b/packages/core/agent/tests/agent.spec.ts
index c344cd2a6f..861b3bd3cc 100644
--- a/packages/core/agent/tests/agent.spec.ts
+++ b/packages/core/agent/tests/agent.spec.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import AgentRegistry, { Agent, AgentId } from '@deepseek-ai/dsh-agent'
@@ -76,6 +76,129 @@ describe('AgentRegistry', () => {
   })
 })
 
+describe('AgentRegistry.onCleanup / drainCleanups', () => {
+  it('drains cleanups in registration order, awaiting each', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const agent = stubAgent('a1')
+    ctx.agents.register(agent)
+
+    const ran: string[] = []
+    ctx.agents.onCleanup(agent.id, async () => {
+      ran.push('first:start')
+      await new Promise(r => setTimeout(r, 10))
+      ran.push('first:end')
+    })
+    ctx.agents.onCleanup(agent.id, () => {
+      ran.push('second')
+      return Promise.resolve()
+    })
+
+    await ctx.agents.drainCleanups(agent.id)
+    // Sequential await: the second cleanup starts only after the first settled.
+    expect(ran).toEqual(['first:start', 'first:end', 'second'])
+    // Drained cleanups are detached: a second drain is a no-op.
+    await ctx.agents.drainCleanups(agent.id)
+    expect(ran).toEqual(['first:start', 'first:end', 'second'])
+  })
+
+  it('contains a rejecting cleanup: logged, later cleanups still run', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const agent = stubAgent('a1')
+    ctx.agents.register(agent)
+
+    let ranAfter = false
+    ctx.agents.onCleanup(agent.id, () => Promise.reject(new Error('cleanup boom')))
+    ctx.agents.onCleanup(agent.id, () => {
+      ranAfter = true
+      return Promise.resolve()
+    })
+
+    await expect(ctx.agents.drainCleanups(agent.id)).resolves.toBeUndefined()
+    expect(ranAfter).toBe(true)
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('cleanup boom'))
+  })
+
+  it('rejects a cleanup for an agent that is not registered', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    expect(() => ctx.agents.onCleanup(AgentId('ghost'), () => Promise.resolve()))
+      .toThrow('agent "ghost" is not registered')
+  })
+
+  it('detaches without running on disposer call and on fiber dispose (HMR safety)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const agent = stubAgent('a1')
+    ctx.agents.register(agent)
+
+    let ranA = false
+    let ranB = false
+    const detach = ctx.agents.onCleanup(agent.id, () => {
+      ranA = true
+      return Promise.resolve()
+    })
+    detach()
+
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.agents.onCleanup(agent.id, () => {
+        ranB = true
+        return Promise.resolve()
+      })
+    }, { inject: ['agents'] }))
+    await fiber.dispose()
+
+    await ctx.agents.drainCleanups(agent.id)
+    expect(ranA).toBe(false)
+    expect(ranB).toBe(false)
+  })
+
+  it('runs a cleanup registered during the drain instead of leaking it', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const agent = stubAgent('a1')
+    ctx.agents.register(agent)
+
+    const ran: string[] = []
+    ctx.agents.onCleanup(agent.id, () => {
+      ran.push('outer')
+      // A settling task registering follow-up cleanup mid-drain: the drain
+      // loop must pick up the fresh set rather than strand it.
+      ctx.agents.onCleanup(agent.id, () => {
+        ran.push('mid-drain')
+        return Promise.resolve()
+      })
+      return Promise.resolve()
+    })
+
+    await ctx.agents.drainCleanups(agent.id)
+    expect(ran).toEqual(['outer', 'mid-drain'])
+  })
+
+  it('a stale disposer from a drained set does not remove a fresh registration', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const agent = stubAgent('a1')
+    ctx.agents.register(agent)
+
+    const detachOld = ctx.agents.onCleanup(agent.id, () => Promise.resolve())
+    await ctx.agents.drainCleanups(agent.id)
+
+    let ranFresh = false
+    ctx.agents.onCleanup(agent.id, () => {
+      ranFresh = true
+      return Promise.resolve()
+    })
+    // The old registration's disposer fires after its set was drained; the
+    // identity guard must keep it away from the fresh set under the same id.
+    detachOld()
+    await ctx.agents.drainCleanups(agent.id)
+    expect(ranFresh).toBe(true)
+  })
+})
+
 describe('AgentRegistry factory seam', () => {
   /** A stub AgentFactory that records calls and returns a stub agent. */
   function stubFactory() {
diff --git a/packages/core/tools/tests/gen-tool-catalog.spec.ts b/packages/core/tools/tests/gen-tool-catalog.spec.ts
index cacc2eef66..fcbc4d9c83 100644
--- a/packages/core/tools/tests/gen-tool-catalog.spec.ts
+++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts
@@ -35,7 +35,7 @@ describe('gen-tool-catalog collectToolCatalog', () => {
   it('boots every shipped tool package and harvests its model-facing schemas', async () => {
     const catalog = await collectToolCatalog()
     const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort()
-    expect(names).toEqual(['bash', 'bash_kill', 'bash_output', 'edit', 'read', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'write'])
+    expect(names).toEqual(['bash', 'edit', 'read', 'subagent', 'task_kill', 'task_list', 'task_output', 'todo_write', 'web_fetch', 'web_search', 'write'])
     // Every tool carries a JSON-Schema `parameters` object (what the model sees).
     for (const entry of catalog) {
       for (const schema of entry.schemas) {
diff --git a/packages/hooks/hook-protocol/tests/runner.spec.ts b/packages/hooks/hook-protocol/tests/runner.spec.ts
index 1972a39c99..1386140ae1 100644
--- a/packages/hooks/hook-protocol/tests/runner.spec.ts
+++ b/packages/hooks/hook-protocol/tests/runner.spec.ts
@@ -25,7 +25,6 @@ function recordingBash(run: (spec: BashExecSpec) => Promise<BashRunResult>): {
         ...request.signal ? { signal: request.signal } : {},
         ...request.stdin !== undefined ? { stdin: request.stdin } : {},
         ...request.env !== undefined ? { env: request.env } : {},
-        owner: request.owner,
       }
     },
     async run(spec: BashExecSpec): Promise<BashRunResult> {
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index 8bab4c61c9..8add2250a0 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -38,6 +38,6 @@ The service also announces provider lifecycle: `subagent/provider-added` (the li
 
 ## Scope (first cut)
 
-The consumer collects **synchronously**: it starts a run and awaits `result`. Steering (`sendMessage`) is part of the contract but intentionally unused. Background / poll / spill semantics are deferred to a future redesign unifying long-running-tool handling across subagents and bash. See the RFC: [docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md](../../../docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md).
+The consumer collects **synchronously by default**: it starts a run and awaits `result`. Background delegation does not change this seam — the consumer registers the run with the generic `ctx.tasks` runtime and the run is collected through the shared task tools ([the background subagent tasks RFC](../../../docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md)). Steering (`sendMessage`) is part of the contract but intentionally unused. See the seam RFC: [docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md](../../../docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md).
 
 See `src/types.ts` for the full contracts.
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 91230b7ff4..3ac3735569 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -14,11 +14,12 @@
  * (`@deepseek-ai/dsh-subagent-spawn`, `-fork`, `-acp`) and the model-facing
  * consumer (`@deepseek-ai/dsh-tool-subagent`) are separate packages.
  *
- * Scope (first cut): the consumer collects synchronously — it starts a run and
- * awaits {@link SubagentRun.result}. Steering ({@link SubagentRun.sendMessage})
- * is part of the contract but intentionally unused; background / poll / spill
- * semantics are deferred to a future redesign that unifies long-running-tool
- * handling across subagents and bash.
+ * Scope: the seam stays collection-agnostic — a run is started and its
+ * `result` awaited, whether the consumer blocks on it (foreground) or
+ * registers it as a `ctx.tasks` background task (the generic runtime owns
+ * ids/polling/stop; this seam gains nothing task-shaped). Steering
+ * ({@link SubagentRun.sendMessage}) is part of the contract but intentionally
+ * unused.
  *
  * The `subagent/start` / `subagent/end` lifecycle events carry an OBSERVE-ONLY
  * payload; `subagent/end` additionally carries the child's `lastAssistantMessage`
@@ -26,8 +27,8 @@
  * FIXME(subagent-continuation): a control-flow `subagent/end` (an awaited
  * waterfall returning a stop/continue decision, like the other interception
  * seams) would require reshaping this emit into a waterfall, awaiting listeners
- * before settling, and a `resume` capability on the in-process provider — part
- * of the deferred background/steering redesign, NOT this observe-only cut.
+ * before settling, and a `resume` capability on the in-process provider — a
+ * deliberate deferral, NOT part of this observe-only cut.
  *
  * @module @deepseek-ai/dsh-subagent
  */
diff --git a/packages/subagent/tool-subagent/README.md b/packages/subagent/tool-subagent/README.md
index 6fe26d3083..78c502bdd3 100644
--- a/packages/subagent/tool-subagent/README.md
+++ b/packages/subagent/tool-subagent/README.md
@@ -4,7 +4,7 @@ The model-facing `subagent` tool: delegate a self-contained task to a child agen
 
 ## Provider selection is config, not model-facing
 
-This plugin binds to **exactly one** provider (`Config.provider`). The model sees only `{ description, prompt }` — there is no provider/type parameter in the schema. To expose more than one transport, load the plugin more than once, each bound to a different provider **and a distinct `toolName`** (the tool registry rejects a duplicate name, so a second load that kept the default `subagent` name would throw). Keeping selection in config (not the schema) is the deliberate split: the *service* holds a multi-provider registry; the *tool* picks one.
+This plugin binds to **exactly one** provider (`Config.provider`). The model sees only `{ description, prompt, run_in_background? }` — there is no provider/type parameter in the schema. To expose more than one transport, load the plugin more than once, each bound to a different provider **and a distinct `toolName`** (the tool registry rejects a duplicate name, so a second load that kept the default `subagent` name would throw). Keeping selection in config (not the schema) is the deliberate split: the *service* holds a multi-provider registry; the *tool* picks one.
 
 ## The description states the provider's context contract
 
@@ -14,10 +14,13 @@ The tool description and the `prompt` parameter description are DERIVED from the
 |---|---|
 | `provider` (required) | The `ctx.subagents` provider name to start runs on (`spawn`, `fork`, `acp`, …). |
 | `toolName` | The model-facing tool name to register (default `subagent`). Set a distinct value per load when exposing multiple providers, e.g. `subagent` + `subagent_acp`. |
+| `enableRunInBackground` | Expose `run_in_background` in this instance's schema (default `true`). Disabled, the parameter is absent entirely — delegation through this instance stays strictly synchronous. |
 | `agentOptions` | Default per-child `{ model? }` applied to every spawned child. (No per-child persona: the deployment persona is a context-wide section every agent shares.) |
 
-## Lifecycle (synchronous collect)
+## Foreground lifecycle (synchronous collect)
 
 `execute` starts a run on the configured provider and **awaits `run.result` inside a `try/finally` that always `dispose()`s the run** — the owned child agent/session is torn down on every path (success, error, abort), never leaked. The tool's abort signal (`exec.signal`) is bridged to `run.cancel()`. A non-`completed` stop reason (aborted/error/max-tokens/refusal) maps to an `isError` tool result rather than returning partial output as success.
 
-Background / poll collection is deferred (see the [RFC](../../../docs/rfc/implemented/feature/2026-06-21-subagent-capability-seam.md)); this cut blocks the parent turn until the child finishes.
+## Background delegation (a generic task)
+
+`run_in_background: true` refuses an already-aborted `exec.signal`, starts the run, registers `{ kind: 'subagent', label: description, owner: parent, cancel, done }` with `ctx.tasks` (`@deepseek-ai/dsh-tasks`), and returns `started background subagent task <id>` — the parent keeps working and collects/stops the child through the generic `task_output`/`task_list`/`task_kill` tools (`@deepseek-ai/dsh-tool-tasks`). The tool-call signal is deliberately NOT wired to the run after the id is returned; cancellation belongs to `task_kill` (its logged `reason` is forwarded to `run.cancel`) and the runtime's owner-disposal cleanup. The task is final-output-only (no incremental transcript — the child session remains the detailed trace), and its `done` settles only after `run.dispose()` (child quiescence), so owner disposal cannot resolve before the child is actually gone. Mapping (exported for tests): `runOutcome` — `completed` carries the final text as the task output; `aborted` → `killed`; `error`/`max-tokens`/`refusal`/unknown → `failed` with the reason as status-line detail — and `settleRun`, which disposes on both result paths and contains an infrastructure rejection as `failed`. A missing `ctx.tasks` fails the call loud (`background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks`). See the [background subagent tasks RFC](../../../docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md).
diff --git a/packages/subagent/tool-subagent/package.json b/packages/subagent/tool-subagent/package.json
index 254c9e2928..3b355d1687 100644
--- a/packages/subagent/tool-subagent/package.json
+++ b/packages/subagent/tool-subagent/package.json
@@ -25,6 +25,7 @@
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-subagent": "^0.0.1",
+    "@deepseek-ai/dsh-tasks": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
@@ -32,13 +33,15 @@
     "schemastery": "^3.18.0"
   },
   "devDependencies": {
+    "@cordisjs/plugin-loader": "^1.0.0-rc.4",
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-subagent": "workspace:^",
     "@deepseek-ai/dsh-subagent-mock": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tasks": "workspace:^",
+    "@deepseek-ai/dsh-tool-tasks": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
-    "@cordisjs/plugin-loader": "^1.0.0-rc.4",
     "cordis": "^4.0.0-rc.6"
   }
 }
diff --git a/packages/subagent/tool-subagent/src/index.ts b/packages/subagent/tool-subagent/src/index.ts
index f48ef4345e..669621cb21 100644
--- a/packages/subagent/tool-subagent/src/index.ts
+++ b/packages/subagent/tool-subagent/src/index.ts
@@ -9,7 +9,7 @@
  * EXACTLY ONE provider name (`Config.provider`). To expose more than one
  * transport, load the plugin more than once, each bound to a different provider
  * — there is no provider/type parameter in the model-facing schema. The model
- * sees only `{ description, prompt }`.
+ * sees only `{ description, prompt }` (plus `run_in_background` when enabled).
  *
  * The tool DESCRIPTION is derived from the bound provider's context contract
  * ({@link providerWording}): a fresh-context provider (spawn, ACP) gets the
@@ -20,13 +20,24 @@
  * provider goes away — so no load-order requirement exists and an HMR reload
  * of the backend re-derives the wording from the fresh provider.
  *
- * Collection is SYNCHRONOUS this cut: `execute` starts a run and awaits
+ * FOREGROUND collection is synchronous: `execute` starts a run and awaits
  * `run.result` inside a `try/finally` that always disposes the run, so the
  * owned child agent/session is torn down on every path (success, error, abort)
  * and never leaks as a live idle child. A non-`completed` stop reason maps to an
  * `isError` tool result (by throwing) rather than returning partial output as
  * success.
  *
+ * BACKGROUND delegation (`run_in_background: true`, exposed only when this
+ * instance's `enableRunInBackground` config allows) is a generic background
+ * TASK: the run is registered with `ctx.tasks` (kind `subagent`, final-output
+ * only — the child session remains the detailed trace) and collected/stopped
+ * through the generic `task_output`/`task_list`/`task_kill` tools. The
+ * tool-call abort signal is deliberately NOT wired to a background child:
+ * after the id is returned the parent step may end while the child works —
+ * cancellation belongs to `task_kill` and the owner-disposal cleanup. The
+ * task's `done` settles only after `run.dispose()` (child quiescence), which
+ * is what makes owner-disposal cleanup an actual no-leak guarantee.
+ *
  * @module @deepseek-ai/dsh-tool-subagent
  */
 
@@ -36,6 +47,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { AgentOptions } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { SubagentProvider, SubagentResult, SubagentRun, SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
+import type { TaskOutcome } from '@deepseek-ai/dsh-tasks'
 
 export const name = 'tool-subagent'
 export const inject = ['tools', 'subagents']
@@ -52,6 +64,14 @@ export interface Config {
    * `{ provider: 'acp', toolName: 'subagent_acp' }`.
    */
   toolName?: string
+  /**
+   * Expose `run_in_background` in this instance's schema (default true).
+   * Disabled, the parameter is absent entirely — schema and capability never
+   * disagree; delegation through this instance stays strictly synchronous.
+   * Backgrounding also needs the `ctx.tasks` runtime at call time; a missing
+   * one fails the call loud with the load-these-packages message.
+   */
+  enableRunInBackground?: boolean
   /**
    * Default per-child agent options (model) applied to every spawned child.
    * Omitted fields fall back to the child loop's own defaults. There is no
@@ -64,6 +84,7 @@ export interface Config {
 export const Config: z<Config> = z.object({
   provider: z.string().required(),
   toolName: z.string().default('subagent'),
+  enableRunInBackground: z.boolean().default(true),
   agentOptions: z.object({
     model: z.string(),
   }),
@@ -102,6 +123,54 @@ function stopReasonError(result: SubagentResult): string | undefined {
   }
 }
 
+/**
+ * Map a settled subagent result onto the generic task-outcome vocabulary:
+ * `completed` carries the final text as the task's idempotent output;
+ * `aborted` is the task-level `killed`; everything else — `error`,
+ * `max-tokens`, `refusal`, and unknown merge-extensible reasons — is `failed`
+ * with the reason as the status-line detail (partial output is NOT reported
+ * as output, mirroring the synchronous path's report-the-reason rule).
+ * Exported for tests.
+ * @param result - the child's terminal result.
+ * @returns the outcome for the `ctx.tasks` registration.
+ */
+export function runOutcome(result: SubagentResult): TaskOutcome {  switch (result.stopReason) {
+  case 'completed':
+    return { status: 'completed', output: outputText(result.output) }
+  case 'aborted':
+    return { status: 'killed' }
+  case 'error':
+  case 'max-tokens':
+  case 'refusal':
+    return { status: 'failed', detail: result.stopReason }
+    // Merge-extensible union: an unknown terminal reason is a failure with
+    // the raw reason as detail, never partial output as success.
+  default:
+    return { status: 'failed', detail: String(result.stopReason) }
+}
+}
+
+/**
+ * Settle a background run at QUIESCENCE: await the child's result, ALWAYS
+ * dispose the run (the owned child agent/session is released on every path),
+ * and only then report the mapped outcome — so the task registry's `done`,
+ * and therefore owner-disposal cleanup, cannot resolve before the child is
+ * actually gone. A rejected `run.result` (infrastructure fault — no
+ * SubagentResult exists) reports `failed` with the error as detail rather
+ * than rejecting the producer contract. Exported for tests.
+ * @param run - the live background run to settle and release.
+ * @returns the task outcome, after the run's resources are released.
+ */
+export async function settleRun(run: SubagentRun): Promise<TaskOutcome> {
+  try {
+    return runOutcome(await run.result)
+  } catch (error: unknown) {
+    return { status: 'failed', detail: String(error) }
+  } finally {
+    await run.dispose()
+  }
+}
+
 /**
  * Model-facing wording per context contract ({@link SubagentProvider.inheritsParentContext}).
  * A fresh child needs a standalone prompt; a forked child already sees the
@@ -150,9 +219,12 @@ export function apply(ctx: Context, config: Config): void {
   let disposeTool: (() => void) | undefined
   const mount = (provider: SubagentProvider): void => {
     const wording = providerWording(provider.inheritsParentContext)
+    const backgroundEnabled = config.enableRunInBackground !== false
     disposeTool = ctx.tools.register(defineTool({
       name: config.toolName ?? 'subagent',
-      description: wording.description,
+      description: wording.description + (backgroundEnabled
+        ? ' Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.'
+        : ''),
       parameters: {
         description: {
           type: 'string',
@@ -164,6 +236,12 @@ export function apply(ctx: Context, config: Config): void {
           required: true,
           description: wording.promptDescription,
         },
+        ...backgroundEnabled ? {
+          run_in_background: {
+            type: 'boolean' as const,
+            description: 'Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill).',
+          },
+        } : {},
       },
       async execute(args, exec): Promise<ContentBlock[]> {
         const parent = exec.agent
@@ -174,6 +252,47 @@ export function apply(ctx: Context, config: Config): void {
           throw new Error('subagent tool requires a calling agent (exec.agent was undefined)')
         }
 
+        if (args.run_in_background === true) {
+          // The generic runtime owns everything task-shaped; without it a task
+          // id would be uncollectable — fail loud with the fix, not a dangle.
+          const tasks = ctx.get('tasks')
+          if (tasks === undefined) {
+            throw new Error('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
+          }
+          // A step already cancelled must not spawn a child. After the id is
+          // returned the tool-call signal is deliberately NOT wired to the run
+          // (the child outlives this step; cancellation belongs to task_kill
+          // and owner-disposal cleanup), so the request carries NO signal.
+          if (exec.signal?.aborted) throw new Error('subagent delegation aborted')
+          const run = ctx.subagents.start(config.provider, {
+            prompt: [{ type: 'text', text: args.prompt }],
+            parent,
+            ...config.agentOptions ? { agentOptions: config.agentOptions } : {},
+          })
+          const done = settleRun(run)
+          let id: string
+          try {
+            id = tasks.register({
+              kind: 'subagent',
+              label: args.description,
+              owner: parent,
+              cancel: (reason) => { run.cancel(reason ?? 'background subagent task killed') },
+              done,
+              // No readOutput: a subagent task is final-output-only — the child
+              // session remains the detailed trace.
+            })
+          } catch (error: unknown) {
+            // A failed registration must not leak the just-started child: the
+            // model never received an id, so nothing could ever task_kill it.
+            // Cancel, await `done` (which settles only after run.dispose() —
+            // child quiescence), then fail the call with the real cause.
+            run.cancel('background task registration failed')
+            await done
+            throw error
+          }
+          return [{ type: 'text', text: `started background subagent task ${id}` }]
+        }
+
         const request: SubagentStartRequest = {
           prompt: [{ type: 'text', text: args.prompt }],
           parent,
diff --git a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
index 611069ef76..06d39c2ec6 100644
--- a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
+++ b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
@@ -5,9 +5,13 @@ import { CallId } from '@deepseek-ai/dsh-llm'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import { AgentId, type Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
 import SubagentService from '@deepseek-ai/dsh-subagent'
+import TaskService from '@deepseek-ai/dsh-tasks'
+import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import * as mock from '@deepseek-ai/dsh-subagent-mock'
 import * as tool from '../src/index.ts'
+import { runOutcome, settleRun } from '../src/index.ts'
 
 /**
  * Drives the REAL plugin body: mounts `dsh-tool-subagent` on a real
@@ -60,12 +64,21 @@ describe('dsh-tool-subagent', () => {
     expect(text(result)).toBe('child says hi')
   })
 
-  it('exposes only description + prompt to the model (no provider/type parameter)', async () => {
+  it('exposes description + prompt + run_in_background to the model (no provider/type parameter)', async () => {
     const ctx = await setup({ provider: 'mock' })
     const schema = ctx.tools.schemas().find(s => s.name === 'subagent')
     expect(schema).toBeDefined()
     const props = (schema!.parameters as { properties?: Record<string, unknown> }).properties ?? {}
+    expect(Object.keys(props).sort()).toEqual(['description', 'prompt', 'run_in_background'])
+    expect(schema!.description).toContain('task_output')
+  })
+
+  it('omits run_in_background entirely when the instance disables it (schema and capability never disagree)', async () => {
+    const ctx = await setup({ provider: 'mock', enableRunInBackground: false })
+    const schema = ctx.tools.schemas().find(s => s.name === 'subagent')
+    const props = (schema!.parameters as { properties?: Record<string, unknown> }).properties ?? {}
     expect(Object.keys(props).sort()).toEqual(['description', 'prompt'])
+    expect(schema!.description).not.toContain('task_output')
   })
 
   it.each([
@@ -452,3 +465,180 @@ describe('dsh-tool-subagent', () => {
     expect(unwrapped.Config).toBeDefined()
   })
 })
+
+describe('dsh-tool-subagent background mode', () => {
+  /** A parent agent carrying a real session token, registered in ctx.agents (owner-cleanup wiring requires a live registry entry). */
+  function ownerAgent(ctx: Context, sessionId: string, inject: (...args: unknown[]) => void = () => {}): Agent {
+    const agent = { id: AgentId(`agent-${sessionId}`), inject, session: { header: { version: 0, id: sessionId, createdAt: 0 } } } as unknown as Agent
+    ctx.agents.register(agent)
+    return agent
+  }
+
+  async function backgroundSetup(toolConfig: tool.Config, mockConfig: Partial<mock.Config> = {}) {
+    const ctx = await setup(toolConfig, mockConfig)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(TaskService)
+    await ctx.plugin(ToolTasks, {})
+    return ctx
+  }
+
+  it('returns a task id immediately and the answer is collected through task_output', async () => {
+    const ctx = await backgroundSetup({ provider: 'mock', agentOptions: { model: 'child-model' } }, { reply: 'background answer' })
+    const parent = ownerAgent(ctx, 'sess-parent')
+
+    const start = await callSubagent(ctx, { description: 'deep research', prompt: 'dig in', run_in_background: true }, { agent: parent })
+    expect(start.isError).toBe(false)
+    expect(text(start)).toBe('started background subagent task subagent-1')
+
+    const collected = await ctx.tools.execute({
+      callId: CallId('collect-1'),
+      name: 'task_output',
+      arguments: { task_id: 'subagent-1', wait: true },
+      agent: parent,
+    })
+    expect(text(collected)).toBe('background answer\n[status: completed]')
+
+    // Final-output reads are idempotent (not consumed).
+    const again = await ctx.tools.execute({
+      callId: CallId('collect-2'),
+      name: 'task_output',
+      arguments: { task_id: 'subagent-1' },
+      agent: parent,
+    })
+    expect(text(again)).toBe('background answer\n[status: completed]')
+  })
+
+  it('fails loud when the tasks runtime is not loaded', async () => {
+    const ctx = await setup({ provider: 'mock' })
+    const result = await callSubagent(ctx, { description: 'd', prompt: 'p', run_in_background: true })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('background tasks unavailable: load @deepseek-ai/dsh-tasks')
+  })
+
+  it('refuses to start when the tool signal is already aborted', async () => {
+    const ctx = await backgroundSetup({ provider: 'mock' })
+    const parent = ownerAgent(ctx, 'sess-parent')
+    const controller = new AbortController()
+    controller.abort()
+    const result = await callSubagent(ctx, { description: 'd', prompt: 'p', run_in_background: true }, { agent: parent, signal: controller.signal })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('subagent delegation aborted')
+  })
+
+  it('forwards task_kill reasons to run.cancel (and defaults one when absent)', async () => {
+    // A provider whose runs settle only on cancel — the mock settles on a
+    // microtask, too fast to observe a LIVE kill through the real tools.
+    const ctx = await backgroundSetup({ provider: 'mock', agentOptions: { model: 'child-model' } })
+    const parent = ownerAgent(ctx, 'sess-parent')
+    const cancels: (string | undefined)[] = []
+    ctx.subagents.registerProvider({
+      name: 'hanging',
+      capabilities: { outputSchema: false, depthLimit: false, toolFilter: false },
+      inheritsParentContext: false,
+      start: () => {
+        let settle!: (value: { output: { type: 'text'; text: string }[]; stopReason: 'aborted' }) => void
+        return {
+          id: AgentId(`hang-${cancels.length}`),
+          result: new Promise((res) => { settle = res }),
+          cancel(reason?: string) { cancels.push(reason); settle({ output: [], stopReason: 'aborted' }) },
+          dispose: () => Promise.resolve(),
+        }
+      },
+    })
+    // Direct apply (schema bypass): schemastery would default agentOptions to
+    // an (truthy) empty object — the raw config exercises the omitted branch
+    // on the background start request.
+    tool.apply(ctx, { provider: 'hanging', toolName: 'subagent_hang' })
+
+    const startOne = await ctx.tools.execute({ callId: CallId('h1'), name: 'subagent_hang', arguments: { description: 'one', prompt: 'p', run_in_background: true }, agent: parent })
+    const startTwo = await ctx.tools.execute({ callId: CallId('h2'), name: 'subagent_hang', arguments: { description: 'two', prompt: 'p', run_in_background: true }, agent: parent })
+    expect(text(startOne)).toBe('started background subagent task subagent-1')
+    expect(text(startTwo)).toBe('started background subagent task subagent-2')
+
+    const withReason = await ctx.tools.execute({ callId: CallId('k1'), name: 'task_kill', arguments: { task_id: 'subagent-1', reason: 'superseded' }, agent: parent })
+    const withoutReason = await ctx.tools.execute({ callId: CallId('k2'), name: 'task_kill', arguments: { task_id: 'subagent-2' }, agent: parent })
+    expect(text(withReason)).toBe('requested cancellation of task subagent-1')
+    expect(text(withoutReason)).toBe('requested cancellation of task subagent-2')
+    expect(cancels).toEqual(['superseded', 'background subagent task killed'])
+
+    // The aborted children settle as killed tasks.
+    const killed = await ctx.tools.execute({ callId: CallId('w1'), name: 'task_output', arguments: { task_id: 'subagent-1', wait: true }, agent: parent })
+    expect(text(killed)).toBe('(no new output)\n[status: killed]')
+  })
+
+  it('runOutcome maps the stop-reason vocabulary onto task outcomes', () => {
+    const output = [{ type: 'text' as const, text: 'partial' }]
+    expect(runOutcome({ output, stopReason: 'completed' })).toEqual({ status: 'completed', output: 'partial' })
+    expect(runOutcome({ output, stopReason: 'aborted' })).toEqual({ status: 'killed' })
+    expect(runOutcome({ output, stopReason: 'error' })).toEqual({ status: 'failed', detail: 'error' })
+    expect(runOutcome({ output, stopReason: 'max-tokens' })).toEqual({ status: 'failed', detail: 'max-tokens' })
+    expect(runOutcome({ output, stopReason: 'refusal' })).toEqual({ status: 'failed', detail: 'refusal' })
+    // Merge-extensible: an unknown reason is failed-with-detail, never success.
+    expect(runOutcome({ output, stopReason: 'paused' as never })).toEqual({ status: 'failed', detail: 'paused' })
+  })
+
+  it('settleRun disposes the run before reporting, on both result paths', async () => {
+    const order: string[] = []
+    const completed = await settleRun({
+      id: AgentId('child-1'),
+      result: Promise.resolve({ output: [{ type: 'text' as const, text: 'ok' }], stopReason: 'completed' as const }),
+      cancel() {},
+      dispose() { order.push('dispose'); return Promise.resolve() },
+    })
+    order.push('reported')
+    expect(completed).toEqual({ status: 'completed', output: 'ok' })
+    expect(order).toEqual(['dispose', 'reported'])
+
+    // An infrastructure rejection still disposes and reports failed.
+    let disposed = false
+    const failed = await settleRun({
+      id: AgentId('child-2'),
+      result: Promise.reject(new Error('transport gone')),
+      cancel() {},
+      dispose() { disposed = true; return Promise.resolve() },
+    })
+    expect(failed).toEqual({ status: 'failed', detail: 'Error: transport gone' })
+    expect(disposed).toBe(true)
+  })
+})
+
+describe('background registration failure (no orphaned child)', () => {
+  it('cancels and disposes the just-started run when register() throws', async () => {
+    // TaskService is loaded but NO control surface is attached, so
+    // ctx.tasks.register throws AFTER the provider run already started.
+    const ctx = await setup({ provider: 'mock' })
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(TaskService)
+    const parent = { id: AgentId('agent-sess-p'), inject: () => {}, session: { header: { version: 0, id: 'sess-p', createdAt: 0 } } } as unknown as Agent
+    ctx.agents.register(parent)
+
+    const events: string[] = []
+    ctx.subagents.registerProvider({
+      name: 'probe',
+      capabilities: { outputSchema: false, depthLimit: false, toolFilter: false },
+      inheritsParentContext: false,
+      start: () => {
+        let settle!: (value: { output: never[]; stopReason: 'aborted' }) => void
+        return {
+          id: AgentId('probe-child'),
+          result: new Promise((res) => { settle = res }),
+          cancel(reason?: string) { events.push(`cancel:${reason}`); settle({ output: [], stopReason: 'aborted' }) },
+          dispose() { events.push('dispose'); return Promise.resolve() },
+        }
+      },
+    })
+    tool.apply(ctx, { provider: 'probe', toolName: 'subagent_probe' })
+
+    const result = await ctx.tools.execute({
+      callId: CallId('probe-1'),
+      name: 'subagent_probe',
+      arguments: { description: 'd', prompt: 'p', run_in_background: true },
+      agent: parent,
+    })
+    expect(result.isError).toBe(true)
+    expect(text(result)).toContain('no control surface is attached')
+    // The child was cancelled AND disposed before the call settled — the
+    // model never got an id, so nothing else could ever collect or kill it.
+    expect(events).toEqual(['cancel:background task registration failed', 'dispose'])
+  })
+})
diff --git a/packages/subagent/tool-subagent/tsconfig.json b/packages/subagent/tool-subagent/tsconfig.json
index 0a10bce7c5..2aa9d4f14e 100644
--- a/packages/subagent/tool-subagent/tsconfig.json
+++ b/packages/subagent/tool-subagent/tsconfig.json
@@ -28,6 +28,9 @@
     },
     {
       "path": "../subagent"
+    },
+    {
+      "path": "../../tasks/tasks"
     }
   ]
 }
diff --git a/packages/tasks/README.md b/packages/tasks/README.md
new file mode 100644
index 0000000000..a22528ba6d
--- /dev/null
+++ b/packages/tasks/README.md
@@ -0,0 +1,10 @@
+# tasks/ — background task capability family
+
+The shared background-task runtime: ONE home for task ids, owner isolation, polling, cancellation, wait, and completion notification, so bash, subagents, and every future long-running tool expose the same model-facing habit instead of cloning a private task protocol each. Rationale and the full design: [the background-task-runtime RFC](../../docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md).
+
+| Package | ctx key | Role |
+|---|---|---|
+| [`tasks`](tasks/README.md) (`@deepseek-ai/dsh-tasks`) | `ctx.tasks` | The registry service: branded `<kind>-N` ids, owner-fenced read/kill/wait/list, settlement bookkeeping, the awaited owner-cleanup path, and the `attachSurface` misconfiguration fence |
+| [`tool-tasks`](tool-tasks/README.md) (`@deepseek-ai/dsh-tool-tasks`) | — | The model-facing control surface: `task_output`, `task_list`, `task_kill`, the completion-notice injection, and the background-habit prompt section |
+
+The split is the state/surface boundary: the registry holds task state (an HMR reload of any tool plugin never orphans or kills a running task), while the tool surface is stateless presentation. Producers (`dsh-tool-bash`, `dsh-tool-subagent`) register running work via `ctx.tasks.register` and keep their own execution concerns; whether a producer exposes `run_in_background` is that producer's own `enableRunInBackground` config, never rewritten by this family.
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
new file mode 100644
index 0000000000..ec5a82f52c
--- /dev/null
+++ b/packages/tasks/tasks/README.md
@@ -0,0 +1,25 @@
+# @deepseek-ai/dsh-tasks
+
+The background task registry (`ctx.tasks`): a runtime-global, CONCRETE service (no interface/implementation split — one sensible in-process implementation exists; a durable job backend would own that extraction) that gives every long-running tool the same ids, isolation, and lifecycle.
+
+## Service API
+
+- `register(registration): TaskId` — a producer hands over running work: `kind` (also the id prefix), `label`, optional `owner: Agent`, `cancel(reason?)`, `done: Promise<TaskOutcome>` (settles at QUIESCENCE, never rejects), optional `readOutput()` (stream kinds; absence = final-output-only). Throws while no control surface is attached — the loud fence against a deployment exposing `run_in_background` with no way to collect or stop the work — and is ATOMIC: a failed registration mutates nothing (no stored task, no counter bump, no owner-cleanup bookkeeping), so producers can reliably cancel their just-started work and rethrow.
+- `get(id, caller?)` / `list(caller?)` — non-consuming snapshots; `list` returns only caller-owned plus unowned tasks (a global listing would leak foreign labels).
+- `read(id, caller?): TaskRead` — stream kinds consume the per-task cursor (v1's single intended reader is the owning model — a non-consuming multi-reader surface would be a cursor/snapshot API extension, not a `read` change); final kinds read the terminal output idempotently.
+- `kill(id, caller?, reason?)` — `'requested'` (live task: producer `cancel` runs first — a throw fails the kill loud and leaves the task untouched — then `stopping`) or `'already-terminal'`. Every successful kill marks the task `reported` (the killer saw the end → completion notice suppressed).
+- `wait(id, timeoutMs, caller?, signal?)` — resolves with the terminal snapshot (marked `reported`), or the live snapshot at timeout; an aborted signal rejects the WAIT only.
+- `onTaskDone(listener)` — exactly once per task with the terminal snapshot; effect-scoped, per-listener containment, silent after service disposal.
+- `attachSurface(name)` — declares a control surface exists (the model tools, or a deployment's custom surface); effect-scoped.
+
+Every read/kill/wait/get compares the task's owner session (`owner.session.header.id`) with the caller's and rejects a foreign one — ids are predictable (`bash-1`), so the fence, not id secrecy, is the isolation boundary.
+
+## Lifecycle
+
+- Registrations are NOT effect-scoped to the registering fiber: tasks belong to their owning agent + producing backend, so producer/surface HMR reloads never touch them.
+- An owned task attaches (once per owner) an awaited cleanup via `ctx.agents.onCleanup`: on the owner's disposal the registry cancels its live tasks, awaits each `done`, and drops the snapshots — `AgentHandle.dispose()` resolves only after quiescence.
+- Service disposal closes the listener registry first (late teardown kills stay silent), cancels every live task with containment, and awaits settlement.
+
+## Non-goals (v1)
+
+Durable/cross-restart tasks, non-consuming observation cursors, and foreground→background promotion are deliberate deferrals — see the [runtime RFC](../../../docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) § Alternatives.
diff --git a/packages/tasks/tasks/package.json b/packages/tasks/tasks/package.json
new file mode 100644
index 0000000000..3b2b9532c2
--- /dev/null
+++ b/packages/tasks/tasks/package.json
@@ -0,0 +1,35 @@
+{
+  "name": "@deepseek-ai/dsh-tasks",
+  "description": "Background task registry (ctx.tasks) for the DeepSeek Harness — shared ids, owner isolation, polling, cancellation, and completion listeners for long-running tool work",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
new file mode 100644
index 0000000000..ac9821b849
--- /dev/null
+++ b/packages/tasks/tasks/src/index.ts
@@ -0,0 +1,457 @@
+/**
+ * The background task registry (`ctx.tasks`): ONE home for the semantics every
+ * long-running tool needs — branded task ids, owner-scoped isolation, status
+ * snapshots, incremental/final output reads, cancellation, wait-for-terminal,
+ * completion listeners, and the awaited owner-cleanup path. Producers
+ * (`dsh-tool-bash` background commands, `dsh-tool-subagent` background
+ * delegations, future long-running tools) register running work via
+ * {@link TaskService.register} and keep their own execution concerns; the
+ * model-facing control surface (`@deepseek-ai/dsh-tool-tasks`) drives the
+ * generic read/list/kill/wait operations.
+ *
+ * A CONCRETE service, not an interface/implementation seam pair: there is one
+ * sensible in-process implementation today, and the capability-seam convention
+ * says not to split preemptively (see the background-task-runtime RFC).
+ *
+ * Cross-session isolation lives IN the registry: task ids are runtime-global
+ * and predictable (`bash-1`, `subagent-1`), so every read/kill/wait compares
+ * the task's owner session against the caller and rejects a foreign one —
+ * every surface gets the fence for free instead of re-implementing it.
+ *
+ * Task registrations are NOT effect-scoped to the registering fiber: a task
+ * belongs to its owning agent and producing backend, not to the tool plugin
+ * whose call started it, so an HMR reload of a producer or of the control
+ * surface never orphans or kills a running task. The registry's own disposal
+ * cancels every live task and awaits settlement — no orphans survive
+ * `fiber.dispose()`.
+ *
+ * @module @deepseek-ai/dsh-tasks
+ */
+
+import { Context, Service } from 'cordis'
+import type { Agent, AgentId } from '@deepseek-ai/dsh-agent'
+import { TaskId } from './types.ts'
+import type { TaskDoneListener, TaskOutcome, TaskRead, TaskRegistration, TaskSnapshot, TaskStatus } from './types.ts'
+
+export { TaskId } from './types.ts'
+export type {
+  TaskDoneListener,
+  TaskOutcome,
+  TaskRead,
+  TaskRegistration,
+  TaskSnapshot,
+  TaskStatus,
+} from './types.ts'
+
+declare module 'cordis' {
+  interface Context {
+    tasks: TaskService
+  }
+}
+
+/** The registry's mutable per-task record (never handed out — see {@link TaskService.snapshot}). */
+interface TrackedTask {
+  id: TaskId
+  kind: string
+  label: string
+  /** The owner's session id (`session.header.id`), or undefined for an unowned task. */
+  ownerSession: string | undefined
+  cancel: (reason?: string) => void
+  readOutput: (() => string) | undefined
+  status: TaskStatus
+  detail: string | undefined
+  output: string | undefined
+  startedAt: number
+  finishedAt: number | undefined
+  reported: boolean
+  /** Resolves once the terminal snapshot is recorded and listeners notified. */
+  settled: Promise<void>
+  /** Resolver for {@link settled} (called exactly once, by {@link TaskService.settle}). */
+  markSettled: () => void
+  /** Live {@link TaskService.wait} calls — a settlement with waiters marks the task reported. */
+  waiters: number
+}
+
+/** True for the three terminal {@link TaskStatus} values. */
+function isTerminal(status: TaskStatus): boolean {
+  return status === 'completed' || status === 'killed' || status === 'failed'
+}
+
+/**
+ * The `tasks` service: the runtime-global background task registry. See the
+ * module doc for the ownership, isolation, and lifecycle contracts.
+ */
+export class TaskService extends Service {
+  private store = new Map<TaskId, TrackedTask>()
+  private counters = new Map<string, number>()
+  private surfaces = new Set<symbol>()
+  private listeners = new Set<TaskDoneListener>()
+  private listenersClosed = false
+  /** Owner agents that already have this registry's cleanup attached. */
+  private ownerCleanups = new Set<AgentId>()
+  /**
+   * The service's OWN construction-time context, for work that outlives the
+   * calling fiber: detached settlement continuations (logging), and the
+   * owner-cleanup registration on `ctx.agents` (which must survive a producer
+   * plugin's HMR reload, unlike the caller-fiber-scoped effects in
+   * {@link onTaskDone}/{@link attachSurface}).
+   */
+  private readonly selfCtx: Context
+
+  constructor(ctx: Context) {
+    super(ctx, 'tasks')
+    this.selfCtx = ctx
+    ctx.effect(() => () => this.disposeAll(), 'tasks teardown')
+  }
+
+  /**
+   * Register running background work and receive its task id (`<kind>-N`,
+   * per-kind counter). The registry attaches ONE continuation to
+   * `registration.done` that records the terminal snapshot, notifies
+   * {@link onTaskDone} listeners, and releases waiters; an owned task also
+   * gets the owner's awaited disposal cleanup attached (once per owner agent)
+   * through `ctx.agents.onCleanup`. Throws when no control surface is
+   * attached ({@link attachSurface}) — a task the model could never read or
+   * stop must fail loud at the start, not dangle — and for an empty
+   * kind/label. ATOMIC: a throw mutates no registry state, so a producer can
+   * cancel its just-started work and rethrow without leaving a stored task
+   * behind.
+   * @param registration - the producer's task contract (see {@link TaskRegistration}).
+   * @returns the registry-issued task id.
+   */
+  register(registration: TaskRegistration): TaskId {
+    if (this.surfaces.size === 0) {
+      throw new Error('background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)')
+    }
+    if (registration.kind.length === 0) throw new Error('invalid task kind: expected a non-empty string')
+    if (registration.label.length === 0) throw new Error('invalid task label: expected a non-empty string')
+    // EVERYTHING that can throw runs before any mutation (counter, store):
+    // a failed registration must leave the registry exactly as it was — no
+    // stored-but-unreturned task the producer could never read or kill.
+    if (registration.owner !== undefined) this.ensureOwnerCleanup(registration.owner)
+
+    const count = (this.counters.get(registration.kind) ?? 0) + 1
+    this.counters.set(registration.kind, count)
+    const id = TaskId(`${registration.kind}-${count}`)
+
+    let markSettled!: () => void
+    const settled = new Promise<void>((resolve) => { markSettled = resolve })
+    const task: TrackedTask = {
+      id,
+      kind: registration.kind,
+      label: registration.label,
+      ownerSession: registration.owner?.session.header.id,
+      cancel: registration.cancel.bind(registration),
+      readOutput: registration.readOutput?.bind(registration),
+      status: 'running',
+      detail: undefined,
+      output: undefined,
+      startedAt: Date.now(),
+      finishedAt: undefined,
+      reported: false,
+      settled,
+      markSettled,
+      waiters: 0,
+    }
+    this.store.set(id, task)
+
+    void registration.done.then(
+      (outcome) => { this.settle(task, outcome) },
+      (error: unknown) => {
+        // Producer contract violation (`done` must never reject) — contained
+        // as a failed outcome so waiters, cleanup, and disposal never hang.
+        this.selfCtx.logger.warn(`tasks: task ${task.id} 'done' rejected (producer contract violation): ${String(error)}`)
+        this.settle(task, { status: 'failed', detail: String(error) })
+      },
+    )
+    return id
+  }
+
+  /**
+   * The caller-VISIBLE tasks (owned by the caller's session, or unowned), in
+   * registration order. Never lists another session's tasks — a global
+   * listing would leak their labels across the isolation fence.
+   * @param caller - the reading agent; undefined (a non-agent caller) sees only unowned tasks.
+   * @returns fresh snapshots; mutating them does not affect the registry.
+   */
+  list(caller?: Agent): TaskSnapshot[] {
+    const session = caller?.session.header.id
+    return [...this.store.values()]
+      .filter(task => task.ownerSession === undefined || task.ownerSession === session)
+      .map(task => this.snapshot(task))
+  }
+
+  /**
+   * A non-consuming snapshot of one task — unlike {@link read}, never touches
+   * the stream cursor or the reported flag (the kill surface uses it to
+   * describe an already-terminal task WITHOUT eating a pending delta).
+   * Throws for an unknown id or a task owned by another session.
+   * @param id - the task to look up.
+   * @param caller - the reading agent, checked against the task's owner.
+   * @returns a fresh snapshot.
+   */
+  get(id: TaskId, caller?: Agent): TaskSnapshot {
+    const task = this.expect(id)
+    this.assertAccess(task, caller)
+    return this.snapshot(task)
+  }
+
+  /**
+   * Read a task's output. Stream kinds (registered with `readOutput`) yield
+   * the CONSUMING delta since the previous read — one cursor per task, the
+   * owning model is v1's single intended reader; final-output kinds yield
+   * empty text while live and the terminal output idempotently once settled.
+   * A read that returns the terminal state marks the task {@link TaskSnapshot.reported}.
+   * Throws for an unknown id or a task owned by another session.
+   * @param id - the task to read.
+   * @param caller - the reading agent, checked against the task's owner.
+   * @returns the read text plus the post-read snapshot.
+   */
+  read(id: TaskId, caller?: Agent): TaskRead {
+    const task = this.expect(id)
+    this.assertAccess(task, caller)
+    const text = task.readOutput !== undefined
+      ? task.readOutput()
+      : isTerminal(task.status) ? task.output ?? '' : ''
+    if (isTerminal(task.status)) task.reported = true
+    return { text, snapshot: this.snapshot(task) }
+  }
+
+  /**
+   * Request cancellation of a task. A live task has its producer
+   * `cancel(reason)` invoked FIRST — a throw propagates (fail loud) and
+   * leaves the task untouched (still `running`, notice not suppressed) —
+   * then moves to `stopping` and settles through the normal `done` path; an
+   * already-terminal task is reported, not failed. Every SUCCESSFUL kill
+   * marks the task {@link TaskSnapshot.reported}: the killer has seen (or
+   * asked for) the end, so the completion notice is suppressed. Throws for
+   * an unknown id or a task owned by another session.
+   * @param id - the task to cancel.
+   * @param caller - the killing agent, checked against the task's owner.
+   * @param reason - the surface's logged reason, forwarded to the producer.
+   * @returns 'requested' when cancellation was asked of a live task, 'already-terminal' otherwise.
+   */
+  kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-terminal' {
+    const task = this.expect(id)
+    this.assertAccess(task, caller)
+    if (isTerminal(task.status)) {
+      task.reported = true
+      return 'already-terminal'
+    }
+    // Producer cancel FIRST: a throw must leave the task untouched (still
+    // `running`, notice not suppressed) — the killer's tool call fails loud,
+    // but task_list and the eventual completion notice keep telling the
+    // truth about a cancellation that never happened. Cancel is synchronous
+    // and settlement lands on a later microtask, so the mutations below
+    // cannot race the settle path.
+    task.cancel(reason)
+    task.status = 'stopping'
+    task.reported = true
+    return 'requested'
+  }
+
+  /**
+   * Wait for a task to settle, bounded by a timeout. Resolves with the
+   * terminal snapshot (marked {@link TaskSnapshot.reported} — the wait
+   * response reports the end, so the completion notice is suppressed), or
+   * with the still-live snapshot when the timeout expires first. An abort of
+   * `signal` rejects the WAIT only — the task keeps running. Throws for an
+   * unknown id, a task owned by another session, or a non-positive timeout.
+   * @param id - the task to wait for.
+   * @param timeoutMs - max wait in milliseconds (positive, finite; the surface caps it).
+   * @param caller - the waiting agent, checked against the task's owner.
+   * @param signal - optional abort for the wait itself.
+   * @returns the snapshot at settlement, or at timeout when the task outlives the wait.
+   */
+  async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot> {
+    const task = this.expect(id)
+    this.assertAccess(task, caller)
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      throw new Error(`invalid wait timeout: expected a positive number of milliseconds, got ${JSON.stringify(timeoutMs)}`)
+    }
+    if (!isTerminal(task.status)) {
+      if (signal?.aborted) throw new Error('wait aborted')
+      task.waiters += 1
+      try {
+        await new Promise<void>((resolve, reject) => {
+          const cleanup = (): void => {
+            clearTimeout(timer)
+            signal?.removeEventListener('abort', onAbort)
+          }
+          const timer = setTimeout(() => { cleanup(); resolve() }, timeoutMs)
+          const onAbort = (): void => { cleanup(); reject(new Error('wait aborted')) }
+          signal?.addEventListener('abort', onAbort, { once: true })
+          void task.settled.then(() => { cleanup(); resolve() })
+        })
+      } finally {
+        task.waiters -= 1
+      }
+    }
+    if (isTerminal(task.status)) task.reported = true
+    return this.snapshot(task)
+  }
+
+  /**
+   * Register a completion listener, called exactly once per task with the
+   * terminal snapshot. Effect-scoped (disposed with the calling fiber);
+   * per-listener containment (one throwing listener is logged, never starves
+   * the rest); never fires after this service is disposed.
+   * @param listener - called with each settling task's terminal snapshot.
+   * @returns the disposer that unregisters the listener.
+   */
+  onTaskDone(listener: TaskDoneListener): () => void {
+    const dispose = this.ctx.effect(() => {
+      this.listeners.add(listener)
+      return () => this.listeners.delete(listener)
+    }, 'tasks.onTaskDone()')
+    return () => void dispose()
+  }
+
+  /**
+   * Declare that a control surface capable of reading/stopping tasks is
+   * loaded. {@link register} refuses to start a background task while NO
+   * surface is attached — the loud fence against a deployment exposing
+   * `run_in_background` without any way to collect or stop the work. The
+   * model-facing `@deepseek-ai/dsh-tool-tasks` attaches on load; a deployment
+   * with a custom (non-model) surface attaches its own. Effect-scoped:
+   * detached with the calling fiber.
+   * @param name - a diagnostic label for the surface (duplicate names count independently).
+   * @returns the disposer that detaches the surface.
+   */
+  attachSurface(name: string): () => void {
+    // One token per attach call: duplicate names stay independent, and the
+    // single-shot effect disposer removes exactly its own attachment.
+    const token = Symbol(name)
+    const dispose = this.ctx.effect(() => {
+      this.surfaces.add(token)
+      return () => this.surfaces.delete(token)
+    }, 'tasks.attachSurface()')
+    return () => void dispose()
+  }
+
+  /** Look up a task or fail loud. */
+  private expect(id: TaskId): TrackedTask {
+    const task = this.store.get(id)
+    if (task === undefined) throw new Error(`unknown task ${id}`)
+    return task
+  }
+
+  /**
+   * The isolation fence: a task with an owner is reachable only by callers
+   * whose session id matches (`!== undefined` semantics — an unowned task is
+   * open, and a no-agent caller can never match an owned one).
+   */
+  private assertAccess(task: TrackedTask, caller?: Agent): void {
+    if (task.ownerSession !== undefined && task.ownerSession !== caller?.session.header.id) {
+      throw new Error(`task ${task.id} belongs to another session`)
+    }
+  }
+
+  /** Project a fresh read-only snapshot from the mutable record. */
+  private snapshot(task: TrackedTask): TaskSnapshot {
+    return {
+      id: task.id,
+      kind: task.kind,
+      label: task.label,
+      ...task.ownerSession !== undefined ? { ownerSession: task.ownerSession } : {},
+      status: task.status,
+      ...task.detail !== undefined ? { detail: task.detail } : {},
+      startedAt: task.startedAt,
+      ...task.finishedAt !== undefined ? { finishedAt: task.finishedAt } : {},
+      reported: task.reported,
+    }
+  }
+
+  /**
+   * Record a task's terminal outcome (called exactly once — the single `done`
+   * continuation is the only caller), notify listeners with containment, then
+   * release waiters. A settlement observed by a pending {@link wait} marks
+   * the task reported BEFORE listeners run, so the notice surface can
+   * suppress its redundant "finished".
+   */
+  private settle(task: TrackedTask, outcome: TaskOutcome): void {
+    task.status = outcome.status
+    task.detail = outcome.detail
+    task.output = outcome.output
+    task.finishedAt = Date.now()
+    if (task.waiters > 0) task.reported = true
+    if (!this.listenersClosed) {
+      const snapshot = this.snapshot(task)
+      for (const listener of this.listeners) {
+        try {
+          listener(snapshot)
+        } catch (error: unknown) {
+          this.selfCtx.logger.warn(`tasks: onTaskDone listener threw for ${task.id}: ${String(error)}`)
+        }
+      }
+    }
+    task.markSettled()
+  }
+
+  /**
+   * Attach the awaited owner-disposal cleanup for an owner agent, once: when
+   * the agent's disposal chain drains (`ctx.agents.drainCleanups`), the
+   * owner's still-live tasks are cancelled, awaited to settlement, and their
+   * snapshots dropped. Registered through {@link selfCtx} so the cleanup
+   * survives producer-plugin reloads. Fails loud when no agent registry is
+   * mounted — an owned background task without the cleanup seam would outlive
+   * its owner silently.
+   */
+  private ensureOwnerCleanup(owner: Agent): void {
+    if (this.ownerCleanups.has(owner.id)) return
+    const agents = this.selfCtx.get('agents')
+    if (agents === undefined) {
+      throw new Error('background task ownership requires the agent registry (load @deepseek-ai/dsh-agent)')
+    }
+    // Attach FIRST, record after: onCleanup throws for an unregistered agent,
+    // and marking the owner as covered before that would make every later
+    // registration for the same owner silently skip the cleanup.
+    agents.onCleanup(owner.id, async () => {
+      this.ownerCleanups.delete(owner.id)
+      await this.disposeOwned(owner.session.header.id)
+    })
+    this.ownerCleanups.add(owner.id)
+  }
+
+  /** Cancel (contained), await, and drop every task owned by one session. */
+  private async disposeOwned(ownerSession: string): Promise<void> {
+    const owned = [...this.store.values()].filter(task => task.ownerSession === ownerSession)
+    this.cancelForTeardown(owned, 'owner disposed')
+    await Promise.all(owned.map(task => task.settled))
+    for (const task of owned) this.store.delete(task.id)
+  }
+
+  /**
+   * Service teardown: close the listener registry FIRST (late completions
+   * from teardown kills stay silent), cancel every live task, and await
+   * quiescence. No orphan child work survives the tasks fiber.
+   */
+  private async disposeAll(): Promise<void> {
+    this.listenersClosed = true
+    this.listeners.clear()
+    const all = [...this.store.values()]
+    this.cancelForTeardown(all, 'tasks service disposed')
+    await Promise.all(all.map(task => task.settled))
+    this.store.clear()
+  }
+
+  /**
+   * Teardown-path cancellation with per-task containment: unlike the
+   * model-facing {@link kill} (where a throwing producer `cancel` should fail
+   * the tool call loudly), a teardown must reach quiescence past a broken
+   * producer, so a throw is logged and the sweep continues.
+   */
+  private cancelForTeardown(tasks: TrackedTask[], reason: string): void {
+    for (const task of tasks) {
+      if (isTerminal(task.status)) continue
+      task.status = 'stopping'
+      try {
+        task.cancel(reason)
+      } catch (error: unknown) {
+        this.selfCtx.logger.warn(`tasks: cancel of ${task.id} threw during teardown: ${String(error)}`)
+      }
+    }
+  }
+}
+
+export default TaskService
diff --git a/packages/tasks/tasks/src/types.ts b/packages/tasks/tasks/src/types.ts
new file mode 100644
index 0000000000..09b1911350
--- /dev/null
+++ b/packages/tasks/tasks/src/types.ts
@@ -0,0 +1,155 @@
+/**
+ * Task-registry vocabulary: the registration a producer hands to
+ * {@link TaskService.register} and the snapshots/reads consumers get back.
+ * Types only — the service lives in `./index.ts`.
+ *
+ * @module @deepseek-ai/dsh-tasks/types
+ */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+
+/**
+ * Identifies one background task in the runtime-global registry. Generated by
+ * {@link TaskService.register} as `<kind>-N` (per-kind counter) — kind-prefixed
+ * so transcripts stay self-describing, sequential because the owner fence (not
+ * id secrecy) is the isolation boundary.
+ */
+export type TaskId = Branded<'TaskId'>
+
+/**
+ * Brand a string as a {@link TaskId}.
+ * @param id - the raw task-id string (the registry generates `<kind>-N`).
+ * @returns the same string, branded; no validation is performed.
+ */
+export function TaskId(id: string): TaskId {
+  return id as TaskId
+}
+
+/**
+ * Task lifecycle. `running` → (`stopping` when cancellation was requested) →
+ * exactly one terminal {@link TaskOutcome.status} (`completed`, `killed`,
+ * `failed`). The vocabulary is generic and CLOSED — kind-specific meaning
+ * (exit codes, stop reasons) rides in {@link TaskSnapshot.detail}, so the
+ * registry never learns process or agent semantics.
+ */
+export type TaskStatus = 'running' | 'stopping' | 'completed' | 'killed' | 'failed'
+
+/**
+ * The terminal result a producer's {@link TaskRegistration.done} resolves
+ * with, mapped from the producer's own vocabulary (a process exit, a subagent
+ * stop reason) into the registry's closed status set.
+ */
+export interface TaskOutcome {
+  /** How the task ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
+  status: 'completed' | 'killed' | 'failed'
+  /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
+  detail?: string
+  /**
+   * Final output for FINAL-OUTPUT-ONLY kinds (no {@link TaskRegistration.readOutput}),
+   * read idempotently after the task settles. Stream kinds leave it unset —
+   * their output is consumed incrementally through `readOutput`.
+   */
+  output?: string
+}
+
+/**
+ * What a producer registers with {@link TaskService.register}: the running
+ * work's identity, its owner, and the three hooks the registry drives it
+ * through. The producer stays the owner of its execution concerns (process
+ * streams, child agents); the registry owns ids, isolation, status, and
+ * completion fan-out.
+ */
+export interface TaskRegistration {
+  /** Producer kind — also the id prefix (`bash`, `subagent`, …). Non-empty. */
+  kind: string
+  /** One-line model-facing label (the command; the delegation description). */
+  label: string
+  /**
+   * The spawning agent. Its `session.header.id` becomes the task's owner
+   * token (read/kill/wait/list are fenced to that session), and its disposal
+   * cancels and awaits the task through the `ctx.agents.onCleanup` seam.
+   * `undefined` registers an UNOWNED task: open to any caller, alive until the
+   * tasks service disposes.
+   */
+  owner?: Agent | undefined
+  /**
+   * Request termination. Idempotent, synchronous, and must lead to
+   * {@link done} settling; a throw propagates to the killer (fail loud — a
+   * cancel that cannot even be requested is a producer bug). The optional
+   * reason is `task_kill`'s logged reason, forwarded verbatim.
+   */
+  cancel(reason?: string): void
+  /**
+   * Settles with the terminal outcome at QUIESCENCE — after the producer has
+   * released the task's resources (process exited, child agent disposed) —
+   * not merely when the work finished. Must never reject; a rejection is
+   * contained as a `failed` outcome and logged as a producer contract
+   * violation.
+   */
+  done: Promise<TaskOutcome>
+  /**
+   * OPTIONAL incremental read (stream kinds): everything produced since the
+   * previous call, formatted by the producer (truncation/spill notices
+   * included). Consecutive calls never re-deliver output; the registry keeps
+   * ONE consuming cursor per task, so v1's single intended reader is the
+   * owning model. Absence marks a final-output-only kind (the method presence
+   * IS the capability).
+   */
+  readOutput?(): string
+}
+
+/**
+ * A read-only projection of one task, safe to hand to listeners and tools —
+ * a fresh object per call, never live registry state.
+ */
+export interface TaskSnapshot {
+  /** The registry-issued id (`<kind>-N`). */
+  id: TaskId
+  /** The producer kind the task was registered with. */
+  kind: string
+  /** The producer-supplied one-line label. */
+  label: string
+  /**
+   * The owner's session id (`session.header.id`), for surfaces that must
+   * reach the owning agent (the completion-notice injector); absent for
+   * unowned tasks. Session ids are runtime-shared identifiers, not secrets —
+   * the read/kill/wait/list FENCE is what isolation rests on.
+   */
+  ownerSession?: string
+  /** Current lifecycle state. */
+  status: TaskStatus
+  /** Kind-specific status detail, present once the producer supplied one (usually terminal). */
+  detail?: string
+  /** Epoch ms when the task was registered. */
+  startedAt: number
+  /** Epoch ms when the task settled; absent while `running`/`stopping`. */
+  finishedAt?: number
+  /**
+   * True once the terminal state has been (or is being) reported to the owner
+   * through an explicit surface response — a `kill` call, or a `read`/`wait`
+   * that returned the terminal state (including a wait pending at settlement).
+   * Completion-notice surfaces suppress their notice when set, so the model
+   * never gets a redundant "finished" for a task it just collected or killed.
+   */
+  reported: boolean
+}
+
+/**
+ * One {@link TaskService.read}: the output text this read yields (may be
+ * empty — the surface decides how to render "nothing new") plus the snapshot
+ * taken after the read.
+ */
+export interface TaskRead {
+  /**
+   * Stream kinds: the consuming delta since the previous read. Final-output
+   * kinds: empty while live, the terminal {@link TaskOutcome.output} (or
+   * empty) once settled — idempotent, never consumed.
+   */
+  text: string
+  /** The task's state at read time. */
+  snapshot: TaskSnapshot
+}
+
+/** Completion callback registered via {@link TaskService.onTaskDone}. */
+export type TaskDoneListener = (snapshot: TaskSnapshot) => void
diff --git a/packages/tasks/tasks/tests/tasks.spec.ts b/packages/tasks/tasks/tests/tasks.spec.ts
new file mode 100644
index 0000000000..87a71cd565
--- /dev/null
+++ b/packages/tasks/tasks/tests/tasks.spec.ts
@@ -0,0 +1,465 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import TaskService, { TaskId } from '@deepseek-ai/dsh-tasks'
+import type { TaskOutcome, TaskRegistration, TaskSnapshot } from '@deepseek-ai/dsh-tasks'
+
+function stubAgent(rawId: string): Agent {
+  const id = AgentId(rawId)
+  return {
+    id,
+    options: {},
+    session: new Session(SessionId(`${id}-session`)),
+    status: 'idle',
+    send() {},
+    steer() {},
+    inject() {},
+    cancel() {},
+    whenIdle() { return Promise.resolve() },
+  }
+}
+
+/** A controllable producer: settle its `done` on demand, record cancels. */
+function producer(overrides: Partial<TaskRegistration> = {}) {
+  let settle!: (outcome: TaskOutcome) => void
+  let reject!: (error: unknown) => void
+  const cancels: (string | undefined)[] = []
+  const registration: TaskRegistration = {
+    kind: 'bash',
+    label: 'sleep 60',
+    cancel(reason) { cancels.push(reason) },
+    done: new Promise<TaskOutcome>((res, rej) => { settle = res; reject = rej }),
+    ...overrides,
+  }
+  return { registration, settle, reject, cancels }
+}
+
+async function harness() {
+  const ctx = new Context()
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(TaskService)
+  ctx.tasks.attachSurface('test-surface')
+  return ctx
+}
+
+/** Let the settlement continuation (a `done.then`) run. */
+const tick = () => new Promise<void>(r => setTimeout(r, 0))
+
+describe('TaskService.register', () => {
+  it('refuses to register while no control surface is attached', async () => {
+    const ctx = new Context()
+    await ctx.plugin(TaskService)
+    expect(() => ctx.tasks.register(producer().registration))
+      .toThrow('background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)')
+  })
+
+  it('rejects an empty kind and an empty label', async () => {
+    const ctx = await harness()
+    expect(() => ctx.tasks.register(producer({ kind: '' }).registration)).toThrow('invalid task kind')
+    expect(() => ctx.tasks.register(producer({ label: '' }).registration)).toThrow('invalid task label')
+  })
+
+  it('issues kind-prefixed ids from per-kind counters', async () => {
+    const ctx = await harness()
+    expect(ctx.tasks.register(producer().registration)).toBe('bash-1')
+    expect(ctx.tasks.register(producer().registration)).toBe('bash-2')
+    expect(ctx.tasks.register(producer({ kind: 'subagent' }).registration)).toBe('subagent-1')
+  })
+})
+
+describe('TaskService reads and settlement', () => {
+  it('stream kinds read a consuming delta; terminal reads mark reported', async () => {
+    const ctx = await harness()
+    const chunks = ['first', '', 'rest']
+    const p = producer({ readOutput: () => chunks.shift() ?? '' })
+    const id = ctx.tasks.register(p.registration)
+
+    expect(ctx.tasks.read(id)).toMatchObject({ text: 'first', snapshot: { status: 'running', reported: false } })
+    expect(ctx.tasks.read(id).text).toBe('')
+
+    p.settle({ status: 'completed', detail: 'exit code: 0' })
+    await tick()
+    const read = ctx.tasks.read(id)
+    expect(read.text).toBe('rest')
+    expect(read.snapshot).toMatchObject({ status: 'completed', detail: 'exit code: 0', reported: true })
+    expect(read.snapshot.finishedAt).toBeTypeOf('number')
+  })
+
+  it('final-output kinds read empty while live, the outcome output idempotently once settled', async () => {
+    const ctx = await harness()
+    const p = producer({ kind: 'subagent', label: 'research task' })
+    const id = ctx.tasks.register(p.registration)
+
+    expect(ctx.tasks.read(id)).toMatchObject({ text: '', snapshot: { status: 'running' } })
+
+    p.settle({ status: 'completed', output: 'final answer' })
+    await tick()
+    expect(ctx.tasks.read(id).text).toBe('final answer')
+    expect(ctx.tasks.read(id).text).toBe('final answer') // idempotent, not consumed
+  })
+
+  it('a settled task without output reads as empty text', async () => {
+    const ctx = await harness()
+    const p = producer({ kind: 'subagent' })
+    const id = ctx.tasks.register(p.registration)
+    p.settle({ status: 'failed', detail: 'max-tokens' })
+    await tick()
+    expect(ctx.tasks.read(id)).toMatchObject({ text: '', snapshot: { status: 'failed', detail: 'max-tokens' } })
+  })
+
+  it('throws for unknown task ids', async () => {
+    const ctx = await harness()
+    expect(() => ctx.tasks.read(TaskId('bash-99'))).toThrow('unknown task bash-99')
+  })
+
+  it('notifies onTaskDone once per task with containment across listeners', async () => {
+    const ctx = await harness()
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const seen: TaskSnapshot[] = []
+    ctx.tasks.onTaskDone(() => { throw new Error('listener boom') })
+    ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot))
+
+    const p = producer()
+    const id = ctx.tasks.register(p.registration)
+    p.settle({ status: 'completed', detail: 'exit code: 0' })
+    await tick()
+
+    expect(seen).toHaveLength(1)
+    expect(seen[0]).toMatchObject({ id, status: 'completed', reported: false })
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('listener boom'))
+  })
+
+  it('contains a rejecting done as a failed outcome (producer contract violation)', async () => {
+    const ctx = await harness()
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const p = producer()
+    const id = ctx.tasks.register(p.registration)
+    p.reject(new Error('transport exploded'))
+    await tick()
+
+    expect(ctx.tasks.read(id).snapshot).toMatchObject({ status: 'failed', detail: 'Error: transport exploded' })
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('producer contract violation'))
+  })
+
+  it('unregisters onTaskDone listeners with the contributing fiber (HMR safety)', async () => {
+    const ctx = await harness()
+    const seen: string[] = []
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.tasks.onTaskDone(snapshot => void seen.push(snapshot.id))
+    }, { inject: ['tasks'] }))
+    await fiber.dispose()
+    // The returned disposer detaches too (the non-fiber path).
+    const detach = ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot.id))
+    detach()
+
+    const p = producer()
+    ctx.tasks.register(p.registration)
+    p.settle({ status: 'completed' })
+    await tick()
+    expect(seen).toEqual([])
+  })
+})
+
+describe('TaskService.kill', () => {
+  it('cancels a live task with the forwarded reason and suppresses the notice', async () => {
+    const ctx = await harness()
+    const seen: TaskSnapshot[] = []
+    ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot))
+    const p = producer()
+    const id = ctx.tasks.register(p.registration)
+
+    expect(ctx.tasks.kill(id, undefined, 'no longer needed')).toBe('requested')
+    expect(p.cancels).toEqual(['no longer needed'])
+    expect(ctx.tasks.list()[0]).toMatchObject({ status: 'stopping', reported: true })
+
+    p.settle({ status: 'killed' })
+    await tick()
+    // The listener still fires (telemetry may care), but carries reported: true
+    // so the notice surface suppresses its redundant "finished".
+    expect(seen[0]).toMatchObject({ id, status: 'killed', reported: true })
+  })
+
+  it('reports an already-terminal task instead of failing', async () => {
+    const ctx = await harness()
+    const p = producer()
+    const id = ctx.tasks.register(p.registration)
+    p.settle({ status: 'completed' })
+    await tick()
+    expect(ctx.tasks.kill(id)).toBe('already-terminal')
+  })
+
+  it('propagates a throwing producer cancel and leaves the task untouched', async () => {
+    const ctx = await harness()
+    const seen: TaskSnapshot[] = []
+    ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot))
+    let broken = true
+    let settle!: (outcome: TaskOutcome) => void
+    const id = ctx.tasks.register({
+      kind: 'bash',
+      label: 'flaky cancel',
+      cancel() { if (broken) throw new Error('cancel boom') },
+      done: new Promise<TaskOutcome>((res) => { settle = res }),
+    })
+    expect(() => ctx.tasks.kill(id)).toThrow('cancel boom')
+    // The failed kill mutated NOTHING: still running, notice not suppressed,
+    // and a later (successful) kill still works.
+    expect(ctx.tasks.get(id)).toMatchObject({ status: 'running', reported: false })
+    settle({ status: 'completed' })
+    await tick()
+    expect(seen[0]).toMatchObject({ id, reported: false }) // notice would still fire
+
+    broken = false
+    expect(ctx.tasks.kill(id)).toBe('already-terminal')
+  })
+})
+
+describe('TaskService.wait', () => {
+  it('resolves with the terminal snapshot when the task settles, marked reported', async () => {
+    const ctx = await harness()
+    const seen: TaskSnapshot[] = []
+    ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot))
+    const p = producer()
+    const id = ctx.tasks.register(p.registration)
+
+    const wait = ctx.tasks.wait(id, 5_000)
+    p.settle({ status: 'completed', detail: 'exit code: 0' })
+    expect(await wait).toMatchObject({ status: 'completed', reported: true })
+    // The pending wait marked the task reported BEFORE listeners ran.
+    expect(seen[0]).toMatchObject({ id, reported: true })
+  })
+
+  it('returns the live snapshot on timeout without marking reported', async () => {
+    const ctx = await harness()
+    const id = ctx.tasks.register(producer().registration)
+    expect(await ctx.tasks.wait(id, 5)).toMatchObject({ status: 'running', reported: false })
+  })
+
+  it('returns immediately for an already-terminal task', async () => {
+    const ctx = await harness()
+    const p = producer()
+    const id = ctx.tasks.register(p.registration)
+    p.settle({ status: 'completed' })
+    await tick()
+    expect(await ctx.tasks.wait(id, 5_000)).toMatchObject({ status: 'completed', reported: true })
+  })
+
+  it('rejects a non-positive or non-finite timeout', async () => {
+    const ctx = await harness()
+    const id = ctx.tasks.register(producer().registration)
+    await expect(ctx.tasks.wait(id, 0)).rejects.toThrow('invalid wait timeout')
+    await expect(ctx.tasks.wait(id, Number.NaN)).rejects.toThrow('invalid wait timeout')
+  })
+
+  it('an aborted signal rejects the wait only — the task stays alive', async () => {
+    const ctx = await harness()
+    const id = ctx.tasks.register(producer().registration)
+
+    const controller = new AbortController()
+    const wait = ctx.tasks.wait(id, 5_000, undefined, controller.signal)
+    controller.abort()
+    await expect(wait).rejects.toThrow('wait aborted')
+    expect(ctx.tasks.list()[0]).toMatchObject({ status: 'running' })
+
+    const preAborted = new AbortController()
+    preAborted.abort()
+    await expect(ctx.tasks.wait(id, 5_000, undefined, preAborted.signal)).rejects.toThrow('wait aborted')
+  })
+})
+
+describe('TaskService owner isolation', () => {
+  it('fences read/kill/wait to the owning session and keeps unowned tasks open', async () => {
+    const ctx = await harness()
+    const owner = stubAgent('owner')
+    ctx.agents.register(owner)
+    const other = stubAgent('other')
+
+    const owned = ctx.tasks.register(producer({ owner }).registration)
+    const open = ctx.tasks.register(producer().registration)
+
+    // The owner and the unowned task are reachable.
+    expect(ctx.tasks.read(owned, owner).snapshot.id).toBe(owned)
+    expect(ctx.tasks.read(open, other).snapshot.id).toBe(open)
+
+    // A different session and a no-agent caller are rejected.
+    expect(() => ctx.tasks.read(owned, other)).toThrow(`task ${owned} belongs to another session`)
+    expect(() => ctx.tasks.kill(owned, other)).toThrow('belongs to another session')
+    await expect(ctx.tasks.wait(owned, 10, other)).rejects.toThrow('belongs to another session')
+    expect(() => ctx.tasks.read(owned)).toThrow('belongs to another session')
+  })
+
+  it('list() shows only caller-owned plus unowned tasks', async () => {
+    const ctx = await harness()
+    const alice = stubAgent('alice')
+    const bob = stubAgent('bob')
+    ctx.agents.register(alice)
+    ctx.agents.register(bob)
+
+    const aliceTask = ctx.tasks.register(producer({ owner: alice }).registration)
+    const bobTask = ctx.tasks.register(producer({ owner: bob }).registration)
+    const openTask = ctx.tasks.register(producer({ kind: 'subagent' }).registration)
+
+    expect(ctx.tasks.list(alice).map(t => t.id)).toEqual([aliceTask, openTask])
+    expect(ctx.tasks.list(bob).map(t => t.id)).toEqual([bobTask, openTask])
+    expect(ctx.tasks.list().map(t => t.id)).toEqual([openTask])
+  })
+
+  it('rejects an owned registration when no agent registry is mounted', async () => {
+    const ctx = new Context()
+    await ctx.plugin(TaskService)
+    ctx.tasks.attachSurface('test-surface')
+    expect(() => ctx.tasks.register(producer({ owner: stubAgent('a') }).registration))
+      .toThrow('background task ownership requires the agent registry')
+    // The failed registration mutated nothing: no stored task, counter untouched.
+    expect(ctx.tasks.list()).toEqual([])
+    expect(ctx.tasks.register(producer().registration)).toBe('bash-1')
+  })
+
+  it('a failed owner-cleanup attach leaves the registry unchanged and does not poison the owner', async () => {
+    const ctx = await harness()
+    const ghost = stubAgent('ghost') // never registered in ctx.agents
+
+    // onCleanup rejects the unregistered agent BEFORE any registry mutation.
+    expect(() => ctx.tasks.register(producer({ owner: ghost }).registration))
+      .toThrow('is not registered')
+    expect(ctx.tasks.list(ghost)).toEqual([])
+
+    // Once the agent actually exists, the same owner gets a WORKING cleanup —
+    // the failed attempt must not have marked it as already covered.
+    ctx.agents.register(ghost)
+    const cancels: (string | undefined)[] = []
+    let settle!: (outcome: TaskOutcome) => void
+    const id = ctx.tasks.register({
+      kind: 'bash',
+      label: 'after retry',
+      owner: ghost,
+      cancel(reason) { cancels.push(reason); settle({ status: 'killed' }) },
+      done: new Promise<TaskOutcome>((res) => { settle = res }),
+    })
+    expect(id).toBe('bash-1') // the failed attempt burned no counter
+    await ctx.agents.drainCleanups(ghost.id)
+    expect(cancels).toEqual(['owner disposed'])
+    expect(ctx.tasks.list(ghost)).toEqual([])
+  })
+})
+
+describe('TaskService owner cleanup', () => {
+  it('drains the owner: cancels live tasks, awaits settlement, drops snapshots', async () => {
+    const ctx = await harness()
+    const owner = stubAgent('owner')
+    ctx.agents.register(owner)
+
+    // The producer settles only when cancelled — models a child that stops on request.
+    let settle!: (outcome: TaskOutcome) => void
+    const cancels: (string | undefined)[] = []
+    ctx.tasks.register({
+      kind: 'subagent',
+      label: 'long research',
+      owner,
+      cancel(reason) { cancels.push(reason); settle({ status: 'killed' }) },
+      done: new Promise<TaskOutcome>((res) => { settle = res }),
+    })
+    const terminal = producer({ owner })
+    ctx.tasks.register(terminal.registration)
+    terminal.settle({ status: 'completed' })
+    await tick()
+
+    await ctx.agents.drainCleanups(owner.id)
+    expect(cancels).toEqual(['owner disposed'])
+    // Snapshots dropped: nothing of the owner's remains, listing is empty.
+    expect(ctx.tasks.list(owner)).toEqual([])
+  })
+
+  it('attaches one cleanup per owner and re-attaches after a drain', async () => {
+    const ctx = await harness()
+    const owner = stubAgent('owner')
+    ctx.agents.register(owner)
+
+    const first = producer({ owner })
+    const second = producer({ owner })
+    ctx.tasks.register(first.registration)
+    ctx.tasks.register(second.registration)
+    first.settle({ status: 'completed' })
+    second.settle({ status: 'completed' })
+    await tick()
+    await ctx.agents.drainCleanups(owner.id)
+
+    // A fresh task after the drain gets a fresh cleanup (the set was consumed).
+    const third = producer({ owner })
+    ctx.tasks.register(third.registration)
+    third.settle({ status: 'completed' })
+    await tick()
+    expect(ctx.tasks.list(owner)).toHaveLength(1)
+    await ctx.agents.drainCleanups(owner.id)
+    expect(ctx.tasks.list(owner)).toEqual([])
+  })
+
+  it('contains a throwing producer cancel on the cleanup path', async () => {
+    const ctx = await harness()
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const owner = stubAgent('owner')
+    ctx.agents.register(owner)
+
+    let settle!: (outcome: TaskOutcome) => void
+    ctx.tasks.register({
+      kind: 'bash',
+      label: 'broken producer',
+      owner,
+      cancel() { throw new Error('cancel boom') },
+      done: new Promise<TaskOutcome>((res) => { settle = res }),
+    })
+
+    const drain = ctx.agents.drainCleanups(owner.id)
+    settle({ status: 'failed', detail: 'gave up' })
+    await drain
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('cancel boom'))
+    expect(ctx.tasks.list(owner)).toEqual([])
+  })
+})
+
+describe('TaskService disposal', () => {
+  it('cancels live tasks, awaits settlement, and silences listeners', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const fiber = await ctx.plugin(TaskService)
+    const surface = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.tasks.attachSurface('test-surface')
+    }, { inject: ['tasks'] }))
+    void surface
+
+    const seen: string[] = []
+    ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot.id))
+    let settle!: (outcome: TaskOutcome) => void
+    const cancels: (string | undefined)[] = []
+    ctx.tasks.register({
+      kind: 'bash',
+      label: 'sleep 600',
+      cancel(reason) { cancels.push(reason); settle({ status: 'killed' }) },
+      done: new Promise<TaskOutcome>((res) => { settle = res }),
+    })
+
+    await fiber.dispose()
+    expect(cancels).toEqual(['tasks service disposed'])
+    // The teardown kill settles AFTER the listener registry closed: silent.
+    expect(seen).toEqual([])
+  })
+
+  it('detaching the last surface re-arms the register fence', async () => {
+    const ctx = new Context()
+    await ctx.plugin(TaskService)
+    const detachA1 = ctx.tasks.attachSurface('a')
+    const detachA2 = ctx.tasks.attachSurface('a') // duplicate name counts independently
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.tasks.attachSurface('b')
+    }, { inject: ['tasks'] }))
+
+    detachA1()
+    detachA1() // second call of the same disposer is a no-op
+    expect(() => ctx.tasks.register(producer().registration)).not.toThrow() // a ×1 + b remain
+    detachA2()
+    expect(() => ctx.tasks.register(producer().registration)).not.toThrow() // b remains
+    await fiber.dispose() // detaches b with its fiber (HMR safety)
+    expect(() => ctx.tasks.register(producer().registration)).toThrow('no control surface is attached')
+  })
+})
diff --git a/packages/tasks/tasks/tsconfig.json b/packages/tasks/tasks/tsconfig.json
new file mode 100644
index 0000000000..97fb432ffb
--- /dev/null
+++ b/packages/tasks/tasks/tsconfig.json
@@ -0,0 +1,24 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../core/agent"
+    }
+  ]
+}
diff --git a/packages/tasks/tool-tasks/README.md b/packages/tasks/tool-tasks/README.md
new file mode 100644
index 0000000000..0548526474
--- /dev/null
+++ b/packages/tasks/tool-tasks/README.md
@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-tool-tasks
+
+The model-facing background task control surface over `ctx.tasks`: three kind-agnostic tools, the completion-notice injection, and the prompt section that teaches the background habit. Loading this plugin calls `ctx.tasks.attachSurface('tool-tasks')`, which is what arms producers' `register()`.
+
+## Tools
+
+- `task_output(task_id, wait?, timeout_ms?)` — non-blocking read by default (stream kinds: the consuming delta since the previous read; final kinds: the final answer once terminal); every response ends with a `[status: …]` line (generic status + producer detail, e.g. `[status: completed, exit code: 0]`). `wait: true` blocks until settlement, bounded by `waitTimeoutMs`/`maxWaitTimeoutMs` config; a timed-out wait returns `[status: running]` and leaves the task alive.
+- `task_list()` — the caller's tasks, `<id> [<kind>] <status> — <label>` per line.
+- `task_kill(task_id, reason?)` — requests cancellation and returns immediately; the logged `reason` is forwarded to the producer. An already-terminal task is described via a non-consuming snapshot (never eats a pending delta).
+
+ACP render intent: all three are `generic` cards (`read`/`read`/`execute`) — a task read is not a terminal.
+
+## Completion notices
+
+On `onTaskDone`, injects `background task <id> (<kind>: <label>) finished [status: …]. Read its output with task_output.` into the owning agent's session (`agent.inject()` — durable context for the next request, not a wake-up). Suppressed when the snapshot is `reported` (the model already killed it, or a read/wait returned the end) — never a redundant "finished". The disposed-owner race is contained; a missing agent registry drops the notice.
+
+## Config
+
+| key | default | meaning |
+|---|---|---|
+| `waitTimeoutMs` | `30000` | wait duration when `task_output` sets `wait` without `timeout_ms` |
+| `maxWaitTimeoutMs` | `600000` | hard cap; larger model-supplied `timeout_ms` values are clamped |
+
+A config whose default exceeds the cap fails loud at load.
diff --git a/packages/tasks/tool-tasks/package.json b/packages/tasks/tool-tasks/package.json
new file mode 100644
index 0000000000..9e0b19d307
--- /dev/null
+++ b/packages/tasks/tool-tasks/package.json
@@ -0,0 +1,43 @@
+{
+  "name": "@deepseek-ai/dsh-tool-tasks",
+  "description": "Model-facing background task control tools (task_output, task_list, task_kill) over the ctx.tasks registry",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "@deepseek-ai/dsh-tasks": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tasks": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}
diff --git a/packages/tasks/tool-tasks/src/index.ts b/packages/tasks/tool-tasks/src/index.ts
new file mode 100644
index 0000000000..30ff629e88
--- /dev/null
+++ b/packages/tasks/tool-tasks/src/index.ts
@@ -0,0 +1,183 @@
+/**
+ * The model-facing background task control tools: `task_output`, `task_list`,
+ * `task_kill`. Kind-agnostic — a background bash command and a background
+ * subagent read, list, and die through the same three schemas — with every
+ * task concern (ids, isolation, cursors, settlement) behind the `ctx.tasks`
+ * registry (`@deepseek-ai/dsh-tasks`).
+ *
+ * This plugin IS the control surface: it calls `ctx.tasks.attachSurface()` on
+ * load, which is what re-arms producers' `register()` (the registry refuses
+ * background work while no surface could collect or stop it).
+ *
+ * Completion notices: when a task settles, a short notice is injected into
+ * the owning agent's session (`agent.inject()` — durable context for the NEXT
+ * model request, not a wake-up). A task whose terminal state the model
+ * already saw (`snapshot.reported` — an explicit kill, or a read/wait that
+ * returned the end) is suppressed, so the model never gets a redundant
+ * "finished" for work it just collected.
+ *
+ * @module @deepseek-ai/dsh-tool-tasks
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { GenericCallView } from '@deepseek-ai/dsh-tools'
+import { TaskId } from '@deepseek-ai/dsh-tasks'
+import type { TaskSnapshot } from '@deepseek-ai/dsh-tasks'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+
+export const name = 'tool-tasks'
+export const inject = ['tools', 'tasks', 'systemPrompt']
+
+/** Config: the `task_output` wait bounds (defaulted, capped — never hardcoded). */
+export interface Config {
+  /** Wait duration applied when `task_output` sets `wait` without `timeout_ms` (default 30s). */
+  waitTimeoutMs?: number
+  /** Hard cap on any single wait; a larger model-supplied `timeout_ms` is clamped down to it (default 10min). */
+  maxWaitTimeoutMs?: number
+}
+
+export const Config: z<Config> = z.object({
+  waitTimeoutMs: z.number().min(1).default(30_000),
+  maxWaitTimeoutMs: z.number().min(1).default(600_000),
+})
+
+/**
+ * Render a snapshot's status line — generic status plus the producer's
+ * kind-specific detail: `[status: completed, exit code: 0]`,
+ * `[status: failed, max-tokens]`, `[status: running]`. Exported for tests
+ * and for producers that want a consistent line in their own results.
+ * @param snapshot - the task state to render.
+ * @returns the bracketed status line.
+ */
+export function statusLine(snapshot: TaskSnapshot): string {
+  return snapshot.detail !== undefined
+    ? `[status: ${snapshot.status}, ${snapshot.detail}]`
+    : `[status: ${snapshot.status}]`
+}
+
+/**
+ * Reject an empty `task_id`. Type/presence come from the SchemaSpec
+ * validation; only the non-empty constraint, which the DSL cannot express,
+ * is checked here.
+ */
+function validateTaskId(value: string): TaskId {
+  if (value.length === 0) {
+    throw new Error(`invalid task_id: expected a non-empty string, got ${JSON.stringify(value)}`)
+  }
+  return TaskId(value)
+}
+
+/** Pending-state presentation shared by the three control tools (generic cards by design — a task read/kill is not a terminal). */
+function presentTaskCall(title: string, kind: 'read' | 'execute', rawInput?: string): GenericCallView {
+  return { card: 'generic', title, kind, ...rawInput !== undefined ? { rawInput } : {} }
+}
+
+export function apply(ctx: Context, config: Config): void {
+  const waitDefault = config.waitTimeoutMs ?? 30_000
+  const waitCap = config.maxWaitTimeoutMs ?? 600_000
+  if (waitDefault > waitCap) {
+    throw new Error(`tool-tasks: waitTimeoutMs (${waitDefault}) exceeds maxWaitTimeoutMs (${waitCap})`)
+  }
+
+  // The registry's misconfiguration fence: producers can register background
+  // work only while a surface capable of collecting/stopping it is attached.
+  ctx.tasks.attachSurface('tool-tasks')
+
+  // The cross-call HABIT the per-tool descriptions cannot carry. Order 106:
+  // right after tool:bash (105), before deployment product sections.
+  ctx.systemPrompt.section({
+    name: 'tool:tasks',
+    order: 106,
+    text: 'Track every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task\'s work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.',
+  })
+
+  // Background completion → inject a notice into the owning agent's session.
+  // `ctx.get('agents')` (not static inject): this listener runs from a
+  // detached settlement continuation on the tasks fiber — a foreign fiber —
+  // where the `ctx.agents` property proxy would throw; `ctx.get` is the
+  // topology-independent lookup. No registry mounted → drop the notice.
+  ctx.tasks.onTaskDone((snapshot) => {
+    // A reported terminal state was already surfaced by an explicit
+    // read/wait/kill response — a notice would be a redundant "finished".
+    if (snapshot.reported || snapshot.ownerSession === undefined) return
+    const agent = ctx.get('agents')?.list().find(a => a.session.header.id === snapshot.ownerSession)
+    if (!agent) return
+    try {
+      agent.inject(
+        [{ type: 'text', text: `background task ${snapshot.id} (${snapshot.kind}: ${snapshot.label}) finished ${statusLine(snapshot)}. Read its output with task_output.` }],
+        { source: { kind: 'plugin', plugin: 'tool-tasks' } },
+      )
+    } catch (error: unknown) {
+      // The ONE expected failure: the agent was disposed between settlement
+      // and this injection (inject throws `agent "<id>" is disposed`). That
+      // race is benign — drop the notice. Anything else must surface.
+      if (error instanceof Error && error.message.includes('is disposed')) return
+      throw error
+    }
+  })
+
+  ctx.tools.register(defineTool({
+    name: 'task_output',
+    description: 'Read output/status from a background task (started by a tool with `run_in_background`). '
+      + 'Stream tasks (bash) return only output produced since your previous task_output call; '
+      + 'final-output tasks (subagent) return the final answer once the task finishes. '
+      + 'Every response ends with a [status: ...] line. Non-blocking by default; '
+      + 'set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.',
+    parameters: {
+      task_id: { type: 'string', required: true, description: 'Task id returned by the tool that started the background work.' },
+      wait: { type: 'boolean', description: 'Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive.' },
+      timeout_ms: { type: 'number', description: 'Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum.' },
+    },
+    async execute(args, exec) {
+      const id = validateTaskId(args.task_id)
+      if (args.wait === true) {
+        const timeout = Math.min(args.timeout_ms ?? waitDefault, waitCap)
+        await ctx.tasks.wait(id, timeout, exec.agent, exec.signal)
+      }
+      const read = ctx.tasks.read(id, exec.agent)
+      const body = read.text.length > 0 ? read.text : '(no new output)'
+      const separator = body.endsWith('\n') ? '' : '\n'
+      return [{ type: 'text', text: `${body}${separator}${statusLine(read.snapshot)}` }]
+    },
+    presentCall: args => presentTaskCall(`Read output from background task ${args.task_id}`, 'read', args.task_id),
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'task_list',
+    description: 'List your background tasks (running and finished) with their ids, kinds, and statuses.',
+    parameters: {},
+    // execute is synchronous (registry reads + string shaping) but the
+    // ToolDefinition contract wants a Promise — hence resolve(), not async.
+    execute(_args, exec) {
+      const tasks = ctx.tasks.list(exec.agent)
+      const text = tasks.length === 0
+        ? '(no background tasks)'
+        : tasks.map(t => `${t.id} [${t.kind}] ${t.status} — ${t.label}`).join('\n')
+      return Promise.resolve([{ type: 'text', text }])
+    },
+    presentCall: () => presentTaskCall('List background tasks', 'read'),
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'task_kill',
+    description: 'Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.',
+    parameters: {
+      task_id: { type: 'string', required: true, description: 'Task id returned by the tool that started the background work.' },
+      reason: { type: 'string', description: 'Optional short reason, recorded in the log and forwarded to the task.' },
+    },
+    execute(args, exec) {
+      const id = validateTaskId(args.task_id)
+      const result = ctx.tasks.kill(id, exec.agent, args.reason)
+      if (result === 'already-terminal') {
+        // ctx.tasks.get, NOT .read: a read would consume a stream task's
+        // pending delta just to describe the terminal state.
+        const snapshot = ctx.tasks.get(id, exec.agent)
+        return Promise.resolve([{ type: 'text', text: `task ${id} had already finished ${statusLine(snapshot)}` }])
+      }
+      return Promise.resolve([{ type: 'text', text: `requested cancellation of task ${id}` }])
+    },
+    presentCall: args => presentTaskCall(`Kill background task ${args.task_id}`, 'execute', args.task_id),
+  }))
+}
diff --git a/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
new file mode 100644
index 0000000000..930dc2b019
--- /dev/null
+++ b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
@@ -0,0 +1,306 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import TaskService from '@deepseek-ai/dsh-tasks'
+import type { TaskOutcome, TaskRegistration, TaskSnapshot } from '@deepseek-ai/dsh-tasks'
+import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
+import { statusLine } from '@deepseek-ai/dsh-tool-tasks'
+
+async function setup(config: ToolTasks.Config = {}) {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  const agentsFiber = await ctx.plugin(AgentRegistry)
+  await ctx.plugin(TaskService)
+  const toolsFiber = await ctx.plugin(ToolTasks, config)
+  return { ctx, agentsFiber, toolsFiber }
+}
+
+/**
+ * A fake agent whose session token is `sessionId`, registered in `ctx.agents`
+ * (the notice path finds the owner by scanning the registry for a matching
+ * `session.header.id` — the agent id is deliberately DIFFERENT so a
+ * wrong-field match fails the test).
+ */
+function fakeAgent(ctx: Context, sessionId: string, inject: (...args: unknown[]) => void = () => {}): Agent {
+  const agent = { id: `agent-${sessionId}`, inject, session: { header: { version: 0, id: sessionId, createdAt: 0 } } } as unknown as Agent
+  ctx.agents.register(agent)
+  return agent
+}
+
+/** A controllable producer registration (settle `done` on demand, record cancels). */
+function producer(overrides: Partial<TaskRegistration> = {}) {
+  let settle!: (outcome: TaskOutcome) => void
+  const cancels: (string | undefined)[] = []
+  const registration: TaskRegistration = {
+    kind: 'bash',
+    label: 'sleep 60',
+    cancel(reason) { cancels.push(reason) },
+    done: new Promise<TaskOutcome>((res) => { settle = res }),
+    ...overrides,
+  }
+  return { registration, settle, cancels }
+}
+
+let callCounter = 0
+function call(ctx: Context, name: string, args: unknown, agent?: Agent) {
+  return ctx.tools.execute({ callId: CallId(`call-${++callCounter}`), name, arguments: args, ...agent ? { agent } : {} })
+}
+
+function text(result: { content: { type: string; text?: string }[] }): string {
+  return result.content.filter(block => block.type === 'text').map(block => block.text).join('')
+}
+
+const tick = () => new Promise<void>(r => setTimeout(r, 0))
+
+describe('tool-tasks setup', () => {
+  it('attaches the control surface on load and detaches it with the fiber', async () => {
+    const { ctx, toolsFiber } = await setup()
+    expect(() => ctx.tasks.register(producer().registration)).not.toThrow()
+    await toolsFiber.dispose()
+    expect(() => ctx.tasks.register(producer().registration)).toThrow('no control surface is attached')
+  })
+
+  it('rejects a config whose default wait exceeds the cap', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(TaskService)
+    await expect(ctx.plugin(ToolTasks, { waitTimeoutMs: 100, maxWaitTimeoutMs: 50 }))
+      .rejects.toThrow('waitTimeoutMs (100) exceeds maxWaitTimeoutMs (50)')
+  })
+
+  it('renders status lines with and without producer detail', () => {
+    const base = { id: 'bash-1', kind: 'bash', label: 'x', startedAt: 0, reported: false } as unknown as TaskSnapshot
+    expect(statusLine({ ...base, status: 'running' })).toBe('[status: running]')
+    expect(statusLine({ ...base, status: 'completed', detail: 'exit code: 0' })).toBe('[status: completed, exit code: 0]')
+  })
+
+  it('applies the built-in wait bounds when apply() receives a bare config', async () => {
+    // Bypasses the schemastery defaults on purpose: apply() must stand on its
+    // own `??` fallbacks when embedded programmatically without the schema.
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(TaskService)
+    ToolTasks.apply(ctx, {})
+    expect(ctx.tools.get('task_output')).toBeDefined()
+    expect(() => ctx.tasks.register(producer().registration)).not.toThrow()
+  })
+})
+
+describe('task_output', () => {
+  it('reads a consuming delta with a trailing status line', async () => {
+    const { ctx } = await setup()
+    const chunks = ['line one\n', '']
+    ctx.tasks.register(producer({ readOutput: () => chunks.shift() ?? '' }).registration)
+
+    // A body already ending in a newline gets no doubled separator.
+    expect(text(await call(ctx, 'task_output', { task_id: 'bash-1' }))).toBe('line one\n[status: running]')
+    expect(text(await call(ctx, 'task_output', { task_id: 'bash-1' }))).toBe('(no new output)\n[status: running]')
+  })
+
+  it('returns the final output of a settled final-output task', async () => {
+    const { ctx } = await setup()
+    const p = producer({ kind: 'subagent', label: 'research' })
+    ctx.tasks.register(p.registration)
+    expect(text(await call(ctx, 'task_output', { task_id: 'subagent-1' }))).toBe('(no new output)\n[status: running]')
+
+    p.settle({ status: 'completed', detail: 'completed', output: 'the answer' })
+    await tick()
+    expect(text(await call(ctx, 'task_output', { task_id: 'subagent-1' }))).toBe('the answer\n[status: completed, completed]')
+  })
+
+  it('wait: true blocks until settlement and reports the terminal state', async () => {
+    const { ctx } = await setup()
+    const p = producer({ kind: 'subagent', label: 'research' })
+    ctx.tasks.register(p.registration)
+
+    const pending = call(ctx, 'task_output', { task_id: 'subagent-1', wait: true })
+    p.settle({ status: 'completed', output: 'done deal' })
+    expect(text(await pending)).toBe('done deal\n[status: completed]')
+  })
+
+  it('wait: true times out against the configured cap and leaves the task alive', async () => {
+    const { ctx } = await setup({ waitTimeoutMs: 10, maxWaitTimeoutMs: 20 })
+    ctx.tasks.register(producer().registration)
+
+    // A model-supplied timeout far above the cap is clamped: this returns
+    // promptly (≤ the 20ms cap), not after ten minutes.
+    const result = await call(ctx, 'task_output', { task_id: 'bash-1', wait: true, timeout_ms: 600_000 })
+    expect(text(result)).toBe('(no new output)\n[status: running]')
+  })
+
+  it('rejects an empty or unknown task id as an errored result', async () => {
+    const { ctx } = await setup()
+    expect((await call(ctx, 'task_output', { task_id: '' })).isError).toBe(true)
+    const unknown = await call(ctx, 'task_output', { task_id: 'bash-99' })
+    expect(unknown.isError).toBe(true)
+    expect(text(unknown)).toContain('unknown task bash-99')
+  })
+})
+
+describe('task_list', () => {
+  it('lists caller-visible tasks and renders the empty case', async () => {
+    const { ctx } = await setup()
+    expect(text(await call(ctx, 'task_list', {}))).toBe('(no background tasks)')
+
+    const alice = fakeAgent(ctx, 'sess-alice')
+    ctx.tasks.register(producer({ owner: alice, label: 'pnpm test' }).registration)
+    ctx.tasks.register(producer({ kind: 'subagent', label: 'open research' }).registration)
+    const p = producer({ owner: alice, label: 'build' })
+    ctx.tasks.register(p.registration)
+    p.settle({ status: 'completed', detail: 'exit code: 0' })
+    await tick()
+
+    expect(text(await call(ctx, 'task_list', {}, alice))).toBe([
+      'bash-1 [bash] running — pnpm test',
+      'subagent-1 [subagent] running — open research',
+      'bash-2 [bash] completed — build',
+    ].join('\n'))
+    // A different caller sees only the unowned task.
+    const bob = fakeAgent(ctx, 'sess-bob')
+    expect(text(await call(ctx, 'task_list', {}, bob))).toBe('subagent-1 [subagent] running — open research')
+  })
+})
+
+describe('task_kill', () => {
+  it('requests cancellation with the forwarded reason', async () => {
+    const { ctx } = await setup()
+    const p = producer()
+    ctx.tasks.register(p.registration)
+
+    const result = await call(ctx, 'task_kill', { task_id: 'bash-1', reason: 'superseded' })
+    expect(text(result)).toBe('requested cancellation of task bash-1')
+    expect(p.cancels).toEqual(['superseded'])
+  })
+
+  it('reports an already-terminal task without consuming its pending delta', async () => {
+    const { ctx } = await setup()
+    let delta = 'unread tail'
+    const p = producer({ readOutput: () => { const d = delta; delta = ''; return d } })
+    ctx.tasks.register(p.registration)
+    p.settle({ status: 'completed', detail: 'exit code: 0' })
+    await tick()
+
+    expect(text(await call(ctx, 'task_kill', { task_id: 'bash-1' })))
+      .toBe('task bash-1 had already finished [status: completed, exit code: 0]')
+    // The kill described the task via a non-consuming snapshot: the delta is intact.
+    expect(text(await call(ctx, 'task_output', { task_id: 'bash-1' }))).toBe('unread tail\n[status: completed, exit code: 0]')
+  })
+
+  it('rejects an empty task id as an errored result', async () => {
+    const { ctx } = await setup()
+    expect((await call(ctx, 'task_kill', { task_id: '' })).isError).toBe(true)
+  })
+})
+
+describe('tool-owned UI presentation (presentCall)', () => {
+  it('renders generic cards for all three control tools', async () => {
+    const { ctx } = await setup()
+    expect(ctx.tools.get('task_output')?.presentCall?.({ task_id: 'bash-1' }))
+      .toEqual({ card: 'generic', title: 'Read output from background task bash-1', kind: 'read', rawInput: 'bash-1' })
+    expect(ctx.tools.get('task_list')?.presentCall?.({}))
+      .toEqual({ card: 'generic', title: 'List background tasks', kind: 'read' })
+    expect(ctx.tools.get('task_kill')?.presentCall?.({ task_id: 'subagent-2' }))
+      .toEqual({ card: 'generic', title: 'Kill background task subagent-2', kind: 'execute', rawInput: 'subagent-2' })
+  })
+})
+
+describe('completion notices', () => {
+  it('injects a notice into the owning agent when an unreported task settles', async () => {
+    const { ctx } = await setup()
+    const inject = vi.fn()
+    const owner = fakeAgent(ctx, 'sess-1', inject)
+    const p = producer({ owner, label: 'pnpm test' })
+    ctx.tasks.register(p.registration)
+
+    p.settle({ status: 'completed', detail: 'exit code: 0' })
+    await tick()
+    expect(inject).toHaveBeenCalledTimes(1)
+    expect(inject).toHaveBeenCalledWith(
+      [{ type: 'text', text: 'background task bash-1 (bash: pnpm test) finished [status: completed, exit code: 0]. Read its output with task_output.' }],
+      { source: { kind: 'plugin', plugin: 'tool-tasks' } },
+    )
+  })
+
+  it('suppresses the notice for a task the model already killed', async () => {
+    const { ctx } = await setup()
+    const inject = vi.fn()
+    const owner = fakeAgent(ctx, 'sess-1', inject)
+    const p = producer({ owner })
+    ctx.tasks.register(p.registration)
+
+    await call(ctx, 'task_kill', { task_id: 'bash-1' }, owner)
+    p.settle({ status: 'killed' })
+    await tick()
+    expect(inject).not.toHaveBeenCalled()
+  })
+
+  it('suppresses the notice when a wait returned the terminal state', async () => {
+    const { ctx } = await setup()
+    const inject = vi.fn()
+    const owner = fakeAgent(ctx, 'sess-1', inject)
+    const p = producer({ owner, kind: 'subagent' })
+    ctx.tasks.register(p.registration)
+
+    const pending = call(ctx, 'task_output', { task_id: 'subagent-1', wait: true }, owner)
+    p.settle({ status: 'completed', output: 'answer' })
+    expect(text(await pending)).toContain('answer')
+    expect(inject).not.toHaveBeenCalled()
+  })
+
+  it('drops the notice for unowned tasks and for a disposed owner (benign race)', async () => {
+    const { ctx } = await setup()
+    // Unowned: settles with nobody to notify — nothing throws.
+    const unowned = producer()
+    ctx.tasks.register(unowned.registration)
+    unowned.settle({ status: 'completed' })
+    await tick()
+
+    // Disposed owner: inject throws the disposed message — contained.
+    const inject = vi.fn(() => { throw new Error('agent "agent-sess-1" is disposed') })
+    const owner = fakeAgent(ctx, 'sess-1', inject)
+    const p = producer({ owner })
+    ctx.tasks.register(p.registration)
+    p.settle({ status: 'completed' })
+    await tick()
+    expect(inject).toHaveBeenCalledTimes(1)
+  })
+
+  it('propagates a non-disposed inject failure (a real bug must surface)', async () => {
+    const { ctx } = await setup()
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const owner = fakeAgent(ctx, 'sess-1', () => { throw new Error('unexpected inject bug') })
+    const p = producer({ owner })
+    ctx.tasks.register(p.registration)
+    p.settle({ status: 'completed' })
+    await tick()
+    // The throw escapes the notice listener and is contained (logged) by the
+    // registry's per-listener containment — visible, not swallowed.
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('unexpected inject bug'))
+  })
+
+  it('drops the notice when no live agent matches and when the agent registry is gone', async () => {
+    const { ctx, agentsFiber } = await setup()
+    const inject = vi.fn()
+    const owner = fakeAgent(ctx, 'sess-1', inject)
+
+    // Owner known at registration, unregistered before settlement → no match.
+    const p1 = producer({ owner })
+    ctx.tasks.register(p1.registration)
+    // A second task whose settlement happens after the whole registry is gone.
+    const p2 = producer({ owner })
+    ctx.tasks.register(p2.registration)
+
+    await agentsFiber.dispose()
+    p1.settle({ status: 'completed' })
+    p2.settle({ status: 'failed' })
+    await tick()
+    expect(inject).not.toHaveBeenCalled()
+  })
+})
diff --git a/packages/tasks/tool-tasks/tsconfig.json b/packages/tasks/tool-tasks/tsconfig.json
new file mode 100644
index 0000000000..9e5411df25
--- /dev/null
+++ b/packages/tasks/tool-tasks/tsconfig.json
@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../tasks"
+    }
+  ]
+}
diff --git a/packages/ui/acp-agent/tests/acp-agent.spec.ts b/packages/ui/acp-agent/tests/acp-agent.spec.ts
index 7e1de1226f..1dc62218bf 100644
--- a/packages/ui/acp-agent/tests/acp-agent.spec.ts
+++ b/packages/ui/acp-agent/tests/acp-agent.spec.ts
@@ -70,7 +70,9 @@ describe('dsh-acp-agent composition', () => {
       })
     }
     const assembly = await ctx.get('systemPrompt')!.assemble()
-    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha'])
+    // The rest-slot is lexicographic: the bundle's own task control tools
+    // (tool-tasks needs no executor, unlike the pending bash tool) follow alpha.
+    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'task_kill', 'task_list', 'task_output'])
     await ctx.fiber.dispose()
   })
 
diff --git a/packages/ui/acp/README.md b/packages/ui/acp/README.md
index 60363566b7..863bddee9c 100644
--- a/packages/ui/acp/README.md
+++ b/packages/ui/acp/README.md
@@ -35,7 +35,7 @@ The `initialize` handshake reports a fixed server identity (`agentInfo: { name:
 
 The bridge multiplexes N sessions over one connection. Live sessions are held in a `Map<sessionId, SessionRecord>` (forward) with a `WeakMap<Agent, sessionId>` reverse map so `agent/*` events — which carry only the `Agent` — demux in O(1). Every `session/event` and `agent/status` is routed strictly to its owning record, so concurrent sessions never cross-settle or interleave their `session/update` notifications. State is per session: one in-flight prompt each, `session/cancel` aborts and settles only its own agent/prompt, and disposal drains every live session in parallel to quiescence. (Per-session *permission* ownership is reserved for the deferred permission gate — `TODO(rfc010-permission-gate)`.)
 
-Background-task isolation rides on `dsh-tool-bash`: bash task ids are global and predictable, so each task carries an opaque owner token — the owning agent's `session.header.id` — stored on the task inside the executor (`dsh-bash`'s `ownerOf(id)` seam). `bash_output`/`bash_kill` reject a task whose token differs from the caller's session token, so one session's agent can't read or kill another's task. Ownership is by session TOKEN, not `Agent` object identity — a different `Agent` object on the same session may access the task — and because the token lives on the executor's task it survives a `tool-bash` HMR reload.
+Background-task isolation rides on the `ctx.tasks` runtime (`dsh-tasks`): task ids are global and predictable, so every read/kill/wait/list is fenced to the owning agent's session (`session.header.id`), and one session's agent can't read or kill another's task through `task_output`/`task_kill`. Ownership is by session token, not `Agent` object identity — a different `Agent` object on the same session may access the task — and because the registration lives in the tasks service it survives a producer-plugin HMR reload.
 
 ## Per-session cwd
 
diff --git a/packages/ui/stdio-agent/tests/stdio-agent.spec.ts b/packages/ui/stdio-agent/tests/stdio-agent.spec.ts
index 34ba201040..71ce537c68 100644
--- a/packages/ui/stdio-agent/tests/stdio-agent.spec.ts
+++ b/packages/ui/stdio-agent/tests/stdio-agent.spec.ts
@@ -92,7 +92,9 @@ describe('dsh-stdio-agent app', () => {
       })
     }
     const assembly = await ctx.get('systemPrompt')!.assemble()
-    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha'])
+    // The rest-slot is lexicographic: the bundle's own task control tools
+    // (tool-tasks needs no executor, unlike the pending bash tool) follow alpha.
+    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'task_kill', 'task_list', 'task_output'])
     await ctx.fiber.dispose()
   })
 
diff --git a/packages/util/README.md b/packages/util/README.md
index ae73c8125f..886de2290e 100644
--- a/packages/util/README.md
+++ b/packages/util/README.md
@@ -6,4 +6,4 @@ Zero-dependency primitives shared across the other groups. A package lands here
 |---|---|
 | `brand/` | The type-only `Branded<B>` nominal-typing primitive (no runtime code, no harness deps) |
 
-`dsh-brand` is the canonical case: it owns ONLY the `Branded<B>` helper, so a capability package can brand the ids it owns (`dsh-bash`'s `BashTaskId`/`OwnerToken`, `dsh-session`'s `SessionId`, …) by depending on `dsh-brand` alone, without pulling in an unrelated package just to reach `Branded`.
+`dsh-brand` is the canonical case: it owns ONLY the `Branded<B>` helper, so a capability package can brand the ids it owns (`dsh-tasks`'s `TaskId`, `dsh-session`'s `SessionId`, …) by depending on `dsh-brand` alone, without pulling in an unrelated package just to reach `Branded`.
diff --git a/packages/util/brand/README.md b/packages/util/brand/README.md
index 8f7943def7..41cdb8f774 100644
--- a/packages/util/brand/README.md
+++ b/packages/util/brand/README.md
@@ -21,6 +21,6 @@ Construction goes through the per-id factory in the OWNING package (a plain cast
 
 ## Policy: brand ids that cross package boundaries
 
-A package brands the ids it OWNS — `CallId` in `dsh-llm` (tool-call correlation), `SessionId` in `dsh-session`, `AgentId` in `dsh-agent`, `BashTaskId`/`OwnerToken` in `dsh-bash`. Branding is for ids that cross package boundaries and could plausibly be confused; **not every string needs a brand.**
+A package brands the ids it OWNS — `CallId` in `dsh-llm` (tool-call correlation), `SessionId` in `dsh-session`, `AgentId` in `dsh-agent`, `TaskId` in `dsh-tasks`. Branding is for ids that cross package boundaries and could plausibly be confused; **not every string needs a brand.**
 
-This package owns ONLY the primitive — no concrete id, no runtime code beyond the (erased) type. Keeping the primitive dependency-free is the point: a capability package can brand its ids without depending on an unrelated package. `dsh-bash`, for example, brands `BashTaskId`/`OwnerToken` by depending on `dsh-brand` alone — it never pulls in `dsh-llm` (or `dsh-session`) just to reach `Branded`.
+This package owns ONLY the primitive — no concrete id, no runtime code beyond the (erased) type. Keeping the primitive dependency-free is the point: a capability package can brand its ids without depending on an unrelated package. `dsh-tasks`, for example, brands `TaskId` by depending on `dsh-brand` alone — it never pulls in `dsh-llm` (or `dsh-session`) just to reach `Branded`.
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 32ffa0d389..59294e9fe4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -77,9 +77,6 @@ importers:
 
   packages/bash/bash:
     devDependencies:
-      '@deepseek-ai/dsh-brand':
-        specifier: workspace:^
-        version: link:../../util/brand
       cordis:
         specifier: ^4.0.0-rc.6
         version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
@@ -98,6 +95,10 @@ importers:
         version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
 
   packages/bash/tool-bash:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: 3.18.0
     devDependencies:
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
@@ -120,6 +121,12 @@ importers:
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tasks':
+        specifier: workspace:^
+        version: link:../../tasks/tasks
+      '@deepseek-ai/dsh-tool-tasks':
+        specifier: workspace:^
+        version: link:../../tasks/tool-tasks
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
@@ -220,9 +227,15 @@ importers:
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../system-prompt
+      '@deepseek-ai/dsh-tasks':
+        specifier: workspace:^
+        version: link:../../tasks/tasks
       '@deepseek-ai/dsh-tool-bash':
         specifier: workspace:^
         version: link:../../bash/tool-bash
+      '@deepseek-ai/dsh-tool-tasks':
+        specifier: workspace:^
+        version: link:../../tasks/tool-tasks
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../tools
@@ -747,6 +760,12 @@ importers:
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tasks':
+        specifier: workspace:^
+        version: link:../../tasks/tasks
+      '@deepseek-ai/dsh-tool-tasks':
+        specifier: workspace:^
+        version: link:../../tasks/tool-tasks
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
@@ -819,6 +838,49 @@ importers:
         specifier: ^4.0.0-rc.6
         version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
 
+  packages/tasks/tasks:
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      cordis:
+        specifier: ^4.0.0-rc.6
+        version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
+
+  packages/tasks/tool-tasks:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: 3.18.0
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tasks':
+        specifier: workspace:^
+        version: link:../tasks
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      cordis:
+        specifier: ^4.0.0-rc.6
+        version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
+
   packages/todo/tool-todo:
     devDependencies:
       '@deepseek-ai/dsh-agent':
diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json
index fc2b9d12c2..76fdd4e648 100644
--- a/scripts/doc-budgets.manifest.json
+++ b/scripts/doc-budgets.manifest.json
@@ -1,11 +1,11 @@
 {
   "AGENTS.md": 1691,
   "docs/AGENTS.md": 1315,
-  "docs/architecture.md": 1640,
+  "docs/architecture.md": 1760,
   "docs/cordis-primer.md": 550,
   "docs/defensive-patterns.md": 550,
   "docs/testing.md": 800,
   "examples/AGENTS.md": 610,
   "packages/AGENTS.md": 450,
-  "packages/README.md": 605
+  "packages/README.md": 645
 }
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 6440a672be..d0bc987fdc 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -73,6 +73,7 @@ const GROUP_ORDER = [
   'fs',
   'compact',
   'subagent',
+  'tasks',
   'web',
   'todo',
   'hooks',
@@ -186,6 +187,14 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['tool-subagent'],
     note: 'Providers implement transports; tool-subagent exposes one configured provider as a model-facing tool name.',
   },
+  {
+    key: 'tasks',
+    pkg: 'tasks',
+    title: 'Background task registry',
+    mode: 'core',
+    consumers: ['tool-bash', 'tool-subagent', 'tool-tasks'],
+    note: 'Producers (tool-bash background commands, tool-subagent background delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it.',
+  },
   {
     key: 'web',
     pkg: 'web',
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 24739e1388..ef933fc325 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -46,8 +46,10 @@ import * as WebSearchExa from '@deepseek-ai/dsh-web-search-exa'
 import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import * as SubagentMock from '@deepseek-ai/dsh-subagent-mock'
+import TaskService from '@deepseek-ai/dsh-tasks'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
+import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
 import * as ToolSubagent from '@deepseek-ai/dsh-tool-subagent'
 import * as ToolWeb from '@deepseek-ai/dsh-tool-web'
@@ -104,14 +106,14 @@ const TOOL_PACKAGES: ToolPackage[] = [
     pkg: '@deepseek-ai/dsh-tool-bash',
     dir: 'tool-bash',
     source: 'packages/bash/tool-bash/src/index.ts',
-    requires: ['ctx.tools', 'ctx.bash'],
-    writes: ['tool/call', 'tool/result', 'context/message via agent.inject() for background completion notices'],
+    requires: ['ctx.tools', 'ctx.bash', 'ctx.tasks at call time for run_in_background'],
+    writes: ['tool/call', 'tool/result'],
     async mount(ctx) {
       await ctx.plugin(LocalBashExecutor)
       await ctx.plugin(ToolBash)
     },
     note:
-      'The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam.',
+      'The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.tasks` runtime and is collected/stopped through the `task_*` tools from `@deepseek-ai/dsh-tool-tasks`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-fs',
@@ -145,6 +147,19 @@ const TOOL_PACKAGES: ToolPackage[] = [
     note:
       'The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`.',
   },
+  {
+    pkg: '@deepseek-ai/dsh-tool-tasks',
+    dir: 'tool-tasks',
+    source: 'packages/tasks/tool-tasks/src/index.ts',
+    requires: ['ctx.tools', 'ctx.tasks', 'ctx.systemPrompt'],
+    writes: ['tool/call', 'tool/result', 'context/message via agent.inject() for background completion notices'],
+    async mount(ctx) {
+      await ctx.plugin(TaskService)
+      await ctx.plugin(ToolTasks)
+    },
+    note:
+      'The kind-agnostic background-task control surface: a background bash command and a background subagent are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers\' `ctx.tasks.register()`.',
+  },
   {
     pkg: '@deepseek-ai/dsh-tool-todo',
     dir: 'tool-todo',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 613280ee1b..b4e19c8f13 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -52,8 +52,13 @@
     { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecSpec", "source": "packages/bash/bash/src/types.ts" },
     { "doc": "docs/core-data-structures/bash.md", "symbol": "BashRunResult", "source": "packages/bash/bash/src/types.ts" },
     { "doc": "docs/core-data-structures/bash.md", "symbol": "CollectedOutput", "source": "packages/bash/bash/src/types.ts" },
-    { "doc": "docs/core-data-structures/bash.md", "symbol": "BashTask", "source": "packages/bash/bash/src/types.ts" },
-    { "doc": "docs/core-data-structures/bash.md", "symbol": "BashTaskRead", "source": "packages/bash/bash/src/types.ts" },
+    { "doc": "docs/core-data-structures/bash.md", "symbol": "BashProcess", "source": "packages/bash/bash/src/types.ts" },
+    { "doc": "docs/core-data-structures/bash.md", "symbol": "BashProcessRead", "source": "packages/bash/bash/src/types.ts" },
+
+    { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskRegistration", "source": "packages/tasks/tasks/src/types.ts" },
+    { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskOutcome", "source": "packages/tasks/tasks/src/types.ts" },
+    { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskSnapshot", "source": "packages/tasks/tasks/src/types.ts" },
+    { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskRead", "source": "packages/tasks/tasks/src/types.ts" },
 
     { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeRunRequest", "source": "packages/code-runtime/code-runtime/src/types.ts" },
     { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeRunResult", "source": "packages/code-runtime/code-runtime/src/types.ts" },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index ea1d804ba5..29d71d6560 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -47,6 +47,7 @@
         "./packages/fs/*/src",
         "./packages/compact/*/src",
         "./packages/subagent/*/src",
+        "./packages/tasks/*/src",
         "./packages/web/*/src",
         "./packages/todo/*/src",
         "./packages/hooks/*/src",
diff --git a/tsconfig.build.json b/tsconfig.build.json
index 3d99ad4e28..fb1b8d199d 100644
--- a/tsconfig.build.json
+++ b/tsconfig.build.json
@@ -53,6 +53,8 @@
     { "path": "./packages/subagent/subagent-spawn" },
     { "path": "./packages/subagent/subagent-fork" },
     { "path": "./packages/subagent/subagent-acp" },
+    { "path": "./packages/tasks/tasks" },
+    { "path": "./packages/tasks/tool-tasks" },
     { "path": "./packages/todo/tool-todo" },
     { "path": "./packages/hooks/hook-protocol" },
     { "path": "./packages/hooks/hooks-claude" },
diff --git a/tsconfig.json b/tsconfig.json
index 2091283c93..c60cf63458 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -64,6 +64,8 @@
     { "path": "./packages/subagent/subagent-spawn" },
     { "path": "./packages/subagent/subagent-fork" },
     { "path": "./packages/subagent/subagent-acp" },
+    { "path": "./packages/tasks/tasks" },
+    { "path": "./packages/tasks/tool-tasks" },
     { "path": "./packages/todo/tool-todo" },
     { "path": "./packages/hooks/hook-protocol" },
     { "path": "./packages/hooks/hooks-claude" },

From f858c647a6767bafa198b1faba6dcfe3ebc911c5 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 9 Jul 2026 21:36:56 +0800
Subject: [PATCH 04/48] refactor(tasks): drive wait() timing through
 dsh-timeout
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ctx.tasks.wait arms a deadline() fusing the caller's abort with the
wait timeout and classifies the outcome with timeoutOf scoped to the
new TASK_WAIT_TIMEOUT code: a wait timeout resolves to the live
snapshot (the task keeps running), a caller abort rejects the wait —
same contract, no hand-rolled timer/listener plumbing, and a nested
foreign deadline can no longer misread as a wait timeout. task_output
deliberately declares NO ToolDefinition.timeoutMs: timeout-policy
turns a timed-out call into a structured TOOL_TIMEOUT failure, but a
timed-out wait is a SUCCESS that must still report [status: running]
(decision recorded in the runtime RFC alternatives).
---
 docs/cordis-catalog/services.md               |  2 +-
 ...06-20-generic-long-running-tool-runtime.md |  4 +++
 packages/tasks/tasks/README.md                |  2 +-
 packages/tasks/tasks/package.json             |  4 ++-
 packages/tasks/tasks/src/index.ts             | 30 ++++++++++++++-----
 packages/tasks/tasks/tsconfig.json            |  3 ++
 packages/tasks/tool-tasks/src/index.ts        |  5 ++++
 pnpm-lock.yaml                                |  3 ++
 8 files changed, 43 insertions(+), 10 deletions(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 4db3b1c6e4..fce449c6bb 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -224,7 +224,7 @@ attachSurface(name: string): () => void
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/tasks/tasks/src/index.ts:84`](../../packages/tasks/tasks/src/index.ts)
+Source: [`packages/tasks/tasks/src/index.ts:93`](../../packages/tasks/tasks/src/index.ts)
 
 ## `ctx.tools` — `ToolRegistry`
 
diff --git a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index a049df012f..5664c19dd5 100644
--- a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -142,6 +142,10 @@ The established bash habit is poll-between-work, and the guidance tells the mode
 
 Waiting is never useful without reading the result afterwards; a separate tool doubles the calls and the schema surface for zero information. Folding it into `task_output` matches the only real usage pattern.
 
+### Why not `ToolDefinition.timeoutMs` (the timeout-policy plugin) for `task_output`'s wait?
+
+The [timeout library](2026-07-06-timeout-deadline-library.md) gives `wait()` its timing internals — `ctx.tasks.wait` arms a `deadline()` and classifies wait-timeout vs caller-abort with `timeoutOf` scoped to `TASK_WAIT_TIMEOUT` — but the tool-call-level policy is deliberately NOT adopted: timeout-policy replaces a timed-out call with a structured `TOOL_TIMEOUT` failure, whereas a timed-out `task_output(wait: true)` is a SUCCESS that must still report `[status: running]` (the model needs the task's state either way, and the task keeps running). The wait therefore bounds its own deadline through the tool's `waitTimeoutMs`/`maxWaitTimeoutMs` config. For the same reason, no timeout policy manages a background task's LIFETIME: once the id is returned the work is off the tool-call deadline entirely — cancellation belongs to `task_kill` and owner cleanup.
+
 ### Why not a push-sink producer contract (`appendOutput`/`settle`), as Kimi Code's manager uses?
 
 A sink centralizes output buffering, truncation, and spill in the runtime, which is elegant when the runtime owns output storage. In this codebase those concerns already live — bounded, tested, spill-file-aware — inside `dsh-bash-local`, and keeping process concerns in the executor is the point of the bash seam. The pull contract (`readOutput()` returning a formatted delta) reuses that machinery as-is; a sink would relocate it for no v1 gain. If a durable backend later makes the runtime own output storage, the producer contract is the one seam to revisit.
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index ec5a82f52c..14a2f75d6e 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -8,7 +8,7 @@ The background task registry (`ctx.tasks`): a runtime-global, CONCRETE service (
 - `get(id, caller?)` / `list(caller?)` — non-consuming snapshots; `list` returns only caller-owned plus unowned tasks (a global listing would leak foreign labels).
 - `read(id, caller?): TaskRead` — stream kinds consume the per-task cursor (v1's single intended reader is the owning model — a non-consuming multi-reader surface would be a cursor/snapshot API extension, not a `read` change); final kinds read the terminal output idempotently.
 - `kill(id, caller?, reason?)` — `'requested'` (live task: producer `cancel` runs first — a throw fails the kill loud and leaves the task untouched — then `stopping`) or `'already-terminal'`. Every successful kill marks the task `reported` (the killer saw the end → completion notice suppressed).
-- `wait(id, timeoutMs, caller?, signal?)` — resolves with the terminal snapshot (marked `reported`), or the live snapshot at timeout; an aborted signal rejects the WAIT only.
+- `wait(id, timeoutMs, caller?, signal?)` — resolves with the terminal snapshot (marked `reported`), or the live snapshot at timeout; an aborted signal rejects the WAIT only. Timing is a [`dsh-timeout`](../../util/timeout/README.md) `deadline()` scoped to the `TASK_WAIT_TIMEOUT` code, so a nested foreign deadline never misreads as a wait timeout.
 - `onTaskDone(listener)` — exactly once per task with the terminal snapshot; effect-scoped, per-listener containment, silent after service disposal.
 - `attachSurface(name)` — declares a control surface exists (the model tools, or a deployment's custom surface); effect-scoped.
 
diff --git a/packages/tasks/tasks/package.json b/packages/tasks/tasks/package.json
index 3b2b9532c2..8db26d7ff2 100644
--- a/packages/tasks/tasks/package.json
+++ b/packages/tasks/tasks/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-tasks",
-  "description": "Background task registry (ctx.tasks) for the DeepSeek Harness — shared ids, owner isolation, polling, cancellation, and completion listeners for long-running tool work",
+  "description": "Background task registry (ctx.tasks) for the DeepSeek Harness \u2014 shared ids, owner isolation, polling, cancellation, and completion listeners for long-running tool work",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -24,12 +24,14 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
     "cordis": "^4.0.0-rc.6"
   }
 }
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index ac9821b849..5d926b5230 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -30,6 +30,7 @@
 
 import { Context, Service } from 'cordis'
 import type { Agent, AgentId } from '@deepseek-ai/dsh-agent'
+import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
 import { TaskId } from './types.ts'
 import type { TaskDoneListener, TaskOutcome, TaskRead, TaskRegistration, TaskSnapshot, TaskStatus } from './types.ts'
 
@@ -49,6 +50,14 @@ declare module 'cordis' {
   }
 }
 
+/**
+ * The `dsh-timeout` code stamped on a {@link TaskService.wait} deadline's
+ * `TimeoutReason`. A wait timeout only ends the WAIT (the task keeps running
+ * and the live snapshot is returned) — scoping `timeoutOf` to this code keeps
+ * a foreign (outer, nested) deadline's timeout from being misread as ours.
+ */
+export const TASK_WAIT_TIMEOUT = 'TASK_WAIT_TIMEOUT'
+
 /** The registry's mutable per-task record (never handed out — see {@link TaskService.snapshot}). */
 interface TrackedTask {
   id: TaskId
@@ -273,15 +282,22 @@ export class TaskService extends Service {
       if (signal?.aborted) throw new Error('wait aborted')
       task.waiters += 1
       try {
+        // The dsh-timeout deadline fits wait() exactly because both only
+        // NOTIFY: a wait timeout returns the live snapshot (the task keeps
+        // running — nothing is terminated), and timeoutOf scoped to our own
+        // code tells that timeout apart from a caller abort, which rejects
+        // the wait. `using` clears the timer on every exit path.
+        using d = deadline(signal, timeoutMs, TASK_WAIT_TIMEOUT)
         await new Promise<void>((resolve, reject) => {
-          const cleanup = (): void => {
-            clearTimeout(timer)
-            signal?.removeEventListener('abort', onAbort)
+          const onAbort = (): void => {
+            if (timeoutOf(d.signal, TASK_WAIT_TIMEOUT) !== undefined) resolve()
+            else reject(new Error('wait aborted'))
           }
-          const timer = setTimeout(() => { cleanup(); resolve() }, timeoutMs)
-          const onAbort = (): void => { cleanup(); reject(new Error('wait aborted')) }
-          signal?.addEventListener('abort', onAbort, { once: true })
-          void task.settled.then(() => { cleanup(); resolve() })
+          d.signal.addEventListener('abort', onAbort, { once: true })
+          void task.settled.then(() => {
+            d.signal.removeEventListener('abort', onAbort)
+            resolve()
+          })
         })
       } finally {
         task.waiters -= 1
diff --git a/packages/tasks/tasks/tsconfig.json b/packages/tasks/tasks/tsconfig.json
index 97fb432ffb..bf369ad156 100644
--- a/packages/tasks/tasks/tsconfig.json
+++ b/packages/tasks/tasks/tsconfig.json
@@ -19,6 +19,9 @@
     },
     {
       "path": "../../core/agent"
+    },
+    {
+      "path": "../../util/timeout"
     }
   ]
 }
diff --git a/packages/tasks/tool-tasks/src/index.ts b/packages/tasks/tool-tasks/src/index.ts
index 30ff629e88..859c2b0f21 100644
--- a/packages/tasks/tool-tasks/src/index.ts
+++ b/packages/tasks/tool-tasks/src/index.ts
@@ -125,6 +125,11 @@ export function apply(ctx: Context, config: Config): void {
       + 'final-output tasks (subagent) return the final answer once the task finishes. '
       + 'Every response ends with a [status: ...] line. Non-blocking by default; '
       + 'set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.',
+    // Deliberately NO ToolDefinition.timeoutMs: the timeout-policy plugin
+    // replaces a timed-out call with a structured TOOL_TIMEOUT failure, but a
+    // timed-out wait here is a SUCCESS that reports [status: running] — the
+    // task's state must reach the model either way, so the wait bounds its
+    // own deadline (waitTimeoutMs/maxWaitTimeoutMs) via ctx.tasks.wait.
     parameters: {
       task_id: { type: 'string', required: true, description: 'Task id returned by the tool that started the background work.' },
       wait: { type: 'boolean', description: 'Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive.' },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 07d0bb41a7..03cb98ede7 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -893,6 +893,9 @@ importers:
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
+      '@deepseek-ai/dsh-timeout':
+        specifier: workspace:^
+        version: link:../../util/timeout
       cordis:
         specifier: ^4.0.0-rc.6
         version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)

From bd59fddacdab4031d6b4e7ca6fc53f18e42f5b79 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 9 Jul 2026 21:53:48 +0800
Subject: [PATCH 05/48] =?UTF-8?q?refactor(tasks):=20declare-then-execute?=
 =?UTF-8?q?=20=E2=80=94=20ctx.tasks.start()=20replaces=20register()?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

start({ kind, label, owner, run }) preflights everything that can fail
(the attachSurface fence, validation, the owner-cleanup attach) BEFORE
invoking the producer's run() starter, then commits atomically —
'work started but never got a collectable id' is now structurally
impossible instead of a producer try/catch rollback obligation (the
P1 review fix, rebuilt on #185's declare/execute split). Producers
lose their catch-wraps; the leak tests now pin the stronger property
that a failed preflight never spawns anything. TaskRegistration splits
into TaskStart (identity + run) and TaskHooks (cancel/done/readOutput);
docs, type-equiv manifest, catalogs, and both RFCs move with it.
---
 docs/cookbook/adding-a-tool.md                |   2 +-
 docs/cordis-catalog/services.md               |   4 +-
 docs/core-data-structures/core.md             |   2 +-
 docs/core-data-structures/tasks.md            |  30 +++--
 docs/module-graph.md                          |   3 +-
 ...06-20-generic-long-running-tool-runtime.md |  21 +--
 .../2026-07-08-background-subagent-tasks.md   |   6 +-
 docs/tool-catalog.md                          |   4 +-
 packages/bash/tool-bash/src/index.ts          |  35 +++--
 packages/bash/tool-bash/tests/tools.spec.ts   |  32 ++---
 packages/subagent/tool-subagent/src/index.ts  |  45 +++----
 .../tool-subagent/tests/tool-subagent.spec.ts |  24 ++--
 packages/tasks/README.md                      |   2 +-
 packages/tasks/tasks/README.md                |   2 +-
 packages/tasks/tasks/src/index.ts             |  72 +++++-----
 packages/tasks/tasks/src/types.ts             |  44 ++++--
 packages/tasks/tasks/tests/tasks.spec.ts      | 126 ++++++++++--------
 packages/tasks/tool-tasks/README.md           |   2 +-
 packages/tasks/tool-tasks/src/index.ts        |   4 +-
 .../tasks/tool-tasks/tests/tool-tasks.spec.ts |  56 ++++----
 scripts/gen-tool-catalog.ts                   |   2 +-
 scripts/type-equiv.manifest.json              |   3 +-
 22 files changed, 281 insertions(+), 240 deletions(-)

diff --git a/docs/cookbook/adding-a-tool.md b/docs/cookbook/adding-a-tool.md
index ba89caf387..efd5c8a132 100644
--- a/docs/cookbook/adding-a-tool.md
+++ b/docs/cookbook/adding-a-tool.md
@@ -41,7 +41,7 @@ Registration is effect-based: disposing the plugin fiber unregisters the tool (w
 
 ## Long-running work
 
-Register the running work with the shared task runtime instead of inventing a task protocol: gate a `run_in_background` parameter behind your plugin's own defaulted `enableRunInBackground`-style config, start the work, and hand it to `ctx.tasks.register({ kind, label, owner: exec.agent, cancel, done, readOutput? })` (`@deepseek-ai/dsh-tasks`). The runtime issues the `<kind>-N` id, fences access to the owning session, cancels-and-awaits your task when the owner disposes, and the generic `task_output`/`task_list`/`task_kill` tools plus the completion notice come from `@deepseek-ai/dsh-tool-tasks` — your tool returns `started background task <id>` and is done. Your producer keeps its execution concerns: `done` must settle at quiescence (resources released), and a stream-kind `readOutput` owns its own truncation/spill formatting (bound buffers, spill full output to disk so nothing is silently lost — see tool-bash's `renderProcessRead`). Do NOT wire `exec.signal` to the background work after the id is returned; check `exec.signal?.aborted` once before starting, then leave cancellation to `task_kill` and owner cleanup. **A failed `register()` must not orphan the work**: `register()` is atomic (a throw — the no-control-surface fence, a bad owner — mutates no registry state), so wrap it in try/catch, cancel the just-started work, AWAIT its quiescence, and rethrow — the model never learns an id, so nothing else could ever collect or kill what you started (tool-bash's `proc.kill(); await proc.done` and tool-subagent's `run.cancel(); await done` are the templates).
+Hand long-running work to the shared task runtime instead of inventing a task protocol: gate a `run_in_background` parameter behind your plugin's own defaulted `enableRunInBackground`-style config, then call `ctx.tasks.start({ kind, label, owner: exec.agent, run: () => ({ cancel, done, readOutput? }) })` (`@deepseek-ai/dsh-tasks`) — the runtime preflights everything that can fail (the control-surface fence, validation, owner-cleanup attach) BEFORE invoking your `run()` starter, so work that started without a collectable id is structurally impossible (no try/catch rollback in your tool). The runtime issues the `<kind>-N` id, fences access to the owning session, cancels-and-awaits your task when the owner disposes, and the generic `task_output`/`task_list`/`task_kill` tools plus the completion notice come from `@deepseek-ai/dsh-tool-tasks` — your tool returns `started background task <id>` and is done. Your producer keeps its execution concerns: `done` must settle at quiescence (resources released), and a stream-kind `readOutput` owns its own truncation/spill formatting (bound buffers, spill full output to disk so nothing is silently lost — see tool-bash's `renderProcessRead`). Do NOT wire `exec.signal` to the background work after the id is returned; check `exec.signal?.aborted` once before calling `start`, then leave cancellation to `task_kill` and owner cleanup.
 
 ## Permissions / sandboxing
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index fce449c6bb..793203cc1b 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -212,7 +212,7 @@ Source: [`packages/core/system-prompt/src/index.ts:291`](../../packages/core/sys
 The `tasks` service: the runtime-global background task registry. See the module doc for the ownership, isolation, and lifecycle contracts.
 
 ```ts cordis-catalog
-register(registration: TaskRegistration): TaskId
+start(spec: TaskStart): TaskId
 list(caller?: Agent): TaskSnapshot[]
 get(id: TaskId, caller?: Agent): TaskSnapshot
 read(id: TaskId, caller?: Agent): TaskRead
@@ -224,7 +224,7 @@ attachSurface(name: string): () => void
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/tasks/tasks/src/index.ts:93`](../../packages/tasks/tasks/src/index.ts)
+Source: [`packages/tasks/tasks/src/index.ts:95`](../../packages/tasks/tasks/src/index.ts)
 
 ## `ctx.tools` — `ToolRegistry`
 
diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md
index 0c640828cf..212570c358 100644
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -21,7 +21,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [tools.md](tools.md) | `ToolDefinition` full fields, the schema DSL, `ToolExecution`/`ToolResult`, tool-presentation UI types, the `tools/pre-execute`/`tools/post-execute` pipeline |
 | [user-interaction.md](user-interaction.md) | the UI-backed human question/answer seam: `AskUserQuestionRequest`, answer/options vocabulary, provider API, error taxonomy |
 | [bash.md](bash.md) | the bash executor seam: `BashExecRequest`/`Spec`, `BashRunResult`, the background `BashProcess` handle |
-| [tasks.md](tasks.md) | the background task runtime: `TaskId`, `TaskRegistration`, `TaskOutcome`, `TaskSnapshot`/`TaskRead`, owner isolation, the control-tool surface |
+| [tasks.md](tasks.md) | the background task runtime: `TaskId`, `TaskStart`/`TaskHooks`, `TaskOutcome`, `TaskSnapshot`/`TaskRead`, owner isolation, the control-tool surface |
 | [code-runtime.md](code-runtime.md) | the code-execution seam: `CodeRunRequest`/`Result`, binding namespaces, captured logs, the `CodeRunFailure` taxonomy |
 | [filesystem.md](filesystem.md) | the filesystem seam: `FsTarget`, read/write/edit outcomes, observed-file state, `FsErrorCode` |
 | [compaction.md](compaction.md) | the compaction seam: the `compact/*` session events, `CompactionResult`, the `CompactService` interface |
diff --git a/docs/core-data-structures/tasks.md b/docs/core-data-structures/tasks.md
index f229e402ee..10e1d7f6d2 100644
--- a/docs/core-data-structures/tasks.md
+++ b/docs/core-data-structures/tasks.md
@@ -1,6 +1,6 @@
 # Background Task Runtime
 
-The shared background-task vocabulary — what a producer (`dsh-tool-bash`, `dsh-tool-subagent`, any future long-running tool) hands to `ctx.tasks.register()` and what consumers (the `task_output`/`task_list`/`task_kill` tools, completion-notice injection) get back. The runtime is ONE concrete service ([dsh-tasks](../../packages/tasks/tasks), `ctx.tasks`), not an interface/implementation seam pair — see [the runtime RFC](../rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) for the decision and [the tasks group README](../../packages/tasks/README.md) for the package split.
+The shared background-task vocabulary — what a producer (`dsh-tool-bash`, `dsh-tool-subagent`, any future long-running tool) hands to `ctx.tasks.start()` and what consumers (the `task_output`/`task_list`/`task_kill` tools, completion-notice injection) get back. The runtime is ONE concrete service ([dsh-tasks](../../packages/tasks/tasks), `ctx.tasks`), not an interface/implementation seam pair — see [the runtime RFC](../rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) for the decision and [the tasks group README](../../packages/tasks/README.md) for the package split.
 
 Source: [`packages/tasks/tasks/src/types.ts`](../../packages/tasks/tasks/src/types.ts)
 
@@ -8,12 +8,12 @@ Source: [`packages/tasks/tasks/src/types.ts`](../../packages/tasks/tasks/src/typ
 
 `TaskId` is [branded](core.md#branded-ids) (`Branded<'TaskId'>` + a same-named factory), generated by the registry as `<kind>-N` with a per-kind counter (`bash-1`, `subagent-1`) — kind-prefixed so transcripts stay self-describing, sequential because the owner fence (not id secrecy) is the isolation boundary. `TaskStatus` is generic and CLOSED: `'running' | 'stopping' | 'completed' | 'killed' | 'failed'` — kind-specific meaning (exit codes, stop reasons) rides in `TaskSnapshot.detail`, so the registry never learns process or agent semantics.
 
-## The producer contract: `TaskRegistration`
+## The producer contract: `TaskStart` and `TaskHooks`
 
-A producer starts its work, then hands the running work over. The producer stays the owner of its execution concerns (process streams, child agents); the registry owns ids, isolation, status, and completion fan-out. The optional `readOutput` marks a STREAM kind — the method presence is the capability, mirroring `SubagentRun.sendMessage`.
+Declare-then-execute: the producer hands its task's identity plus a `run()` starter to `ctx.tasks.start()`, which preflights everything that can fail (the control-surface fence, validation, the owner-cleanup attach) BEFORE invoking `run()`, and commits atomically after — work that started without a collectable id is structurally impossible. The producer stays the owner of its execution concerns (process streams, child agents); the runtime owns ids, isolation, status, and completion fan-out. The optional `readOutput` hook marks a STREAM kind — the method presence is the capability, mirroring `SubagentRun.sendMessage`.
 
 ```ts type-equiv
-interface TaskRegistration {
+interface TaskStart {
   /** Producer kind — also the id prefix (`bash`, `subagent`, …). Non-empty. */
   kind: string
   /** One-line model-facing label (the command; the delegation description). */
@@ -22,10 +22,24 @@ interface TaskRegistration {
    * The spawning agent. Its `session.header.id` becomes the task's owner
    * token (read/kill/wait/list are fenced to that session), and its disposal
    * cancels and awaits the task through the `ctx.agents.onCleanup` seam.
-   * `undefined` registers an UNOWNED task: open to any caller, alive until the
+   * `undefined` starts an UNOWNED task: open to any caller, alive until the
    * tasks service disposes.
    */
   owner?: Agent | undefined
+  /**
+   * Start the actual work and return its {@link TaskHooks}. Called EXACTLY
+   * once, synchronously, after every preflight check (control-surface fence,
+   * validation, owner-cleanup attach) has passed — nothing in the runtime can
+   * fail after it returns, so the started work is always registered. A throw
+   * here propagates with nothing registered; the producer owns any partial
+   * cleanup of its own failed start.
+   */
+  run(): TaskHooks
+}
+```
+
+```ts type-equiv
+interface TaskHooks {
   /**
    * Request termination. Idempotent, synchronous, and must lead to
    * {@link done} settling; a throw propagates to the killer (fail loud — a
@@ -53,8 +67,6 @@ interface TaskRegistration {
 }
 ```
 
-`register()` is ATOMIC: a throw (the no-control-surface fence, an owner-cleanup attach failure) mutates no registry state, so the producer cancels and awaits its just-started work and rethrows — background work never runs without a collectable id.
-
 ```ts type-equiv
 interface TaskOutcome {
   /** How the task ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
@@ -62,7 +74,7 @@ interface TaskOutcome {
   /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
   detail?: string
   /**
-   * Final output for FINAL-OUTPUT-ONLY kinds (no {@link TaskRegistration.readOutput}),
+   * Final output for FINAL-OUTPUT-ONLY kinds (no {@link TaskHooks.readOutput}),
    * read idempotently after the task settles. Stream kinds leave it unset —
    * their output is consumed incrementally through `readOutput`.
    */
@@ -123,4 +135,4 @@ interface TaskRead {
 
 ## The service
 
-`TaskService` (`ctx.tasks` — [`packages/tasks/tasks/src/index.ts`](../../packages/tasks/tasks/src/index.ts)): `register` (atomic, fenced by `attachSurface`), non-consuming `get`/`list` (caller-scoped — owned-by-caller plus unowned only), `read` (consuming for stream kinds), `kill` (producer `cancel` first; a throw leaves the task untouched), `wait` (bounded, abort cancels the wait only), and `onTaskDone` (a `TaskDoneListener` per settlement, effect-scoped, contained). Every read/kill/wait/get compares the task's owner session with the caller's and rejects a foreign one. Owned tasks are cancelled and awaited when their owning agent disposes (the `ctx.agents.onCleanup` seam); the model-facing surface over all of this is [dsh-tool-tasks](../../packages/tasks/tool-tasks/README.md).
+`TaskService` (`ctx.tasks` — [`packages/tasks/tasks/src/index.ts`](../../packages/tasks/tasks/src/index.ts)): `start` (preflight → producer `run()` → atomic commit, fenced by `attachSurface`), non-consuming `get`/`list` (caller-scoped — owned-by-caller plus unowned only), `read` (consuming for stream kinds), `kill` (producer `cancel` first; a throw leaves the task untouched), `wait` (bounded, abort cancels the wait only), and `onTaskDone` (a `TaskDoneListener` per settlement, effect-scoped, contained). Every read/kill/wait/get compares the task's owner session with the caller's and rejects a foreign one. Owned tasks are cancelled and awaited when their owning agent disposes (the `ctx.agents.onCleanup` seam); the model-facing surface over all of this is [dsh-tool-tasks](../../packages/tasks/tool-tasks/README.md).
diff --git a/docs/module-graph.md b/docs/module-graph.md
index cec471df99..fe4dfe5099 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -144,6 +144,7 @@ flowchart TD
   pkg_user_interaction --> pkg_llm
   pkg_tasks --> pkg_agent
   pkg_tasks --> pkg_brand
+  pkg_tasks --> pkg_timeout
   pkg_agent_loop --> pkg_agent
   pkg_agent_loop --> pkg_llm
   pkg_agent_loop --> pkg_session
@@ -282,7 +283,7 @@ flowchart TD
 | [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
 | [`invariants`](../packages/support/invariants) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`user-interaction`](../packages/ui/user-interaction) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm) |
-| [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand) |
+| [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`timeout`](../packages/util/timeout) |
 | [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
diff --git a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index 5664c19dd5..86aafa7944 100644
--- a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -25,16 +25,21 @@ The registry is a CONCRETE service, not an interface/implementation seam pair: t
 
 `dsh-tasks` owns the vocabulary ([data-structure catalog](../../../core-data-structures/tasks.md)). `TaskId` is branded, generated by the registry as `<kind>-N` with a per-kind counter (`bash-1`, `subagent-1`) — the kind prefix keeps ids self-describing in transcripts and preserves the pre-runtime `bash-N` shape. Ids are runtime-global and predictable, so every access is authorized (below).
 
-A producer registers a task with:
+A producer hands its work to `ctx.tasks.start()` in a declare-then-execute shape (the pattern the timeout-policy plugin set: the capability declares, the shared layer executes): identity first, then a `run()` starter the runtime invokes only once nothing can fail anymore.
 
 ```ts ignore-check
-interface TaskRegistration {
+interface TaskStart {
   /** Producer kind — also the id prefix ('bash', 'subagent', …). */
   kind: string
   /** One-line model-facing label (the command; the delegation description). */
   label: string
   /** The spawning agent; undefined = unowned (open access, dies with the service). */
   owner?: Agent
+  /** Start the actual work; called exactly once, after preflight passed. */
+  run(): TaskHooks
+}
+
+interface TaskHooks {
   /** Request termination; idempotent; must lead to `done` settling. The optional reason is `task_kill`'s logged reason, forwarded. */
   cancel(reason?: string): void
   /** Settles at QUIESCENCE — after the producer has released the task's resources. Never rejects. */
@@ -64,7 +69,7 @@ Cross-session isolation lives IN the runtime so every consumer gets the same rul
 
 ```ts ignore-check
 class TaskService extends Service {           // ctx.tasks
-  register(reg: TaskRegistration): TaskId     // throws when no control surface is attached; ATOMIC — a throw mutates nothing
+  start(spec: TaskStart): TaskId              // preflight (throws) → spec.run() starts the work → atomic commit (cannot fail)
   get(id: TaskId, caller?: Agent): TaskSnapshot            // non-consuming; throws: unknown id, foreign owner
   list(caller?: Agent): TaskSnapshot[]                     // caller-visible only
   read(id: TaskId, caller?: Agent): TaskRead               // delta (stream kinds, consuming) or final output (final kinds, idempotent) + snapshot
@@ -77,7 +82,7 @@ class TaskService extends Service {           // ctx.tasks
 
 `TaskSnapshot` is the read-only projection: id, kind, label, owner session, status, detail, started/finished timestamps, and the `reported` notice-suppression flag (below). `wait` resolves with the terminal snapshot, or with the still-`running` snapshot on timeout; aborting the wait cancels only the wait.
 
-**Misconfiguration fails loud**: a deployment that loads a background-capable producer without any control surface would let the model start tasks it can never read or stop — the half-loaded failure mode the subagent RFC's first draft reshaped a whole plugin to avoid. The fence is `attachSurface()`: `dsh-tool-tasks` attaches (effect-scoped) on load, and `register()` throws `background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)` when none is attached — the earliest self-contained moment, since concurrent plugin start makes a load-time check racy. The registry stays ignorant of tool names; a deployment with a custom (non-model) surface attaches its own.
+**Misconfiguration fails loud**: a deployment that loads a background-capable producer without any control surface would let the model start tasks it can never read or stop — the half-loaded failure mode the subagent RFC's first draft reshaped a whole plugin to avoid. The fence is `attachSurface()`: `dsh-tool-tasks` attaches (effect-scoped) on load, and `start()` throws `background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)` when none is attached — the earliest self-contained moment, since concurrent plugin start makes a load-time check racy. The registry stays ignorant of tool names; a deployment with a custom (non-model) surface attaches its own.
 
 ## The model-facing control tools
 
@@ -95,7 +100,7 @@ Completion notices stay durable context, not a wake-up (`agent.inject()` appends
 
 ## Producer opt-in and schema exposure
 
-Whether a producer tool offers `run_in_background` is that producer's own defaulted config: `enableRunInBackground?: boolean` on `dsh-tool-bash` and on each `dsh-tool-subagent` instance (both default `true` — bash keeps its always-exposed behavior, and a deployment disables either per instance from cordis.yml, no code edit). A disabled producer omits the parameter from its schema entirely, so schema and capability can never disagree. `ctx.tasks` plays no part in schema shaping — it never rewrites or decorates a producer's tool schema (Kimi Code regex-rewrites its bash description when background is disabled; config-owns-the-schema makes that trick unnecessary) — it only provides runtime registration. The two halves compose fail-loud: the producer's config decides what the model sees, and a background call that still reaches `register()` without a control surface throws the load-this-package error. `register()` is atomic (a throw mutates no registry state), and a producer whose registration fails cancels and awaits its just-started work before rethrowing — background work never runs without a collectable id.
+Whether a producer tool offers `run_in_background` is that producer's own defaulted config: `enableRunInBackground?: boolean` on `dsh-tool-bash` and on each `dsh-tool-subagent` instance (both default `true` — bash keeps its always-exposed behavior, and a deployment disables either per instance from cordis.yml, no code edit). A disabled producer omits the parameter from its schema entirely, so schema and capability can never disagree. `ctx.tasks` plays no part in schema shaping — it never rewrites or decorates a producer's tool schema (Kimi Code regex-rewrites its bash description when background is disabled; config-owns-the-schema makes that trick unnecessary) — it only provides runtime registration. The two halves compose fail-loud: the producer's config decides what the model sees, and a background call that still reaches `start()` without a control surface throws the load-this-package error. `start()` preflights every failable check (the fence, validation, the owner-cleanup attach) BEFORE invoking the producer's `run()` and commits atomically after — background work started without a collectable id is structurally impossible, not a producer rollback obligation.
 
 ## The awaited owner-cleanup seam
 
@@ -110,11 +115,11 @@ A background task must not outlive its owner: the subagent case leaks live child
 
 `dsh-bash` keeps the execution contract and carries no registry. The seam is `resolve`, `run`, and `start`, where `start(spec)` returns a process handle — `BashProcess`: `{ command, status, exitCode, signal, done, readOutput(), kill() }` — instead of a registry entry: `get`/`ownerOf`/`list`/`onTaskDone`, the listener machinery, `BashTaskId`, `OwnerToken`, and the spec's `owner` field are gone (a consumer census found `get`/`list` reached only by test harnesses and `onTaskDone` single-consumer — `dsh-tool-bash`; the hook bridges consume `resolve`+`run` only). The local executor keeps an internal table of LIVE processes solely for its own disposal quiescence (entries leave on settlement). The foreground trusted-plugin path (`resolve` + `run` with `stdin`/`env`, used by the hook bridges) is untouched and never routes through the runtime; `BashExecSpec.timeoutMs` stays required-but-ignored by `start()` (shared-spec status quo, documented in the seam JSDoc); the credential-scrub duplication between the bash and ACP spawn sites is explicitly NOT this runtime's work — the registry never touches process spawning.
 
-`dsh-tool-bash` keeps the `bash` tool; the `run_in_background` path is `ctx.bash.start(...)` + `ctx.tasks.register({ kind: 'bash', label: command, owner: exec.agent, cancel, done, readOutput })`, where `done` maps the process exit to a `TaskOutcome` (`processOutcome`: `completed`/`killed` + exit-code/signal detail) and `readOutput` wraps the handle's incremental read with the spill/lossy formatting (`renderProcessRead`). The completion-notice listener left `dsh-tool-bash` entirely.
+`dsh-tool-bash` keeps the `bash` tool; the `run_in_background` path is `ctx.tasks.start({ kind: 'bash', label: command, owner: exec.agent, run })` whose `run()` spawns through `ctx.bash.start(...)` and returns the hooks, where `done` maps the process exit to a `TaskOutcome` (`processOutcome`: `completed`/`killed` + exit-code/signal detail) and `readOutput` wraps the handle's incremental read with the spill/lossy formatting (`renderProcessRead`). The completion-notice listener left `dsh-tool-bash` entirely.
 
 ## Subagent integration
 
-[Background subagent tasks](../feature/2026-07-08-background-subagent-tasks.md) rides this runtime; the headline consequence is that `dsh-tool-subagent` KEEPS its one-instance-per-provider shape — the multi-tool reshape existed only to keep cloned companion tools from colliding, and there are no companion tools to clone. Its background call starts the provider run, then registers `{ kind: 'subagent', label: description, owner: parent, cancel: run.cancel, done }` where `done` awaits `run.result`, awaits `run.dispose()` (quiescence), and maps the stop reason (`completed` → `completed`; `aborted` → `killed`; `error`/`max-tokens`/`refusal`/unknown → `failed` with the reason as detail) and the final text as `output`. No `readOutput` — the child session remains the detailed trace, exactly as that RFC argues.
+[Background subagent tasks](../feature/2026-07-08-background-subagent-tasks.md) rides this runtime; the headline consequence is that `dsh-tool-subagent` KEEPS its one-instance-per-provider shape — the multi-tool reshape existed only to keep cloned companion tools from colliding, and there are no companion tools to clone. Its background call is `ctx.tasks.start({ kind: 'subagent', label: description, owner: parent, run })` whose `run()` starts the provider run and returns `{ cancel: run.cancel, done }`, where `done` awaits `run.result`, awaits `run.dispose()` (quiescence), and maps the stop reason (`completed` → `completed`; `aborted` → `killed`; `error`/`max-tokens`/`refusal`/unknown → `failed` with the reason as detail) and the final text as `output`. No `readOutput` — the child session remains the detailed trace, exactly as that RFC argues.
 
 ## Alternatives considered
 
@@ -164,7 +169,7 @@ Everything model-visible already lands in the log: starts and reads are tool cal
 
 ## Testing
 
-Unit coverage pins the registry lifecycle (register/read/kill/wait/list, owner isolation including no-agent callers, stream-vs-final read semantics, listener containment, notice suppression after an explicit kill or terminal read/wait, the `attachSurface` fence, register atomicity — a failed registration mutates nothing and burns no counter; a failed producer `cancel` leaves the task untouched — disposal quiescence, per-kind id counters), the `onCleanup` drain ordering + containment (including mid-drain registration), both producers' registration mapping plus their no-orphan guarantee (a failed `register()` kills/cancels and awaits the just-started work before rethrowing), and unchanged foreground bash/subagent behavior. Snapshot coverage pins the task tool schemas and the prompt section through the pinned-header fixture.
+Unit coverage pins the registry lifecycle (register/read/kill/wait/list, owner isolation including no-agent callers, stream-vs-final read semantics, listener containment, notice suppression after an explicit kill or terminal read/wait, the `attachSurface` fence, start atomicity — a failed preflight mutates nothing and burns no counter; a failed producer `cancel` leaves the task untouched — disposal quiescence, per-kind id counters), the `onCleanup` drain ordering + containment (including mid-drain registration), both producers' start mapping plus the structural no-orphan guarantee (a failed preflight means the producer's `run()` — the spawn — was never invoked), and unchanged foreground bash/subagent behavior. Snapshot coverage pins the task tool schemas and the prompt section through the pinned-header fixture.
 
 ## Consequences
 
diff --git a/docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md b/docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md
index 0c9c7f884e..6774c3eb1f 100644
--- a/docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md
+++ b/docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md
@@ -16,7 +16,7 @@ Each `dsh-tool-subagent` instance may expose `run_in_background?: boolean`, gate
 
 A foreground call keeps the synchronous semantics: it waits for `run.result`, returns final text on `completed`, maps non-clean terminal stop reasons to an errored tool result, and disposes the run in `finally`.
 
-A background call validates that a parent agent exists, checks an already-aborted tool signal before starting, starts the provider run through `ctx.subagents`, registers the run with `ctx.tasks`, and returns `started background subagent task <task_id>`. After the id is returned the tool-call signal is NOT connected to `run.cancel()` — the parent step may finish while the child continues; cancellation belongs to `task_kill` and the owner-cleanup path. A registration that throws (the no-control-surface fence) does not orphan the child: the producer cancels the run, awaits its `done` (which settles only after `run.dispose()`), and rethrows — the model never learns an id for work that is not actually tracked. `ctx.tasks.register()` supplies the runtime guarantees this feature needs and this RFC does not implement: kind-prefixed branded task ids, owner-scoped access (the parent agent is the owner; another session's agent cannot read or kill the task), the loud no-control-surface failure, completion-notice injection, and the generic prompt guidance.
+A background call validates that a parent agent exists, checks an already-aborted tool signal, and hands the delegation to `ctx.tasks.start()` — the runtime preflights the control-surface fence and the owner cleanup BEFORE its `run()` starter creates the child through `ctx.subagents`, so a child that started without a collectable id is structurally impossible — then returns `started background subagent task <task_id>`. After the id is returned the tool-call signal is NOT connected to `run.cancel()` — the parent step may finish while the child continues; cancellation belongs to `task_kill` and the owner-cleanup path. `ctx.tasks.start()` supplies the runtime guarantees this feature needs and this RFC does not implement: kind-prefixed branded task ids, owner-scoped access (the parent agent is the owner; another session's agent cannot read or kill the task), the loud no-control-surface failure, completion-notice injection, and the generic prompt guidance.
 
 The registration maps the seam vocabulary onto the runtime's:
 
@@ -53,10 +53,10 @@ The child session is already the trace for internal reasoning, tool calls, and i
 
 ## Testing
 
-Unit coverage pins the stop-reason → outcome mapping (`runOutcome`, including unknown merge-extensible reasons), `settleRun`'s dispose-before-report on both result paths, the detached-signal contract (a pre-aborted signal refuses to start; a returned id is never wired to the tool signal), background settlement collected through the real `task_output`/`task_kill` tools, the no-orphan rollback when `register()` throws, per-instance schema gating (`enableRunInBackground: false` omits the parameter and the background wording), and the loud failure when the tasks runtime is absent. Snapshot coverage pins the changed `subagent`/`subagent_fork` schemas through the pinned-header fixture; recording a live background-delegation transcript requires a `DEEPSEEK_API_KEY` re-record and remains named follow-up work.
+Unit coverage pins the stop-reason → outcome mapping (`runOutcome`, including unknown merge-extensible reasons), `settleRun`'s dispose-before-report on both result paths, the detached-signal contract (a pre-aborted signal refuses to start; a returned id is never wired to the tool signal), background settlement collected through the real `task_output`/`task_kill` tools, the structural no-orphan guarantee (a failed `tasks.start` preflight never invokes the provider), per-instance schema gating (`enableRunInBackground: false` omits the parameter and the background wording), and the loud failure when the tasks runtime is absent. Snapshot coverage pins the changed `subagent`/`subagent_fork` schemas through the pinned-header fixture; recording a live background-delegation transcript requires a `DEEPSEEK_API_KEY` re-record and remains named follow-up work.
 
 ## Consequences
 
-Slow delegation no longer holds the parent step open: the model fans out background children, keeps working, and collects with the same three control tools it already uses for bash — no new habit, no schema clones, and `dsh-tool-subagent`'s per-provider shape survived unchanged. The feature's usability depends on the tasks pair being loaded; the runtime's `register()` fence turns a missing control surface into a loud, actionable error rather than a silent dead end, and the `dsh-agent-core` bundle ships the pair so every stock deployment has it.
+Slow delegation no longer holds the parent step open: the model fans out background children, keeps working, and collects with the same three control tools it already uses for bash — no new habit, no schema clones, and `dsh-tool-subagent`'s per-provider shape survived unchanged. The feature's usability depends on the tasks pair being loaded; the runtime's `start()` preflight fence turns a missing control surface into a loud, actionable error (raised before any child exists) rather than a silent dead end, and the `dsh-agent-core` bundle ships the pair so every stock deployment has it.
 
 The prompt guidance reduces abandoned tasks but cannot force a model to collect every background result. Runtime cleanup through the awaited owner-disposal path is the hard stop; a future planner or guard could enforce "no final answer with relevant running tasks" more strongly if the prompt proves insufficient. A background child outliving its starting tool call means a misbehaving child consumes tokens until collected, killed, or owner-disposed; `task_list` keeps it visible, and setting `enableRunInBackground: false` per instance keeps a deployment's delegation strictly synchronous.
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index b309895936..b00e768a3b 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -19,7 +19,7 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`, `ctx.bash`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.tasks` runtime and is collected/stopped through the `task_*` tools from `@deepseek-ai/dsh-tool-tasks`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled. |
 | `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. |
 | `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. |
-| `@deepseek-ai/dsh-tool-tasks` | `task_kill`, `task_list`, `task_output` | `ctx.tools`, `ctx.tasks`, `ctx.systemPrompt` | `tool/call`, `tool/result`, `context/message via agent.inject() for background completion notices` | - | The kind-agnostic background-task control surface: a background bash command and a background subagent are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers' `ctx.tasks.register()`. |
+| `@deepseek-ai/dsh-tool-tasks` | `task_kill`, `task_list`, `task_output` | `ctx.tools`, `ctx.tasks`, `ctx.systemPrompt` | `tool/call`, `tool/result`, `context/message via agent.inject() for background completion notices` | - | The kind-agnostic background-task control surface: a background bash command and a background subagent are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers' `ctx.tasks.start()`. |
 | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist or ACP plan. |
 | `@deepseek-ai/dsh-tool-web` | `web_fetch`, `web_search` | `ctx.tools`, `ctx.web`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | web_search and web_fetch keep provider selection behind ctx.web so model-visible schemas stay stable across backend swaps. |
 
@@ -332,7 +332,7 @@ Read output/status from a background task (started by a tool with `run_in_backgr
 
 Source: [`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/src/index.ts)
 
-The kind-agnostic background-task control surface: a background bash command and a background subagent are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers' `ctx.tasks.register()`.
+The kind-agnostic background-task control surface: a background bash command and a background subagent are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers' `ctx.tasks.start()`.
 
 ## `@deepseek-ai/dsh-tool-todo`
 
diff --git a/packages/bash/tool-bash/src/index.ts b/packages/bash/tool-bash/src/index.ts
index bb02b67b00..6bc0d334f3 100644
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -361,25 +361,22 @@ export function apply(ctx: Context, config: Config): void {
         // (cancellation belongs to task_kill / owner cleanup), so the check
         // happens here, once, instead of passing the signal to start().
         if (exec.signal?.aborted) throw new Error('command aborted')
-        const proc = ctx.bash.start(ctx.bash.resolve(request))
-        let id: string
-        try {
-          id = tasks.register({
-            kind: 'bash',
-            label: args.command,
-            ...exec.agent ? { owner: exec.agent } : {},
-            cancel: () => void proc.kill(),
-            done: proc.done.then(() => processOutcome(proc)),
-            readOutput: () => renderProcessRead(proc.readOutput()),
-          })
-        } catch (error: unknown) {
-          // A failed registration must not leak the just-started process: the
-          // model never received an id, so nothing could ever task_kill it.
-          // Kill, await quiescence, then fail the call with the real cause.
-          proc.kill()
-          await proc.done
-          throw error
-        }
+        // tasks.start preflights (surface fence, owner cleanup) BEFORE run()
+        // spawns anything, and cannot fail after — the process can never
+        // start without a collectable id.
+        const id = tasks.start({
+          kind: 'bash',
+          label: args.command,
+          ...exec.agent ? { owner: exec.agent } : {},
+          run: () => {
+            const proc = ctx.bash.start(ctx.bash.resolve(request))
+            return {
+              cancel: () => void proc.kill(),
+              done: proc.done.then(() => processOutcome(proc)),
+              readOutput: () => renderProcessRead(proc.readOutput()),
+            }
+          },
+        })
         return [{ type: 'text', text: `started background task ${id}` }]
       }
       const result = await ctx.bash.run(ctx.bash.resolve({
diff --git a/packages/bash/tool-bash/tests/tools.spec.ts b/packages/bash/tool-bash/tests/tools.spec.ts
index 7aebb310c8..71edc21eb5 100644
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -354,36 +354,30 @@ describe('background execution through the task runtime', () => {
     expect((ctx.bash as CountingStartExecutor).starts).toBe(0)
   })
 
-  it('a failed registration kills the just-started process (no orphan without an id)', async () => {
+  it('never spawns the process when tasks.start preflight throws (no orphan, by construction)', async () => {
     class LeakProbeExecutor extends BashExecutor {
-      kills = 0
+      starts = 0
       resolve(request: BashExecRequest): BashExecSpec {
         return { command: request.command, workdir: request.workdir ?? '/x', timeoutMs: request.timeoutMs ?? 0 }
       }
 
       run(): Promise<BashRunResult> { return Promise.reject(new Error('unused')) }
       start(spec: BashExecSpec): BashProcess {
-        let close!: () => void
-        const done = new Promise<void>((res) => { close = res })
-        const proc: BashProcess = {
+        this.starts += 1
+        return {
           command: spec.command,
-          status: 'running',
-          exitCode: null,
+          status: 'completed',
+          exitCode: 0,
           signal: null,
-          done,
+          done: Promise.resolve(),
           readOutput: () => ({ delta: '', lossy: false }),
-          kill: () => {
-            this.kills += 1
-            proc.status = 'killed'
-            close()
-            return true
-          },
+          kill: () => false,
         }
-        return proc
       }
     }
-    // TaskService WITHOUT any control surface: register() throws AFTER the
-    // process already started — the producer must kill and await it.
+    // TaskService WITHOUT any control surface: tasks.start preflights that
+    // fence BEFORE invoking the producer's run(), so the executor is never
+    // asked to spawn — there is no orphan to roll back.
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
@@ -395,8 +389,8 @@ describe('background execution through the task runtime', () => {
     const result = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
     expect(result.isError).toBe(true)
     expect(text(result)).toContain('no control surface is attached')
-    // The call resolved only after the kill landed (the catch awaits done).
-    expect((ctx.bash as LeakProbeExecutor).kills).toBe(1)
+    // Declare-then-execute: the failed preflight means no process ever ran.
+    expect((ctx.bash as LeakProbeExecutor).starts).toBe(0)
   })
 
   it('enableRunInBackground: false removes the parameter and flips the description', async () => {
diff --git a/packages/subagent/tool-subagent/src/index.ts b/packages/subagent/tool-subagent/src/index.ts
index 669621cb21..b32d6e4d4c 100644
--- a/packages/subagent/tool-subagent/src/index.ts
+++ b/packages/subagent/tool-subagent/src/index.ts
@@ -264,32 +264,27 @@ export function apply(ctx: Context, config: Config): void {
           // (the child outlives this step; cancellation belongs to task_kill
           // and owner-disposal cleanup), so the request carries NO signal.
           if (exec.signal?.aborted) throw new Error('subagent delegation aborted')
-          const run = ctx.subagents.start(config.provider, {
-            prompt: [{ type: 'text', text: args.prompt }],
-            parent,
-            ...config.agentOptions ? { agentOptions: config.agentOptions } : {},
+          // tasks.start preflights (surface fence, owner cleanup) BEFORE run()
+          // spawns the child, and cannot fail after — a child can never start
+          // without a collectable id.
+          const id = tasks.start({
+            kind: 'subagent',
+            label: args.description,
+            owner: parent,
+            run: () => {
+              const run = ctx.subagents.start(config.provider, {
+                prompt: [{ type: 'text', text: args.prompt }],
+                parent,
+                ...config.agentOptions ? { agentOptions: config.agentOptions } : {},
+              })
+              return {
+                cancel: (reason?: string) => { run.cancel(reason ?? 'background subagent task killed') },
+                done: settleRun(run),
+                // No readOutput: a subagent task is final-output-only — the
+                // child session remains the detailed trace.
+              }
+            },
           })
-          const done = settleRun(run)
-          let id: string
-          try {
-            id = tasks.register({
-              kind: 'subagent',
-              label: args.description,
-              owner: parent,
-              cancel: (reason) => { run.cancel(reason ?? 'background subagent task killed') },
-              done,
-              // No readOutput: a subagent task is final-output-only — the child
-              // session remains the detailed trace.
-            })
-          } catch (error: unknown) {
-            // A failed registration must not leak the just-started child: the
-            // model never received an id, so nothing could ever task_kill it.
-            // Cancel, await `done` (which settles only after run.dispose() —
-            // child quiescence), then fail the call with the real cause.
-            run.cancel('background task registration failed')
-            await done
-            throw error
-          }
           return [{ type: 'text', text: `started background subagent task ${id}` }]
         }
 
diff --git a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
index 06d39c2ec6..70e5e82c0b 100644
--- a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
+++ b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
@@ -602,28 +602,29 @@ describe('dsh-tool-subagent background mode', () => {
   })
 })
 
-describe('background registration failure (no orphaned child)', () => {
-  it('cancels and disposes the just-started run when register() throws', async () => {
-    // TaskService is loaded but NO control surface is attached, so
-    // ctx.tasks.register throws AFTER the provider run already started.
+describe('background preflight failure (no orphaned child, by construction)', () => {
+  it('never starts the child when tasks.start preflight throws', async () => {
+    // TaskService is loaded but NO control surface is attached: tasks.start
+    // preflights that fence BEFORE invoking the producer's run(), so the
+    // provider is never asked to spawn — there is no orphan to roll back.
     const ctx = await setup({ provider: 'mock' })
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(TaskService)
     const parent = { id: AgentId('agent-sess-p'), inject: () => {}, session: { header: { version: 0, id: 'sess-p', createdAt: 0 } } } as unknown as Agent
     ctx.agents.register(parent)
 
-    const events: string[] = []
+    let starts = 0
     ctx.subagents.registerProvider({
       name: 'probe',
       capabilities: { outputSchema: false, depthLimit: false, toolFilter: false },
       inheritsParentContext: false,
       start: () => {
-        let settle!: (value: { output: never[]; stopReason: 'aborted' }) => void
+        starts += 1
         return {
           id: AgentId('probe-child'),
-          result: new Promise((res) => { settle = res }),
-          cancel(reason?: string) { events.push(`cancel:${reason}`); settle({ output: [], stopReason: 'aborted' }) },
-          dispose() { events.push('dispose'); return Promise.resolve() },
+          result: Promise.resolve({ output: [], stopReason: 'completed' as const }),
+          cancel() {},
+          dispose: () => Promise.resolve(),
         }
       },
     })
@@ -637,8 +638,7 @@ describe('background registration failure (no orphaned child)', () => {
     })
     expect(result.isError).toBe(true)
     expect(text(result)).toContain('no control surface is attached')
-    // The child was cancelled AND disposed before the call settled — the
-    // model never got an id, so nothing else could ever collect or kill it.
-    expect(events).toEqual(['cancel:background task registration failed', 'dispose'])
+    // Declare-then-execute: the failed preflight means no child ever existed.
+    expect(starts).toBe(0)
   })
 })
diff --git a/packages/tasks/README.md b/packages/tasks/README.md
index a22528ba6d..e2221dce64 100644
--- a/packages/tasks/README.md
+++ b/packages/tasks/README.md
@@ -7,4 +7,4 @@ The shared background-task runtime: ONE home for task ids, owner isolation, poll
 | [`tasks`](tasks/README.md) (`@deepseek-ai/dsh-tasks`) | `ctx.tasks` | The registry service: branded `<kind>-N` ids, owner-fenced read/kill/wait/list, settlement bookkeeping, the awaited owner-cleanup path, and the `attachSurface` misconfiguration fence |
 | [`tool-tasks`](tool-tasks/README.md) (`@deepseek-ai/dsh-tool-tasks`) | — | The model-facing control surface: `task_output`, `task_list`, `task_kill`, the completion-notice injection, and the background-habit prompt section |
 
-The split is the state/surface boundary: the registry holds task state (an HMR reload of any tool plugin never orphans or kills a running task), while the tool surface is stateless presentation. Producers (`dsh-tool-bash`, `dsh-tool-subagent`) register running work via `ctx.tasks.register` and keep their own execution concerns; whether a producer exposes `run_in_background` is that producer's own `enableRunInBackground` config, never rewritten by this family.
+The split is the state/surface boundary: the registry holds task state (an HMR reload of any tool plugin never orphans or kills a running task), while the tool surface is stateless presentation. Producers (`dsh-tool-bash`, `dsh-tool-subagent`) hand their work to `ctx.tasks.start` (preflight, then the producer's starter, then an atomic commit) and keep their own execution concerns; whether a producer exposes `run_in_background` is that producer's own `enableRunInBackground` config, never rewritten by this family.
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index 14a2f75d6e..1d491cd6e0 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -4,7 +4,7 @@ The background task registry (`ctx.tasks`): a runtime-global, CONCRETE service (
 
 ## Service API
 
-- `register(registration): TaskId` — a producer hands over running work: `kind` (also the id prefix), `label`, optional `owner: Agent`, `cancel(reason?)`, `done: Promise<TaskOutcome>` (settles at QUIESCENCE, never rejects), optional `readOutput()` (stream kinds; absence = final-output-only). Throws while no control surface is attached — the loud fence against a deployment exposing `run_in_background` with no way to collect or stop the work — and is ATOMIC: a failed registration mutates nothing (no stored task, no counter bump, no owner-cleanup bookkeeping), so producers can reliably cancel their just-started work and rethrow.
+- `start(spec): TaskId` — declare-then-execute: the producer hands identity (`kind` — also the id prefix — `label`, optional `owner: Agent`) plus `run()`, the starter that returns the work's `TaskHooks` (`cancel(reason?)`, `done: Promise<TaskOutcome>` settling at QUIESCENCE and never rejecting, optional `readOutput()` for stream kinds; absence = final-output-only). Every check that can fail — the control-surface fence (the loud guard against a deployment exposing `run_in_background` with no way to collect or stop the work), validation, the owner-cleanup attach — runs BEFORE `run()` starts the actual work, and nothing can fail after it returns: work started without a collectable id is structurally impossible, not a producer rollback obligation.
 - `get(id, caller?)` / `list(caller?)` — non-consuming snapshots; `list` returns only caller-owned plus unowned tasks (a global listing would leak foreign labels).
 - `read(id, caller?): TaskRead` — stream kinds consume the per-task cursor (v1's single intended reader is the owning model — a non-consuming multi-reader surface would be a cursor/snapshot API extension, not a `read` change); final kinds read the terminal output idempotently.
 - `kill(id, caller?, reason?)` — `'requested'` (live task: producer `cancel` runs first — a throw fails the kill loud and leaves the task untouched — then `stopping`) or `'already-terminal'`. Every successful kill marks the task `reported` (the killer saw the end → completion notice suppressed).
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index 5d926b5230..2b89f461e1 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -4,8 +4,9 @@
  * snapshots, incremental/final output reads, cancellation, wait-for-terminal,
  * completion listeners, and the awaited owner-cleanup path. Producers
  * (`dsh-tool-bash` background commands, `dsh-tool-subagent` background
- * delegations, future long-running tools) register running work via
- * {@link TaskService.register} and keep their own execution concerns; the
+ * delegations, future long-running tools) hand their work to
+ * {@link TaskService.start} — preflight, then the producer's starter, then an
+ * atomic commit — and keep their own execution concerns; the
  * model-facing control surface (`@deepseek-ai/dsh-tool-tasks`) drives the
  * generic read/list/kill/wait operations.
  *
@@ -32,15 +33,16 @@ import { Context, Service } from 'cordis'
 import type { Agent, AgentId } from '@deepseek-ai/dsh-agent'
 import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
 import { TaskId } from './types.ts'
-import type { TaskDoneListener, TaskOutcome, TaskRead, TaskRegistration, TaskSnapshot, TaskStatus } from './types.ts'
+import type { TaskDoneListener, TaskOutcome, TaskRead, TaskSnapshot, TaskStart, TaskStatus } from './types.ts'
 
 export { TaskId } from './types.ts'
 export type {
   TaskDoneListener,
+  TaskHooks,
   TaskOutcome,
   TaskRead,
-  TaskRegistration,
   TaskSnapshot,
+  TaskStart,
   TaskStatus,
 } from './types.ts'
 
@@ -114,44 +116,48 @@ export class TaskService extends Service {
   }
 
   /**
-   * Register running background work and receive its task id (`<kind>-N`,
-   * per-kind counter). The registry attaches ONE continuation to
-   * `registration.done` that records the terminal snapshot, notifies
-   * {@link onTaskDone} listeners, and releases waiters; an owned task also
-   * gets the owner's awaited disposal cleanup attached (once per owner agent)
-   * through `ctx.agents.onCleanup`. Throws when no control surface is
-   * attached ({@link attachSurface}) — a task the model could never read or
-   * stop must fail loud at the start, not dangle — and for an empty
-   * kind/label. ATOMIC: a throw mutates no registry state, so a producer can
-   * cancel its just-started work and rethrow without leaving a stored task
-   * behind.
-   * @param registration - the producer's task contract (see {@link TaskRegistration}).
+   * PREFLIGHT, start, then atomically register background work; returns its
+   * task id (`<kind>-N`, per-kind counter). Every check that can fail — the
+   * control-surface fence ({@link attachSurface}; a task the model could
+   * never read or stop must fail loud before it exists), kind/label
+   * validation, and the owner's awaited disposal-cleanup attach (once per
+   * owner agent, through `ctx.agents.onCleanup`) — runs BEFORE
+   * `spec.run()` starts the actual work, and nothing in the runtime can fail
+   * after it returns: "work started but never got a collectable id" is
+   * structurally impossible, not a producer rollback obligation. The runtime
+   * attaches ONE continuation to the returned `done` that records the
+   * terminal snapshot, notifies {@link onTaskDone} listeners, and releases
+   * waiters. A throwing `run()` propagates with nothing registered (the
+   * producer owns any partial cleanup of its own failed start).
+   * @param spec - the task's identity/owner plus the `run()` starter (see {@link TaskStart}).
    * @returns the registry-issued task id.
    */
-  register(registration: TaskRegistration): TaskId {
+  start(spec: TaskStart): TaskId {
+    // -- Preflight: everything that can throw, before any work or mutation. --
     if (this.surfaces.size === 0) {
       throw new Error('background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)')
     }
-    if (registration.kind.length === 0) throw new Error('invalid task kind: expected a non-empty string')
-    if (registration.label.length === 0) throw new Error('invalid task label: expected a non-empty string')
-    // EVERYTHING that can throw runs before any mutation (counter, store):
-    // a failed registration must leave the registry exactly as it was — no
-    // stored-but-unreturned task the producer could never read or kill.
-    if (registration.owner !== undefined) this.ensureOwnerCleanup(registration.owner)
+    if (spec.kind.length === 0) throw new Error('invalid task kind: expected a non-empty string')
+    if (spec.label.length === 0) throw new Error('invalid task label: expected a non-empty string')
+    if (spec.owner !== undefined) this.ensureOwnerCleanup(spec.owner)
 
-    const count = (this.counters.get(registration.kind) ?? 0) + 1
-    this.counters.set(registration.kind, count)
-    const id = TaskId(`${registration.kind}-${count}`)
+    // -- Start: the producer's work begins only now, preflight-clean. --
+    const hooks = spec.run()
+
+    // -- Commit: pure mutations; nothing below can throw. --
+    const count = (this.counters.get(spec.kind) ?? 0) + 1
+    this.counters.set(spec.kind, count)
+    const id = TaskId(`${spec.kind}-${count}`)
 
     let markSettled!: () => void
     const settled = new Promise<void>((resolve) => { markSettled = resolve })
     const task: TrackedTask = {
       id,
-      kind: registration.kind,
-      label: registration.label,
-      ownerSession: registration.owner?.session.header.id,
-      cancel: registration.cancel.bind(registration),
-      readOutput: registration.readOutput?.bind(registration),
+      kind: spec.kind,
+      label: spec.label,
+      ownerSession: spec.owner?.session.header.id,
+      cancel: hooks.cancel.bind(hooks),
+      readOutput: hooks.readOutput?.bind(hooks),
       status: 'running',
       detail: undefined,
       output: undefined,
@@ -164,7 +170,7 @@ export class TaskService extends Service {
     }
     this.store.set(id, task)
 
-    void registration.done.then(
+    void hooks.done.then(
       (outcome) => { this.settle(task, outcome) },
       (error: unknown) => {
         // Producer contract violation (`done` must never reject) — contained
@@ -325,7 +331,7 @@ export class TaskService extends Service {
 
   /**
    * Declare that a control surface capable of reading/stopping tasks is
-   * loaded. {@link register} refuses to start a background task while NO
+   * loaded. {@link start} refuses to start a background task while NO
    * surface is attached — the loud fence against a deployment exposing
    * `run_in_background` without any way to collect or stop the work. The
    * model-facing `@deepseek-ai/dsh-tool-tasks` attaches on load; a deployment
diff --git a/packages/tasks/tasks/src/types.ts b/packages/tasks/tasks/src/types.ts
index 09b1911350..843ab11671 100644
--- a/packages/tasks/tasks/src/types.ts
+++ b/packages/tasks/tasks/src/types.ts
@@ -1,7 +1,8 @@
 /**
- * Task-registry vocabulary: the registration a producer hands to
- * {@link TaskService.register} and the snapshots/reads consumers get back.
- * Types only — the service lives in `./index.ts`.
+ * Task-runtime vocabulary: the {@link TaskStart} a producer hands to
+ * {@link TaskService.start} (identity + the `run()` starter), the
+ * {@link TaskHooks} its work is driven through, and the snapshots/reads
+ * consumers get back. Types only — the service lives in `./index.ts`.
  *
  * @module @deepseek-ai/dsh-tasks/types
  */
@@ -36,7 +37,7 @@ export function TaskId(id: string): TaskId {
 export type TaskStatus = 'running' | 'stopping' | 'completed' | 'killed' | 'failed'
 
 /**
- * The terminal result a producer's {@link TaskRegistration.done} resolves
+ * The terminal result a producer's {@link TaskHooks.done} resolves
  * with, mapped from the producer's own vocabulary (a process exit, a subagent
  * stop reason) into the registry's closed status set.
  */
@@ -46,7 +47,7 @@ export interface TaskOutcome {
   /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
   detail?: string
   /**
-   * Final output for FINAL-OUTPUT-ONLY kinds (no {@link TaskRegistration.readOutput}),
+   * Final output for FINAL-OUTPUT-ONLY kinds (no {@link TaskHooks.readOutput}),
    * read idempotently after the task settles. Stream kinds leave it unset —
    * their output is consumed incrementally through `readOutput`.
    */
@@ -54,13 +55,15 @@ export interface TaskOutcome {
 }
 
 /**
- * What a producer registers with {@link TaskService.register}: the running
- * work's identity, its owner, and the three hooks the registry drives it
- * through. The producer stays the owner of its execution concerns (process
- * streams, child agents); the registry owns ids, isolation, status, and
- * completion fan-out.
+ * What a producer hands to {@link TaskService.start}: the task's identity and
+ * owner (preflighted BEFORE any work starts), plus {@link run} — the starter
+ * the runtime invokes only once preflight cannot fail anymore. The producer
+ * stays the owner of its execution concerns (process streams, child agents);
+ * the runtime owns ids, isolation, status, and completion fan-out. This
+ * declare-then-execute split is what makes "work started but never got a
+ * collectable id" structurally impossible.
  */
-export interface TaskRegistration {
+export interface TaskStart {
   /** Producer kind — also the id prefix (`bash`, `subagent`, …). Non-empty. */
   kind: string
   /** One-line model-facing label (the command; the delegation description). */
@@ -69,10 +72,27 @@ export interface TaskRegistration {
    * The spawning agent. Its `session.header.id` becomes the task's owner
    * token (read/kill/wait/list are fenced to that session), and its disposal
    * cancels and awaits the task through the `ctx.agents.onCleanup` seam.
-   * `undefined` registers an UNOWNED task: open to any caller, alive until the
+   * `undefined` starts an UNOWNED task: open to any caller, alive until the
    * tasks service disposes.
    */
   owner?: Agent | undefined
+  /**
+   * Start the actual work and return its {@link TaskHooks}. Called EXACTLY
+   * once, synchronously, after every preflight check (control-surface fence,
+   * validation, owner-cleanup attach) has passed — nothing in the runtime can
+   * fail after it returns, so the started work is always registered. A throw
+   * here propagates with nothing registered; the producer owns any partial
+   * cleanup of its own failed start.
+   */
+  run(): TaskHooks
+}
+
+/**
+ * The live-work hooks a {@link TaskStart.run} returns: how the runtime
+ * cancels the work, observes its settlement, and (for stream kinds) reads
+ * its incremental output.
+ */
+export interface TaskHooks {
   /**
    * Request termination. Idempotent, synchronous, and must lead to
    * {@link done} settling; a throw propagates to the killer (fail loud — a
diff --git a/packages/tasks/tasks/tests/tasks.spec.ts b/packages/tasks/tasks/tests/tasks.spec.ts
index 87a71cd565..58eca32f48 100644
--- a/packages/tasks/tasks/tests/tasks.spec.ts
+++ b/packages/tasks/tasks/tests/tasks.spec.ts
@@ -4,7 +4,7 @@ import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import TaskService, { TaskId } from '@deepseek-ai/dsh-tasks'
-import type { TaskOutcome, TaskRegistration, TaskSnapshot } from '@deepseek-ai/dsh-tasks'
+import type { TaskHooks, TaskOutcome, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks'
 
 function stubAgent(rawId: string): Agent {
   const id = AgentId(rawId)
@@ -21,19 +21,19 @@ function stubAgent(rawId: string): Agent {
   }
 }
 
-/** A controllable producer: settle its `done` on demand, record cancels. */
-function producer(overrides: Partial<TaskRegistration> = {}) {
+/** A controllable producer start-spec: settle its `done` on demand, record cancels. */
+function producer(overrides: Partial<Omit<TaskStart, 'run'> & TaskHooks> = {}) {
   let settle!: (outcome: TaskOutcome) => void
   let reject!: (error: unknown) => void
   const cancels: (string | undefined)[] = []
-  const registration: TaskRegistration = {
-    kind: 'bash',
-    label: 'sleep 60',
+  const { kind = 'bash', label = 'sleep 60', owner, ...hookOverrides } = overrides
+  const hooks: TaskHooks = {
     cancel(reason) { cancels.push(reason) },
     done: new Promise<TaskOutcome>((res, rej) => { settle = res; reject = rej }),
-    ...overrides,
+    ...hookOverrides,
   }
-  return { registration, settle, reject, cancels }
+  const spec: TaskStart = { kind, label, ...owner !== undefined ? { owner } : {}, run: () => hooks }
+  return { spec, settle, reject, cancels }
 }
 
 async function harness() {
@@ -47,25 +47,25 @@ async function harness() {
 /** Let the settlement continuation (a `done.then`) run. */
 const tick = () => new Promise<void>(r => setTimeout(r, 0))
 
-describe('TaskService.register', () => {
+describe('TaskService.start', () => {
   it('refuses to register while no control surface is attached', async () => {
     const ctx = new Context()
     await ctx.plugin(TaskService)
-    expect(() => ctx.tasks.register(producer().registration))
+    expect(() => ctx.tasks.start(producer().spec))
       .toThrow('background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)')
   })
 
   it('rejects an empty kind and an empty label', async () => {
     const ctx = await harness()
-    expect(() => ctx.tasks.register(producer({ kind: '' }).registration)).toThrow('invalid task kind')
-    expect(() => ctx.tasks.register(producer({ label: '' }).registration)).toThrow('invalid task label')
+    expect(() => ctx.tasks.start(producer({ kind: '' }).spec)).toThrow('invalid task kind')
+    expect(() => ctx.tasks.start(producer({ label: '' }).spec)).toThrow('invalid task label')
   })
 
   it('issues kind-prefixed ids from per-kind counters', async () => {
     const ctx = await harness()
-    expect(ctx.tasks.register(producer().registration)).toBe('bash-1')
-    expect(ctx.tasks.register(producer().registration)).toBe('bash-2')
-    expect(ctx.tasks.register(producer({ kind: 'subagent' }).registration)).toBe('subagent-1')
+    expect(ctx.tasks.start(producer().spec)).toBe('bash-1')
+    expect(ctx.tasks.start(producer().spec)).toBe('bash-2')
+    expect(ctx.tasks.start(producer({ kind: 'subagent' }).spec)).toBe('subagent-1')
   })
 })
 
@@ -74,7 +74,7 @@ describe('TaskService reads and settlement', () => {
     const ctx = await harness()
     const chunks = ['first', '', 'rest']
     const p = producer({ readOutput: () => chunks.shift() ?? '' })
-    const id = ctx.tasks.register(p.registration)
+    const id = ctx.tasks.start(p.spec)
 
     expect(ctx.tasks.read(id)).toMatchObject({ text: 'first', snapshot: { status: 'running', reported: false } })
     expect(ctx.tasks.read(id).text).toBe('')
@@ -90,7 +90,7 @@ describe('TaskService reads and settlement', () => {
   it('final-output kinds read empty while live, the outcome output idempotently once settled', async () => {
     const ctx = await harness()
     const p = producer({ kind: 'subagent', label: 'research task' })
-    const id = ctx.tasks.register(p.registration)
+    const id = ctx.tasks.start(p.spec)
 
     expect(ctx.tasks.read(id)).toMatchObject({ text: '', snapshot: { status: 'running' } })
 
@@ -103,7 +103,7 @@ describe('TaskService reads and settlement', () => {
   it('a settled task without output reads as empty text', async () => {
     const ctx = await harness()
     const p = producer({ kind: 'subagent' })
-    const id = ctx.tasks.register(p.registration)
+    const id = ctx.tasks.start(p.spec)
     p.settle({ status: 'failed', detail: 'max-tokens' })
     await tick()
     expect(ctx.tasks.read(id)).toMatchObject({ text: '', snapshot: { status: 'failed', detail: 'max-tokens' } })
@@ -122,7 +122,7 @@ describe('TaskService reads and settlement', () => {
     ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot))
 
     const p = producer()
-    const id = ctx.tasks.register(p.registration)
+    const id = ctx.tasks.start(p.spec)
     p.settle({ status: 'completed', detail: 'exit code: 0' })
     await tick()
 
@@ -135,7 +135,7 @@ describe('TaskService reads and settlement', () => {
     const ctx = await harness()
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
     const p = producer()
-    const id = ctx.tasks.register(p.registration)
+    const id = ctx.tasks.start(p.spec)
     p.reject(new Error('transport exploded'))
     await tick()
 
@@ -155,7 +155,7 @@ describe('TaskService reads and settlement', () => {
     detach()
 
     const p = producer()
-    ctx.tasks.register(p.registration)
+    ctx.tasks.start(p.spec)
     p.settle({ status: 'completed' })
     await tick()
     expect(seen).toEqual([])
@@ -168,7 +168,7 @@ describe('TaskService.kill', () => {
     const seen: TaskSnapshot[] = []
     ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot))
     const p = producer()
-    const id = ctx.tasks.register(p.registration)
+    const id = ctx.tasks.start(p.spec)
 
     expect(ctx.tasks.kill(id, undefined, 'no longer needed')).toBe('requested')
     expect(p.cancels).toEqual(['no longer needed'])
@@ -184,7 +184,7 @@ describe('TaskService.kill', () => {
   it('reports an already-terminal task instead of failing', async () => {
     const ctx = await harness()
     const p = producer()
-    const id = ctx.tasks.register(p.registration)
+    const id = ctx.tasks.start(p.spec)
     p.settle({ status: 'completed' })
     await tick()
     expect(ctx.tasks.kill(id)).toBe('already-terminal')
@@ -196,11 +196,13 @@ describe('TaskService.kill', () => {
     ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot))
     let broken = true
     let settle!: (outcome: TaskOutcome) => void
-    const id = ctx.tasks.register({
+    const id = ctx.tasks.start({
       kind: 'bash',
       label: 'flaky cancel',
-      cancel() { if (broken) throw new Error('cancel boom') },
-      done: new Promise<TaskOutcome>((res) => { settle = res }),
+      run: () => ({
+        cancel() { if (broken) throw new Error('cancel boom') },
+        done: new Promise<TaskOutcome>((res) => { settle = res }),
+      }),
     })
     expect(() => ctx.tasks.kill(id)).toThrow('cancel boom')
     // The failed kill mutated NOTHING: still running, notice not suppressed,
@@ -221,7 +223,7 @@ describe('TaskService.wait', () => {
     const seen: TaskSnapshot[] = []
     ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot))
     const p = producer()
-    const id = ctx.tasks.register(p.registration)
+    const id = ctx.tasks.start(p.spec)
 
     const wait = ctx.tasks.wait(id, 5_000)
     p.settle({ status: 'completed', detail: 'exit code: 0' })
@@ -232,14 +234,14 @@ describe('TaskService.wait', () => {
 
   it('returns the live snapshot on timeout without marking reported', async () => {
     const ctx = await harness()
-    const id = ctx.tasks.register(producer().registration)
+    const id = ctx.tasks.start(producer().spec)
     expect(await ctx.tasks.wait(id, 5)).toMatchObject({ status: 'running', reported: false })
   })
 
   it('returns immediately for an already-terminal task', async () => {
     const ctx = await harness()
     const p = producer()
-    const id = ctx.tasks.register(p.registration)
+    const id = ctx.tasks.start(p.spec)
     p.settle({ status: 'completed' })
     await tick()
     expect(await ctx.tasks.wait(id, 5_000)).toMatchObject({ status: 'completed', reported: true })
@@ -247,14 +249,14 @@ describe('TaskService.wait', () => {
 
   it('rejects a non-positive or non-finite timeout', async () => {
     const ctx = await harness()
-    const id = ctx.tasks.register(producer().registration)
+    const id = ctx.tasks.start(producer().spec)
     await expect(ctx.tasks.wait(id, 0)).rejects.toThrow('invalid wait timeout')
     await expect(ctx.tasks.wait(id, Number.NaN)).rejects.toThrow('invalid wait timeout')
   })
 
   it('an aborted signal rejects the wait only — the task stays alive', async () => {
     const ctx = await harness()
-    const id = ctx.tasks.register(producer().registration)
+    const id = ctx.tasks.start(producer().spec)
 
     const controller = new AbortController()
     const wait = ctx.tasks.wait(id, 5_000, undefined, controller.signal)
@@ -275,8 +277,8 @@ describe('TaskService owner isolation', () => {
     ctx.agents.register(owner)
     const other = stubAgent('other')
 
-    const owned = ctx.tasks.register(producer({ owner }).registration)
-    const open = ctx.tasks.register(producer().registration)
+    const owned = ctx.tasks.start(producer({ owner }).spec)
+    const open = ctx.tasks.start(producer().spec)
 
     // The owner and the unowned task are reachable.
     expect(ctx.tasks.read(owned, owner).snapshot.id).toBe(owned)
@@ -296,9 +298,9 @@ describe('TaskService owner isolation', () => {
     ctx.agents.register(alice)
     ctx.agents.register(bob)
 
-    const aliceTask = ctx.tasks.register(producer({ owner: alice }).registration)
-    const bobTask = ctx.tasks.register(producer({ owner: bob }).registration)
-    const openTask = ctx.tasks.register(producer({ kind: 'subagent' }).registration)
+    const aliceTask = ctx.tasks.start(producer({ owner: alice }).spec)
+    const bobTask = ctx.tasks.start(producer({ owner: bob }).spec)
+    const openTask = ctx.tasks.start(producer({ kind: 'subagent' }).spec)
 
     expect(ctx.tasks.list(alice).map(t => t.id)).toEqual([aliceTask, openTask])
     expect(ctx.tasks.list(bob).map(t => t.id)).toEqual([bobTask, openTask])
@@ -309,11 +311,11 @@ describe('TaskService owner isolation', () => {
     const ctx = new Context()
     await ctx.plugin(TaskService)
     ctx.tasks.attachSurface('test-surface')
-    expect(() => ctx.tasks.register(producer({ owner: stubAgent('a') }).registration))
+    expect(() => ctx.tasks.start(producer({ owner: stubAgent('a') }).spec))
       .toThrow('background task ownership requires the agent registry')
     // The failed registration mutated nothing: no stored task, counter untouched.
     expect(ctx.tasks.list()).toEqual([])
-    expect(ctx.tasks.register(producer().registration)).toBe('bash-1')
+    expect(ctx.tasks.start(producer().spec)).toBe('bash-1')
   })
 
   it('a failed owner-cleanup attach leaves the registry unchanged and does not poison the owner', async () => {
@@ -321,7 +323,7 @@ describe('TaskService owner isolation', () => {
     const ghost = stubAgent('ghost') // never registered in ctx.agents
 
     // onCleanup rejects the unregistered agent BEFORE any registry mutation.
-    expect(() => ctx.tasks.register(producer({ owner: ghost }).registration))
+    expect(() => ctx.tasks.start(producer({ owner: ghost }).spec))
       .toThrow('is not registered')
     expect(ctx.tasks.list(ghost)).toEqual([])
 
@@ -330,12 +332,14 @@ describe('TaskService owner isolation', () => {
     ctx.agents.register(ghost)
     const cancels: (string | undefined)[] = []
     let settle!: (outcome: TaskOutcome) => void
-    const id = ctx.tasks.register({
+    const id = ctx.tasks.start({
       kind: 'bash',
       label: 'after retry',
       owner: ghost,
-      cancel(reason) { cancels.push(reason); settle({ status: 'killed' }) },
-      done: new Promise<TaskOutcome>((res) => { settle = res }),
+      run: () => ({
+        cancel(reason) { cancels.push(reason); settle({ status: 'killed' }) },
+        done: new Promise<TaskOutcome>((res) => { settle = res }),
+      }),
     })
     expect(id).toBe('bash-1') // the failed attempt burned no counter
     await ctx.agents.drainCleanups(ghost.id)
@@ -353,15 +357,17 @@ describe('TaskService owner cleanup', () => {
     // The producer settles only when cancelled — models a child that stops on request.
     let settle!: (outcome: TaskOutcome) => void
     const cancels: (string | undefined)[] = []
-    ctx.tasks.register({
+    ctx.tasks.start({
       kind: 'subagent',
       label: 'long research',
       owner,
-      cancel(reason) { cancels.push(reason); settle({ status: 'killed' }) },
-      done: new Promise<TaskOutcome>((res) => { settle = res }),
+      run: () => ({
+        cancel(reason) { cancels.push(reason); settle({ status: 'killed' }) },
+        done: new Promise<TaskOutcome>((res) => { settle = res }),
+      }),
     })
     const terminal = producer({ owner })
-    ctx.tasks.register(terminal.registration)
+    ctx.tasks.start(terminal.spec)
     terminal.settle({ status: 'completed' })
     await tick()
 
@@ -378,8 +384,8 @@ describe('TaskService owner cleanup', () => {
 
     const first = producer({ owner })
     const second = producer({ owner })
-    ctx.tasks.register(first.registration)
-    ctx.tasks.register(second.registration)
+    ctx.tasks.start(first.spec)
+    ctx.tasks.start(second.spec)
     first.settle({ status: 'completed' })
     second.settle({ status: 'completed' })
     await tick()
@@ -387,7 +393,7 @@ describe('TaskService owner cleanup', () => {
 
     // A fresh task after the drain gets a fresh cleanup (the set was consumed).
     const third = producer({ owner })
-    ctx.tasks.register(third.registration)
+    ctx.tasks.start(third.spec)
     third.settle({ status: 'completed' })
     await tick()
     expect(ctx.tasks.list(owner)).toHaveLength(1)
@@ -402,12 +408,14 @@ describe('TaskService owner cleanup', () => {
     ctx.agents.register(owner)
 
     let settle!: (outcome: TaskOutcome) => void
-    ctx.tasks.register({
+    ctx.tasks.start({
       kind: 'bash',
       label: 'broken producer',
       owner,
-      cancel() { throw new Error('cancel boom') },
-      done: new Promise<TaskOutcome>((res) => { settle = res }),
+      run: () => ({
+        cancel() { throw new Error('cancel boom') },
+        done: new Promise<TaskOutcome>((res) => { settle = res }),
+      }),
     })
 
     const drain = ctx.agents.drainCleanups(owner.id)
@@ -432,11 +440,13 @@ describe('TaskService disposal', () => {
     ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot.id))
     let settle!: (outcome: TaskOutcome) => void
     const cancels: (string | undefined)[] = []
-    ctx.tasks.register({
+    ctx.tasks.start({
       kind: 'bash',
       label: 'sleep 600',
-      cancel(reason) { cancels.push(reason); settle({ status: 'killed' }) },
-      done: new Promise<TaskOutcome>((res) => { settle = res }),
+      run: () => ({
+        cancel(reason) { cancels.push(reason); settle({ status: 'killed' }) },
+        done: new Promise<TaskOutcome>((res) => { settle = res }),
+      }),
     })
 
     await fiber.dispose()
@@ -456,10 +466,10 @@ describe('TaskService disposal', () => {
 
     detachA1()
     detachA1() // second call of the same disposer is a no-op
-    expect(() => ctx.tasks.register(producer().registration)).not.toThrow() // a ×1 + b remain
+    expect(() => ctx.tasks.start(producer().spec)).not.toThrow() // a ×1 + b remain
     detachA2()
-    expect(() => ctx.tasks.register(producer().registration)).not.toThrow() // b remains
+    expect(() => ctx.tasks.start(producer().spec)).not.toThrow() // b remains
     await fiber.dispose() // detaches b with its fiber (HMR safety)
-    expect(() => ctx.tasks.register(producer().registration)).toThrow('no control surface is attached')
+    expect(() => ctx.tasks.start(producer().spec)).toThrow('no control surface is attached')
   })
 })
diff --git a/packages/tasks/tool-tasks/README.md b/packages/tasks/tool-tasks/README.md
index 0548526474..9246375926 100644
--- a/packages/tasks/tool-tasks/README.md
+++ b/packages/tasks/tool-tasks/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-tool-tasks
 
-The model-facing background task control surface over `ctx.tasks`: three kind-agnostic tools, the completion-notice injection, and the prompt section that teaches the background habit. Loading this plugin calls `ctx.tasks.attachSurface('tool-tasks')`, which is what arms producers' `register()`.
+The model-facing background task control surface over `ctx.tasks`: three kind-agnostic tools, the completion-notice injection, and the prompt section that teaches the background habit. Loading this plugin calls `ctx.tasks.attachSurface('tool-tasks')`, which is what arms producers' `ctx.tasks.start()`.
 
 ## Tools
 
diff --git a/packages/tasks/tool-tasks/src/index.ts b/packages/tasks/tool-tasks/src/index.ts
index 859c2b0f21..65d9f0ce0e 100644
--- a/packages/tasks/tool-tasks/src/index.ts
+++ b/packages/tasks/tool-tasks/src/index.ts
@@ -6,8 +6,8 @@
  * registry (`@deepseek-ai/dsh-tasks`).
  *
  * This plugin IS the control surface: it calls `ctx.tasks.attachSurface()` on
- * load, which is what re-arms producers' `register()` (the registry refuses
- * background work while no surface could collect or stop it).
+ * load, which is what arms producers' `ctx.tasks.start()` (the runtime's
+ * preflight refuses background work while no surface could collect or stop it).
  *
  * Completion notices: when a task settles, a short notice is injected into
  * the owning agent's session (`agent.inject()` — durable context for the NEXT
diff --git a/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
index 930dc2b019..639d17dfb0 100644
--- a/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
+++ b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
@@ -6,7 +6,7 @@ import ToolRegistry from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import TaskService from '@deepseek-ai/dsh-tasks'
-import type { TaskOutcome, TaskRegistration, TaskSnapshot } from '@deepseek-ai/dsh-tasks'
+import type { TaskHooks, TaskOutcome, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks'
 import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import { statusLine } from '@deepseek-ai/dsh-tool-tasks'
 
@@ -32,18 +32,18 @@ function fakeAgent(ctx: Context, sessionId: string, inject: (...args: unknown[])
   return agent
 }
 
-/** A controllable producer registration (settle `done` on demand, record cancels). */
-function producer(overrides: Partial<TaskRegistration> = {}) {
+/** A controllable producer start-spec (settle `done` on demand, record cancels). */
+function producer(overrides: Partial<Omit<TaskStart, 'run'> & TaskHooks> = {}) {
   let settle!: (outcome: TaskOutcome) => void
   const cancels: (string | undefined)[] = []
-  const registration: TaskRegistration = {
-    kind: 'bash',
-    label: 'sleep 60',
+  const { kind = 'bash', label = 'sleep 60', owner, ...hookOverrides } = overrides
+  const hooks: TaskHooks = {
     cancel(reason) { cancels.push(reason) },
     done: new Promise<TaskOutcome>((res) => { settle = res }),
-    ...overrides,
+    ...hookOverrides,
   }
-  return { registration, settle, cancels }
+  const spec: TaskStart = { kind, label, ...owner !== undefined ? { owner } : {}, run: () => hooks }
+  return { spec, settle, cancels }
 }
 
 let callCounter = 0
@@ -60,9 +60,9 @@ const tick = () => new Promise<void>(r => setTimeout(r, 0))
 describe('tool-tasks setup', () => {
   it('attaches the control surface on load and detaches it with the fiber', async () => {
     const { ctx, toolsFiber } = await setup()
-    expect(() => ctx.tasks.register(producer().registration)).not.toThrow()
+    expect(() => ctx.tasks.start(producer().spec)).not.toThrow()
     await toolsFiber.dispose()
-    expect(() => ctx.tasks.register(producer().registration)).toThrow('no control surface is attached')
+    expect(() => ctx.tasks.start(producer().spec)).toThrow('no control surface is attached')
   })
 
   it('rejects a config whose default wait exceeds the cap', async () => {
@@ -89,7 +89,7 @@ describe('tool-tasks setup', () => {
     await ctx.plugin(TaskService)
     ToolTasks.apply(ctx, {})
     expect(ctx.tools.get('task_output')).toBeDefined()
-    expect(() => ctx.tasks.register(producer().registration)).not.toThrow()
+    expect(() => ctx.tasks.start(producer().spec)).not.toThrow()
   })
 })
 
@@ -97,7 +97,7 @@ describe('task_output', () => {
   it('reads a consuming delta with a trailing status line', async () => {
     const { ctx } = await setup()
     const chunks = ['line one\n', '']
-    ctx.tasks.register(producer({ readOutput: () => chunks.shift() ?? '' }).registration)
+    ctx.tasks.start(producer({ readOutput: () => chunks.shift() ?? '' }).spec)
 
     // A body already ending in a newline gets no doubled separator.
     expect(text(await call(ctx, 'task_output', { task_id: 'bash-1' }))).toBe('line one\n[status: running]')
@@ -107,7 +107,7 @@ describe('task_output', () => {
   it('returns the final output of a settled final-output task', async () => {
     const { ctx } = await setup()
     const p = producer({ kind: 'subagent', label: 'research' })
-    ctx.tasks.register(p.registration)
+    ctx.tasks.start(p.spec)
     expect(text(await call(ctx, 'task_output', { task_id: 'subagent-1' }))).toBe('(no new output)\n[status: running]')
 
     p.settle({ status: 'completed', detail: 'completed', output: 'the answer' })
@@ -118,7 +118,7 @@ describe('task_output', () => {
   it('wait: true blocks until settlement and reports the terminal state', async () => {
     const { ctx } = await setup()
     const p = producer({ kind: 'subagent', label: 'research' })
-    ctx.tasks.register(p.registration)
+    ctx.tasks.start(p.spec)
 
     const pending = call(ctx, 'task_output', { task_id: 'subagent-1', wait: true })
     p.settle({ status: 'completed', output: 'done deal' })
@@ -127,7 +127,7 @@ describe('task_output', () => {
 
   it('wait: true times out against the configured cap and leaves the task alive', async () => {
     const { ctx } = await setup({ waitTimeoutMs: 10, maxWaitTimeoutMs: 20 })
-    ctx.tasks.register(producer().registration)
+    ctx.tasks.start(producer().spec)
 
     // A model-supplied timeout far above the cap is clamped: this returns
     // promptly (≤ the 20ms cap), not after ten minutes.
@@ -150,10 +150,10 @@ describe('task_list', () => {
     expect(text(await call(ctx, 'task_list', {}))).toBe('(no background tasks)')
 
     const alice = fakeAgent(ctx, 'sess-alice')
-    ctx.tasks.register(producer({ owner: alice, label: 'pnpm test' }).registration)
-    ctx.tasks.register(producer({ kind: 'subagent', label: 'open research' }).registration)
+    ctx.tasks.start(producer({ owner: alice, label: 'pnpm test' }).spec)
+    ctx.tasks.start(producer({ kind: 'subagent', label: 'open research' }).spec)
     const p = producer({ owner: alice, label: 'build' })
-    ctx.tasks.register(p.registration)
+    ctx.tasks.start(p.spec)
     p.settle({ status: 'completed', detail: 'exit code: 0' })
     await tick()
 
@@ -172,7 +172,7 @@ describe('task_kill', () => {
   it('requests cancellation with the forwarded reason', async () => {
     const { ctx } = await setup()
     const p = producer()
-    ctx.tasks.register(p.registration)
+    ctx.tasks.start(p.spec)
 
     const result = await call(ctx, 'task_kill', { task_id: 'bash-1', reason: 'superseded' })
     expect(text(result)).toBe('requested cancellation of task bash-1')
@@ -183,7 +183,7 @@ describe('task_kill', () => {
     const { ctx } = await setup()
     let delta = 'unread tail'
     const p = producer({ readOutput: () => { const d = delta; delta = ''; return d } })
-    ctx.tasks.register(p.registration)
+    ctx.tasks.start(p.spec)
     p.settle({ status: 'completed', detail: 'exit code: 0' })
     await tick()
 
@@ -217,7 +217,7 @@ describe('completion notices', () => {
     const inject = vi.fn()
     const owner = fakeAgent(ctx, 'sess-1', inject)
     const p = producer({ owner, label: 'pnpm test' })
-    ctx.tasks.register(p.registration)
+    ctx.tasks.start(p.spec)
 
     p.settle({ status: 'completed', detail: 'exit code: 0' })
     await tick()
@@ -233,7 +233,7 @@ describe('completion notices', () => {
     const inject = vi.fn()
     const owner = fakeAgent(ctx, 'sess-1', inject)
     const p = producer({ owner })
-    ctx.tasks.register(p.registration)
+    ctx.tasks.start(p.spec)
 
     await call(ctx, 'task_kill', { task_id: 'bash-1' }, owner)
     p.settle({ status: 'killed' })
@@ -246,7 +246,7 @@ describe('completion notices', () => {
     const inject = vi.fn()
     const owner = fakeAgent(ctx, 'sess-1', inject)
     const p = producer({ owner, kind: 'subagent' })
-    ctx.tasks.register(p.registration)
+    ctx.tasks.start(p.spec)
 
     const pending = call(ctx, 'task_output', { task_id: 'subagent-1', wait: true }, owner)
     p.settle({ status: 'completed', output: 'answer' })
@@ -258,7 +258,7 @@ describe('completion notices', () => {
     const { ctx } = await setup()
     // Unowned: settles with nobody to notify — nothing throws.
     const unowned = producer()
-    ctx.tasks.register(unowned.registration)
+    ctx.tasks.start(unowned.spec)
     unowned.settle({ status: 'completed' })
     await tick()
 
@@ -266,7 +266,7 @@ describe('completion notices', () => {
     const inject = vi.fn(() => { throw new Error('agent "agent-sess-1" is disposed') })
     const owner = fakeAgent(ctx, 'sess-1', inject)
     const p = producer({ owner })
-    ctx.tasks.register(p.registration)
+    ctx.tasks.start(p.spec)
     p.settle({ status: 'completed' })
     await tick()
     expect(inject).toHaveBeenCalledTimes(1)
@@ -277,7 +277,7 @@ describe('completion notices', () => {
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
     const owner = fakeAgent(ctx, 'sess-1', () => { throw new Error('unexpected inject bug') })
     const p = producer({ owner })
-    ctx.tasks.register(p.registration)
+    ctx.tasks.start(p.spec)
     p.settle({ status: 'completed' })
     await tick()
     // The throw escapes the notice listener and is contained (logged) by the
@@ -292,10 +292,10 @@ describe('completion notices', () => {
 
     // Owner known at registration, unregistered before settlement → no match.
     const p1 = producer({ owner })
-    ctx.tasks.register(p1.registration)
+    ctx.tasks.start(p1.spec)
     // A second task whose settlement happens after the whole registry is gone.
     const p2 = producer({ owner })
-    ctx.tasks.register(p2.registration)
+    ctx.tasks.start(p2.spec)
 
     await agentsFiber.dispose()
     p1.settle({ status: 'completed' })
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index d8e6b85627..23a57f332b 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -173,7 +173,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolTasks)
     },
     note:
-      'The kind-agnostic background-task control surface: a background bash command and a background subagent are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers\' `ctx.tasks.register()`.',
+      'The kind-agnostic background-task control surface: a background bash command and a background subagent are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers\' `ctx.tasks.start()`.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-todo',
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index b619b9c882..d0bdbb2f4e 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -63,7 +63,8 @@
     { "doc": "docs/core-data-structures/bash.md", "symbol": "BashProcess", "source": "packages/bash/bash/src/types.ts" },
     { "doc": "docs/core-data-structures/bash.md", "symbol": "BashProcessRead", "source": "packages/bash/bash/src/types.ts" },
 
-    { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskRegistration", "source": "packages/tasks/tasks/src/types.ts" },
+    { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskStart", "source": "packages/tasks/tasks/src/types.ts" },
+    { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskHooks", "source": "packages/tasks/tasks/src/types.ts" },
     { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskOutcome", "source": "packages/tasks/tasks/src/types.ts" },
     { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskSnapshot", "source": "packages/tasks/tasks/src/types.ts" },
     { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskRead", "source": "packages/tasks/tasks/src/types.ts" },

From 6771a733097b0cb077a9630fd4befb60cadb0f6e Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 9 Jul 2026 22:08:38 +0800
Subject: [PATCH 06/48] =?UTF-8?q?docs(tasks):=20fix=20review=20finding=20?=
 =?UTF-8?q?=E2=80=94=20TaskId=20JSDoc=20links=20TaskService.start,=20not?=
 =?UTF-8?q?=20the=20removed=20register()?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/tasks/tasks/src/types.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/tasks/tasks/src/types.ts b/packages/tasks/tasks/src/types.ts
index 843ab11671..c03c8a2584 100644
--- a/packages/tasks/tasks/src/types.ts
+++ b/packages/tasks/tasks/src/types.ts
@@ -12,7 +12,7 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 
 /**
  * Identifies one background task in the runtime-global registry. Generated by
- * {@link TaskService.register} as `<kind>-N` (per-kind counter) — kind-prefixed
+ * {@link TaskService.start} as `<kind>-N` (per-kind counter) — kind-prefixed
  * so transcripts stay self-describing, sequential because the owner fence (not
  * id secrecy) is the isolation boundary.
  */

From 43d60286e3ef4df567ab96f743f11bce3c52c5db Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 9 Jul 2026 23:08:26 +0800
Subject: [PATCH 07/48] fix(tasks): an aborted wait must not leave a settled
 task notice-suppressed (review finding)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two windows where settle() could read a live waiter count, mark the
task reported (suppressing the completion notice), and then watch that
waiter reject with 'wait aborted' delivering nothing — leaving the
owning session with no terminal notification at all:

- abort and settlement in the same tick, settle continuation ordered
  first: the waiter now un-counts itself SYNCHRONOUSLY inside onAbort
  (the finally decrement alone lands a microtask too late), so the
  settle path sees no live waiter and the notice fires;
- abort landing after settlement but before the wait's resolve
  microtask: the wait now resolves and DELIVERS the terminal snapshot
  it owes instead of rejecting (settlement suppressed the notice on
  this waiter's behalf).

Both windows pinned by deterministic tests that fail on the previous
implementation; wait()'s abort contract updated in JSDoc/README/RFC.
---
 ...06-20-generic-long-running-tool-runtime.md |  2 +-
 packages/tasks/tasks/README.md                |  2 +-
 packages/tasks/tasks/src/index.ts             | 34 ++++++++++++---
 packages/tasks/tasks/tests/tasks.spec.ts      | 43 +++++++++++++++++++
 4 files changed, 74 insertions(+), 7 deletions(-)

diff --git a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index 86aafa7944..8393de41c2 100644
--- a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -80,7 +80,7 @@ class TaskService extends Service {           // ctx.tasks
 }
 ```
 
-`TaskSnapshot` is the read-only projection: id, kind, label, owner session, status, detail, started/finished timestamps, and the `reported` notice-suppression flag (below). `wait` resolves with the terminal snapshot, or with the still-`running` snapshot on timeout; aborting the wait cancels only the wait.
+`TaskSnapshot` is the read-only projection: id, kind, label, owner session, status, detail, started/finished timestamps, and the `reported` notice-suppression flag (below). `wait` resolves with the terminal snapshot, or with the still-`running` snapshot on timeout; aborting the wait cancels only the wait — unless the task already settled, in which case the wait still delivers the terminal snapshot (settlement suppressed the completion notice on this live waiter's behalf, and an aborted waiter un-counts itself synchronously so a same-tick settlement never suppresses a notice nobody will deliver).
 
 **Misconfiguration fails loud**: a deployment that loads a background-capable producer without any control surface would let the model start tasks it can never read or stop — the half-loaded failure mode the subagent RFC's first draft reshaped a whole plugin to avoid. The fence is `attachSurface()`: `dsh-tool-tasks` attaches (effect-scoped) on load, and `start()` throws `background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)` when none is attached — the earliest self-contained moment, since concurrent plugin start makes a load-time check racy. The registry stays ignorant of tool names; a deployment with a custom (non-model) surface attaches its own.
 
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index 1d491cd6e0..df2f21ee91 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -8,7 +8,7 @@ The background task registry (`ctx.tasks`): a runtime-global, CONCRETE service (
 - `get(id, caller?)` / `list(caller?)` — non-consuming snapshots; `list` returns only caller-owned plus unowned tasks (a global listing would leak foreign labels).
 - `read(id, caller?): TaskRead` — stream kinds consume the per-task cursor (v1's single intended reader is the owning model — a non-consuming multi-reader surface would be a cursor/snapshot API extension, not a `read` change); final kinds read the terminal output idempotently.
 - `kill(id, caller?, reason?)` — `'requested'` (live task: producer `cancel` runs first — a throw fails the kill loud and leaves the task untouched — then `stopping`) or `'already-terminal'`. Every successful kill marks the task `reported` (the killer saw the end → completion notice suppressed).
-- `wait(id, timeoutMs, caller?, signal?)` — resolves with the terminal snapshot (marked `reported`), or the live snapshot at timeout; an aborted signal rejects the WAIT only. Timing is a [`dsh-timeout`](../../util/timeout/README.md) `deadline()` scoped to the `TASK_WAIT_TIMEOUT` code, so a nested foreign deadline never misreads as a wait timeout.
+- `wait(id, timeoutMs, caller?, signal?)` — resolves with the terminal snapshot (marked `reported`), or the live snapshot at timeout; an aborted signal rejects the WAIT only — unless the task already settled, in which case the wait still resolves and delivers the terminal snapshot (settlement suppressed the completion notice on this waiter's behalf, so rejecting would leave the finish both unreported and un-noticed). Timing is a [`dsh-timeout`](../../util/timeout/README.md) `deadline()` scoped to the `TASK_WAIT_TIMEOUT` code, so a nested foreign deadline never misreads as a wait timeout.
 - `onTaskDone(listener)` — exactly once per task with the terminal snapshot; effect-scoped, per-listener containment, silent after service disposal.
 - `attachSurface(name)` — declares a control surface exists (the model tools, or a deployment's custom surface); effect-scoped.
 
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index 2b89f461e1..9601e296b3 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -270,8 +270,12 @@ export class TaskService extends Service {
    * terminal snapshot (marked {@link TaskSnapshot.reported} — the wait
    * response reports the end, so the completion notice is suppressed), or
    * with the still-live snapshot when the timeout expires first. An abort of
-   * `signal` rejects the WAIT only — the task keeps running. Throws for an
-   * unknown id, a task owned by another session, or a non-positive timeout.
+   * `signal` rejects the WAIT only (the task keeps running) — UNLESS the task
+   * has already settled: settlement saw this live waiter and suppressed the
+   * completion notice on its behalf, so the wait still resolves and delivers
+   * the terminal snapshot it owes (an abort must never leave a finished task
+   * both unreported and notice-suppressed). Throws for an unknown id, a task
+   * owned by another session, or a non-positive timeout.
    * @param id - the task to wait for.
    * @param timeoutMs - max wait in milliseconds (positive, finite; the surface caps it).
    * @param caller - the waiting agent, checked against the task's owner.
@@ -286,7 +290,19 @@ export class TaskService extends Service {
     }
     if (!isTerminal(task.status)) {
       if (signal?.aborted) throw new Error('wait aborted')
+      // `waiters` is the settle-path heuristic "someone WILL deliver the
+      // terminal snapshot, suppress the notice". An abort breaks that promise,
+      // so the un-count must happen SYNCHRONOUSLY inside onAbort — the
+      // `finally` decrement alone runs a microtask later, after a same-tick
+      // settlement could already have read the stale count and suppressed the
+      // notice for a waiter that then rejects and delivers nothing.
       task.waiters += 1
+      let counted = true
+      const uncount = (): void => {
+        if (!counted) return
+        counted = false
+        task.waiters -= 1
+      }
       try {
         // The dsh-timeout deadline fits wait() exactly because both only
         // NOTIFY: a wait timeout returns the live snapshot (the task keeps
@@ -296,8 +312,16 @@ export class TaskService extends Service {
         using d = deadline(signal, timeoutMs, TASK_WAIT_TIMEOUT)
         await new Promise<void>((resolve, reject) => {
           const onAbort = (): void => {
-            if (timeoutOf(d.signal, TASK_WAIT_TIMEOUT) !== undefined) resolve()
-            else reject(new Error('wait aborted'))
+            if (timeoutOf(d.signal, TASK_WAIT_TIMEOUT) !== undefined) {
+              resolve()
+            } else if (isTerminal(task.status)) {
+              // Settlement already ran and suppressed the notice for this
+              // waiter — deliver the terminal snapshot instead of rejecting.
+              resolve()
+            } else {
+              uncount()
+              reject(new Error('wait aborted'))
+            }
           }
           d.signal.addEventListener('abort', onAbort, { once: true })
           void task.settled.then(() => {
@@ -306,7 +330,7 @@ export class TaskService extends Service {
           })
         })
       } finally {
-        task.waiters -= 1
+        uncount()
       }
     }
     if (isTerminal(task.status)) task.reported = true
diff --git a/packages/tasks/tasks/tests/tasks.spec.ts b/packages/tasks/tasks/tests/tasks.spec.ts
index 58eca32f48..a2324448cf 100644
--- a/packages/tasks/tasks/tests/tasks.spec.ts
+++ b/packages/tasks/tasks/tests/tasks.spec.ts
@@ -268,6 +268,49 @@ describe('TaskService.wait', () => {
     preAborted.abort()
     await expect(ctx.tasks.wait(id, 5_000, undefined, preAborted.signal)).rejects.toThrow('wait aborted')
   })
+
+  it('an abort racing settlement in the same tick does not swallow the notice (review finding)', async () => {
+    const ctx = await harness()
+    const seen: TaskSnapshot[] = []
+    ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot))
+    const p = producer()
+    const id = ctx.tasks.start(p.spec)
+
+    const controller = new AbortController()
+    const wait = ctx.tasks.wait(id, 5_000, undefined, controller.signal)
+    // Same synchronous tick, settlement QUEUED first: the settle continuation
+    // will run before the rejected wait's `finally`, so only the SYNCHRONOUS
+    // un-count inside onAbort keeps it from reading a stale waiter count,
+    // marking the task reported, and suppressing the completion notice for a
+    // wait that then delivers nothing.
+    p.settle({ status: 'completed', detail: 'exit code: 0' })
+    controller.abort()
+    await expect(wait).rejects.toThrow('wait aborted')
+    expect(seen).toHaveLength(1)
+    expect(seen[0]).toMatchObject({ id, status: 'completed', reported: false })
+  })
+
+  it('an abort landing AFTER settlement still delivers the terminal snapshot it owes', async () => {
+    const ctx = await harness()
+    const controller = new AbortController()
+    const seen: TaskSnapshot[] = []
+    // The listener runs synchronously inside settle — aborting HERE lands the
+    // abort after settlement marked this waiter reported (notice suppressed)
+    // but before the wait's own resolve microtask. Rejecting now would leave
+    // the finished task both unreported and notice-suppressed, so the wait
+    // must resolve and deliver instead.
+    ctx.tasks.onTaskDone((snapshot) => {
+      seen.push(snapshot)
+      controller.abort()
+    })
+    const p = producer()
+    const id = ctx.tasks.start(p.spec)
+
+    const wait = ctx.tasks.wait(id, 5_000, undefined, controller.signal)
+    p.settle({ status: 'completed', detail: 'exit code: 0' })
+    await expect(wait).resolves.toMatchObject({ status: 'completed', reported: true })
+    expect(seen[0]).toMatchObject({ id, reported: true }) // suppression stays honest: the wait delivered
+  })
 })
 
 describe('TaskService owner isolation', () => {

From 35acd34fd96c5ebbfdd2bd0a263e9700dad62035 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Thu, 9 Jul 2026 23:37:51 +0800
Subject: [PATCH 08/48] fix(tools): enforce a disabled run_in_background at
 execution time (review findings)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

enableRunInBackground: false removed the parameter from the advertised
schema only — the arg validator deliberately allows undeclared keys, so
a caller (or a model that has seen the parameter elsewhere) could still
force run_in_background: true and start background work past the
deployment's opt-out, in both tool-bash and tool-subagent. Both
producers now refuse the forced key loud in execute(); tests pin the
refusal (and that nothing spawns) alongside the untouched foreground
path; the schema-omission-is-advertising rule is recorded in the
runtime RFC and both READMEs.
---
 ...026-06-20-generic-long-running-tool-runtime.md |  2 +-
 packages/bash/tool-bash/README.md                 |  2 +-
 packages/bash/tool-bash/src/index.ts              |  7 +++++++
 packages/bash/tool-bash/tests/tools.spec.ts       |  9 +++++++++
 packages/subagent/tool-subagent/README.md         |  2 +-
 packages/subagent/tool-subagent/src/index.ts      |  7 +++++++
 .../tool-subagent/tests/tool-subagent.spec.ts     | 15 +++++++++++++++
 7 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index 8393de41c2..39f2e70dae 100644
--- a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -100,7 +100,7 @@ Completion notices stay durable context, not a wake-up (`agent.inject()` appends
 
 ## Producer opt-in and schema exposure
 
-Whether a producer tool offers `run_in_background` is that producer's own defaulted config: `enableRunInBackground?: boolean` on `dsh-tool-bash` and on each `dsh-tool-subagent` instance (both default `true` — bash keeps its always-exposed behavior, and a deployment disables either per instance from cordis.yml, no code edit). A disabled producer omits the parameter from its schema entirely, so schema and capability can never disagree. `ctx.tasks` plays no part in schema shaping — it never rewrites or decorates a producer's tool schema (Kimi Code regex-rewrites its bash description when background is disabled; config-owns-the-schema makes that trick unnecessary) — it only provides runtime registration. The two halves compose fail-loud: the producer's config decides what the model sees, and a background call that still reaches `start()` without a control surface throws the load-this-package error. `start()` preflights every failable check (the fence, validation, the owner-cleanup attach) BEFORE invoking the producer's `run()` and commits atomically after — background work started without a collectable id is structurally impossible, not a producer rollback obligation.
+Whether a producer tool offers `run_in_background` is that producer's own defaulted config: `enableRunInBackground?: boolean` on `dsh-tool-bash` and on each `dsh-tool-subagent` instance (both default `true` — bash keeps its always-exposed behavior, and a deployment disables either per instance from cordis.yml, no code edit). A disabled producer omits the parameter from its schema entirely — and, because the arg validator deliberately allows undeclared keys, its `execute` ALSO refuses a forced `run_in_background: true` loud (the omission is advertising; the execution-time check is the enforcement). `ctx.tasks` plays no part in schema shaping — it never rewrites or decorates a producer's tool schema (Kimi Code regex-rewrites its bash description when background is disabled; config-owns-the-schema makes that trick unnecessary) — it only provides runtime registration. The two halves compose fail-loud: the producer's config decides what the model sees, and a background call that still reaches `start()` without a control surface throws the load-this-package error. `start()` preflights every failable check (the fence, validation, the owner-cleanup attach) BEFORE invoking the producer's `run()` and commits atomically after — background work started without a collectable id is structurally impossible, not a producer rollback obligation.
 
 ## The awaited owner-cleanup seam
 
diff --git a/packages/bash/tool-bash/README.md b/packages/bash/tool-bash/README.md
index 44bc2f1b35..eb59289dd0 100644
--- a/packages/bash/tool-bash/README.md
+++ b/packages/bash/tool-bash/README.md
@@ -10,7 +10,7 @@ The plugin also contributes the `tool:bash` prompt section (order 105) — the c
 
 | key | default | meaning |
 |---|---|---|
-| `enableRunInBackground` | `true` | Expose `run_in_background` in the schema. Disabled, the parameter is absent entirely (schema and capability never disagree) and the description says background execution is unavailable. |
+| `enableRunInBackground` | `true` | Expose `run_in_background` in the schema. Disabled, the parameter is absent entirely (schema and capability never disagree), the description says background execution is unavailable, and a caller that forces the key anyway is refused at execution time (the arg validator allows undeclared keys, so the schema omission alone is not enforcement). |
 
 ## The `bash` tool
 
diff --git a/packages/bash/tool-bash/src/index.ts b/packages/bash/tool-bash/src/index.ts
index 6bc0d334f3..98a5f6bfd4 100644
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -350,6 +350,13 @@ export function apply(ctx: Context, config: Config): void {
         ...args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {},
       }
       if (args.run_in_background === true) {
+        // The schema omission is advertising, not enforcement — the arg
+        // validator deliberately allows undeclared keys, so a caller (or a
+        // model that has seen the parameter elsewhere) can still send it.
+        // A disabled deployment must refuse at execution time, loud.
+        if (!backgroundEnabled) {
+          throw new Error('run_in_background is disabled for this deployment (enableRunInBackground: false)')
+        }
         // The generic runtime owns everything task-shaped; without it a task
         // id would be uncollectable — fail loud with the fix, not a dangle.
         const tasks = ctx.get('tasks')
diff --git a/packages/bash/tool-bash/tests/tools.spec.ts b/packages/bash/tool-bash/tests/tools.spec.ts
index 71edc21eb5..23e2dac95a 100644
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -408,6 +408,15 @@ describe('background execution through the task runtime', () => {
     // The registry-held definition agrees (schema and capability never disagree).
     const parameters = ctx.tools.get('bash')!.parameters as { properties: Record<string, unknown> }
     expect('run_in_background' in parameters.properties).toBe(false)
+
+    // Schema omission is advertising, not enforcement: the arg validator
+    // allows undeclared keys, so a forced run_in_background must be REFUSED
+    // at execution time (review finding) — while foreground still works.
+    const forced = await call(ctx, 'bash', { command: 'echo hi', description: 'test command', run_in_background: true })
+    expect(forced.isError).toBe(true)
+    expect(text(forced)).toContain('run_in_background is disabled for this deployment')
+    const foreground = await call(ctx, 'bash', { command: 'echo hi', description: 'test command' })
+    expect(foreground.isError).toBe(false)
   })
 })
 
diff --git a/packages/subagent/tool-subagent/README.md b/packages/subagent/tool-subagent/README.md
index 78c502bdd3..1e7d95a5a7 100644
--- a/packages/subagent/tool-subagent/README.md
+++ b/packages/subagent/tool-subagent/README.md
@@ -14,7 +14,7 @@ The tool description and the `prompt` parameter description are DERIVED from the
 |---|---|
 | `provider` (required) | The `ctx.subagents` provider name to start runs on (`spawn`, `fork`, `acp`, …). |
 | `toolName` | The model-facing tool name to register (default `subagent`). Set a distinct value per load when exposing multiple providers, e.g. `subagent` + `subagent_acp`. |
-| `enableRunInBackground` | Expose `run_in_background` in this instance's schema (default `true`). Disabled, the parameter is absent entirely — delegation through this instance stays strictly synchronous. |
+| `enableRunInBackground` | Expose `run_in_background` in this instance's schema (default `true`). Disabled, the parameter is absent entirely AND a caller that forces the key anyway is refused at execution time (the arg validator allows undeclared keys) — delegation through this instance stays strictly synchronous. |
 | `agentOptions` | Default per-child `{ model? }` applied to every spawned child. (No per-child persona: the deployment persona is a context-wide section every agent shares.) |
 
 ## Foreground lifecycle (synchronous collect)
diff --git a/packages/subagent/tool-subagent/src/index.ts b/packages/subagent/tool-subagent/src/index.ts
index b32d6e4d4c..fbe2b1cdc2 100644
--- a/packages/subagent/tool-subagent/src/index.ts
+++ b/packages/subagent/tool-subagent/src/index.ts
@@ -253,6 +253,13 @@ export function apply(ctx: Context, config: Config): void {
         }
 
         if (args.run_in_background === true) {
+          // The schema omission is advertising, not enforcement — the arg
+          // validator deliberately allows undeclared keys, so a caller (or a
+          // model that has seen the parameter elsewhere) can still send it.
+          // A disabled instance must refuse at execution time, loud.
+          if (!backgroundEnabled) {
+            throw new Error('run_in_background is disabled for this tool instance (enableRunInBackground: false)')
+          }
           // The generic runtime owns everything task-shaped; without it a task
           // id would be uncollectable — fail loud with the fix, not a dangle.
           const tasks = ctx.get('tasks')
diff --git a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
index 70e5e82c0b..89affcf163 100644
--- a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
+++ b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
@@ -81,6 +81,21 @@ describe('dsh-tool-subagent', () => {
     expect(schema!.description).not.toContain('task_output')
   })
 
+  it('refuses a forced run_in_background at execution time when the instance disables it (review finding)', async () => {
+    // Schema omission is advertising, not enforcement: the arg validator
+    // allows undeclared keys, so the opt-out must also hold in execute().
+    const ctx = await setup({ provider: 'mock', enableRunInBackground: false })
+    const parent = { id: AgentId('agent-sess-off'), inject: () => {}, session: { header: { version: 0, id: 'sess-off', createdAt: 0 } } } as unknown as Agent
+
+    const forced = await callSubagent(ctx, { description: 'd', prompt: 'p', run_in_background: true }, { agent: parent })
+    expect(forced.isError).toBe(true)
+    expect(text(forced)).toContain('run_in_background is disabled for this tool instance')
+    // The provider was never asked to start a child.
+    expect(ctx.subagents.getProvider('mock')).toBeDefined()
+    const foreground = await callSubagent(ctx, { description: 'd', prompt: 'p' }, { agent: parent })
+    expect(foreground.isError).toBe(false)
+  })
+
   it.each([
     { stopReason: 'aborted' as const, fragment: 'cancelled' },
     { stopReason: 'error' as const, fragment: 'failed' },

From 712d481bdf8c804d3df587ccf9aa066b01d80f71 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Fri, 10 Jul 2026 10:19:54 +0800
Subject: [PATCH 09/48] fix(bash): classify signal-terminated background
 processes

---
 packages/bash/bash-local/src/index.ts           | 10 ++++++----
 packages/bash/bash-local/tests/executor.spec.ts |  9 +++++++++
 packages/bash/tool-bash/tests/tools.spec.ts     |  8 ++++++++
 3 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/packages/bash/bash-local/src/index.ts b/packages/bash/bash-local/src/index.ts
index 1ad81d9014..61cb7cf617 100644
--- a/packages/bash/bash-local/src/index.ts
+++ b/packages/bash/bash-local/src/index.ts
@@ -175,10 +175,12 @@ export class LocalBashExecutor extends BashExecutor {
       exitCode: null,
       signal: null,
       done: running.done.then((outcome) => {
-        // Abort-killed processes report as killed, not completed. Background
-        // runs forward only the upstream signal (no timeout), so its aborted
-        // state is the authoritative "was this cancelled" signal.
-        if (proc.status === 'running') proc.status = spec.signal?.aborted === true ? 'killed' : 'completed'
+        // Caller-aborted and signal-terminated processes report as killed, not
+        // completed. The signal check also covers commands that terminate
+        // themselves without aborting the upstream signal.
+        if (proc.status === 'running') {
+          proc.status = spec.signal?.aborted === true || outcome.signal !== null ? 'killed' : 'completed'
+        }
         proc.exitCode = outcome.exitCode
         proc.signal = outcome.signal
         this.live.delete(proc)
diff --git a/packages/bash/bash-local/tests/executor.spec.ts b/packages/bash/bash-local/tests/executor.spec.ts
index fa9bb23f5f..e2d799f5ae 100644
--- a/packages/bash/bash-local/tests/executor.spec.ts
+++ b/packages/bash/bash-local/tests/executor.spec.ts
@@ -249,6 +249,15 @@ describe('LocalBashExecutor.start (background process handles)', () => {
     expect(proc.signal).toBe('SIGTERM')
   })
 
+  it('a self-signal exit settles the handle as killed, not completed', async () => {
+    const { bash } = await setup()
+    const proc = bash.start(bash.resolve({ command: 'kill -TERM $$' }))
+    await proc.done
+    expect(proc.status).toBe('killed')
+    expect(proc.exitCode).toBeNull()
+    expect(proc.signal).toBe('SIGTERM')
+  })
+
   it('a background spawn failure settles as killed with the error readable on stderr', async () => {
     const { bash } = await setup()
     const proc = bash.start(bash.resolve({ command: 'true', workdir: '/nonexistent-dsh' }))
diff --git a/packages/bash/tool-bash/tests/tools.spec.ts b/packages/bash/tool-bash/tests/tools.spec.ts
index 23e2dac95a..30d71e1d61 100644
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -288,6 +288,14 @@ describe('background execution through the task runtime', () => {
     expect(text(final)).toContain('[status: killed, signal: SIGTERM]')
   })
 
+  it('a self-signal background exit is reported as killed through the REAL task_output tool', async () => {
+    const ctx = await setupWithTasks()
+    await call(ctx, 'bash', { command: 'kill -TERM $$', description: 'test command', run_in_background: true })
+
+    const final = await call(ctx, 'task_output', { task_id: 'bash-1', wait: true })
+    expect(text(final)).toContain('[status: killed, signal: SIGTERM]')
+  })
+
   it('a background task started by an agent is registered with that agent as owner', async () => {
     // The fence SEMANTICS are pinned in dsh-tasks; this only pins that
     // tool-bash forwards exec.agent as the registration's owner.

From b23da625bb36a658e25f4976aa0d0d5f01ff2490 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 11 Jul 2026 23:12:45 +0800
Subject: [PATCH 10/48] docs: trim package and example indexes to budgets

---
 examples/AGENTS.md | 4 ++--
 packages/README.md | 8 ++++----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/examples/AGENTS.md b/examples/AGENTS.md
index d54104a189..6317d0e92a 100644
--- a/examples/AGENTS.md
+++ b/examples/AGENTS.md
@@ -1,8 +1,8 @@
 # AGENTS.md — Examples
 
-Runnable demos showing how the harness is wired. **Examples are NOT workspaces** — each `examples/*/package.json` is a private, dependency-free stub, never built. They are booted as unbuilt `tsx` subprocesses via the cordis Loader reading a `cordis.yml`; the `@deepseek-ai/dsh-*` plugin names in those YAML files resolve through the root `tsconfig.json` `paths` map, not through `node_modules`.
+Runnable harness compositions. **Examples are NOT workspaces**: their private `package.json` files are dependency-free stubs, and the cordis Loader boots each `cordis.yml` unbuilt through `tsx` plus the root tsconfig paths.
 
-Because examples are not under the `packages/*/src` coverage gate, an example that grows real, reusable *logic* should extract it into a `packages/` package (where it gets the per-file 100% gate and a README). Keep only example-specific glue here: the `cordis.yml` wiring, demo-only mocks/teaching artifacts, and the e2e/snapshot scenarios. There is no `start.ts` — the boot glue lives in each app package's `bin` (`@deepseek-ai/dsh-stdio-agent`, `@deepseek-ai/dsh-acp-agent`), which the `demo:*` scripts invoke against the leaf `cordis.yml`.
+Extract reusable logic into `packages/`, where per-file coverage and README gates apply. Examples keep only `cordis.yml` wiring, demo artifacts, and e2e/snapshot scenarios; app package bins own boot glue.
 
 ## Every example ships e2e smokes (keyless + with-key)
 
diff --git a/packages/README.md b/packages/README.md
index 34a86d12fd..ed714671ce 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -1,10 +1,10 @@
 # Packages
 
-Harness packages use the `@deepseek-ai/dsh-*` scope. Each is a Cordis plugin: a default `Service` subclass or functional plugin declaring ctx keys/events through declaration merging and contributing through `ctx.effect()`, `ctx.on()`, or `ctx.waterfall()`. Authoring conventions: [AGENTS.md](AGENTS.md) and root [AGENTS.md](../AGENTS.md) § Conventions.
+Harness packages use the `@deepseek-ai/dsh-*` scope. Each is a Cordis service or functional plugin contributing through the framework's effect/event seams. Authoring conventions: [AGENTS.md](AGENTS.md) and root [AGENTS.md](../AGENTS.md).
 
 ## Hierarchy
 
-Packages are grouped by modular role at `packages/<group>/<pkg>/`. The group directory is a pure container (no `package.json`); the package name stays `@deepseek-ai/dsh-<pkg>` regardless of group. **Each group README is the canonical per-package map** — package roles, ctx keys, and the product-vs-support split live there, next to the code.
+Packages live at `packages/<group>/<pkg>/`; groups are containers, while names remain `@deepseek-ai/dsh-<pkg>`. **Each group README is the canonical package/ctx-key map.**
 
 | Group | Role | Release expectation |
 |---|---|---|
@@ -30,12 +30,12 @@ Packages are grouped by modular role at `packages/<group>/<pkg>/`. The group dir
 | [`support/`](support/README.md) | Dev/test/example infrastructure (invariants, replay adapter, subagent mock) | Support — lower compatibility expectations |
 | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (the `Branded<B>` primitive) | Support — small, stable, harness-dep-free |
 
-The split is the point: a package's group says whether it is part of the product API or support/test/example infrastructure, so release and removal decisions do not treat every package as an equal public contract. New packages join an existing group; adding a new top-level group is a deliberate act (extend the group READMEs and this table).
+Groups distinguish product API from support infrastructure. New packages join an existing group; a new group updates its README and this table.
 
 ## Dependencies
 
 The inter-package dependency graph is generated: [docs/module-graph.md](../docs/module-graph.md) (`pnpm run gen-module-graph`, freshness-gated in CI).
 
-The rule it must obey: **extension plugins depend on interfaces, never on the concrete loop.** `dsh-agent-loop` is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced. The sanctioned exception is a **composition/bundle** package like `dsh-agent-core`, whose whole job is to assemble the concrete spine: it depends on `dsh-agent-loop` (and the other concrete spine plugins) on purpose. The rule constrains plugins that EXTEND the system, not the bundle that COMPOSES it. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — see [capability seams](../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)).
+**Extension plugins depend on interfaces, never the concrete loop.** Composition bundles such as `dsh-agent-core` intentionally assemble that loop. Swappable capabilities split into interface, implementation, and consumer packages; see [capability seams](../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md).
 
 Each package has its own `README.md` with purpose, service API, events, extension points, and deliberate non-goals (TODOs).

From e19043881a115a2bb65b9339d2adaec5086fe991 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sat, 11 Jul 2026 23:27:20 +0800
Subject: [PATCH 11/48] docs(agent-core): restore composed capability
 description

---
 packages/core/agent-core/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/core/agent-core/package.json b/packages/core/agent-core/package.json
index 469629e8c1..e08d7f4cf3 100644
--- a/packages/core/agent-core/package.json
+++ b/packages/core/agent-core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-agent-core",
-  "description": "The providerless/executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + agents + invariants + tool-bash + agent-loop)",
+  "description": "The default executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + skills + agents + tasks + invariants + tool-bash + tool-skill + tool-tasks + agent-loop)",
   "version": "0.0.1",
   "private": true,
   "type": "module",

From bd9abba638c81fa4ebecb5dc9d12ab975c429da0 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sun, 12 Jul 2026 16:00:56 +0800
Subject: [PATCH 12/48] fix(tasks): harden lifecycle and bundle config

---
 docs/config-catalog.md                        | 21 +++-
 docs/cordis-catalog/services.md               |  2 +-
 docs/core-data-structures/tasks.md            |  6 +-
 ...06-20-generic-long-running-tool-runtime.md | 14 +--
 packages/core/agent-core/README.md            |  5 +-
 packages/core/agent-core/src/index.ts         | 26 ++++-
 .../core/agent-core/tests/agent-core.spec.ts  | 34 ++++++-
 packages/tasks/tasks/README.md                |  7 +-
 packages/tasks/tasks/src/index.ts             | 79 ++++++++++-----
 packages/tasks/tasks/src/types.ts             |  4 +-
 packages/tasks/tasks/tests/tasks.spec.ts      | 99 ++++++++++++++++++-
 packages/ui/acp-agent/README.md               |  4 +
 packages/ui/acp-agent/src/index.ts            |  8 ++
 packages/ui/acp-agent/tests/acp-agent.spec.ts | 16 ++-
 packages/ui/stdio-agent/README.md             |  4 +
 packages/ui/stdio-agent/src/index.ts          |  8 ++
 .../ui/stdio-agent/tests/stdio-agent.spec.ts  | 16 ++-
 17 files changed, 295 insertions(+), 58 deletions(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 73e064426a..5b8a925914 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -58,6 +58,10 @@ export interface Config {
   persistenceRoot?: string
   /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
   skills?: agentCore.SkillConfig
+  /** Model-facing bash tool config forwarded through agent-core. */
+  toolBash?: NonNullable<agentCore.Config['toolBash']>
+  /** Generic background-task control-tool config forwarded through agent-core. */
+  toolTasks?: NonNullable<agentCore.Config['toolTasks']>
 }
 ```
 
@@ -73,7 +77,10 @@ Source: [`packages/ui/acp-agent/src/index.ts:52`](../packages/ui/acp-agent/src/i
  * `agents` to the agent loop (an app that pre-creates no agents, like the ACP
  * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
  * plugin (the deployment's persona section and the explicit model-facing tool
- * order), the `tools` object to the tool registry (its presentation `mode`).
+ * order), the `tools` object to the tool registry (its presentation `mode`),
+ * and `toolBash`/`toolTasks` to the two model-facing tool plugins this bundle
+ * owns. Producer opt-in stays producer-local: `toolBash` configures bash only;
+ * future background-capable tools remain independently composed plugins.
  * Every field is optional INPUT here because each owner's schema
  * supplies the default (`[]` / `''` / absent — lexicographic / `native`); the
  * schema is the INTERSECTION of the owners' own schemas (the registry's
@@ -91,6 +98,10 @@ export interface Config {
   tools?: ToolsConfig
   /** Skill registry, local provider, and model-facing consumer config. */
   skills?: SkillConfig
+  /** Model-facing bash tool config, including this producer's background opt-in. */
+  toolBash?: toolBash.Config
+  /** Generic background-task control-tool wait bounds. */
+  toolTasks?: toolTasks.Config
 }
 
 /** Skill bundle config forwarded to the registry, local provider, and model-facing consumer. */
@@ -104,9 +115,9 @@ export interface SkillConfig {
 }
 ```
 
-Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`SkillLocal`](../packages/skill/skill-local/src/index.ts) · [`SkillRegistryConfig`](#deepseek-aidsh-skill) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`toolSkill`](../packages/skill/tool-skill/src/index.ts)
+Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`SkillLocal`](../packages/skill/skill-local/src/index.ts) · [`SkillRegistryConfig`](#deepseek-aidsh-skill) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`toolBash`](../packages/bash/tool-bash/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`toolSkill`](../packages/skill/tool-skill/src/index.ts) · [`toolTasks`](../packages/tasks/tool-tasks/src/index.ts)
 
-Source: [`packages/core/agent-core/src/index.ts:87`](../packages/core/agent-core/src/index.ts)
+Source: [`packages/core/agent-core/src/index.ts:90`](../packages/core/agent-core/src/index.ts)
 
 ## `@deepseek-ai/dsh-agent-loop`
 
@@ -631,6 +642,10 @@ export interface Config {
   welcome?: string
   /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
   skills?: agentCore.SkillConfig
+  /** Model-facing bash tool config forwarded through agent-core. */
+  toolBash?: NonNullable<agentCore.Config['toolBash']>
+  /** Generic background-task control-tool config forwarded through agent-core. */
+  toolTasks?: NonNullable<agentCore.Config['toolTasks']>
   /**
    * If set, the `main` agent RESUMES this persisted session id instead of
    * starting fresh. Sourced from an env var in the leaf `cordis.yml`
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index cea4ec626f..0178a95a08 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -271,7 +271,7 @@ attachSurface(name: string): () => void
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/tasks/tasks/src/index.ts:95`](../../packages/tasks/tasks/src/index.ts)
+Source: [`packages/tasks/tasks/src/index.ts:96`](../../packages/tasks/tasks/src/index.ts)
 
 ## `ctx.tools` — `ToolRegistry`
 
diff --git a/docs/core-data-structures/tasks.md b/docs/core-data-structures/tasks.md
index 10e1d7f6d2..b0cab68522 100644
--- a/docs/core-data-structures/tasks.md
+++ b/docs/core-data-structures/tasks.md
@@ -52,7 +52,9 @@ interface TaskHooks {
    * released the task's resources (process exited, child agent disposed) —
    * not merely when the work finished. Must never reject; a rejection is
    * contained as a `failed` outcome and logged as a producer contract
-   * violation.
+   * violation. If `cancel` throws during teardown, the runtime may force-fail
+   * only its registry record to avoid deadlock because this promise may never
+   * settle; that fallback explicitly does not claim work quiescence.
    */
   done: Promise<TaskOutcome>
   /**
@@ -135,4 +137,4 @@ interface TaskRead {
 
 ## The service
 
-`TaskService` (`ctx.tasks` — [`packages/tasks/tasks/src/index.ts`](../../packages/tasks/tasks/src/index.ts)): `start` (preflight → producer `run()` → atomic commit, fenced by `attachSurface`), non-consuming `get`/`list` (caller-scoped — owned-by-caller plus unowned only), `read` (consuming for stream kinds), `kill` (producer `cancel` first; a throw leaves the task untouched), `wait` (bounded, abort cancels the wait only), and `onTaskDone` (a `TaskDoneListener` per settlement, effect-scoped, contained). Every read/kill/wait/get compares the task's owner session with the caller's and rejects a foreign one. Owned tasks are cancelled and awaited when their owning agent disposes (the `ctx.agents.onCleanup` seam); the model-facing surface over all of this is [dsh-tool-tasks](../../packages/tasks/tool-tasks/README.md).
+`TaskService` (`ctx.tasks` — [`packages/tasks/tasks/src/index.ts`](../../packages/tasks/tasks/src/index.ts)): `start` (preflight → producer `run()` → atomic commit, fenced by `attachSurface`), non-consuming `get`/`list` (caller-scoped — owned-by-caller plus unowned only), `read` (consuming for stream kinds), `kill` (producer `cancel` first; a throw leaves the task untouched), `wait` (bounded, abort cancels the wait only), and `onTaskDone` (a `TaskDoneListener` per terminal record, effect-scoped, contained). Every read/kill/wait/get compares the task's owner session with the caller's and rejects a foreign one. Owned tasks are cancelled and normally awaited to producer quiescence when their owning agent disposes (the `ctx.agents.onCleanup` seam); a teardown cancel that throws force-fails only the registry record and reports that the underlying work may be orphaned, preventing disposal deadlock without claiming quiescence. The model-facing surface over all of this is [dsh-tool-tasks](../../packages/tasks/tool-tasks/README.md).
diff --git a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index 39f2e70dae..137f6cd6ae 100644
--- a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -59,9 +59,9 @@ interface TaskOutcome {
 
 The task status vocabulary is generic and closed: `running`, `stopping` (cancel requested, not yet settled), and the three terminal values above. Kind-specific meaning rides in `detail`, so the registry never learns process or agent semantics — the method presence (`readOutput`) is the capability, mirroring `SubagentRun.sendMessage`.
 
-The registry attaches ONE continuation to `done`: record the terminal snapshot, then notify task-done listeners with per-listener containment (the guarantee the bash seam's `notifyTaskDone` used to give its own listener set). `done` settling at quiescence — not merely at completion — is what makes owner cleanup and service disposal awaitable without a second completion surface; this resolves the old seam's duplication of a per-task `done` promise AND a global `onTaskDone` registry by making the promise the producer contract and the listener registry the consumer surface.
+The registry attaches ONE continuation to `done`: record the terminal snapshot, then notify task-done listeners with per-listener containment (the guarantee the bash seam's `notifyTaskDone` used to give its own listener set). `done` settling at quiescence — not merely at completion — makes ordinary owner cleanup and service disposal awaitable without a second completion surface. Settlement is first-wins because teardown has one explicit failure fallback: if producer `cancel` throws before the request is delivered, `done` may never settle, so the registry force-fails the record with a possible-orphan detail instead of deadlocking disposal; a late producer outcome cannot overwrite that diagnosis or notify twice. This fallback terminates bookkeeping, not necessarily the underlying work.
 
-Registrations are NOT effect-scoped to the registering fiber: a task belongs to its owning agent and its producing backend, not to the tool plugin whose call started it, so an HMR reload of `dsh-tool-bash` or `dsh-tool-tasks` never orphans or kills a running task (the same argument that used to keep bash ownership in the executor). The registry's own disposal cancels every live task and awaits settlement — no orphans survive `fiber.dispose()`.
+Registrations are NOT effect-scoped to the registering fiber: a task belongs to its owning agent and its producing backend, not to the tool plugin whose call started it, so an HMR reload of `dsh-tool-bash` or `dsh-tool-tasks` never orphans or kills a running task (the same argument that used to keep bash ownership in the executor). The registry's own disposal cancels every live task and awaits contract-compliant producers to quiescence. A teardown cancel that throws force-fails the terminal record and logs that work may be orphaned; this prevents a broken producer from deadlocking the fiber without pretending the work stopped.
 
 ## Authorization and the service surface
 
@@ -100,16 +100,16 @@ Completion notices stay durable context, not a wake-up (`agent.inject()` appends
 
 ## Producer opt-in and schema exposure
 
-Whether a producer tool offers `run_in_background` is that producer's own defaulted config: `enableRunInBackground?: boolean` on `dsh-tool-bash` and on each `dsh-tool-subagent` instance (both default `true` — bash keeps its always-exposed behavior, and a deployment disables either per instance from cordis.yml, no code edit). A disabled producer omits the parameter from its schema entirely — and, because the arg validator deliberately allows undeclared keys, its `execute` ALSO refuses a forced `run_in_background: true` loud (the omission is advertising; the execution-time check is the enforcement). `ctx.tasks` plays no part in schema shaping — it never rewrites or decorates a producer's tool schema (Kimi Code regex-rewrites its bash description when background is disabled; config-owns-the-schema makes that trick unnecessary) — it only provides runtime registration. The two halves compose fail-loud: the producer's config decides what the model sees, and a background call that still reaches `start()` without a control surface throws the load-this-package error. `start()` preflights every failable check (the fence, validation, the owner-cleanup attach) BEFORE invoking the producer's `run()` and commits atomically after — background work started without a collectable id is structurally impossible, not a producer rollback obligation.
+Whether a producer tool offers `run_in_background` is that producer's own defaulted config: `enableRunInBackground?: boolean` on `dsh-tool-bash` and on each `dsh-tool-subagent` instance (both default `true` — bash keeps its always-exposed behavior, and a deployment disables either per instance from cordis.yml, no code edit). A bundle forwards the configs of the child plugins it owns: `dsh-agent-core` exposes `toolBash` for its built-in producer and `toolTasks` for the generic control surface, while independently composed producers such as subagent instances receive config directly. This forwarding is config reachability, not producer registration: future background-capable tools do not become `agent-core` fields unless that bundle also chooses to own them. A disabled producer omits the parameter from its schema entirely — and, because the arg validator deliberately allows undeclared keys, its `execute` ALSO refuses a forced `run_in_background: true` loud (the omission is advertising; the execution-time check is the enforcement). `ctx.tasks` plays no part in schema shaping — it never rewrites or decorates a producer's tool schema (Kimi Code regex-rewrites its bash description when background is disabled; config-owns-the-schema makes that trick unnecessary) — it only provides runtime registration. The two halves compose fail-loud: the producer's config decides what the model sees, and a background call that still reaches `start()` without a control surface throws the load-this-package error. `start()` preflights every failable check (the fence, validation, the owner-cleanup attach) BEFORE invoking the producer's `run()` and commits atomically after — background work started without a collectable id is structurally impossible, not a producer rollback obligation.
 
 ## The awaited owner-cleanup seam
 
-A background task must not outlive its owner: the subagent case leaks live child agents/sessions otherwise, and `agent/disposed` is emitted synchronously inside the disposal chain without awaiting listener work, so an emit listener cannot promise quiescence (the analysis in [the feature RFC](../feature/2026-07-08-background-subagent-tasks.md)). The runtime therefore needs a seam the owning agent's disposal chain actually awaits, and that seam belongs to `dsh-agent`, where every lifecycle consumer can reach it:
+A contract-compliant background task must not outlive its owner: the subagent case leaks live child agents/sessions otherwise, and `agent/disposed` is emitted synchronously inside the disposal chain without awaiting listener work, so an emit listener cannot promise quiescence (the analysis in [the feature RFC](../feature/2026-07-08-background-subagent-tasks.md)). The runtime therefore needs a seam the owning agent's disposal chain actually awaits, and that seam belongs to `dsh-agent`, where every lifecycle consumer can reach it:
 
 - `AgentRegistry.onCleanup(agentId, cleanup: () => Promise<void>): () => void` — a per-agent cleanup registry (registrations are effects; the disposer unregisters).
 - The loop's composite disposal chain carries one link for it: after stop-and-drain and before unregister, `await ctx.agents.drainCleanups(agent.id)` runs every registered cleanup with per-cleanup containment (a throwing cleanup is logged and never starves later cleanups or the rest of the chain). This is a documented `dsh-agent-loop` change; running cleanups is part of the `AgentFactory` dispose contract so a replacement loop honors it too.
 
-`dsh-tasks` consumes the seam: the first task registered for an owner attaches one cleanup that cancels the owner's still-live tasks, awaits each task's `done` (quiescence), and drops the owner's snapshots. `AgentHandle.dispose()` thus resolves only after the owner's background children are actually gone, and the guarantee composes transitively: a background subagent that started background tasks of its own drains them when its child agent disposes inside the parent task's settlement path (the cascade OpenCode implements with explicit parent-chain walking falls out of the seam here). This is a deliberate behavior change for bash — a background bash task used to outlive its owning agent until service disposal — adopted for uniformity: an ownerless task is the sanctioned way to outlive an agent, and a future durable-job RFC is the way to outlive the runtime.
+`dsh-tasks` consumes the seam: the first task registered for an owner attaches one cleanup that cancels the owner's still-live tasks, normally awaits each task's `done` (quiescence), and drops the owner's snapshots. For contract-compliant producers, `AgentHandle.dispose()` therefore resolves only after the owner's background children are actually gone, and the guarantee composes transitively: a background subagent that started background tasks of its own drains them when its child agent disposes inside the parent task's settlement path (the cascade OpenCode implements with explicit parent-chain walking falls out of the seam here). A producer whose teardown cancel throws is the explicit degradation: its record settles `failed` with a possible-orphan detail and cleanup continues. An ownerless task is the sanctioned way for healthy work to outlive an agent, and a future durable-job RFC is the way to outlive the runtime.
 
 ## Bash migration
 
@@ -169,7 +169,7 @@ Everything model-visible already lands in the log: starts and reads are tool cal
 
 ## Testing
 
-Unit coverage pins the registry lifecycle (register/read/kill/wait/list, owner isolation including no-agent callers, stream-vs-final read semantics, listener containment, notice suppression after an explicit kill or terminal read/wait, the `attachSurface` fence, start atomicity — a failed preflight mutates nothing and burns no counter; a failed producer `cancel` leaves the task untouched — disposal quiescence, per-kind id counters), the `onCleanup` drain ordering + containment (including mid-drain registration), both producers' start mapping plus the structural no-orphan guarantee (a failed preflight means the producer's `run()` — the spawn — was never invoked), and unchanged foreground bash/subagent behavior. Snapshot coverage pins the task tool schemas and the prompt section through the pinned-header fixture.
+Unit coverage pins the registry lifecycle (register/read/kill/wait/list, owner isolation including no-agent callers, stream-vs-final read semantics, listener containment, notice suppression after an explicit kill or terminal read/wait, the `attachSurface` fence, start atomicity — a failed preflight mutates nothing and burns no counter; a model-facing failed `cancel` leaves the task untouched; a teardown failed `cancel` force-fails the record once without awaiting `done` — ordinary disposal quiescence, per-kind id counters), the `onCleanup` drain ordering + containment (including mid-drain registration and effect self-release), both producers' start mapping plus the structural no-uncollectable-work guarantee (a failed preflight means the producer's `run()` — the spawn — was never invoked), and unchanged foreground bash/subagent behavior. Snapshot coverage pins the task tool schemas and the prompt section through the pinned-header fixture.
 
 ## Consequences
 
@@ -177,4 +177,6 @@ One background-task contract exists instead of a per-capability clone family: a
 
 Owner-scoped cleanup changed bash semantics: a task that previously outlived its agent now dies with it. Deployments that relied on fire-and-forget background commands start them unowned (a non-agent caller) or accept the new lifecycle; the uniformity was judged worth the change, and the durable-job direction remains open for real survival requirements.
 
+Teardown trusts the producer contract that a successful `cancel` leads to `done` settling at quiescence. An explicit cancel throw is detectable and force-fails the record with a possible-orphan warning so disposal cannot deadlock; a cancel that returns but silently fails is indistinguishable from a slow stop and can still stall teardown. Covering that residual requires a bounded lifetime or a separate forced-disposal contract, both outside this runtime shape.
+
 `wait` is the first blocking tool call whose duration is model-controlled; the config cap bounds it, but a model that serializes on `wait` loses the parallelism the feature exists for — prompt guidance mitigates, and a future continuation-policy guard can enforce. Recording live background-flow snapshot scenarios (a polled and killed background command, a completion-notice turn) and a with-key e2e background lifecycle require a `DEEPSEEK_API_KEY` re-record and remain named follow-up work. The runtime deliberately defers durable/cross-restart tasks, non-consuming observation cursors, and foreground→background promotion (see Alternatives).
diff --git a/packages/core/agent-core/README.md b/packages/core/agent-core/README.md
index 351ae1fdf4..44909ed19c 100644
--- a/packages/core/agent-core/README.md
+++ b/packages/core/agent-core/README.md
@@ -41,11 +41,12 @@ This is the [interface/implementation/consumer seam](../../../docs/rfc/implement
 
 ```ts
 import type { Config } from '@deepseek-ai/dsh-agent-core'
-// { agents?, persona?, toolOrder?, tools?, skills? } — the schema intersects the owner schemas,
+// { agents?, persona?, toolOrder?, tools?, skills?, toolBash?, toolTasks? }
+// The schema intersects the owner schemas,
 // 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`) — `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; and `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer. 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` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. `toolBash.enableRunInBackground` controls only the bash producer, while `toolTasks` controls generic `task_output` wait bounds; independently loaded producers keep their own config. 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
 
diff --git a/packages/core/agent-core/src/index.ts b/packages/core/agent-core/src/index.ts
index 64e1eaa2f8..4b3a41e98e 100644
--- a/packages/core/agent-core/src/index.ts
+++ b/packages/core/agent-core/src/index.ts
@@ -77,7 +77,10 @@ export interface SkillConfig {
  * `agents` to the agent loop (an app that pre-creates no agents, like the ACP
  * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
  * plugin (the deployment's persona section and the explicit model-facing tool
- * order), the `tools` object to the tool registry (its presentation `mode`).
+ * order), the `tools` object to the tool registry (its presentation `mode`),
+ * and `toolBash`/`toolTasks` to the two model-facing tool plugins this bundle
+ * owns. Producer opt-in stays producer-local: `toolBash` configures bash only;
+ * future background-capable tools remain independently composed plugins.
  * Every field is optional INPUT here because each owner's schema
  * supplies the default (`[]` / `''` / absent — lexicographic / `native`); the
  * schema is the INTERSECTION of the owners' own schemas (the registry's
@@ -95,6 +98,10 @@ export interface Config {
   tools?: ToolsConfig
   /** Skill registry, local provider, and model-facing consumer config. */
   skills?: SkillConfig
+  /** Model-facing bash tool config, including this producer's background opt-in. */
+  toolBash?: toolBash.Config
+  /** Generic background-task control-tool wait bounds. */
+  toolTasks?: toolTasks.Config
 }
 
 /** The skill config schema exported for app packages that forward `skills`. */
@@ -104,11 +111,22 @@ export const SkillConfigSchema: z<SkillConfig> = z.object({
   tool: toolSkill.Config,
 })
 
+/** The bash-tool config schema exported for app packages that forward `toolBash`. */
+export const ToolBashConfigSchema: z<toolBash.Config> = toolBash.Config
+
+/** The task-control-tool config schema exported for app packages that forward `toolTasks`. */
+export const ToolTasksConfigSchema: z<toolTasks.Config> = toolTasks.Config
+
 /** Intersect the owners' schemas so validation + defaulting stay identical. */
 export const Config = z.intersect([
   AgentLoop.Config,
   SystemPrompt.Config,
-  z.object({ tools: ToolRegistry.Config, skills: SkillConfigSchema }),
+  z.object({
+    tools: ToolRegistry.Config,
+    skills: SkillConfigSchema,
+    toolBash: ToolBashConfigSchema,
+    toolTasks: ToolTasksConfigSchema,
+  }),
 ]) as unknown as z<Config>
 
 /**
@@ -140,8 +158,8 @@ export function apply(ctx: Context, config: Config): void {
   ctx.plugin(AgentRegistry)
   ctx.plugin(TaskService)
   ctx.plugin(invariants)
-  ctx.plugin(toolBash)
+  ctx.plugin(toolBash, config.toolBash ?? {})
   ctx.plugin(toolSkill, config.skills?.tool ?? {})
-  ctx.plugin(toolTasks)
+  ctx.plugin(toolTasks, config.toolTasks ?? {})
   ctx.plugin(AgentLoop, { agents: config.agents ?? [] })
 }
diff --git a/packages/core/agent-core/tests/agent-core.spec.ts b/packages/core/agent-core/tests/agent-core.spec.ts
index 1803a5e3dd..e9bc584418 100644
--- a/packages/core/agent-core/tests/agent-core.spec.ts
+++ b/packages/core/agent-core/tests/agent-core.spec.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { mkdir, mkdtemp, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
@@ -7,7 +7,7 @@ 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'
-import type { Message } from '@deepseek-ai/dsh-llm'
+import { CallId, type Message } from '@deepseek-ai/dsh-llm'
 
 async function composePrefix(ctx: Context, cwd: string): Promise<Message[]> {
   const empty: Message[] = []
@@ -27,12 +27,13 @@ async function composePrefix(ctx: Context, cwd: string): Promise<Message[]> {
  * Loader-path guard (export shape, `unwrapExports`) is the app packages' keyless
  * bin smokes; here we assert the composition + config forwarding.
  */
-async function mount(config?: agentCore.Config): Promise<Context> {
+async function mount(config?: agentCore.Config, withBash = false): Promise<Context> {
   const oldDshHome = process.env.DSH_HOME
   const oldAgentsHome = process.env.DSH_AGENTS_HOME
   process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-home-'))
   process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-agents-'))
   const ctx = new Context()
+  if (withBash) ctx.provide('bash', { sandboxMode: undefined })
   try {
     await ctx.plugin(agentCore, config)
     // The bundle mounts its children inside apply() (not awaited there); let their
@@ -153,6 +154,33 @@ describe('dsh-agent-core bundle', () => {
     await ctx.fiber.dispose()
   })
 
+  it('forwards its bundled tool configs to tool-bash and tool-tasks', async () => {
+    const ctx = await mount({
+      toolBash: { enableRunInBackground: false },
+      toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
+    }, true)
+
+    const bash = ctx.tools.schemas().find(tool => tool.name === 'bash')
+    expect(bash).toBeDefined()
+    expect(Object.keys((bash!.parameters as { properties: Record<string, unknown> }).properties))
+      .not.toContain('run_in_background')
+
+    const id = ctx.tasks.start({
+      kind: 'probe',
+      label: 'config forwarding probe',
+      run: () => ({ cancel: () => {}, done: Promise.resolve({ status: 'completed' }) }),
+    })
+    const wait = vi.spyOn(ctx.tasks, 'wait')
+    await ctx.tools.execute({
+      callId: CallId('task-config-forwarding'),
+      name: 'task_output',
+      arguments: { task_id: id, wait: true },
+    })
+    expect(wait).toHaveBeenCalledWith(id, 7, undefined, undefined)
+
+    await ctx.fiber.dispose()
+  })
+
   it('uses the default skill config when apply is called directly without skills', async () => {
     await withIsolatedSkillHomes(async () => {
       const ctx = new Context()
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index df2f21ee91..3cfab12f45 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -9,7 +9,7 @@ The background task registry (`ctx.tasks`): a runtime-global, CONCRETE service (
 - `read(id, caller?): TaskRead` — stream kinds consume the per-task cursor (v1's single intended reader is the owning model — a non-consuming multi-reader surface would be a cursor/snapshot API extension, not a `read` change); final kinds read the terminal output idempotently.
 - `kill(id, caller?, reason?)` — `'requested'` (live task: producer `cancel` runs first — a throw fails the kill loud and leaves the task untouched — then `stopping`) or `'already-terminal'`. Every successful kill marks the task `reported` (the killer saw the end → completion notice suppressed).
 - `wait(id, timeoutMs, caller?, signal?)` — resolves with the terminal snapshot (marked `reported`), or the live snapshot at timeout; an aborted signal rejects the WAIT only — unless the task already settled, in which case the wait still resolves and delivers the terminal snapshot (settlement suppressed the completion notice on this waiter's behalf, so rejecting would leave the finish both unreported and un-noticed). Timing is a [`dsh-timeout`](../../util/timeout/README.md) `deadline()` scoped to the `TASK_WAIT_TIMEOUT` code, so a nested foreign deadline never misreads as a wait timeout.
-- `onTaskDone(listener)` — exactly once per task with the terminal snapshot; effect-scoped, per-listener containment, silent after service disposal.
+- `onTaskDone(listener)` — exactly once per terminal task record; effect-scoped, per-listener containment, silent after service disposal.
 - `attachSurface(name)` — declares a control surface exists (the model tools, or a deployment's custom surface); effect-scoped.
 
 Every read/kill/wait/get compares the task's owner session (`owner.session.header.id`) with the caller's and rejects a foreign one — ids are predictable (`bash-1`), so the fence, not id secrecy, is the isolation boundary.
@@ -17,8 +17,9 @@ Every read/kill/wait/get compares the task's owner session (`owner.session.heade
 ## Lifecycle
 
 - Registrations are NOT effect-scoped to the registering fiber: tasks belong to their owning agent + producing backend, so producer/surface HMR reloads never touch them.
-- An owned task attaches (once per owner) an awaited cleanup via `ctx.agents.onCleanup`: on the owner's disposal the registry cancels its live tasks, awaits each `done`, and drops the snapshots — `AgentHandle.dispose()` resolves only after quiescence.
-- Service disposal closes the listener registry first (late teardown kills stay silent), cancels every live task with containment, and awaits settlement.
+- An owned task attaches (once per owner) an awaited cleanup via `ctx.agents.onCleanup`: on owner disposal the registry cancels live tasks, awaits contract-compliant producers to quiescence, and drops their snapshots. If a teardown cancel throws, it force-fails the record and logs that the underlying work may be orphaned rather than deadlocking `AgentHandle.dispose()`.
+- Service disposal closes the listener registry first (late teardown settlements stay silent), then applies the same cancellation rule to every live task and awaits terminal records.
+- A producer whose `cancel` returns but never causes `done` to settle remains indistinguishable from a slow stop and can stall teardown; solving that residual requires an explicit bounded-lifetime or forced-disposal design.
 
 ## Non-goals (v1)
 
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index 9601e296b3..244211fa4f 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -23,8 +23,9 @@
  * belongs to its owning agent and producing backend, not to the tool plugin
  * whose call started it, so an HMR reload of a producer or of the control
  * surface never orphans or kills a running task. The registry's own disposal
- * cancels every live task and awaits settlement — no orphans survive
- * `fiber.dispose()`.
+ * cancels every live task and awaits contract-compliant producers to
+ * quiescence. If a teardown cancel throws, the registry force-fails its record
+ * to avoid deadlock and logs that the underlying work may be orphaned.
  *
  * @module @deepseek-ai/dsh-tasks
  */
@@ -77,7 +78,7 @@ interface TrackedTask {
   reported: boolean
   /** Resolves once the terminal snapshot is recorded and listeners notified. */
   settled: Promise<void>
-  /** Resolver for {@link settled} (called exactly once, by {@link TaskService.settle}). */
+  /** Resolver for {@link settled} (called by the first effective {@link TaskService.settle}). */
   markSettled: () => void
   /** Live {@link TaskService.wait} calls — a settlement with waiters marks the task reported. */
   waiters: number
@@ -98,8 +99,8 @@ export class TaskService extends Service {
   private surfaces = new Set<symbol>()
   private listeners = new Set<TaskDoneListener>()
   private listenersClosed = false
-  /** Owner agents that already have this registry's cleanup attached. */
-  private ownerCleanups = new Set<AgentId>()
+  /** Owner agents whose cleanup effect is attached, mapped to its self-detacher. */
+  private ownerCleanups = new Map<AgentId, () => void>()
   /**
    * The service's OWN construction-time context, for work that outlives the
    * calling fiber: detached settlement continuations (logging), and the
@@ -338,8 +339,8 @@ export class TaskService extends Service {
   }
 
   /**
-   * Register a completion listener, called exactly once per task with the
-   * terminal snapshot. Effect-scoped (disposed with the calling fiber);
+   * Register a completion listener, called exactly once per terminal task
+   * record with its snapshot. Effect-scoped (disposed with the calling fiber);
    * per-listener containment (one throwing listener is logged, never starves
    * the rest); never fires after this service is disposed.
    * @param listener - called with each settling task's terminal snapshot.
@@ -409,13 +410,17 @@ export class TaskService extends Service {
   }
 
   /**
-   * Record a task's terminal outcome (called exactly once — the single `done`
-   * continuation is the only caller), notify listeners with containment, then
-   * release waiters. A settlement observed by a pending {@link wait} marks
-   * the task reported BEFORE listeners run, so the notice surface can
+   * Record the first terminal outcome, notify listeners with containment, then
+   * release waiters. Normally the producer's single `done` continuation calls
+   * this; teardown also force-fails the record when `cancel` throws and `done`
+   * may never settle. First-wins makes a producer outcome arriving after that
+   * fallback a no-op, so listeners fire once and the diagnosed terminal state
+   * is never overwritten. A settlement observed by a pending {@link wait}
+   * marks the task reported BEFORE listeners run, so the notice surface can
    * suppress its redundant "finished".
    */
   private settle(task: TrackedTask, outcome: TaskOutcome): void {
+    if (isTerminal(task.status)) return
     task.status = outcome.status
     task.detail = outcome.detail
     task.output = outcome.output
@@ -439,27 +444,38 @@ export class TaskService extends Service {
    * the agent's disposal chain drains (`ctx.agents.drainCleanups`), the
    * owner's still-live tasks are cancelled, awaited to settlement, and their
    * snapshots dropped. Registered through {@link selfCtx} so the cleanup
-   * survives producer-plugin reloads. Fails loud when no agent registry is
-   * mounted — an owned background task without the cleanup seam would outlive
-   * its owner silently.
+   * survives producer-plugin reloads. When the cleanup starts, it detaches its
+   * own effect before awaiting task settlement, so completed owners do not
+   * accumulate effect wrappers (and captured sessions) on the long-lived tasks
+   * fiber. A narrow race remains if new work starts on an agent already being
+   * drained: before this callback clears the owner entry, that start can reuse
+   * the in-flight cleanup after its task snapshot was taken.
+   * Fails loud when no agent registry is mounted — an owned background task
+   * without the cleanup seam would outlive its owner silently.
    */
   private ensureOwnerCleanup(owner: Agent): void {
-    if (this.ownerCleanups.has(owner.id)) return
+    const ownerId = owner.id
+    if (this.ownerCleanups.has(ownerId)) return
     const agents = this.selfCtx.get('agents')
     if (agents === undefined) {
       throw new Error('background task ownership requires the agent registry (load @deepseek-ai/dsh-agent)')
     }
+    const ownerSession = owner.session.header.id
     // Attach FIRST, record after: onCleanup throws for an unregistered agent,
     // and marking the owner as covered before that would make every later
     // registration for the same owner silently skip the cleanup.
-    agents.onCleanup(owner.id, async () => {
-      this.ownerCleanups.delete(owner.id)
-      await this.disposeOwned(owner.session.header.id)
+    const detach = agents.onCleanup(ownerId, async () => {
+      const disposeEffect = this.ownerCleanups.get(ownerId)
+      this.ownerCleanups.delete(ownerId)
+      // A drain racing lifecycle teardown may find that the effect was already
+      // detached; otherwise this removes its wrapper from the tasks fiber now.
+      disposeEffect?.()
+      await this.disposeOwned(ownerSession)
     })
-    this.ownerCleanups.add(owner.id)
+    this.ownerCleanups.set(ownerId, detach)
   }
 
-  /** Cancel (contained), await, and drop every task owned by one session. */
+  /** Cancel, await terminal records, and drop every task owned by one session. */
   private async disposeOwned(ownerSession: string): Promise<void> {
     const owned = [...this.store.values()].filter(task => task.ownerSession === ownerSession)
     this.cancelForTeardown(owned, 'owner disposed')
@@ -469,8 +485,10 @@ export class TaskService extends Service {
 
   /**
    * Service teardown: close the listener registry FIRST (late completions
-   * from teardown kills stay silent), cancel every live task, and await
-   * quiescence. No orphan child work survives the tasks fiber.
+   * from teardown kills stay silent), cancel every live task, and await each
+   * terminal record. Contract-compliant producers settle at quiescence; a
+   * producer whose cancel throws is force-failed so disposal cannot deadlock,
+   * with the possible underlying orphan logged explicitly.
    */
   private async disposeAll(): Promise<void> {
     this.listenersClosed = true
@@ -483,18 +501,25 @@ export class TaskService extends Service {
 
   /**
    * Teardown-path cancellation with per-task containment: unlike the
-   * model-facing {@link kill} (where a throwing producer `cancel` should fail
-   * the tool call loudly), a teardown must reach quiescence past a broken
-   * producer, so a throw is logged and the sweep continues.
+   * model-facing {@link kill} (where a throwing producer `cancel` fails the tool
+   * call and leaves the record live), teardown force-fails a record whose cancel
+   * throws because its `done` may depend on a request that never arrived. This
+   * prevents disposal deadlock but cannot prove the underlying work stopped, so
+   * the potential orphan is carried in the detail and warning. A cancel that
+   * returns but never leads to `done` remains indistinguishable from a slow stop
+   * and can still stall teardown; fixing that requires a separate bounded-lifetime
+   * or forced-disposal design.
    */
   private cancelForTeardown(tasks: TrackedTask[], reason: string): void {
     for (const task of tasks) {
       if (isTerminal(task.status)) continue
-      task.status = 'stopping'
       try {
         task.cancel(reason)
+        task.status = 'stopping'
       } catch (error: unknown) {
-        this.selfCtx.logger.warn(`tasks: cancel of ${task.id} threw during teardown: ${String(error)}`)
+        const detail = `cancel threw during teardown; work may be orphaned: ${String(error)}`
+        this.selfCtx.logger.warn(`tasks: cancel of ${task.id} threw during teardown; task record forced failed and work may be orphaned: ${String(error)}`)
+        this.settle(task, { status: 'failed', detail })
       }
     }
   }
diff --git a/packages/tasks/tasks/src/types.ts b/packages/tasks/tasks/src/types.ts
index c03c8a2584..b4337cc1ff 100644
--- a/packages/tasks/tasks/src/types.ts
+++ b/packages/tasks/tasks/src/types.ts
@@ -105,7 +105,9 @@ export interface TaskHooks {
    * released the task's resources (process exited, child agent disposed) —
    * not merely when the work finished. Must never reject; a rejection is
    * contained as a `failed` outcome and logged as a producer contract
-   * violation.
+   * violation. If `cancel` throws during teardown, the runtime may force-fail
+   * only its registry record to avoid deadlock because this promise may never
+   * settle; that fallback explicitly does not claim work quiescence.
    */
   done: Promise<TaskOutcome>
   /**
diff --git a/packages/tasks/tasks/tests/tasks.spec.ts b/packages/tasks/tasks/tests/tasks.spec.ts
index a2324448cf..11cf9ff8b0 100644
--- a/packages/tasks/tasks/tests/tasks.spec.ts
+++ b/packages/tasks/tasks/tests/tasks.spec.ts
@@ -444,11 +444,46 @@ describe('TaskService owner cleanup', () => {
     expect(ctx.tasks.list(owner)).toEqual([])
   })
 
-  it('contains a throwing producer cancel on the cleanup path', async () => {
+  it('releases the owner-cleanup effect from the tasks fiber after its drain', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const tasksFiber = await ctx.plugin(TaskService)
+    ctx.tasks.attachSurface('test-surface')
+    const owner = stubAgent('owner')
+    ctx.agents.register(owner)
+    const ownerCleanupEffects = () => tasksFiber.getEffects()
+      .filter(effect => effect.label === 'agents.onCleanup()')
+
+    const first = producer({ owner })
+    ctx.tasks.start(first.spec)
+    expect(ownerCleanupEffects()).toHaveLength(1)
+    first.settle({ status: 'completed' })
+    await tick()
+    await ctx.agents.drainCleanups(owner.id)
+
+    // Only the owner registration is released; the long-lived tasks service
+    // and its own teardown effect remain active.
+    expect(ownerCleanupEffects()).toHaveLength(0)
+    expect(ctx.get('tasks')).toBeDefined()
+    expect(tasksFiber.getEffects().some(effect => effect.label === 'tasks teardown')).toBe(true)
+
+    // The same still-live owner can attach and release a fresh registration.
+    const second = producer({ owner })
+    ctx.tasks.start(second.spec)
+    expect(ownerCleanupEffects()).toHaveLength(1)
+    second.settle({ status: 'completed' })
+    await tick()
+    await ctx.agents.drainCleanups(owner.id)
+    expect(ownerCleanupEffects()).toHaveLength(0)
+  })
+
+  it('force-fails a throwing teardown cancel without awaiting producer done, first outcome wins', async () => {
     const ctx = await harness()
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
     const owner = stubAgent('owner')
     ctx.agents.register(owner)
+    const seen: TaskSnapshot[] = []
+    ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot))
 
     let settle!: (outcome: TaskOutcome) => void
     ctx.tasks.start({
@@ -462,9 +497,27 @@ describe('TaskService owner cleanup', () => {
     })
 
     const drain = ctx.agents.drainCleanups(owner.id)
-    settle({ status: 'failed', detail: 'gave up' })
-    await drain
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('cancel boom'))
+    let drained = false
+    void drain.then(() => { drained = true })
+    await tick()
+    const drainedWithoutProducerDone = drained
+    if (!drainedWithoutProducerDone) {
+      // Failure-path cleanup for the pre-fix implementation: let its pending
+      // drain finish without weakening the assertion captured above.
+      settle({ status: 'completed' })
+      await drain
+    } else {
+      // A late producer completion must not replace the forced failed record or
+      // notify listeners a second time.
+      settle({ status: 'completed' })
+      await tick()
+    }
+
+    expect(drainedWithoutProducerDone).toBe(true)
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('work may be orphaned'))
+    expect(seen).toHaveLength(1)
+    expect(seen[0]?.status).toBe('failed')
+    expect(seen[0]?.detail).toContain('cancel threw during teardown')
     expect(ctx.tasks.list(owner)).toEqual([])
   })
 })
@@ -498,6 +551,44 @@ describe('TaskService disposal', () => {
     expect(seen).toEqual([])
   })
 
+  it('force-fails a throwing cancel so service disposal does not await producer done', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const fiber = await ctx.plugin(TaskService)
+    ctx.tasks.attachSurface('test-surface')
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const seen: TaskSnapshot[] = []
+    ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot))
+
+    let settle!: (outcome: TaskOutcome) => void
+    ctx.tasks.start({
+      kind: 'bash',
+      label: 'broken service task',
+      run: () => ({
+        cancel() { throw new Error('service cancel boom') },
+        done: new Promise<TaskOutcome>((resolve) => { settle = resolve }),
+      }),
+    })
+
+    const disposal = fiber.dispose()
+    let disposed = false
+    void disposal.then(() => { disposed = true })
+    await tick()
+    const disposedWithoutProducerDone = disposed
+    if (!disposedWithoutProducerDone) {
+      // Failure-path cleanup for the pre-fix implementation.
+      settle({ status: 'completed' })
+      await disposal
+    } else {
+      settle({ status: 'completed' })
+      await tick()
+    }
+
+    expect(disposedWithoutProducerDone).toBe(true)
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('work may be orphaned'))
+    expect(seen).toEqual([])
+  })
+
   it('detaching the last surface re-arms the register fence', async () => {
     const ctx = new Context()
     await ctx.plugin(TaskService)
diff --git a/packages/ui/acp-agent/README.md b/packages/ui/acp-agent/README.md
index d81c9cc091..856dbfd217 100644
--- a/packages/ui/acp-agent/README.md
+++ b/packages/ui/acp-agent/README.md
@@ -27,6 +27,10 @@ Because the package wires no logger entry, an ACP leaf has **nothing to get wron
 | `model` | (required) | the per-session agent template the bridge creates agents from |
 | `persona` | — | the deployment persona template (may reference `{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
 | `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
+| `tools` | `{ mode: 'native' }` | tool-registry presentation config through `agent-core` |
+| `skills` | owner defaults | skill registry, local provider, and model-facing skill-tool config through `agent-core` |
+| `toolBash` | owner defaults | model-facing bash config through `agent-core`, including bash's producer-local `enableRunInBackground` |
+| `toolTasks` | owner defaults | generic `task_output` wait bounds through `agent-core` |
 | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
 
 The leaf supplies the swappable backends: an LLM adapter (`llm-deepseek` for the real model, `llm-replay` for keyless snapshot replay) and a bash executor (`bash-local`).
diff --git a/packages/ui/acp-agent/src/index.ts b/packages/ui/acp-agent/src/index.ts
index 27b919f756..4fc867eda6 100644
--- a/packages/ui/acp-agent/src/index.ts
+++ b/packages/ui/acp-agent/src/index.ts
@@ -62,6 +62,10 @@ export interface Config {
   persistenceRoot?: string
   /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
   skills?: agentCore.SkillConfig
+  /** Model-facing bash tool config forwarded through agent-core. */
+  toolBash?: NonNullable<agentCore.Config['toolBash']>
+  /** Generic background-task control-tool config forwarded through agent-core. */
+  toolTasks?: NonNullable<agentCore.Config['toolTasks']>
 }
 
 export const Config: z<Config> = z.object({
@@ -74,6 +78,8 @@ export const Config: z<Config> = z.object({
   tools: ToolRegistry.Config,
   persistenceRoot: z.string().default('./.sessions'),
   skills: agentCore.SkillConfigSchema,
+  toolBash: agentCore.ToolBashConfigSchema,
+  toolTasks: agentCore.ToolTasksConfigSchema,
 })
 
 /**
@@ -89,6 +95,8 @@ export function apply(ctx: Context, config: Config): void {
     ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
     ...config.tools !== undefined ? { tools: config.tools } : {},
     ...config.skills !== undefined ? { skills: config.skills } : {},
+    ...config.toolBash !== undefined ? { toolBash: config.toolBash } : {},
+    ...config.toolTasks !== undefined ? { toolTasks: config.toolTasks } : {},
   })
   ctx.plugin(UserInteractionService)
   ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
diff --git a/packages/ui/acp-agent/tests/acp-agent.spec.ts b/packages/ui/acp-agent/tests/acp-agent.spec.ts
index a9b207bfb7..e396d33d4d 100644
--- a/packages/ui/acp-agent/tests/acp-agent.spec.ts
+++ b/packages/ui/acp-agent/tests/acp-agent.spec.ts
@@ -18,8 +18,9 @@ import * as acpAgent from '../src/index.ts'
  * ACP operations end-to-end) is the keyless bin smoke in `load-path.e2e.ts`;
  * this spec asserts the composition and the persistenceRoot default branch.
  */
-async function mount(config: acpAgent.Config): Promise<Context> {
+async function mount(config: acpAgent.Config, withBash = false): Promise<Context> {
   const ctx = new Context()
+  if (withBash) ctx.provide('bash', { sandboxMode: undefined })
   await ctx.plugin(acpAgent, config)
   // The bundle mounts its children inside apply() (not awaited there); let their
   // fibers settle so the spine services are ready.
@@ -110,6 +111,19 @@ describe('dsh-acp-agent composition', () => {
     await ctx.fiber.dispose()
   })
 
+  it('forwards bundled tool config into agent-core', async () => {
+    const ctx = await mount({
+      model: 'mock',
+      toolBash: { enableRunInBackground: false },
+      toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
+      skills: await isolatedSkillsConfig(),
+    }, true)
+    const bash = ctx.tools.schemas().find(tool => tool.name === 'bash')
+    expect(Object.keys((bash!.parameters as { properties: Record<string, unknown> }).properties))
+      .not.toContain('run_in_background')
+    await ctx.fiber.dispose()
+  })
+
   it('exposes its plugin shape', () => {
     expect(acpAgent.name).toBe('acp-agent')
     expect(acpAgent.Config).toBeDefined()
diff --git a/packages/ui/stdio-agent/README.md b/packages/ui/stdio-agent/README.md
index 27f0d20be7..45bc6847df 100644
--- a/packages/ui/stdio-agent/README.md
+++ b/packages/ui/stdio-agent/README.md
@@ -28,6 +28,10 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte
 | `model` | (required) | the pre-created `main` agent's model |
 | `persona` | — | the deployment persona template (may reference `{{model}}`), routed to `dsh-system-prompt` |
 | `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
+| `tools` | `{ mode: 'native' }` | tool-registry presentation config through `agent-core` |
+| `skills` | owner defaults | skill registry, local provider, and model-facing skill-tool config through `agent-core` |
+| `toolBash` | owner defaults | model-facing bash config through `agent-core`, including bash's producer-local `enableRunInBackground` |
+| `toolTasks` | owner defaults | generic `task_output` wait bounds through `agent-core` |
 | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
 | `welcome` | `ready.` | the stdin-chat banner |
 | `resumeSessionId` | — | resume a persisted session id instead of starting fresh (sourced from an env var in the leaf) |
diff --git a/packages/ui/stdio-agent/src/index.ts b/packages/ui/stdio-agent/src/index.ts
index 1037c28112..babdb41690 100644
--- a/packages/ui/stdio-agent/src/index.ts
+++ b/packages/ui/stdio-agent/src/index.ts
@@ -77,6 +77,10 @@ export interface Config {
   welcome?: string
   /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
   skills?: agentCore.SkillConfig
+  /** Model-facing bash tool config forwarded through agent-core. */
+  toolBash?: NonNullable<agentCore.Config['toolBash']>
+  /** Generic background-task control-tool config forwarded through agent-core. */
+  toolTasks?: NonNullable<agentCore.Config['toolTasks']>
   /**
    * If set, the `main` agent RESUMES this persisted session id instead of
    * starting fresh. Sourced from an env var in the leaf `cordis.yml`
@@ -96,6 +100,8 @@ export const Config: z<Config> = z.object({
   persistenceRoot: z.string().default('./.sessions'),
   welcome: z.string().default('ready.'),
   skills: agentCore.SkillConfigSchema,
+  toolBash: agentCore.ToolBashConfigSchema,
+  toolTasks: agentCore.ToolTasksConfigSchema,
   resumeSessionId: z.string(),
 })
 
@@ -119,6 +125,8 @@ export function apply(ctx: Context, config: Config): void {
       ...config.resumeSessionId !== undefined ? { resumeSessionId: SessionId(config.resumeSessionId) } : {},
     }],
     ...config.skills !== undefined ? { skills: config.skills } : {},
+    ...config.toolBash !== undefined ? { toolBash: config.toolBash } : {},
+    ...config.toolTasks !== undefined ? { toolTasks: config.toolTasks } : {},
   })
   ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
   ctx.plugin(UserInteractionService)
diff --git a/packages/ui/stdio-agent/tests/stdio-agent.spec.ts b/packages/ui/stdio-agent/tests/stdio-agent.spec.ts
index cbd54b39b6..34a3268b3a 100644
--- a/packages/ui/stdio-agent/tests/stdio-agent.spec.ts
+++ b/packages/ui/stdio-agent/tests/stdio-agent.spec.ts
@@ -25,8 +25,9 @@ import * as stdioAgent from '../src/index.ts'
  * stray default rather than crash). Here we assert the composition + config
  * forwarding the unit tier can reach.
  */
-async function mount(config: stdioAgent.Config): Promise<Context> {
+async function mount(config: stdioAgent.Config, withBash = false): Promise<Context> {
   const ctx = new Context()
+  if (withBash) ctx.provide('bash', { sandboxMode: undefined })
   await ctx.plugin(stdioAgent, config)
   // The app mounts its children inside apply() (not awaited there); let their
   // fibers settle so the spine services + the pre-created agent are ready.
@@ -135,6 +136,19 @@ describe('dsh-stdio-agent app', () => {
     await ctx.fiber.dispose()
   })
 
+  it('forwards bundled tool config into agent-core', async () => {
+    const ctx = await mount({
+      model: 'mock',
+      toolBash: { enableRunInBackground: false },
+      toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
+      skills: await isolatedSkillsConfig(),
+    }, true)
+    const bash = ctx.tools.schemas().find(tool => tool.name === 'bash')
+    expect(Object.keys((bash!.parameters as { properties: Record<string, unknown> }).properties))
+      .not.toContain('run_in_background')
+    await ctx.fiber.dispose()
+  })
+
   it('exposes its name and Config schema', () => {
     expect(stdioAgent.name).toBe('stdio-agent')
     expect(stdioAgent.Config).toBeDefined()

From 8f5ea04c3fe6369fbd13aec1bd204841836d2f2f Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Sun, 12 Jul 2026 17:10:02 +0800
Subject: [PATCH 13/48] fix(tasks): validate owner identity and brand session
 ids

---
 docs/cordis-catalog/services.md               |  2 +-
 docs/core-data-structures/tasks.md            | 13 ++++---
 docs/module-graph.md                          |  3 +-
 ...06-20-generic-long-running-tool-runtime.md | 10 ++---
 .../cordis/tool-cordis/src/api-catalog.ts     |  2 +-
 packages/tasks/tasks/README.md                |  2 +-
 packages/tasks/tasks/package.json             |  1 +
 packages/tasks/tasks/src/index.ts             | 21 ++++++----
 packages/tasks/tasks/src/types.ts             | 10 +++--
 packages/tasks/tasks/tests/tasks.spec.ts      | 39 ++++++++++++++++---
 packages/tasks/tasks/tsconfig.json            |  3 ++
 11 files changed, 77 insertions(+), 29 deletions(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 0178a95a08..dc2dfcac7e 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -271,7 +271,7 @@ attachSurface(name: string): () => void
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/tasks/tasks/src/index.ts:96`](../../packages/tasks/tasks/src/index.ts)
+Source: [`packages/tasks/tasks/src/index.ts:97`](../../packages/tasks/tasks/src/index.ts)
 
 ## `ctx.tools` — `ToolRegistry`
 
diff --git a/docs/core-data-structures/tasks.md b/docs/core-data-structures/tasks.md
index b0cab68522..5914053720 100644
--- a/docs/core-data-structures/tasks.md
+++ b/docs/core-data-structures/tasks.md
@@ -21,7 +21,9 @@ interface TaskStart {
   /**
    * The spawning agent. Its `session.header.id` becomes the task's owner
    * token (read/kill/wait/list are fenced to that session), and its disposal
-   * cancels and awaits the task through the `ctx.agents.onCleanup` seam.
+   * cancels and awaits the task through the `ctx.agents.onCleanup` seam. It
+   * must be the exact live instance currently registered under its agent id;
+   * a stale object whose id has been reused is rejected before work starts.
    * `undefined` starts an UNOWNED task: open to any caller, alive until the
    * tasks service disposes.
    */
@@ -86,7 +88,7 @@ interface TaskOutcome {
 
 ## What consumers see: `TaskSnapshot` and `TaskRead`
 
-Snapshots are fresh projections, never live registry state. `reported` is the notice-suppression flag: the completion-notice injector (`dsh-tool-tasks`) skips a task whose terminal state the model already saw.
+Snapshots are fresh projections, never live registry state. `ownerSession` retains the shared branded `SessionId` type across the package boundary. `reported` is the notice-suppression flag: the completion-notice injector (`dsh-tool-tasks`) skips a task whose terminal state the model already saw.
 
 ```ts type-equiv
 interface TaskSnapshot {
@@ -100,9 +102,10 @@ interface TaskSnapshot {
    * The owner's session id (`session.header.id`), for surfaces that must
    * reach the owning agent (the completion-notice injector); absent for
    * unowned tasks. Session ids are runtime-shared identifiers, not secrets —
-   * the read/kill/wait/list FENCE is what isolation rests on.
+   * the read/kill/wait/list FENCE is what isolation rests on. The shared
+   * {@link SessionId} brand is preserved across this package boundary.
    */
-  ownerSession?: string
+  ownerSession?: SessionId
   /** Current lifecycle state. */
   status: TaskStatus
   /** Kind-specific status detail, present once the producer supplied one (usually terminal). */
@@ -137,4 +140,4 @@ interface TaskRead {
 
 ## The service
 
-`TaskService` (`ctx.tasks` — [`packages/tasks/tasks/src/index.ts`](../../packages/tasks/tasks/src/index.ts)): `start` (preflight → producer `run()` → atomic commit, fenced by `attachSurface`), non-consuming `get`/`list` (caller-scoped — owned-by-caller plus unowned only), `read` (consuming for stream kinds), `kill` (producer `cancel` first; a throw leaves the task untouched), `wait` (bounded, abort cancels the wait only), and `onTaskDone` (a `TaskDoneListener` per terminal record, effect-scoped, contained). Every read/kill/wait/get compares the task's owner session with the caller's and rejects a foreign one. Owned tasks are cancelled and normally awaited to producer quiescence when their owning agent disposes (the `ctx.agents.onCleanup` seam); a teardown cancel that throws force-fails only the registry record and reports that the underlying work may be orphaned, preventing disposal deadlock without claiming quiescence. The model-facing surface over all of this is [dsh-tool-tasks](../../packages/tasks/tool-tasks/README.md).
+`TaskService` (`ctx.tasks` — [`packages/tasks/tasks/src/index.ts`](../../packages/tasks/tasks/src/index.ts)): `start` (preflight → producer `run()` → atomic commit, fenced by `attachSurface`), non-consuming `get`/`list` (caller-scoped — owned-by-caller plus unowned only), `read` (consuming for stream kinds), `kill` (producer `cancel` first; a throw leaves the task untouched), `wait` (bounded, abort cancels the wait only), and `onTaskDone` (a `TaskDoneListener` per terminal record, effect-scoped, contained). Start validates that an owned task names the exact live Agent instance currently registered under its id, so an old reference cannot bind work to a replacement agent's cleanup after id reuse. Every read/kill/wait/get separately compares the task's owner session with the caller's and rejects a foreign one. Owned tasks are cancelled and normally awaited to producer quiescence when their owning agent disposes (the `ctx.agents.onCleanup` seam); a teardown cancel that throws force-fails only the registry record and reports that the underlying work may be orphaned, preventing disposal deadlock without claiming quiescence. The model-facing surface over all of this is [dsh-tool-tasks](../../packages/tasks/tool-tasks/README.md).
diff --git a/docs/module-graph.md b/docs/module-graph.md
index aaebc6e6f9..db5aec2186 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -173,6 +173,7 @@ flowchart TD
   pkg_user_interaction --> pkg_llm
   pkg_tasks --> pkg_agent
   pkg_tasks --> pkg_brand
+  pkg_tasks --> pkg_session
   pkg_tasks --> pkg_timeout
   pkg_workflow --> pkg_agent
   pkg_workflow --> pkg_brand
@@ -356,7 +357,7 @@ flowchart TD
 | [`invariants`](../packages/support/invariants) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`user-approval`](../packages/ui/user-approval) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`user-interaction`](../packages/ui/user-interaction) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm) |
-| [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`timeout`](../packages/util/timeout) |
+| [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) |
 | [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/ui/user-approval) |
 | [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`sandbox`](../packages/sandbox/sandbox) |
diff --git a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index 137f6cd6ae..18b8494c51 100644
--- a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -65,7 +65,7 @@ Registrations are NOT effect-scoped to the registering fiber: a task belongs to
 
 ## Authorization and the service surface
 
-Cross-session isolation lives IN the runtime so every consumer gets the same rule for free: read/kill/wait/get take the caller (`Agent | undefined`), and a task whose owner session differs from the caller's session is rejected (`!== undefined` comparison — an unowned task is open, a no-agent caller cannot match an owned task). `list(caller)` returns only the caller-visible tasks (owned-by-caller or unowned) — a global listing would leak other sessions' labels. Owner identity is `session.header.id`, the canonical id every other subsystem keys on; because both sides of the comparison come from live `Agent`s, the freestanding `OwnerToken` brand the bash seam used to carry became internal state rather than a seam type.
+Cross-session isolation lives IN the runtime so every consumer gets the same rule for free: read/kill/wait/get take the caller (`Agent | undefined`), and a task whose owner session differs from the caller's session is rejected (`!== undefined` comparison — an unowned task is open, a no-agent caller cannot match an owned one). `list(caller)` returns only the caller-visible tasks (owned-by-caller or unowned) — a global listing would leak other sessions' labels. The snapshot carries that owner as the canonical branded `SessionId`, not a package-local token or bare string. Lifecycle ownership is checked independently at start: the supplied owner must be the exact live `Agent` instance currently registered under its id, so an old object cannot attach its session's work to a replacement agent's cleanup after id reuse.
 
 ```ts ignore-check
 class TaskService extends Service {           // ctx.tasks
@@ -80,7 +80,7 @@ class TaskService extends Service {           // ctx.tasks
 }
 ```
 
-`TaskSnapshot` is the read-only projection: id, kind, label, owner session, status, detail, started/finished timestamps, and the `reported` notice-suppression flag (below). `wait` resolves with the terminal snapshot, or with the still-`running` snapshot on timeout; aborting the wait cancels only the wait — unless the task already settled, in which case the wait still delivers the terminal snapshot (settlement suppressed the completion notice on this live waiter's behalf, and an aborted waiter un-counts itself synchronously so a same-tick settlement never suppresses a notice nobody will deliver).
+`TaskSnapshot` is the read-only projection: id, kind, label, branded owner `SessionId`, status, detail, started/finished timestamps, and the `reported` notice-suppression flag (below). `wait` resolves with the terminal snapshot, or with the still-`running` snapshot on timeout; aborting the wait cancels only the wait — unless the task already settled, in which case the wait still delivers the terminal snapshot (settlement suppressed the completion notice on this live waiter's behalf, and an aborted waiter un-counts itself synchronously so a same-tick settlement never suppresses a notice nobody will deliver).
 
 **Misconfiguration fails loud**: a deployment that loads a background-capable producer without any control surface would let the model start tasks it can never read or stop — the half-loaded failure mode the subagent RFC's first draft reshaped a whole plugin to avoid. The fence is `attachSurface()`: `dsh-tool-tasks` attaches (effect-scoped) on load, and `start()` throws `background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)` when none is attached — the earliest self-contained moment, since concurrent plugin start makes a load-time check racy. The registry stays ignorant of tool names; a deployment with a custom (non-model) surface attaches its own.
 
@@ -100,7 +100,7 @@ Completion notices stay durable context, not a wake-up (`agent.inject()` appends
 
 ## Producer opt-in and schema exposure
 
-Whether a producer tool offers `run_in_background` is that producer's own defaulted config: `enableRunInBackground?: boolean` on `dsh-tool-bash` and on each `dsh-tool-subagent` instance (both default `true` — bash keeps its always-exposed behavior, and a deployment disables either per instance from cordis.yml, no code edit). A bundle forwards the configs of the child plugins it owns: `dsh-agent-core` exposes `toolBash` for its built-in producer and `toolTasks` for the generic control surface, while independently composed producers such as subagent instances receive config directly. This forwarding is config reachability, not producer registration: future background-capable tools do not become `agent-core` fields unless that bundle also chooses to own them. A disabled producer omits the parameter from its schema entirely — and, because the arg validator deliberately allows undeclared keys, its `execute` ALSO refuses a forced `run_in_background: true` loud (the omission is advertising; the execution-time check is the enforcement). `ctx.tasks` plays no part in schema shaping — it never rewrites or decorates a producer's tool schema (Kimi Code regex-rewrites its bash description when background is disabled; config-owns-the-schema makes that trick unnecessary) — it only provides runtime registration. The two halves compose fail-loud: the producer's config decides what the model sees, and a background call that still reaches `start()` without a control surface throws the load-this-package error. `start()` preflights every failable check (the fence, validation, the owner-cleanup attach) BEFORE invoking the producer's `run()` and commits atomically after — background work started without a collectable id is structurally impossible, not a producer rollback obligation.
+Whether a producer tool offers `run_in_background` is that producer's own defaulted config: `enableRunInBackground?: boolean` on `dsh-tool-bash` and on each `dsh-tool-subagent` instance (both default `true` — bash keeps its always-exposed behavior, and a deployment disables either per instance from cordis.yml, no code edit). A bundle forwards the configs of the child plugins it owns: `dsh-agent-core` exposes `toolBash` for its built-in producer and `toolTasks` for the generic control surface, while independently composed producers such as subagent instances receive config directly. This forwarding is config reachability, not producer registration: future background-capable tools do not become `agent-core` fields unless that bundle also chooses to own them. A disabled producer omits the parameter from its schema entirely — and, because the arg validator deliberately allows undeclared keys, its `execute` ALSO refuses a forced `run_in_background: true` loud (the omission is advertising; the execution-time check is the enforcement). `ctx.tasks` plays no part in schema shaping — it never rewrites or decorates a producer's tool schema (Kimi Code regex-rewrites its bash description when background is disabled; config-owns-the-schema makes that trick unnecessary) — it only provides runtime registration. The two halves compose fail-loud: the producer's config decides what the model sees, and a background call that still reaches `start()` without a control surface throws the load-this-package error. `start()` preflights every failable check (the fence, validation, exact live owner instance, and owner-cleanup attach) BEFORE invoking the producer's `run()` and commits atomically after — background work started without a collectable id is structurally impossible, not a producer rollback obligation.
 
 ## The awaited owner-cleanup seam
 
@@ -109,7 +109,7 @@ A contract-compliant background task must not outlive its owner: the subagent ca
 - `AgentRegistry.onCleanup(agentId, cleanup: () => Promise<void>): () => void` — a per-agent cleanup registry (registrations are effects; the disposer unregisters).
 - The loop's composite disposal chain carries one link for it: after stop-and-drain and before unregister, `await ctx.agents.drainCleanups(agent.id)` runs every registered cleanup with per-cleanup containment (a throwing cleanup is logged and never starves later cleanups or the rest of the chain). This is a documented `dsh-agent-loop` change; running cleanups is part of the `AgentFactory` dispose contract so a replacement loop honors it too.
 
-`dsh-tasks` consumes the seam: the first task registered for an owner attaches one cleanup that cancels the owner's still-live tasks, normally awaits each task's `done` (quiescence), and drops the owner's snapshots. For contract-compliant producers, `AgentHandle.dispose()` therefore resolves only after the owner's background children are actually gone, and the guarantee composes transitively: a background subagent that started background tasks of its own drains them when its child agent disposes inside the parent task's settlement path (the cascade OpenCode implements with explicit parent-chain walking falls out of the seam here). A producer whose teardown cancel throws is the explicit degradation: its record settles `failed` with a possible-orphan detail and cleanup continues. An ownerless task is the sanctioned way for healthy work to outlive an agent, and a future durable-job RFC is the way to outlive the runtime.
+`dsh-tasks` consumes the seam: after validating the exact registered owner instance, the first task for that owner attaches one cleanup that cancels the owner's still-live tasks, normally awaits each task's `done` (quiescence), and drops the owner's snapshots. For contract-compliant producers, `AgentHandle.dispose()` therefore resolves only after the owner's background children are actually gone, and the guarantee composes transitively: a background subagent that started background tasks of its own drains them when its child agent disposes inside the parent task's settlement path (the cascade OpenCode implements with explicit parent-chain walking falls out of the seam here). A producer whose teardown cancel throws is the explicit degradation: its record settles `failed` with a possible-orphan detail and cleanup continues. An ownerless task is the sanctioned way for healthy work to outlive an agent, and a future durable-job RFC is the way to outlive the runtime.
 
 ## Bash migration
 
@@ -169,7 +169,7 @@ Everything model-visible already lands in the log: starts and reads are tool cal
 
 ## Testing
 
-Unit coverage pins the registry lifecycle (register/read/kill/wait/list, owner isolation including no-agent callers, stream-vs-final read semantics, listener containment, notice suppression after an explicit kill or terminal read/wait, the `attachSurface` fence, start atomicity — a failed preflight mutates nothing and burns no counter; a model-facing failed `cancel` leaves the task untouched; a teardown failed `cancel` force-fails the record once without awaiting `done` — ordinary disposal quiescence, per-kind id counters), the `onCleanup` drain ordering + containment (including mid-drain registration and effect self-release), both producers' start mapping plus the structural no-uncollectable-work guarantee (a failed preflight means the producer's `run()` — the spawn — was never invoked), and unchanged foreground bash/subagent behavior. Snapshot coverage pins the task tool schemas and the prompt section through the pinned-header fixture.
+Unit coverage pins the registry lifecycle (register/read/kill/wait/list, owner isolation including no-agent callers and stale owner objects after id reuse, stream-vs-final read semantics, listener containment, notice suppression after an explicit kill or terminal read/wait, the `attachSurface` fence, start atomicity — a failed preflight mutates nothing and burns no counter; a model-facing failed `cancel` leaves the task untouched; a teardown failed `cancel` force-fails the record once without awaiting `done` — ordinary disposal quiescence, per-kind id counters), the branded `SessionId` snapshot boundary, the `onCleanup` drain ordering + containment (including mid-drain registration and effect self-release), both producers' start mapping plus the structural no-uncollectable-work guarantee (a failed preflight means the producer's `run()` — the spawn — was never invoked), and unchanged foreground bash/subagent behavior. Snapshot coverage pins the task tool schemas and the prompt section through the pinned-header fixture.
 
 ## Consequences
 
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 0f6f20b053..060030a961 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -883,7 +883,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'TaskSnapshot',
-    declaration: 'export interface TaskSnapshot {\n    id: TaskId;\n    kind: string;\n    label: string;\n    ownerSession?: string;\n    status: TaskStatus;\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n    reported: boolean;\n}',
+    declaration: 'export interface TaskSnapshot {\n    id: TaskId;\n    kind: string;\n    label: string;\n    ownerSession?: SessionId;\n    status: TaskStatus;\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n    reported: boolean;\n}',
   },
   {
     name: 'TaskStart',
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index 3cfab12f45..2d0eacd91d 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -17,7 +17,7 @@ Every read/kill/wait/get compares the task's owner session (`owner.session.heade
 ## Lifecycle
 
 - Registrations are NOT effect-scoped to the registering fiber: tasks belong to their owning agent + producing backend, so producer/surface HMR reloads never touch them.
-- An owned task attaches (once per owner) an awaited cleanup via `ctx.agents.onCleanup`: on owner disposal the registry cancels live tasks, awaits contract-compliant producers to quiescence, and drops their snapshots. If a teardown cancel throws, it force-fails the record and logs that the underlying work may be orphaned rather than deadlocking `AgentHandle.dispose()`.
+- An owned task must name the exact live `Agent` instance currently registered under its id (stale objects are rejected after id reuse), then attaches once per owner an awaited cleanup via `ctx.agents.onCleanup`: on owner disposal the registry cancels live tasks, awaits contract-compliant producers to quiescence, and drops their snapshots. If a teardown cancel throws, it force-fails the record and logs that the underlying work may be orphaned rather than deadlocking `AgentHandle.dispose()`.
 - Service disposal closes the listener registry first (late teardown settlements stay silent), then applies the same cancellation rule to every live task and awaits terminal records.
 - A producer whose `cancel` returns but never causes `done` to settle remains indistinguishable from a slow stop and can stall teardown; solving that residual requires an explicit bounded-lifetime or forced-disposal design.
 
diff --git a/packages/tasks/tasks/package.json b/packages/tasks/tasks/package.json
index 8db26d7ff2..9e5f824418 100644
--- a/packages/tasks/tasks/package.json
+++ b/packages/tasks/tasks/package.json
@@ -24,6 +24,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-timeout": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index 244211fa4f..56c23d82de 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -32,6 +32,7 @@
 
 import { Context, Service } from 'cordis'
 import type { Agent, AgentId } from '@deepseek-ai/dsh-agent'
+import type { SessionId } from '@deepseek-ai/dsh-session'
 import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
 import { TaskId } from './types.ts'
 import type { TaskDoneListener, TaskOutcome, TaskRead, TaskSnapshot, TaskStart, TaskStatus } from './types.ts'
@@ -67,7 +68,7 @@ interface TrackedTask {
   kind: string
   label: string
   /** The owner's session id (`session.header.id`), or undefined for an unowned task. */
-  ownerSession: string | undefined
+  ownerSession: SessionId | undefined
   cancel: (reason?: string) => void
   readOutput: (() => string) | undefined
   status: TaskStatus
@@ -121,8 +122,9 @@ export class TaskService extends Service {
    * task id (`<kind>-N`, per-kind counter). Every check that can fail — the
    * control-surface fence ({@link attachSurface}; a task the model could
    * never read or stop must fail loud before it exists), kind/label
-   * validation, and the owner's awaited disposal-cleanup attach (once per
-   * owner agent, through `ctx.agents.onCleanup`) — runs BEFORE
+   * validation, exact live owner-instance identity, and the owner's awaited
+   * disposal-cleanup attach (once per owner agent, through
+   * `ctx.agents.onCleanup`) — runs BEFORE
    * `spec.run()` starts the actual work, and nothing in the runtime can fail
    * after it returns: "work started but never got a collectable id" is
    * structurally impossible, not a producer rollback obligation. The runtime
@@ -450,16 +452,21 @@ export class TaskService extends Service {
    * fiber. A narrow race remains if new work starts on an agent already being
    * drained: before this callback clears the owner entry, that start can reuse
    * the in-flight cleanup after its task snapshot was taken.
-   * Fails loud when no agent registry is mounted — an owned background task
-   * without the cleanup seam would outlive its owner silently.
+   * Fails loud when no agent registry is mounted or when `owner` is not the
+   * exact live instance currently registered under its id — accepting a stale
+   * object after id reuse would attach its session's task to another agent's
+   * lifecycle.
    */
   private ensureOwnerCleanup(owner: Agent): void {
     const ownerId = owner.id
-    if (this.ownerCleanups.has(ownerId)) return
     const agents = this.selfCtx.get('agents')
     if (agents === undefined) {
       throw new Error('background task ownership requires the agent registry (load @deepseek-ai/dsh-agent)')
     }
+    if (agents.get(ownerId) !== owner) {
+      throw new Error(`agent "${ownerId}" is not the registered agent instance (background task owner must be live)`)
+    }
+    if (this.ownerCleanups.has(ownerId)) return
     const ownerSession = owner.session.header.id
     // Attach FIRST, record after: onCleanup throws for an unregistered agent,
     // and marking the owner as covered before that would make every later
@@ -476,7 +483,7 @@ export class TaskService extends Service {
   }
 
   /** Cancel, await terminal records, and drop every task owned by one session. */
-  private async disposeOwned(ownerSession: string): Promise<void> {
+  private async disposeOwned(ownerSession: SessionId): Promise<void> {
     const owned = [...this.store.values()].filter(task => task.ownerSession === ownerSession)
     this.cancelForTeardown(owned, 'owner disposed')
     await Promise.all(owned.map(task => task.settled))
diff --git a/packages/tasks/tasks/src/types.ts b/packages/tasks/tasks/src/types.ts
index b4337cc1ff..8312769604 100644
--- a/packages/tasks/tasks/src/types.ts
+++ b/packages/tasks/tasks/src/types.ts
@@ -9,6 +9,7 @@
 
 import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { SessionId } from '@deepseek-ai/dsh-session'
 
 /**
  * Identifies one background task in the runtime-global registry. Generated by
@@ -71,7 +72,9 @@ export interface TaskStart {
   /**
    * The spawning agent. Its `session.header.id` becomes the task's owner
    * token (read/kill/wait/list are fenced to that session), and its disposal
-   * cancels and awaits the task through the `ctx.agents.onCleanup` seam.
+   * cancels and awaits the task through the `ctx.agents.onCleanup` seam. It
+   * must be the exact live instance currently registered under its agent id;
+   * a stale object whose id has been reused is rejected before work starts.
    * `undefined` starts an UNOWNED task: open to any caller, alive until the
    * tasks service disposes.
    */
@@ -136,9 +139,10 @@ export interface TaskSnapshot {
    * The owner's session id (`session.header.id`), for surfaces that must
    * reach the owning agent (the completion-notice injector); absent for
    * unowned tasks. Session ids are runtime-shared identifiers, not secrets —
-   * the read/kill/wait/list FENCE is what isolation rests on.
+   * the read/kill/wait/list FENCE is what isolation rests on. The shared
+   * {@link SessionId} brand is preserved across this package boundary.
    */
-  ownerSession?: string
+  ownerSession?: SessionId
   /** Current lifecycle state. */
   status: TaskStatus
   /** Kind-specific status detail, present once the producer supplied one (usually terminal). */
diff --git a/packages/tasks/tasks/tests/tasks.spec.ts b/packages/tasks/tasks/tests/tasks.spec.ts
index 11cf9ff8b0..466027e982 100644
--- a/packages/tasks/tasks/tests/tasks.spec.ts
+++ b/packages/tasks/tasks/tests/tasks.spec.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, expectTypeOf, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
@@ -6,12 +6,12 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import TaskService, { TaskId } from '@deepseek-ai/dsh-tasks'
 import type { TaskHooks, TaskOutcome, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks'
 
-function stubAgent(rawId: string): Agent {
+function stubAgent(rawId: string, rawSessionId = `${rawId}-session`): Agent {
   const id = AgentId(rawId)
   return {
     id,
     options: {},
-    session: new Session(SessionId(`${id}-session`)),
+    session: new Session(SessionId(rawSessionId)),
     status: 'idle',
     send() {},
     steer() {},
@@ -48,6 +48,10 @@ async function harness() {
 const tick = () => new Promise<void>(r => setTimeout(r, 0))
 
 describe('TaskService.start', () => {
+  it('preserves the SessionId brand on public owner snapshots', () => {
+    expectTypeOf<TaskSnapshot['ownerSession']>().toEqualTypeOf<SessionId | undefined>()
+  })
+
   it('refuses to register while no control surface is attached', async () => {
     const ctx = new Context()
     await ctx.plugin(TaskService)
@@ -365,9 +369,10 @@ describe('TaskService owner isolation', () => {
     const ctx = await harness()
     const ghost = stubAgent('ghost') // never registered in ctx.agents
 
-    // onCleanup rejects the unregistered agent BEFORE any registry mutation.
+    // Exact-instance preflight rejects the unregistered agent BEFORE any
+    // registry mutation or owner-cleanup attachment.
     expect(() => ctx.tasks.start(producer({ owner: ghost }).spec))
-      .toThrow('is not registered')
+      .toThrow('is not the registered agent instance')
     expect(ctx.tasks.list(ghost)).toEqual([])
 
     // Once the agent actually exists, the same owner gets a WORKING cleanup —
@@ -389,6 +394,30 @@ describe('TaskService owner isolation', () => {
     expect(cancels).toEqual(['owner disposed'])
     expect(ctx.tasks.list(ghost)).toEqual([])
   })
+
+  it('rejects a stale owner instance after another agent reuses its id', async () => {
+    const ctx = await harness()
+    const staleOwner = stubAgent('owner', 'stale-session')
+    const unregisterStale = ctx.agents.register(staleOwner)
+    unregisterStale()
+
+    const currentOwner = stubAgent('owner', 'current-session')
+    ctx.agents.register(currentOwner)
+    const current = producer({ owner: currentOwner })
+    ctx.tasks.start(current.spec) // Attach the current owner's cleanup first.
+
+    const stale = producer({ owner: staleOwner })
+    const staleRun = vi.fn(() => stale.spec.run())
+    expect(() => ctx.tasks.start({ ...stale.spec, run: staleRun }))
+      .toThrow('is not the registered agent instance')
+    expect(staleRun).not.toHaveBeenCalled()
+    expect(ctx.tasks.list(staleOwner)).toEqual([])
+    expect(ctx.tasks.list(currentOwner)).toHaveLength(1)
+
+    current.settle({ status: 'completed' })
+    await tick()
+    await ctx.agents.drainCleanups(currentOwner.id)
+  })
 })
 
 describe('TaskService owner cleanup', () => {
diff --git a/packages/tasks/tasks/tsconfig.json b/packages/tasks/tasks/tsconfig.json
index bf369ad156..392d3f8d8a 100644
--- a/packages/tasks/tasks/tsconfig.json
+++ b/packages/tasks/tasks/tsconfig.json
@@ -20,6 +20,9 @@
     {
       "path": "../../core/agent"
     },
+    {
+      "path": "../../core/session"
+    },
     {
       "path": "../../util/timeout"
     }

From 351a2e42b3d70a2514d78b5a9b7348e71a523ec5 Mon Sep 17 00:00:00 2001
From: Yichen Jiang <jyc132780208@sina.com>
Date: Mon, 13 Jul 2026 16:29:50 +0800
Subject: [PATCH 14/48] fix(tasks): close background task review findings

---
 docs/cordis-catalog/services.md               |  2 +-
 docs/core-data-structures/tasks.md            |  2 +-
 packages/bash/bash-local/src/index.ts         |  6 ++--
 packages/bash/bash-sandbox/README.md          |  2 +-
 packages/bash/bash-sandbox/src/index.ts       |  8 +++---
 .../bash/bash-sandbox/tests/sandbox.spec.ts   | 14 ++++++++++
 packages/core/agent-loop/README.md            |  2 +-
 packages/tasks/tasks/README.md                |  2 +-
 packages/tasks/tasks/src/index.ts             | 23 +++++++++++----
 packages/tasks/tasks/src/types.ts             |  2 +-
 packages/tasks/tasks/tests/tasks.spec.ts      | 28 +++++++++++++++++++
 packages/ui/acp/acp-feature-support.md        |  2 +-
 packages/util/brand/src/index.ts              |  8 +++---
 scripts/gen-cordis-catalog.ts                 |  2 --
 14 files changed, 78 insertions(+), 25 deletions(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 7e0e663f37..c4711ce37e 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -270,7 +270,7 @@ attachSurface(name: string): () => void
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/tasks/tasks/src/index.ts:97`](../../packages/tasks/tasks/src/index.ts)
+Source: [`packages/tasks/tasks/src/index.ts:99`](../../packages/tasks/tasks/src/index.ts)
 
 ## `ctx.tools` — `ToolRegistry`
 
diff --git a/docs/core-data-structures/tasks.md b/docs/core-data-structures/tasks.md
index 3753c3cf6d..83351f0651 100644
--- a/docs/core-data-structures/tasks.md
+++ b/docs/core-data-structures/tasks.md
@@ -20,7 +20,7 @@ interface TaskStart {
   label: string
   /**
    * The spawning agent. Its `session.header.id` becomes the task's owner
-   * token (read/kill/wait/list are fenced to that session), and its `ctx` scope
+   * identity (read/kill/wait/list are fenced to that session), and its `ctx` scope
    * owns an async cleanup that cancels and awaits the task during disposal. It
    * must be the exact live instance currently registered under its agent id;
    * a stale object whose id has been reused is rejected before work starts.
diff --git a/packages/bash/bash-local/src/index.ts b/packages/bash/bash-local/src/index.ts
index 065516da6a..198142f822 100644
--- a/packages/bash/bash-local/src/index.ts
+++ b/packages/bash/bash-local/src/index.ts
@@ -194,6 +194,7 @@ export class LocalBashExecutor extends BashExecutor {
         // suffices — runBash only rejects with Error instances.
         proc.status = 'killed'
         running.stderr.push(Buffer.from(`spawn failed: ${String(error)}`))
+        this.onProcessDone(proc, running)
         this.live.delete(proc)
       }),
       readOutput: (): BashProcessRead => {
@@ -227,8 +228,9 @@ export class LocalBashExecutor extends BashExecutor {
 
   /**
    * Settlement hook for subclasses that attach execution facts to a process.
-   * Called after exit facts are stamped and before {@link BashProcess.done}
-   * resolves. The base implementation is intentionally empty.
+   * Called after exit facts or spawn-failure output are stamped and before
+   * {@link BashProcess.done} resolves. The base implementation is intentionally
+   * empty.
    * @param _proc - the settled process handle.
    * @param _running - the process collectors, including full in-memory stderr.
    */
diff --git a/packages/bash/bash-sandbox/README.md b/packages/bash/bash-sandbox/README.md
index 5d462fe1f3..4f27ec878d 100644
--- a/packages/bash/bash-sandbox/README.md
+++ b/packages/bash/bash-sandbox/README.md
@@ -13,7 +13,7 @@ Every command is confined by handing the provider the exact `['bash', '-c', comm
 Semantics:
 
 - **Denials are result facts.** A failed run whose stderr carries the selected backend's own denial dialect — the signatures the provider stamps on every wrap (EROFS text under bwrap, EACCES under Landlock, EPERM under Seatbelt) — is reported as `BashRunResult.sandbox.denied: true` (conservative classification, read from the collected stderr tail); every CONFINED run also carries the mode it executed under (`result.sandbox.mode`) and the provider's enforcement completeness (`result.sandbox.enforcement`: `full`, or `partial` on an older Landlock ABI).
-- **Runner failures are sandbox failures, never command failures.** Foreground execution throws `SANDBOX_UNAVAILABLE`; a settled background process stamps `process.sandbox.runnerFailed`, which the bash producer renders through generic `task_output`.
+- **Runner failures are sandbox failures, never command failures.** Foreground execution throws `SANDBOX_UNAVAILABLE`; a settled background process stamps `process.sandbox.runnerFailed`, which the bash producer renders through generic `task_output`. Spawn failures also pass through settlement, so confined background handles retain their mode/enforcement facts and release per-process accounting.
 - **Config-time default, per-call policy.** The DEFAULT mode is fixed by this entry's config for the executor's lifetime; `resolve()` stamps it onto every spec, and an explicit request-level `sandboxMode` override — set by the tool layer only for a call whose wider mode a human granted through `ctx.approval` ([the sandbox RFC § Escalation](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md)) — makes THAT call run, classify, and report under its own mode while every neighbor keeps the default (background facts are stamped per task at settle). The capability fact `ctx.bash.sandboxMode` reports the configured default so the tool layer advertises escalation only when this executor is mounted. The model learns of the sandbox only through result facts — the static bash tool description explains the denial marker; there is no current-mode statement in the system prompt.
 - **File effects only.** Network and process visibility are deliberately not restricted — the mode vocabulary does not pretend to cover what the backend does not enforce.
 - Process mechanics (spawn, process-group kills, output collection/spill, background handles, credential scrub) are inherited from [`dsh-bash-local`](../bash-local/); runner selection lives in [`dsh-sandbox-local`](../../sandbox/sandbox-local/).
diff --git a/packages/bash/bash-sandbox/src/index.ts b/packages/bash/bash-sandbox/src/index.ts
index 3cc2a84aaf..5a7e102d6d 100644
--- a/packages/bash/bash-sandbox/src/index.ts
+++ b/packages/bash/bash-sandbox/src/index.ts
@@ -164,8 +164,8 @@ export class SandboxBashExecutor extends LocalBashExecutor {
   private readonly mode: SandboxMode
   private readonly workspaceRoot: string
   /**
-   * Per-task facts, keyed by task id from `start()` until the settle stamp
-   * consumes them: the mode the task runs under (per-call — an escalated task
+   * Per-process facts, keyed by handle from `start()` until the settle stamp
+   * consumes them: the mode the process runs under (per-call — an escalated task
    * differs from its neighbors) plus its wrap facts. The seam returns facts
    * PER WRAP — a provider may legally vary enforcement or dialect between
    * calls — so overlapping background tasks must each classify against their
@@ -234,8 +234,8 @@ export class SandboxBashExecutor extends LocalBashExecutor {
     // Sandbox facts are stamped at settle time by onProcessDone()
     // (denial classification runs against the settled task's collected
     // stderr). The map entry lands synchronously after spawn, strictly
-    // before the earliest possible settle (a process exit reaches us no
-    // sooner than the next tick).
+    // before the earliest possible settle (including a spawn rejection, whose
+    // promise reaction cannot run until this synchronous start call returns).
     const confined = this.confine(spec.command, mode)
     const proc = super.start({ ...spec, command: confined.command })
     const { enforcement, denialSignatures, runnerFailureSignatures } = confined
diff --git a/packages/bash/bash-sandbox/tests/sandbox.spec.ts b/packages/bash/bash-sandbox/tests/sandbox.spec.ts
index f9e5a7ad10..eddbe5c164 100644
--- a/packages/bash/bash-sandbox/tests/sandbox.spec.ts
+++ b/packages/bash/bash-sandbox/tests/sandbox.spec.ts
@@ -246,6 +246,20 @@ describe('result facts', () => {
 })
 
 describe('background sandbox facts', () => {
+  it('stamps facts and releases accounting when background spawn fails', async () => {
+    const { bash } = await setup()
+    const missingWorkdir = join(mkdtempSync(join(tmpdir(), 'dsh-sandbox-missing-cwd-')), 'missing')
+    const task = bash.start(bash.resolve({ command: 'true', workdir: missingWorkdir }))
+
+    await task.done
+
+    expect(task.status).toBe('killed')
+    expect(task.readOutput().delta).toContain('spawn failed:')
+    expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full' })
+    const accounting = (bash as unknown as { processFacts: Map<unknown, unknown> }).processFacts
+    expect(accounting.size).toBe(0)
+  })
+
   it('stamps a settled denial: nonzero exit + permission stderr under a confined mode', async () => {
     const { bash } = await setup()
     const task = bash.start(bash.resolve({ command: 'echo "x: Permission denied" >&2; exit 1' }))
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index 6832800d2e..932a0f2638 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -104,6 +104,6 @@ Everything that goes beyond "call the model, run the tools, repeat" belongs to p
 - Hooks and policy: the relevant `agent/*` checkpoints plus the guarded `tools/pre-execute` → `tools/execute` → `tools/post-execute` → `tools/result` pipeline; exact signatures and modes live in the [generated event catalog](../../../docs/cordis-catalog/events.md)
 - Compaction: `agent/pre-step`
 - Sandbox, permission, plan mode: `tools/pre-execute` for extensible deny/ask, `tools.guard()` for monotonic owner policy, `tools/post-execute` for result decisions, and `tools/result` for final observation
-- Sub-agents: implemented outside the loop as `ctx.subagents` providers; in-process providers use `ctx.agents.create()` and owned `AgentHandle` teardown, while child streaming/progress and background/poll collection remain deferred.
+- Sub-agents: implemented outside the loop as `ctx.subagents` providers; in-process providers use `ctx.agents.create()` and owned `AgentHandle` teardown, while generic [`ctx.tasks`](../../tasks/tasks/) plus [`dsh-tool-subagent`](../../subagent/tool-subagent/) own background collection.
 - Persistence: `session/event` + `session/flush`
 - UI: `session/event` (assistant token stream, boundaries, tool activity) + `agent/*` control events (`agent/status`, `agent/created`/`agent/disposed`)
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index 854880d180..cbf3a8a308 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -8,7 +8,7 @@ The background task registry (`ctx.tasks`): a runtime-global, CONCRETE service (
 - `get(id, caller?)` / `list(caller?)` — non-consuming snapshots; `list` returns only caller-owned plus unowned tasks (a global listing would leak foreign labels).
 - `read(id, caller?): TaskRead` — stream kinds consume the per-task cursor (v1's single intended reader is the owning model — a non-consuming multi-reader surface would be a cursor/snapshot API extension, not a `read` change); final kinds read the terminal output idempotently.
 - `kill(id, caller?, reason?)` — `'requested'` (live task: producer `cancel` runs first — a throw fails the kill loud and leaves the task untouched — then `stopping`) or `'already-terminal'`. Every successful kill marks the task `reported` (the killer saw the end → completion notice suppressed).
-- `wait(id, timeoutMs, caller?, signal?)` — resolves with the terminal snapshot (marked `reported`), or the live snapshot at timeout; an aborted signal rejects the WAIT only — unless the task already settled, in which case the wait still resolves and delivers the terminal snapshot (settlement suppressed the completion notice on this waiter's behalf, so rejecting would leave the finish both unreported and un-noticed). Timing is a [`dsh-timeout`](../../util/timeout/README.md) `deadline()` scoped to the `TASK_WAIT_TIMEOUT` code, so a nested foreign deadline never misreads as a wait timeout.
+- `wait(id, timeoutMs, caller?, signal?)` — resolves with the terminal snapshot (marked `reported`), or the live snapshot at timeout; an aborted signal rejects the WAIT only — unless the task already settled, in which case the wait still resolves and delivers the terminal snapshot (settlement suppressed the completion notice on this waiter's behalf, so rejecting would leave the finish both unreported and un-noticed). Timing is a [`dsh-timeout`](../../util/timeout/README.md) `deadline()` scoped to the `TASK_WAIT_TIMEOUT` code, so a nested foreign deadline never misreads as a wait timeout; timeout and abort detach their settlement resolver immediately, keeping retention bounded while the task remains live.
 - `onTaskDone(listener)` — exactly once per terminal task record; effect-scoped, per-listener containment, silent after service disposal.
 - `attachSurface(name)` — declares a control surface exists (the model tools, or a deployment's custom surface); effect-scoped.
 
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index 4f7b00a864..f7218d773f 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -83,6 +83,8 @@ interface TrackedTask {
   markSettled: () => void
   /** Live {@link TaskService.wait} calls — a settlement with waiters marks the task reported. */
   waiters: number
+  /** Removable resolvers for live waits; timeout/abort unregister before the task settles. */
+  waitResolvers: Set<() => void>
 }
 
 /** True for the three terminal {@link TaskStatus} values. */
@@ -169,6 +171,7 @@ export class TaskService extends Service {
       settled,
       markSettled,
       waiters: 0,
+      waitResolvers: new Set(),
     }
     this.store.set(id, task)
 
@@ -276,8 +279,10 @@ export class TaskService extends Service {
    * has already settled: settlement saw this live waiter and suppressed the
    * completion notice on its behalf, so the wait still resolves and delivers
    * the terminal snapshot it owes (an abort must never leave a finished task
-   * both unreported and notice-suppressed). Throws for an unknown id, a task
-   * owned by another session, or a non-positive timeout.
+   * both unreported and notice-suppressed). Each live wait uses a removable
+   * resolver that timeout/abort detaches, so a long-running task does not
+   * retain expired waits. Throws for an unknown id, a task owned by another
+   * session, or a non-positive timeout.
    * @param id - the task to wait for.
    * @param timeoutMs - max wait in milliseconds (positive, finite; the surface caps it).
    * @param caller - the waiting agent, checked against the task's owner.
@@ -313,7 +318,13 @@ export class TaskService extends Service {
         // the wait. `using` clears the timer on every exit path.
         using d = deadline(signal, timeoutMs, TASK_WAIT_TIMEOUT)
         await new Promise<void>((resolve, reject) => {
+          const onSettled = (): void => {
+            task.waitResolvers.delete(onSettled)
+            d.signal.removeEventListener('abort', onAbort)
+            resolve()
+          }
           const onAbort = (): void => {
+            task.waitResolvers.delete(onSettled)
             if (timeoutOf(d.signal, TASK_WAIT_TIMEOUT) !== undefined) {
               resolve()
             } else if (isTerminal(task.status)) {
@@ -325,11 +336,8 @@ export class TaskService extends Service {
               reject(new Error('wait aborted'))
             }
           }
+          task.waitResolvers.add(onSettled)
           d.signal.addEventListener('abort', onAbort, { once: true })
-          void task.settled.then(() => {
-            d.signal.removeEventListener('abort', onAbort)
-            resolve()
-          })
         })
       } finally {
         uncount()
@@ -437,6 +445,9 @@ export class TaskService extends Service {
         }
       }
     }
+    const waitResolvers = [...task.waitResolvers]
+    task.waitResolvers.clear()
+    for (const resolveWait of waitResolvers) resolveWait()
     task.markSettled()
   }
 
diff --git a/packages/tasks/tasks/src/types.ts b/packages/tasks/tasks/src/types.ts
index 7414eb216a..0345269645 100644
--- a/packages/tasks/tasks/src/types.ts
+++ b/packages/tasks/tasks/src/types.ts
@@ -71,7 +71,7 @@ export interface TaskStart {
   label: string
   /**
    * The spawning agent. Its `session.header.id` becomes the task's owner
-   * token (read/kill/wait/list are fenced to that session), and its `ctx` scope
+   * identity (read/kill/wait/list are fenced to that session), and its `ctx` scope
    * owns an async cleanup that cancels and awaits the task during disposal. It
    * must be the exact live instance currently registered under its agent id;
    * a stale object whose id has been reused is rejected before work starts.
diff --git a/packages/tasks/tasks/tests/tasks.spec.ts b/packages/tasks/tasks/tests/tasks.spec.ts
index a38503a2f8..1ae4567dce 100644
--- a/packages/tasks/tasks/tests/tasks.spec.ts
+++ b/packages/tasks/tasks/tests/tasks.spec.ts
@@ -59,6 +59,14 @@ async function harness() {
 /** Let the settlement continuation (a `done.then`) run. */
 const tick = () => new Promise<void>(r => setTimeout(r, 0))
 
+/** Inspect the internal resolver registry to pin bounded retention while a task stays live. */
+function waitResolverCount(ctx: Context, id: TaskId): number {
+  const service = ctx.tasks as unknown as { store: Map<TaskId, { waitResolvers: Set<() => void> }> }
+  const task = service.store.get(id)
+  if (task === undefined) throw new Error(`missing test task ${id}`)
+  return task.waitResolvers.size
+}
+
 describe('TaskService.start', () => {
   it('preserves the SessionId brand on public owner snapshots', () => {
     expectTypeOf<TaskSnapshot['ownerSession']>().toEqualTypeOf<SessionId | undefined>()
@@ -254,6 +262,26 @@ describe('TaskService.wait', () => {
     expect(await ctx.tasks.wait(id, 5)).toMatchObject({ status: 'running', reported: false })
   })
 
+  it('unregisters timed-out and aborted wait resolvers while the task remains live', async () => {
+    const ctx = await harness()
+    const id = ctx.tasks.start(producer().spec)
+
+    for (let index = 0; index < 3; index += 1) {
+      const wait = ctx.tasks.wait(id, 5)
+      expect(waitResolverCount(ctx, id)).toBe(1)
+      await expect(wait).resolves.toMatchObject({ status: 'running' })
+      expect(waitResolverCount(ctx, id)).toBe(0)
+    }
+
+    const controller = new AbortController()
+    const wait = ctx.tasks.wait(id, 5_000, undefined, controller.signal)
+    expect(waitResolverCount(ctx, id)).toBe(1)
+    controller.abort()
+    await expect(wait).rejects.toThrow('wait aborted')
+    expect(waitResolverCount(ctx, id)).toBe(0)
+    expect(ctx.tasks.get(id).status).toBe('running')
+  })
+
   it('returns immediately for an already-terminal task', async () => {
     const ctx = await harness()
     const p = producer()
diff --git a/packages/ui/acp/acp-feature-support.md b/packages/ui/acp/acp-feature-support.md
index be14fe6237..69ba9f33bb 100644
--- a/packages/ui/acp/acp-feature-support.md
+++ b/packages/ui/acp/acp-feature-support.md
@@ -133,7 +133,7 @@ The bridge rejects unsupported prompt blocks rather than silently dropping them
 | Multi-session (N per connection) | S | ✅ | Strict per-session demux; concurrent streams never interleave. See the [multi-session RFC](../../../docs/rfc/implemented/feature/2026-06-14-acp-multi-session.md). |
 | Disconnect / disposal teardown | S | ✅ | Quiesces every live session on client disconnect or Cordis disposal. |
 | `_meta` extensibility | S | ⚠️ | Consumed (Zed terminal cap) and emitted (terminal `_meta`); no other custom extensions. |
-| Background-task ownership isolation | — | ✅ | `bash_output`/`bash_kill` reject another session's task via an opaque owner token. |
+| Background-task ownership isolation | — | ✅ | Generic `task_output`/`task_kill` reject tasks whose branded owner `SessionId` belongs to another session. |
 | stdout-is-the-protocol guarantee | S | ✅ | The bridge runs in an example with no stdout logger. |
 
 ## Gap summary
diff --git a/packages/util/brand/src/index.ts b/packages/util/brand/src/index.ts
index 051ced94b7..0c669e2416 100644
--- a/packages/util/brand/src/index.ts
+++ b/packages/util/brand/src/index.ts
@@ -10,13 +10,13 @@
  * comparison, logging, and serialization all behave as ordinary strings.
  *
  * Policy: a package brands the ids it owns — `CallId` in dsh-llm (tool-call
- * correlation), `SessionId` in dsh-session, `AgentId` in dsh-agent,
- * `BashTaskId`/`OwnerToken` in dsh-bash. Branding is for ids that cross package
- * boundaries and could plausibly be confused; not every string needs a brand.
+ * correlation), `SessionId` in dsh-session, `AgentId` in dsh-agent, and
+ * `TaskId` in dsh-tasks. Branding is for ids that cross package boundaries and
+ * could plausibly be confused; not every string needs a brand.
  * This package owns ONLY the primitive — no concrete id, no runtime code beyond
  * the (erased) type — so the brand vocabulary stays dependency-free and a
  * package can brand its ids without depending on an unrelated capability
- * package (e.g. dsh-bash brands its ids without pulling in dsh-llm).
+ * package.
  *
  * @module @deepseek-ai/dsh-brand
  */
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 68139e9ff8..2db6f871ff 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -101,8 +101,6 @@ export const LINK_MAP: Record<string, string> = {
   BashExecRequest: 'bash.md',
   BashExecSpec: 'bash.md',
   BashRunResult: 'bash.md',
-  BashTask: 'bash.md',
-  BashTaskRead: 'bash.md',
   ConfinedArgv: 'sandbox.md',
   SandboxMode: 'sandbox.md',
   SandboxPolicy: 'sandbox.md',

From b2025337b56b8584ffbb71a54b486c48b285fc78 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 14 Jul 2026 03:47:32 +0800
Subject: [PATCH 15/48] refactor: hide sandbox implementation helpers

---
 docs/config-catalog.md                        |   4 +-
 packages/bash/bash-sandbox/README.md          |   2 +
 packages/bash/bash-sandbox/src/helpers.ts     |  49 +++++++++
 packages/bash/bash-sandbox/src/index.ts       |  70 +-----------
 packages/bash/bash-sandbox/tests/bwrap.e2e.ts |   3 +-
 .../bash/bash-sandbox/tests/sandbox.spec.ts   |   3 +-
 .../bash/bash-sandbox/tests/seatbelt.e2e.ts   |   3 +-
 packages/sandbox/sandbox-local/README.md      |   2 +
 packages/sandbox/sandbox-local/src/index.ts   | 102 +-----------------
 .../sandbox/sandbox-local/src/profiles.ts     |  67 ++++++++++++
 .../sandbox/sandbox-local/tests/bwrap.e2e.ts  |   3 +-
 .../sandbox/sandbox-local/tests/local.spec.ts |   4 +-
 .../sandbox-local/tests/seatbelt.e2e.ts       |   3 +-
 13 files changed, 136 insertions(+), 179 deletions(-)
 create mode 100644 packages/bash/bash-sandbox/src/helpers.ts
 create mode 100644 packages/sandbox/sandbox-local/src/profiles.ts

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index b0391d7a65..af46798fc5 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -176,7 +176,7 @@ export interface Config extends LocalConfig {
 
 Depends on: [`LocalConfig`](#deepseek-aidsh-bash-local) · [`SandboxMode`](core-data-structures/sandbox.md)
 
-Source: [`packages/bash/bash-sandbox/src/index.ts:60`](../packages/bash/bash-sandbox/src/index.ts)
+Source: [`packages/bash/bash-sandbox/src/index.ts:61`](../packages/bash/bash-sandbox/src/index.ts)
 
 ## `@deepseek-ai/dsh-code-runtime-worker`
 
@@ -521,7 +521,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/sandbox/sandbox-local/src/index.ts:36`](../packages/sandbox/sandbox-local/src/index.ts)
+Source: [`packages/sandbox/sandbox-local/src/index.ts:35`](../packages/sandbox/sandbox-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-persistence-jsonl`
 
diff --git a/packages/bash/bash-sandbox/README.md b/packages/bash/bash-sandbox/README.md
index 2a5ae63b8e..0aab0965be 100644
--- a/packages/bash/bash-sandbox/README.md
+++ b/packages/bash/bash-sandbox/README.md
@@ -2,6 +2,8 @@
 
 Sandbox-consuming implementation of the [`@deepseek-ai/dsh-bash`](../bash/) executor seam. Load it **instead of** `@deepseek-ai/dsh-bash-local`, together with a [`ctx.sandbox`](../../sandbox/sandbox/) provider (e.g. [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)) — the model-facing tool layer (`dsh-tool-bash`) is untouched; that swap is exactly what the seams exist for.
 
+The package root exports the default and named `SandboxBashExecutor` plugin plus its `Config`; quoting and result-classification helpers stay internal.
+
 Every command is confined by handing the provider the exact `['bash', '-c', command]` argv this executor is about to spawn and spawning the returned (wrapped) argv instead. WHICH platform runner confines it — and whether one is usable at all (fail closed with a structured `SANDBOX_UNAVAILABLE` error, never a silent unconfined run) — is the provider's concern; this package owns the bash side only.
 
 | Mode | File effects |
diff --git a/packages/bash/bash-sandbox/src/helpers.ts b/packages/bash/bash-sandbox/src/helpers.ts
new file mode 100644
index 0000000000..a98f47216e
--- /dev/null
+++ b/packages/bash/bash-sandbox/src/helpers.ts
@@ -0,0 +1,49 @@
+/**
+ * Internal shell-quoting and sandbox-result classification helpers.
+ *
+ * @module @deepseek-ai/dsh-bash-sandbox/helpers
+ */
+
+import type { BashRunResult } from '@deepseek-ai/dsh-bash'
+
+/**
+ * Quote one string as a single-quoted POSIX shell word.
+ * @param text - raw argv element to preserve through the outer shell parse.
+ * @returns the quoted shell word.
+ */
+export function shellQuote(text: string): string {
+  return `'${text.replaceAll("'", String.raw`'\''`)}'`
+}
+
+/**
+ * Classify a failed run against the selected backend's denial dialect.
+ * @param result - settled foreground run.
+ * @param signatures - case-insensitive denial substrings from the active wrap.
+ * @returns whether the failed run matches that denial dialect.
+ */
+export function classifyDenial(result: BashRunResult, signatures: readonly string[]): boolean {
+  return matchesSignature(result.exitCode, result.stderr.text, signatures)
+}
+
+/**
+ * Classify a failed run against the selected backend's runner-failure dialect.
+ * @param result - settled foreground run.
+ * @param signatures - case-insensitive runner-failure substrings from the active wrap.
+ * @returns whether the failed run matches that runner-failure dialect.
+ */
+export function classifyRunnerFailure(result: BashRunResult, signatures: readonly string[]): boolean {
+  return matchesSignature(result.exitCode, result.stderr.text, signatures)
+}
+
+/**
+ * Match a non-zero exit against case-insensitive stderr signatures.
+ * @param exitCode - process exit code; null means signal termination.
+ * @param stderr - collected stderr text.
+ * @param signatures - substrings identifying the selected backend's dialect.
+ * @returns whether this is a non-zero exit whose stderr matches a signature.
+ */
+export function matchesSignature(exitCode: number | null, stderr: string, signatures: readonly string[]): boolean {
+  if (exitCode === null || exitCode === 0) return false
+  const lowered = stderr.toLowerCase()
+  return signatures.some(signature => lowered.includes(signature.toLowerCase()))
+}
diff --git a/packages/bash/bash-sandbox/src/index.ts b/packages/bash/bash-sandbox/src/index.ts
index 090d06b2fe..5236040a16 100644
--- a/packages/bash/bash-sandbox/src/index.ts
+++ b/packages/bash/bash-sandbox/src/index.ts
@@ -49,6 +49,7 @@ import { SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedSandboxMode, SandboxEnforcement, SandboxMode } from '@deepseek-ai/dsh-sandbox'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import type { Config as LocalConfig } from '@deepseek-ai/dsh-bash-local'
+import { classifyDenial, classifyRunnerFailure, matchesSignature, shellQuote } from './helpers.ts'
 
 /**
  * Plugin config: the local executor's knobs plus the sandbox policy. All
@@ -67,75 +68,6 @@ export interface Config extends LocalConfig {
   workspaceRoot?: string
 }
 
-/**
- * Quote one string as a single-quoted POSIX shell word (embedded single
- * quotes become `'\''`), so a wrapped argv element survives the outer
- * `bash -c` re-parse byte-for-byte.
- * @param text - the raw argv element to quote.
- * @returns the single-quoted shell word.
- */
-export function shellQuote(text: string): string {
-  return `'${text.replaceAll("'", String.raw`'\''`)}'`
-}
-
-/**
- * Conservative sandbox-denial classifier: a run counts as denied only when it
- * FAILED (nonzero exit — a signal kill is not a denial) and its stderr
- * carries one of the SELECTED BACKEND's own denial signatures — the dialect
- * the provider stamps on every wrap (`ConfinedArgv.denialSignatures`:
- * `Read-only file system` under bwrap's EROFS mounts, `Permission denied`
- * under Landlock's EACCES, `Operation not permitted` under Seatbelt's
- * EPERM). Matching the backend's dialect rather than a cross-backend union
- * keeps the classifier from claiming denials the active backend never
- * produces (bare EPERM text under a Linux runner names non-file boundaries —
- * mount, kill, ptrace — that fail the same way unsandboxed). Text inference
- * is the fallback signal until a runner provides a structured one (which
- * wins once it exists); it errs toward NOT claiming a denial, and its known
- * residual imprecision is non-sandbox text in the active dialect (an ssh
- * auth failure reads as a denial under Landlock, a refused `kill` under
- * Seatbelt).
- * @param result - the settled foreground run to classify.
- * @param signatures - the active wrap's denial dialect, case-insensitive
- *   stderr substrings.
- * @returns whether the run's failure reads as a sandbox denial.
- */
-export function classifyDenial(result: BashRunResult, signatures: readonly string[]): boolean {
-  return matchesSignature(result.exitCode, result.stderr.text, signatures)
-}
-
-/**
- * Runner-failure classifier: a failed run whose stderr carries the SELECTED
- * BACKEND's own runner-failure signature (`ConfinedArgv.
- * runnerFailureSignatures`: the runner's error prefix, which also matches
- * the shell's runner-not-found message) means the SANDBOX itself failed and
- * the command never ran. Checked BEFORE {@link classifyDenial} — a runner's
- * error text can contain denial words (an unopenable grant root reports
- * `Permission denied`) — and surfaced as the fail-closed
- * `SANDBOX_UNAVAILABLE` error on the foreground path, `sandbox.runnerFailed`
- * on a settled background task. Same conservative-text-inference stance and
- * residual imprecision as the denial classifier (a failing task that itself
- * prints the runner's prefix reads as a runner failure).
- * @param result - the settled foreground run to classify.
- * @param signatures - the active wrap's runner-failure signatures,
- *   case-insensitive stderr substrings.
- * @returns whether the run's failure reads as the runner itself failing.
- */
-export function classifyRunnerFailure(result: BashRunResult, signatures: readonly string[]): boolean {
-  return matchesSignature(result.exitCode, result.stderr.text, signatures)
-}
-
-/**
- * The classifier core shared by foreground results and settled background
- * tasks: failed AND signature present. Lowercases BOTH sides — the seam
- * declares its signatures case-insensitive, and producers compose them from
- * runtime data of any case (an `argv0` path, `No such file or directory`).
- */
-function matchesSignature(exitCode: number | null, stderr: string, signatures: readonly string[]): boolean {
-  if (exitCode === null || exitCode === 0) return false
-  const lowered = stderr.toLowerCase()
-  return signatures.some(signature => lowered.includes(signature.toLowerCase()))
-}
-
 /**
  * Sandbox-consuming bash executor. Registers as `ctx.bash` (loading it
  * INSTEAD OF `dsh-bash-local`, together with a `ctx.sandbox` provider, is
diff --git a/packages/bash/bash-sandbox/tests/bwrap.e2e.ts b/packages/bash/bash-sandbox/tests/bwrap.e2e.ts
index 6a748bc389..92531c5302 100644
--- a/packages/bash/bash-sandbox/tests/bwrap.e2e.ts
+++ b/packages/bash/bash-sandbox/tests/bwrap.e2e.ts
@@ -5,7 +5,8 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import { bwrapProfileArgs, LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { bwrapProfileArgs } from '@deepseek-ai/dsh-sandbox-local/src/profiles.ts'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
 
 /**
diff --git a/packages/bash/bash-sandbox/tests/sandbox.spec.ts b/packages/bash/bash-sandbox/tests/sandbox.spec.ts
index 4f92ba38f0..c197951322 100644
--- a/packages/bash/bash-sandbox/tests/sandbox.spec.ts
+++ b/packages/bash/bash-sandbox/tests/sandbox.spec.ts
@@ -16,7 +16,8 @@ import { Context } from 'cordis'
 import type { BashRunResult, CollectedOutput } from '@deepseek-ai/dsh-bash'
 import { SANDBOX_UNAVAILABLE, SandboxProvider, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
-import { classifyDenial, classifyRunnerFailure, SandboxBashExecutor, shellQuote } from '@deepseek-ai/dsh-bash-sandbox'
+import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
+import { classifyDenial, classifyRunnerFailure, shellQuote } from '../src/helpers.ts'
 import type { Config } from '@deepseek-ai/dsh-bash-sandbox'
 
 const spillDir = mkdtempSync(join(tmpdir(), 'dsh-bash-sandbox-spec-'))
diff --git a/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts b/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts
index 8ae25a8d39..f6564a7b07 100644
--- a/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts
+++ b/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts
@@ -5,7 +5,8 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import { LocalSandboxProvider, seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local'
+import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local/src/profiles.ts'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
 
 /**
diff --git a/packages/sandbox/sandbox-local/README.md b/packages/sandbox/sandbox-local/README.md
index abf7511438..669ebef3dd 100644
--- a/packages/sandbox/sandbox-local/README.md
+++ b/packages/sandbox/sandbox-local/README.md
@@ -2,6 +2,8 @@
 
 Local implementation of the [`@deepseek-ai/dsh-sandbox`](../sandbox/) seam: wraps a caller's argv in a platform confinement runner. Selection is BY PLATFORM, resolved once and cached: each platform names its runner chain, a chain of one is selected directly (probing arbitrates between candidates — a sole candidate leaves nothing to arbitrate), and a chain of several is probed functionally in preference order. Linux: [`bwrap`](https://github.com/containers/bubblewrap) when its probe passes, else the [`landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run) Landlock launcher (kernel confinement that needs no userns/mount privileges — see the [sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md) for the prebuilt-binary decision and profile-parity notes); darwin: `sandbox-exec` speaking a Seatbelt (SBPL) profile, unprobed. A platform with no chain means `confine()` FAILS CLOSED with the seam's structured `SANDBOX_UNAVAILABLE` error (win32 today: a reserved, deliberately empty chain awaiting an AppContainer-family runner); an unprobed runner that turns out unusable fails closed at EXECUTION instead — it refuses to run the command, and every wrap's `runnerFailureSignatures` let the consumer classify that as a sandbox failure rather than a task failure. Never a silent unconfined passthrough on any path.
 
+The package root exports the default and named `LocalSandboxProvider` plugin, `Config`, and its public test-injection seam; platform profile builders stay internal.
+
 Policy is per call (`SandboxPolicy`: mode + workspace root); the provider holds only the mechanism and the cached ladder verdict. Every wrap reports the selected runner's `enforcement` (`full`, or `partial` on an older Landlock ABI that governs only a subset of accesses — read from the launcher's `--probe` report line) and its `denialSignatures` — the stderr dialect that rung's kernel speaks on a denied file effect (EROFS text under bwrap, EACCES under Landlock, EPERM under Seatbelt), which stderr-inferring consumers match instead of a cross-runner union. A non-empty `runnerCommand` config is the operator's assertion of a runner that fully enforces the bwrap-shaped profile: the ladder and probes are skipped (the wrap carries both Linux denial dialects, the mechanism being unknown) — also the deterministic fake-runner seam for keyless test tiers. Its runner-failure dialect is the OUTER shell's argv0-scoped failure shapes (`exec: <argv0>: not found`, `<argv0>: No such file or directory`, `<argv0>: Permission denied`) — the consumer re-joins the wrap through `bash -c 'exec …'`, so a missing or unexecutable configured runner classifies as a sandbox failure (fail closed at execution), never as a failing command or a denial. `probeTimeoutMs` (default 5000) bounds each functional probe, the escape hatch for hosts slow enough that a timed-out probe would otherwise misread as `SANDBOX_UNAVAILABLE`.
 
 The Seatbelt profile is allow-default with `(deny file-write*)` plus write allow-lists, so exactly the mode's promised file effects are governed: `read-only` grants the `/dev/null` literal alone; `workspace-write` adds the workspace root, `/tmp`, and the per-user darwin temp dir (`os.tmpdir()` — the platform's real temp area for mkstemp-family tools), every root canonicalized because Seatbelt matches resolved paths (`/tmp` IS `/private/tmp`). Apple marks the `sandbox-exec` CLI deprecated but ships it on every macOS; the functional probe is what fails closed if that ever changes.
diff --git a/packages/sandbox/sandbox-local/src/index.ts b/packages/sandbox/sandbox-local/src/index.ts
index 66f3077319..e1fa429b6d 100644
--- a/packages/sandbox/sandbox-local/src/index.ts
+++ b/packages/sandbox/sandbox-local/src/index.ts
@@ -23,14 +23,13 @@
  */
 
 import { spawnSync } from 'node:child_process'
-import { realpathSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { grantArgs as landlockGrantArgs, LAUNCHER_BIN, launcherPath as landlockLauncherPath, probe as defaultProbeLandlock } from 'node-addon-landlock-run'
+import { LAUNCHER_BIN, launcherPath as landlockLauncherPath, probe as defaultProbeLandlock } from 'node-addon-landlock-run'
 import { Context } from 'cordis'
 import z from 'schemastery'
 import { assertNever } from '@deepseek-ai/dsh-llm'
 import { SandboxProvider, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
 import type { ConfinedArgv, ConfinedSandboxMode, SandboxEnforcement, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
+import { bwrapProfileArgs, landlockProfileArgs, seatbeltProfileArgs } from './profiles.ts'
 
 /** Plugin config. All optional — `static Config` supplies the defaults. */
 export interface Config {
@@ -73,103 +72,6 @@ export interface Config {
   probeTimeoutMs?: number
 }
 
-/**
- * The `bwrap` profile arguments for one policy. The whole host tree is bound
- * read-only; a fresh `/dev` keeps `>/dev/null` redirects working and a fresh
- * `/proc` keeps process-inspecting tools working. `workspace-write`
- * additionally mounts an ephemeral writable `/tmp` and rebinds the workspace
- * root read-write (bind order matters: later binds overlay earlier ones).
- * Deliberately NO `--unshare-pid` (it would break the process-group kill
- * semantics shell consumers rely on) and NO network unsharing (the seam's
- * mode vocabulary promises file effects only).
- * @param policy - the file-effect policy to express as bwrap arguments.
- * @returns the bwrap profile arguments (before the trailing `--` + argv).
- */
-export function bwrapProfileArgs(policy: SandboxPolicy): string[] {
-  const args = ['--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--die-with-parent']
-  if (policy.mode === 'workspace-write') {
-    args.push('--tmpfs', '/tmp')
-    args.push('--bind', policy.workspaceRoot, policy.workspaceRoot)
-  }
-  return args
-}
-
-/**
- * The `landlock-run` grant arguments for one policy — the bwrap
- * profile's file-effect semantics expressed as a Landlock allow-list
- * (Landlock cannot mount, so there are no fresh/ephemeral filesystems). The
- * whole tree is readable and executable; of `/dev`, ONLY `/dev/null` is
- * writable — a whole-`/dev` grant would expose real host paths beneath it
- * (`/dev/shm`, a shared tmpfs) to persistent writes, which `read-only`
- * promises never happen. bwrap can hand out a fresh ephemeral `/dev`; on the
- * host's own `/dev` the write grant must be node-by-node, and `>/dev/null`
- * is the one redirects need. `workspace-write` adds the HOST `/tmp` (shared
- * and persistent, where bwrap's is ephemeral — the honest difference,
- * recorded in the sandbox RFC's runner notes) plus the workspace
- * root read-write. The flag spelling belongs to `node-addon-landlock-run`'s
- * `grantArgs`; this function owns only the policy → grants mapping.
- * @param policy - the file-effect policy to express as launcher grants.
- * @returns the launcher grant arguments (before `--` + argv).
- */
-export function landlockProfileArgs(policy: SandboxPolicy): string[] {
-  const readWrite = ['/dev/null']
-  if (policy.mode === 'workspace-write') {
-    readWrite.push('/tmp', policy.workspaceRoot)
-  }
-  return landlockGrantArgs({ readOnly: ['/'], readWrite })
-}
-
-/**
- * Resolve a granted root to the path the kernel actually sees. Seatbelt path
- * filters match the CANONICAL path (symlinks resolved), and the roots this
- * profile grants are symlinked on every macOS: `/tmp` is `/private/tmp` and
- * the user temp dir lives under `/var` → `/private/var` — an as-spelled
- * grant would match nothing.
- */
-function canonicalPath(path: string): string {
-  try {
-    return realpathSync(path)
-  } catch {
-    // realpathSync failed: the path (or a prefix) is missing or unreadable.
-    // Grant the spelling as-is — an unresolvable root matches nothing until
-    // it exists, which is the conservative outcome, and inventing a fallback
-    // resolution here would grant a path the caller never named.
-    return path
-  }
-}
-
-/** Quote one path as an SBPL string literal (backslashes and double quotes escaped). */
-function sbplString(path: string): string {
-  return `"${path.replaceAll('\\', String.raw`\\`).replaceAll('"', String.raw`\"`)}"`
-}
-
-/**
- * The `sandbox-exec` arguments for one policy: `-p` plus a Seatbelt (SBPL)
- * profile with the same file-effect semantics as the other dialects, built
- * as allow-default → `(deny file-write*)` → write allow-list (later rules
- * win), so exactly the mode's promised file effects are governed — network
- * and process visibility stay unrestricted, which is all the seam's mode
- * vocabulary claims. Of `/dev`, ONLY the `/dev/null` literal is writable
- * (the same node-not-directory reasoning as the Landlock grant).
- * `workspace-write` adds the workspace root, the host `/tmp`, and the
- * per-user darwin temp dir (`os.tmpdir()`, launchd's `TMPDIR`, inherited by
- * the confined child) — on darwin that directory IS the platform's `/tmp`
- * for every mkstemp-family tool, so omitting it would deny the mode's
- * promised temp area. All granted roots are canonicalized because Seatbelt
- * matches resolved paths ({@link canonicalPath}); duplicates after
- * resolution collapse.
- * @param policy - the file-effect policy to express as an SBPL profile.
- * @returns the `sandbox-exec` arguments (`-p` + profile, before `--` + argv).
- */
-export function seatbeltProfileArgs(policy: SandboxPolicy): string[] {
-  const forms = ['(version 1)', '(allow default)', '(deny file-write*)', `(allow file-write* (literal ${sbplString('/dev/null')}))`]
-  if (policy.mode === 'workspace-write') {
-    const roots = [...new Set([policy.workspaceRoot, '/tmp', tmpdir()].map(canonicalPath))]
-    forms.push(`(allow file-write* ${roots.map(root => `(subpath ${sbplString(root)})`).join(' ')})`)
-  }
-  return ['-p', forms.join(' ')]
-}
-
 /**
  * Functional `bwrap` probe: can it actually build the read-only profile on
  * this host? (`--version` alone would miss a disabled unprivileged user
diff --git a/packages/sandbox/sandbox-local/src/profiles.ts b/packages/sandbox/sandbox-local/src/profiles.ts
new file mode 100644
index 0000000000..9303583cbb
--- /dev/null
+++ b/packages/sandbox/sandbox-local/src/profiles.ts
@@ -0,0 +1,67 @@
+/**
+ * Internal platform-profile builders for the local sandbox provider.
+ *
+ * @module @deepseek-ai/dsh-sandbox-local/profiles
+ */
+
+import { realpathSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { grantArgs as landlockGrantArgs } from 'node-addon-landlock-run'
+import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
+
+/**
+ * Build the bwrap profile arguments for one file-effect policy.
+ * @param policy - file-effect policy to express as bwrap mounts.
+ * @returns profile arguments before the trailing separator and command argv.
+ */
+export function bwrapProfileArgs(policy: SandboxPolicy): string[] {
+  const args = ['--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--die-with-parent']
+  if (policy.mode === 'workspace-write') {
+    args.push('--tmpfs', '/tmp')
+    args.push('--bind', policy.workspaceRoot, policy.workspaceRoot)
+  }
+  return args
+}
+
+/**
+ * Build the Landlock launcher grants for one file-effect policy.
+ * @param policy - file-effect policy to express as Landlock allow-list grants.
+ * @returns launcher grant arguments before the trailing separator and command argv.
+ */
+export function landlockProfileArgs(policy: SandboxPolicy): string[] {
+  const readWrite = ['/dev/null']
+  if (policy.mode === 'workspace-write') {
+    readWrite.push('/tmp', policy.workspaceRoot)
+  }
+  return landlockGrantArgs({ readOnly: ['/'], readWrite })
+}
+
+/** Resolve a granted root to the canonical path the Seatbelt kernel sees. */
+function canonicalPath(path: string): string {
+  try {
+    return realpathSync(path)
+  } catch {
+    // Missing or unreadable roots stay as spelled; an unresolved root grants
+    // nothing until it exists, which is the conservative outcome.
+    return path
+  }
+}
+
+/** Quote one path as an SBPL string literal. */
+function sbplString(path: string): string {
+  return `"${path.replaceAll('\\', String.raw`\\`).replaceAll('"', String.raw`\"`)}"`
+}
+
+/**
+ * Build the sandbox-exec arguments and SBPL profile for one policy.
+ * @param policy - file-effect policy to express as an SBPL profile.
+ * @returns sandbox-exec arguments before the trailing separator and command argv.
+ */
+export function seatbeltProfileArgs(policy: SandboxPolicy): string[] {
+  const forms = ['(version 1)', '(allow default)', '(deny file-write*)', `(allow file-write* (literal ${sbplString('/dev/null')}))`]
+  if (policy.mode === 'workspace-write') {
+    const roots = [...new Set([policy.workspaceRoot, '/tmp', tmpdir()].map(canonicalPath))]
+    forms.push(`(allow file-write* ${roots.map(root => `(subpath ${sbplString(root)})`).join(' ')})`)
+  }
+  return ['-p', forms.join(' ')]
+}
diff --git a/packages/sandbox/sandbox-local/tests/bwrap.e2e.ts b/packages/sandbox/sandbox-local/tests/bwrap.e2e.ts
index da6e683da1..c5211adafb 100644
--- a/packages/sandbox/sandbox-local/tests/bwrap.e2e.ts
+++ b/packages/sandbox/sandbox-local/tests/bwrap.e2e.ts
@@ -6,7 +6,8 @@ import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
-import { bwrapProfileArgs, LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { bwrapProfileArgs } from '../src/profiles.ts'
 
 /**
  * KEYLESS bwrap integration proof for the BACKEND: the REAL `bwrap` confining
diff --git a/packages/sandbox/sandbox-local/tests/local.spec.ts b/packages/sandbox/sandbox-local/tests/local.spec.ts
index 852a50e1e9..e3aee5e32c 100644
--- a/packages/sandbox/sandbox-local/tests/local.spec.ts
+++ b/packages/sandbox/sandbox-local/tests/local.spec.ts
@@ -15,12 +15,10 @@ import { Context } from 'cordis'
 import { SANDBOX_UNAVAILABLE, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
 import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import {
-  bwrapProfileArgs,
-  landlockProfileArgs,
   LocalSandboxProvider,
-  seatbeltProfileArgs,
 } from '@deepseek-ai/dsh-sandbox-local'
 import type { Config } from '@deepseek-ai/dsh-sandbox-local'
+import { bwrapProfileArgs, landlockProfileArgs, seatbeltProfileArgs } from '../src/profiles.ts'
 
 const RO: SandboxPolicy = { mode: 'read-only', workspaceRoot: '/ws' }
 const WW: SandboxPolicy = { mode: 'workspace-write', workspaceRoot: '/ws' }
diff --git a/packages/sandbox/sandbox-local/tests/seatbelt.e2e.ts b/packages/sandbox/sandbox-local/tests/seatbelt.e2e.ts
index 7136e4e524..bc12750e10 100644
--- a/packages/sandbox/sandbox-local/tests/seatbelt.e2e.ts
+++ b/packages/sandbox/sandbox-local/tests/seatbelt.e2e.ts
@@ -6,7 +6,8 @@ import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
-import { LocalSandboxProvider, seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local'
+import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { seatbeltProfileArgs } from '../src/profiles.ts'
 
 /**
  * KEYLESS Seatbelt integration proof for the BACKEND: the REAL macOS

From 0c88df78b209b2e234f65006ae0c7cced8ffc5f6 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 14 Jul 2026 04:21:48 +0800
Subject: [PATCH 16/48] refactor: hide web provider helpers

---
 docs/config-catalog.md                                    | 8 ++++----
 packages/web/web-fetch-local/src/index.ts                 | 2 --
 packages/web/web-fetch-local/tests/fetch-local.spec.ts    | 3 ++-
 packages/web/web-search-deepseek/src/index.ts             | 2 --
 packages/web/web-search-deepseek/tests/deepseek.spec.ts   | 3 +--
 packages/web/web-search-exa/src/index.ts                  | 2 --
 packages/web/web-search-exa/tests/exa.spec.ts             | 3 ++-
 packages/web/web-search-perplexity/src/index.ts           | 2 --
 .../web/web-search-perplexity/tests/perplexity.spec.ts    | 2 +-
 9 files changed, 10 insertions(+), 17 deletions(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 8dec62dce6..8a95859675 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1068,7 +1068,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-fetch-local/src/index.ts:34`](../packages/web/web-fetch-local/src/index.ts)
+Source: [`packages/web/web-fetch-local/src/index.ts:32`](../packages/web/web-fetch-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-search-deepseek`
 
@@ -1092,7 +1092,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-search-deepseek/src/index.ts:48`](../packages/web/web-search-deepseek/src/index.ts)
+Source: [`packages/web/web-search-deepseek/src/index.ts:46`](../packages/web/web-search-deepseek/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-search-exa`
 
@@ -1114,7 +1114,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-search-exa/src/index.ts:39`](../packages/web/web-search-exa/src/index.ts)
+Source: [`packages/web/web-search-exa/src/index.ts:37`](../packages/web/web-search-exa/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-search-perplexity`
 
@@ -1136,7 +1136,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-search-perplexity/src/index.ts:33`](../packages/web/web-search-perplexity/src/index.ts)
+Source: [`packages/web/web-search-perplexity/src/index.ts:31`](../packages/web/web-search-perplexity/src/index.ts)
 
 ## `@deepseek-ai/dsh-workflow-workerthread`
 
diff --git a/packages/web/web-fetch-local/src/index.ts b/packages/web/web-fetch-local/src/index.ts
index 713de4c88a..4ba7cc0b6c 100644
--- a/packages/web/web-fetch-local/src/index.ts
+++ b/packages/web/web-fetch-local/src/index.ts
@@ -18,8 +18,6 @@ export {
   LocalFetchProvider,
 } from './provider.ts'
 export type { LocalFetchLimits } from './provider.ts'
-export { classifyContentType, decoderForCharset, isSameOrigin, parseCharset, validateFetchUrl } from './policy.ts'
-export type { FetchableKind } from './policy.ts'
 
 /** Default `User-Agent`: an explicit product agent, never a browser disguise. */
 export const DEFAULT_USER_AGENT = 'deepseek-harness/0.0.1 (+https://github.com/deepseek-ai)'
diff --git a/packages/web/web-fetch-local/tests/fetch-local.spec.ts b/packages/web/web-fetch-local/tests/fetch-local.spec.ts
index e3eb7d30c7..3d31cd6bf2 100644
--- a/packages/web/web-fetch-local/tests/fetch-local.spec.ts
+++ b/packages/web/web-fetch-local/tests/fetch-local.spec.ts
@@ -3,9 +3,10 @@ import { createServer, type IncomingMessage, type Server, type ServerResponse }
 import { AddressInfo } from 'node:net'
 import { Context } from 'cordis'
 import WebService from '@deepseek-ai/dsh-web'
-import { LocalFetchProvider, LOCAL_FETCH_PROVIDER_ID, classifyContentType, decoderForCharset, isSameOrigin, parseCharset, validateFetchUrl } from '@deepseek-ai/dsh-web-fetch-local'
+import { LocalFetchProvider, LOCAL_FETCH_PROVIDER_ID } from '@deepseek-ai/dsh-web-fetch-local'
 import type { LocalFetchLimits } from '@deepseek-ai/dsh-web-fetch-local'
 import * as fetchPlugin from '@deepseek-ai/dsh-web-fetch-local'
+import { classifyContentType, decoderForCharset, isSameOrigin, parseCharset, validateFetchUrl } from '../src/policy.ts'
 
 const limits: LocalFetchLimits = {
   maxUrlLength: 2048,
diff --git a/packages/web/web-search-deepseek/src/index.ts b/packages/web/web-search-deepseek/src/index.ts
index 2c3f0ede3b..a36dc7817e 100644
--- a/packages/web/web-search-deepseek/src/index.ts
+++ b/packages/web/web-search-deepseek/src/index.ts
@@ -33,8 +33,6 @@ export {
   DEEPSEEK_DEFAULT_MAX_USES,
   DEEPSEEK_DEFAULT_MODEL,
   DEEPSEEK_PROVIDER_ID,
-  citationSnippets,
-  mapAnthropicResponse,
 } from './provider.ts'
 export type { DeepSeekSearchProviderOptions } from './provider.ts'
 
diff --git a/packages/web/web-search-deepseek/tests/deepseek.spec.ts b/packages/web/web-search-deepseek/tests/deepseek.spec.ts
index 12ee4ba55a..0a49286df8 100644
--- a/packages/web/web-search-deepseek/tests/deepseek.spec.ts
+++ b/packages/web/web-search-deepseek/tests/deepseek.spec.ts
@@ -4,11 +4,10 @@ import Loader from '@cordisjs/plugin-loader'
 import WebService from '@deepseek-ai/dsh-web'
 import {
   DeepSeekSearchProvider,
-  citationSnippets,
-  mapAnthropicResponse,
   DEEPSEEK_PROVIDER_ID,
 } from '@deepseek-ai/dsh-web-search-deepseek'
 import * as deepseekPlugin from '@deepseek-ai/dsh-web-search-deepseek'
+import { citationSnippets, mapAnthropicResponse } from '../src/provider.ts'
 import type { AnthropicResponse } from '@deepseek-ai/dsh-web-search-deepseek/src/types.ts'
 
 const options = {
diff --git a/packages/web/web-search-exa/src/index.ts b/packages/web/web-search-exa/src/index.ts
index fc284dd79a..67b2eed574 100644
--- a/packages/web/web-search-exa/src/index.ts
+++ b/packages/web/web-search-exa/src/index.ts
@@ -24,8 +24,6 @@ export {
   EXA_DEFAULT_SEARCH_TYPE,
   EXA_PROVIDER_ID,
   ExaSearchProvider,
-  mapExaResponse,
-  mapExaResult,
 } from './provider.ts'
 export type { ExaSearchProviderOptions } from './provider.ts'
 
diff --git a/packages/web/web-search-exa/tests/exa.spec.ts b/packages/web/web-search-exa/tests/exa.spec.ts
index cf66ea67f9..40c7afda6f 100644
--- a/packages/web/web-search-exa/tests/exa.spec.ts
+++ b/packages/web/web-search-exa/tests/exa.spec.ts
@@ -1,8 +1,9 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import WebService from '@deepseek-ai/dsh-web'
-import { ExaSearchProvider, mapExaResponse, mapExaResult, EXA_PROVIDER_ID } from '@deepseek-ai/dsh-web-search-exa'
+import { ExaSearchProvider, EXA_PROVIDER_ID } from '@deepseek-ai/dsh-web-search-exa'
 import * as exaPlugin from '@deepseek-ai/dsh-web-search-exa'
+import { mapExaResponse, mapExaResult } from '../src/provider.ts'
 
 const options = { apiKey: 'exa-key', baseURL: 'https://api.exa.test', searchType: 'auto' as const, highlightsPerResult: 1 }
 
diff --git a/packages/web/web-search-perplexity/src/index.ts b/packages/web/web-search-perplexity/src/index.ts
index b71d5052d6..d673f575c8 100644
--- a/packages/web/web-search-perplexity/src/index.ts
+++ b/packages/web/web-search-perplexity/src/index.ts
@@ -18,8 +18,6 @@ export {
   PERPLEXITY_DEFAULT_MODEL,
   PERPLEXITY_PROVIDER_ID,
   PerplexitySearchProvider,
-  mapPerplexityResponse,
-  mapPerplexityResult,
 } from './provider.ts'
 export type { PerplexityRecency, PerplexitySearchProviderOptions } from './provider.ts'
 
diff --git a/packages/web/web-search-perplexity/tests/perplexity.spec.ts b/packages/web/web-search-perplexity/tests/perplexity.spec.ts
index e769989d73..9662226bc6 100644
--- a/packages/web/web-search-perplexity/tests/perplexity.spec.ts
+++ b/packages/web/web-search-perplexity/tests/perplexity.spec.ts
@@ -3,10 +3,10 @@ import { Context } from 'cordis'
 import WebService from '@deepseek-ai/dsh-web'
 import {
   PerplexitySearchProvider,
-  mapPerplexityResponse,
   PERPLEXITY_PROVIDER_ID,
 } from '@deepseek-ai/dsh-web-search-perplexity'
 import * as perplexityPlugin from '@deepseek-ai/dsh-web-search-perplexity'
+import { mapPerplexityResponse } from '../src/provider.ts'
 
 const options = { apiKey: 'pplx-key', baseURL: 'https://api.perplexity.test', model: 'sonar', maxTokens: 1024 }
 

From 19504f7e342f1c0f534eb3a2fe43648ee33c3ea9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 14 Jul 2026 22:38:17 +0800
Subject: [PATCH 17/48] fix(i18n): resolve pairing workflow review findings

---
 .agents/skills/dsh-translate-docs/SKILL.md    |   7 +-
 README.i18n.yaml                              |   2 +-
 README.zh.md                                  |   2 +-
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |   2 +-
 docs/development.zh.md                        |   2 +-
 docs/i18n/README.i18n.yaml                    |   4 +-
 docs/i18n/README.md                           |   4 +-
 docs/i18n/README.zh.md                        |   9 +-
 docs/i18n/style-samples.md                    |  20 +-
 docs/i18n/terminology.md                      |   7 +-
 docs/i18n/translation-prompt.md               | 193 ++++++++----------
 docs/i18n/translation-rules.i18n.yaml         |   4 +-
 docs/i18n/translation-rules.md                |  20 +-
 docs/i18n/translation-rules.zh.md             |  30 +--
 ...-bilingual-docs-and-pairing-gate.i18n.yaml |   4 +-
 ...6-07-02-bilingual-docs-and-pairing-gate.md |   4 +-
 ...7-02-bilingual-docs-and-pairing-gate.zh.md |   6 +-
 scripts/verify-translation-pairing.ts         |  43 +++-
 19 files changed, 195 insertions(+), 172 deletions(-)

diff --git a/.agents/skills/dsh-translate-docs/SKILL.md b/.agents/skills/dsh-translate-docs/SKILL.md
index 553cf6f9d1..401e93a859 100644
--- a/.agents/skills/dsh-translate-docs/SKILL.md
+++ b/.agents/skills/dsh-translate-docs/SKILL.md
@@ -42,8 +42,9 @@ Do not process every file the same way:
 - **Pass 1 — write, don't transpose.** Read a semantic unit, then restate it as a native technical author in the nearest [style sample's](../../../docs/i18n/style-samples.md) register. Preserve the required frame without forcing sentence-by-sentence correspondence.
 - **Pass 2 — verify against the source, clause by clause.** Fidelity is checked here, not written in: confirm nothing was added or dropped, every term follows the table, and each code span survived verbatim. Fix by rewriting the sentence natively, not by patching words into it.
 - Write only the final text to the file, never drafts or notes.
-- Every term in [terminology.md](../../../docs/i18n/terminology.md) renders exactly as specified, in both directions, including first-occurrence annotations. A term the table misses: translate only with a citable precedent from a major Chinese OSS/vendor doc; otherwise keep the English and add it to the PR's 「待定术语」 list with your suggested rendering. Never invent a rendering inline — that decision belongs to a human and then to the table.
+- Every term in [terminology.md](../../../docs/i18n/terminology.md) renders exactly as specified. For a Chinese target, use the Chinese and first-occurrence columns; an unlisted term needs a citable Chinese OSS/vendor precedent or stays English under 「待定术语」. For an English target, use the English column and an established English technical term; preserve an ambiguous source term with a short gloss and list it as pending. Never invent a rendering inline.
 - Code blocks are byte-identical across the pair, comments included. Relative links keep their `.md` targets; only the switcher line links `.zh.md`.
+- The pairing gate checks heading depths, fenced blocks, table column counts, list kinds, and link targets. In Pass 2, manually verify list item counts and numbering, table row counts and order, inline code, emphasis, meaning, terminology, and tone.
 
 ## Finish the pair
 
@@ -51,9 +52,9 @@ Do not process every file the same way:
 2. Record consistency: `pnpm run verify-translation-pairing --write` recomputes and records both sides' full blob hashes in `foo.i18n.yaml`. The yaml diff in your PR is the reviewable statement "I confirmed these two say the same thing" — only run it after you actually have.
 3. New batch landed? Add the `.md` paths to `required` in [scripts/translation-pairing.manifest.json](../../../scripts/translation-pairing.manifest.json) so the gate ratchets forward.
 
-## Verify — the gate, not your eyes
+## Verify the mechanical and human halves
 
-Run `pnpm run verify-translation-pairing`, then the rest of the Markdown gates (`pnpm run verify-md-wrap && pnpm run verify-md-links`, or full `pnpm run doc-sync` before the PR). Fix what they report; do not hand-check what they cover. What they can NOT check — whether the two sides truly say the same thing, terminology judgment calls, tone — is exactly what the PR reviewer will read for, so keep the PR reviewable: state which pairs are new vs minimally updated, and list 「待定术语」 prominently.
+Run `pnpm run verify-translation-pairing`, then the rest of the Markdown gates (`pnpm run verify-md-wrap && pnpm run verify-md-links`, or full `pnpm run doc-sync` before the PR). Fix what they report and manually verify the obligations listed in Pass 2 that the gates do not encode. Keep the PR reviewable: state which pairs are new versus minimally updated and list 「待定术语」 prominently.
 
 ## How to respond to translation review
 
diff --git a/README.i18n.yaml b/README.i18n.yaml
index 37a95ccdac..790812344d 100644
--- a/README.i18n.yaml
+++ b/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
 README.md: 53dd3896eb15800125673e7c44f7de02daca9376
-README.zh.md: 2119dabf0ae2d2e16e274e44fda7cbbaec146dc9
+README.zh.md: ab826f62658248249ec18c57b35c0065c0f909d1
diff --git a/README.zh.md b/README.zh.md
index 2119dabf0a..ab826f6265 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-**DeepSeek Harness SDK** 是用于构建 agent harness 的 SDK，采取基于插件的设计。
+**DeepSeek Harness SDK** 是用于构建 agent harness（智能体框架）的 SDK，采取基于插件的设计。
 
 ## 开发
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index cb4807c048..1768f29d8d 100644
--- a/docs/development.i18n.yaml
+++ b/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: 376df72c14b59b8ac8e42b31f19442040d6a47a7
-development.zh.md: 676df50a8a1ab2eff3ec829b5d55904626fa3f5e
+development.md: ca821f74461719a0f43ba4ea30eac8f5fb9b2bae
+development.zh.md: 0d5c07d5f10e20f2632d353f6257e928b7c999a6
diff --git a/docs/development.md b/docs/development.md
index 376df72c14..ca821f7446 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -19,7 +19,7 @@ Install dependencies from the repo root:
 pnpm install
 ```
 
-The install also runs the root `postinstall` script, which installs lefthook from the repo dev dependency through `scripts/install-lefthook.mjs`; the wrapper uses lefthook's reviewed `--force` mode so linked worktrees with an existing `core.hooksPath` do not fail normal `pnpm run …` commands.
+The install also runs the root `postinstall` script, which installs lefthook from the repo dev dependency through `scripts/install-lefthook.mjs`; the wrapper script uses lefthook's reviewed `--force` mode so linked worktrees with an existing `core.hooksPath` do not fail normal `pnpm run …` commands.
 
 If hooks are missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 676df50a8a..0d5c07d5f1 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -58,7 +58,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 
 lefthook 在 `lefthook.yml` 中配置，作为评审前的本地早期检查点：
 
-- `pre-commit` 运行对暂存文件的 ESLint 修复、`pnpm run typecheck` 和 vendor manifest 守卫；
+- `pre-commit` 运行对暂存文件的 ESLint 修复、`pnpm run typecheck` 和 vendor manifest（元数据清单）守卫；
 - `pre-push` 运行 `pnpm run check:pre-push`，其调度器并发运行单元测试、快照测试、构建、module-graph 新鲜度，以及 `pnpm run hygiene` 与 `pnpm run doc-sync` 的各成员门禁。
 
 vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。
diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index 43c64ddd90..7a076524cd 100644
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/README.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
-README.md: 3a5965ab60a7bdb6345b6abe6815f7090fa98fe1
-README.zh.md: 8e62b53ffefa25ad0bbf713889a2ec2ecdb7027a
+README.md: 38474b353820876c4ec859d3cea863f5ef82658f
+README.zh.md: e047680ad273a7066515de0b61c73b7e00ff96e3
diff --git a/docs/i18n/README.md b/docs/i18n/README.md
index 3a5965ab60..38474b3538 100644
--- a/docs/i18n/README.md
+++ b/docs/i18n/README.md
@@ -26,7 +26,7 @@ This repo's documentation is read by people and agents both inside and outside t
 1. Every file listed as `required` in [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) has a complete pair.
 2. Every pair that exists at all — required or not — is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table column counts, list kinds, and every link target apart from the switcher.
 3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all.
-4. Every date-named document (`yyyy-mm-dd-*.md`) dated on or after the manifest's `requiredSince` cutoff has a complete pair — new documents merge bilingual from birth.
+4. Every date-named document (`yyyy-mm-dd-*.md`) dated on or after the manifest's `requiredSince` cutoff has a complete pair — new date-named RFCs merge bilingual from birth.
 
 `pnpm run verify-translation-pairing --list` prints the current pairing state of every document in scope — missing, out-of-sync, or ok — and is the work list for translation batches. It never fails; it reports.
 
@@ -49,4 +49,4 @@ The gate's limit, stated plainly: **a green gate means the pair was confirmed co
 
 ## Division of labor
 
-Counterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate exists so that neither the agent nor the reviewer has to remember the contract: pair completeness, consistency, and structure are checked mechanically, and review attention goes to translation quality and terminology, where human judgment is the whole point.
+Counterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode.
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index 8e62b53ffe..e047680ad2 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此 README 与 docs 目录树以英文和简体中文双语维护。本页定义配对契约、强制门禁与推进策略；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。进仓的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。
+本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此 README 与 docs 目录树以英文和简体中文双语维护。本页定义配对契约、强制门禁与推进策略；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。
 
 ## 配对契约
 
@@ -21,11 +21,12 @@
 
 ## 门禁：verify-translation-pairing
 
-`pnpm run verify-translation-pairing`（`doc-sync` 的一环，因此 CI 和 pre-push 钩子都会运行）机械地强制执行这份契约：
+`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，因此 CI 和 pre-push 钩子都会运行）机械地强制执行这份契约：
 
 1. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 中 `required` 列出的每个文件都有完整配对。
 2. 任何已存在的配对——无论是否 required——都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致——标题深度、逐字节一致的代码块（信息字符串与内容）、表格列数、列表类型，以及除切换行之外的每个链接目标。
 3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。
+4. 日期等于或晚于 manifest（元数据清单）中 `requiredSince` 分界日期的每篇日期命名文档（`yyyy-mm-dd-*.md`）都有完整配对——新增的日期命名 RFC 从创建起就要求双语齐备。
 
 `pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态——missing、out-of-sync 或 ok——是翻译批次的工作清单。它从不失败；它只报告。
 
@@ -44,8 +45,8 @@
 - `docs/i18n/terminology.md` 与 [style-samples.md](style-samples.md)——二者本身即为中英对照文档。
 - [translation-prompt.md](translation-prompt.md)——自动翻译流水线的 prompt 模板；正文逐字进入模型请求，配对翻译会改变流水线行为。
 
-**推进**：以日期命名的文档（`yyyy-mm-dd-*.md`，即 RFC），只要标注日期等于或晚于 manifest 的 `requiredSince` 分界日期，合入时就必须配齐双语文件。更早日期的文件属于待翻清单（backlog），包括分界前夜创建的文件。RFC 文件名记录首次提出日期，因此倒填日期绕过分界属于评审可见的违规。manifest 中的 `required` 列表是当前执行红线，并非全量覆盖这一最终目标。翻译批次将路径加入 `required`，使门禁只向前收紧。未列入的文档仍可通过 `--list` 查看，而任何已存在的配对都受完整契约约束。后续修改必须同步更新两侧，因此 `required` 的扩展速度不能超过翻译评审的承载能力。
+**推进**：以日期命名的文档（`yyyy-mm-dd-*.md`，即 RFC），只要标注日期等于或晚于 manifest 的 `requiredSince` 分界日期，合入时就必须配齐双语文件。更早日期的文件属于 backlog（待翻清单），包括分界前夜创建的文件。RFC 文件名记录首次提出日期，因此倒填日期绕过分界属于评审可见的违规。manifest 中的 `required` 列表是当前执行红线，并非全量覆盖这一最终目标。翻译批次将路径加入 `required`，使门禁只向前收紧。未列入的文档仍可通过 `--list` 查看，而任何已存在的配对都受完整契约约束。后续修改必须同步更新两侧，因此 `required` 的扩展速度不能超过翻译评审的承载能力。
 
 ## 分工
 
-这里的对侧译文由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 产出、由人评审——在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁的存在让 agent 和评审者都不必记住契约：配对完整性、一致性和结构由机械检查兜底，评审注意力投向翻译质量与术语——这正是人的判断的用武之地。
+这里的对侧译文由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 产出、由人评审——在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁机械检查配对完整性、记录的 hash、切换行与文档所列的结构签名；翻译质量、术语以及签名未编码的结构要求仍由评审把关。
diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md
index e97cc331a9..df0a58af2a 100644
--- a/docs/i18n/style-samples.md
+++ b/docs/i18n/style-samples.md
@@ -1,8 +1,8 @@
 # 翻译语体样例（style samples）
 
-本文件是翻译语体的校准锚点：每组样例是一段英文原文与一段人工定稿的中文译文，覆盖本仓库文档的主要文体。**译文的语体以这些样例为准**——它们的效力高于任何对语气的文字描述。翻译或评审时对照最接近的文体样例；样例与规则冲突时，样例胜出。本文件中英对照、自成双语，不参与配对（见 [README.md](README.md) 排除清单）。
+本文件是翻译语体的校准锚点：每组样例是一段英文原文与一段人工定稿的中文译文，覆盖本仓库文档的主要文体。**译文的语体以这些样例为准**——文体样例的效力高于对语气的文字描述，但术语表、忠实性与结构规则仍然优先。翻译或评审时对照最接近的文体样例。本文件中英对照、自成双语，不参与配对（见 [README.md](README.md) 排除清单）。
 
-维护方式：人工评审校准出新的金标段落后追加到对应文体；样例只增不改，改动需评审人签字（PR 评审即签字）。
+维护方式：人工评审校准出新的金标段落后追加到对应文体；发现语义、结构或术语错误时直接修正。新增或修正样例都需经过 PR 评审。
 
 ## ① 架构叙述
 
@@ -16,7 +16,7 @@
 
 > This document covers **behavior**; type shapes live in [core-data-structures/](../core-data-structures/core.md), the per-event/service reference in the [generated catalog](../cordis-catalog/events.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
 
-本文档描述整体行为逻辑；类型定义存放于 [core-data-structures/](../core-data-structures/core.md)；各类事件、服务的详细参考见[生成目录](../cordis-catalog/events.md)；各 package 对外约束协议写在对应包的 README（[索引](../../packages/README.md)）。
+本文档描述整体行为逻辑；类型定义存放于 [core-data-structures/](../core-data-structures/core.md)；各类事件、服务的详细参考见[生成目录](../cordis-catalog/events.md)；各 package 的对外契约写在对应 package 的 README（[索引](../../packages/README.md)）。
 
 ## ② 防御模式规则
 
@@ -26,7 +26,7 @@
 
 > **Dispose must reach quiescence, not just request it** — A teardown that issues kills/aborts but returns before the work stops leaves orphans. Make cleanup async and await the children's exit (kill → await `done`), and close listener/notification registries BEFORE killing so late completions stay silent. Tests prove disposal waited (pid gone right after `await fiber.dispose()`), not merely that the process eventually dies.
 
-**销毁操作必须等待所有任务完全停稳，不能仅下发终止指令就返回**——若销毁逻辑仅发送终止、中断信号，但不等任务停止就直接退出，会产生孤儿进程。清理逻辑需设为异步，等待所有子任务彻底退出（先下发终止信号，再等待执行完成）；在执行终止操作前先关闭监听器与通知注册表，让延迟到达的完成事件不再触发任何通知。测试要验证销毁流程确实完成等待：执行完 `await fiber.dispose()` 后进程 PID 立即消失，不能仅校验进程最终会自行消亡。
+**dispose（资源释放）必须等待所有任务完全停稳，不能仅下发终止指令就返回**——若清理逻辑仅发送终止、中断信号，但不等任务停止就直接退出，会产生孤儿进程。清理逻辑需设为异步，等待所有子任务彻底退出（先下发终止信号，再等待执行完成）；在执行终止操作前先关闭监听器与通知注册表，让延迟到达的完成事件不再触发任何通知。测试要验证 dispose 确实完成等待：执行完 `await fiber.dispose()` 后进程 PID 立即消失，不能仅校验进程最终会自行消亡。
 
 > **Async state is not synchronous state** — `agent.send()` does not flip status before returning; a background task's completion races turn boundaries; `reader.close()` fires for both EOF and disposal. Never gate control flow on a status you only just requested — drive lifecycle off the events/promises that actually fire (`agent/status`, `task.done`), and observe the transition (saw `running` THEN `idle`) rather than counting actions you assume map 1:1 to turns.
 
@@ -40,15 +40,15 @@
 
 > We are DeepSeek — do not ration real-API tests. A no-key test proves the plumbing; only a with-key run proves the agent works against a real model. Write many: real prompts that write files, multi-turn conversations, tool use, cancellation mid-stream. Cheapest and highest-value are **smoke tests** that boot the real example, send one real prompt, and check the world — they catch the "green unit tests, broken product" class that mocks structurally cannot. The self-skip exists only so secretless CI and keyless contributors aren't blocked; it is not a cost signal.
 
-我们是 DeepSeek：真实接口相关测试不得刻意缩减用例数量。无密钥测试仅能验证底层通路；只有携带有效密钥执行的用例，才能确认 agent 可正常对接真实模型。请大量编写此类测试：包含文件写入类真实提示词、多轮对话、工具调用、流式中途取消等场景。
+我们是 DeepSeek：真实接口相关测试不得刻意缩减用例数量。无密钥测试仅能验证底层通路；只有携带有效密钥执行的用例，才能确认 agent（智能体）可正常对接真实模型。请大量编写此类测试：包含文件写入类真实提示词、多轮对话、工具调用、流式中途取消等场景。
 
-成本最低、收益最高的是**冒烟测试**：拉起完整真实示例，发送一条真实提示并校验整体运行状态。这类用例能捕获一类问题——单元测试全部绿灯，但产品实际运行故障，单靠 mock 完全无法发现这类缺陷。
+成本最低、收益最高的是**冒烟测试**：拉起完整真实示例，发送一条真实提示，并检查文件、进程等外部可观察结果。这类用例能捕获一类问题——单元测试全部绿灯，但产品实际运行故障，单靠 mock 完全无法发现这类缺陷。
 
 自带自动跳过逻辑，仅用于保障无密钥 CI 环境、无权限贡献者不会被流程拦截，不代表可以以此为由削减真实接口测试投入。
 
 > **Prefer the real implementation over a mock** — Mock only the genuinely expensive or non-deterministic boundary (the LLM adapter, the network, the clock); keep everything downstream real. A hand-rolled stand-in proves the bridge moves bytes, not that the shipping tool behaves as asserted — the two drift while the test stays green.
 
-**优先使用真实实现，而非 mock 替身**——仅对开销极大、结果不确定的边界模块做 mock（LLM 适配器、网络、时钟），其余下游组件全部使用真实实现。手写的 mock 替身只能验证数据通路能传输字节，无法保证线上工具符合预期逻辑；长期下来业务逻辑与 mock 实现会出现偏差，但测试仍会显示通过。
+**优先使用真实实现，而非 mock 替身**——仅对开销极大、结果不确定的边界模块做 mock（LLM（大语言模型）适配器、网络、时钟），其余下游组件全部使用真实实现。手写的 mock 替身只能验证数据通路能传输字节，无法保证线上工具符合预期逻辑；长期下来业务逻辑与 mock 实现会出现偏差，但测试仍会显示通过。
 
 ## ④ 机制描述
 
@@ -60,7 +60,7 @@
 
 > The gate's limit, stated plainly: a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound. It checks hashes and shape; it cannot judge whether the two sides actually say the same thing — that is the reviewer's half of the contract. A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.
 
-明确门禁校验边界：门禁校验通过，仅代表两份文档哈希与结构完全匹配，不代表译文内容准确无误。门禁仅校验哈希与结构，无法判断双语表意是否统一——译文质量把关是评审人的责任。即便译文粗糙、表意偏差，只要哈希匹配，门禁就会放行，但这类 PR 绝不能通过人工评审。
+明确门禁校验边界：门禁校验通过，仅代表每侧文件的当前 blob hash 与伴随记录中的对应值一致，且两侧结构签名相符，不代表译文内容准确无误。门禁无法判断双语表意是否统一——译文质量把关是评审人的责任。即便译文粗糙、表意偏差，只要两侧当前 blob hash 各自匹配记录值，门禁就会放行，但这类 PR 绝不能通过人工评审。
 
 ## ⑥ RFC 论证
 
@@ -70,9 +70,9 @@
 
 ## ⑦ 推进策略（长段拆分示范）
 
-> **Rollout**: new documents don't wait for a batch — a date-named document dated on or after the manifest's `requiredSince` cutoff must merge with its pair, so everything new is bilingual from birth. For the back-catalog, the `required` list in the manifest is the enforcement frontier, not the goal. […] Pairing a document is a commitment: every later edit to either side must carry the counterpart along, so grow the frontier at the pace translation review is actually resourced, not ahead of it.
+> **Rollout**: date-named RFCs don't wait for a batch — one dated on or after the manifest's `requiredSince` cutoff must merge with its pair, so each new date-named RFC is bilingual from birth. For the back-catalog, the `required` list in the manifest is the enforcement frontier, not the goal. […] Pairing a document is a commitment: every later edit to either side must carry the counterpart along, so grow the frontier at the pace translation review is actually resourced, not ahead of it.
 
-**推进**：新增文档不再走批量分批翻译流程。以日期命名的文档，若其标注日期等于或晚于 manifest 里 `requiredSince` 分界时间，提交合入时必须配套对应的双语译文文件——所有新文档从创建起就要求中英双语齐备。针对存量旧文档：manifest 内的强制翻译列表只是当下执行红线，并非最终目标。（……）文档完成双语配对等同于一份长期约束承诺：后续只要修改任一版本，就必须同步更新对应另一语种文件。因此强制翻译范围的推进节奏，要匹配翻译评审实际可投入人力，切勿超前铺开。
+**推进**：新增的日期命名 RFC 不再走批量翻译流程。若其标注日期等于或晚于 manifest（元数据清单）里的 `requiredSince` 分界时间，提交合入时必须配套双语文件，因此每篇新的日期命名 RFC 从创建起就要求双语齐备。针对存量旧文档：manifest 内的强制翻译列表只是当下执行红线，并非最终目标。（……）文档完成双语配对等同于一份长期约束承诺：后续只要修改任一版本，就必须同步更新对应另一语种文件。因此强制翻译范围的推进节奏，要匹配翻译评审实际可投入人力，切勿超前铺开。
 
 ## 从样例提炼的要点
 
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index 69f0e170e0..33006493c1 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -33,7 +33,7 @@
 | English | 中文 | 首次出现 | 不要译作 | 备注 |
 |---|---|---|---|---|
 | agent | agent | agent（智能体） | | |
-| agent harness | agent harness | | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按 agent 行处理 |
+| agent harness | agent harness | agent harness（智能体框架） | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按对应组合词或 agent 行处理 |
 | agent loop | agent loop | agent loop（智能体循环） | | |
 | backlog | backlog | backlog（待翻清单） | | 仅在双语翻译语境里括注`待翻清单` |
 | blob hash | blob hash | | | `git hash-object` 的结果 |
@@ -77,6 +77,7 @@
 | backend | 后端 | | | |
 | background task | 后台任务 | | | |
 | block | 块 | | | |
+| build target | 构建目标 | | | |
 | cancel | 取消 | | | |
 | capability | 能力 | | | |
 | checkpoint | 检查点 | | | |
@@ -105,7 +106,7 @@
 | extension point | 扩展点 | | | 注意与 `seam` 区分 |
 | fail-fast | 快速失败 | | | |
 | fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |
-| fingerprint | 指纹 | | | i18n 配对机制用语：`.zh.md` 首行记录英文源 blob hash 的注释 |
+| fingerprint | 指纹 | | | 通用内容指纹；双语配对机制使用 sidecar record 记录两侧 blob hash |
 | finish reason | 结束原因 | | | |
 | foreground run | 前台运行 | | | |
 | freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |
@@ -171,3 +172,5 @@
 | vocabulary | 词汇 | | | |
 | wire format | 协议格式 | 协议格式（wire format） | | |
 | workflow | 工作流 | | | |
+| wrapper | 包装层 | | | 软件层或 SDK 包装层 |
+| wrapper script | 包装脚本 | | | 可执行脚本包装层 |
diff --git a/docs/i18n/translation-prompt.md b/docs/i18n/translation-prompt.md
index a300ef64f4..41f7902dbb 100644
--- a/docs/i18n/translation-prompt.md
+++ b/docs/i18n/translation-prompt.md
@@ -1,24 +1,24 @@
 # Translation prompt (pipeline asset)
 
-本文件是自动翻译流水线的 prompt 模板；自 `# Translation Prompt` 起的正文逐字进入模型请求，因此不参与双语配对（见 [README.md](README.md) 排除清单）。渲染时，[terminology.md](terminology.md) 整表填入 `{{terminology}}`。[style-samples.md](style-samples.md) 定义文体，模板内嵌的 Examples 仅抽样问题类型；两者冲突时以文体样例为准。修改本文件即修改翻译行为，需按正常 PR 评审。
+本文件是自动翻译流水线的 prompt 模板；自 `# Translation Prompt` 起的正文逐字进入模型请求，因此不参与双语配对（见 [README.md](README.md) 排除清单）。渲染时，[terminology.md](terminology.md) 整表填入 `{{terminology}}`。[style-samples.md](style-samples.md) 定义文体，模板内嵌的 Examples 仅抽样问题类型；术语表、忠实性与结构规则优先于样例，样例在这些硬约束内决定文体。修改本文件即修改翻译行为，需按正常 PR 评审。
 
 ## 占位符契约
 
-流水线渲染模板时替换以下占位符，除此之外不做任何文本处理：
+流水线渲染模板时替换以下占位符，除此之外不改写系统消息：
 
 | 占位符 | 填入内容 | 来源 |
 |---|---|---|
 | `{{source_lang}}` | 源语言名（`English` / `Chinese`） | 由改动侧文件推断：`.zh.md` 被改则为 `Chinese` |
 | `{{target_lang}}` | 目标语言名（`Chinese` / `English`） | 与 `{{source_lang}}` 相对 |
 | `{{terminology}}` | [terminology.md](terminology.md) 的完整表格（Markdown 原文） | 渲染时读取仓库当前版本，不缓存 |
-| `{{source_filename}}` | 源文档的 basename（如 `foo.md`） | 由流水线从待译文件路径取得 |
-| `{{source_filename_zh}}` | 中文侧 basename（如 `foo.zh.md`） | 由 `{{source_filename}}` 派生 |
+| `{{source_filename}}` | 源文档的 basename（如 `foo.md` 或 `foo.zh.md`） | 由流水线从待译文件路径取得 |
+| `{{source_filename_zh}}` | 中文侧 basename（如 `foo.zh.md`） | 英文源追加 `.zh`；中文源使用自身 basename |
 
-流水线仅支持上表占位符，并按整篇文档翻译。它不支持 `{{to}}`、`{{title_prompt}}`、`{{summary_prompt}}`、`{{terms_prompt}}`、`{{imt_style_guide}}` 或 `%%` 分段协议；输出采用下方三段 XML。
+流水线仅支持上表占位符，并按整篇文档翻译。它不支持 `{{to}}`、`{{title_prompt}}`、`{{summary_prompt}}`、`{{terms_prompt}}`、`{{imt_style_guide}}` 或 `%%` 分段协议。输出是一个以 `<dsh-translation-response>` 为根元素的 XML 文档，三个子元素的任意 Markdown 内容都放在 CDATA 中；内容出现 `]]>` 时写成 `]]]]><![CDATA[>`，XML 解析后仍得到原文。
 
 ## Few-shot 金标
 
-流水线的 few-shot 是**整文档级**的中英对照，不是模板内嵌的句子级正误例（那是最小抽样）。few-shot 集取自以下 5 组人工定稿的配对文档，以仓库当前版本为准、随仓库更新：
+流水线的 few-shot 是**整文档级**的中英对照，不是模板内嵌的句子级正误例。few-shot 集取自以下 5 组经人工评审的配对文档，以仓库当前版本为准、随仓库更新：
 
 - `README.md` ↔ `README.zh.md`
 - `docs/development.md` ↔ `docs/development.zh.md`
@@ -26,131 +26,108 @@
 - `docs/i18n/translation-rules.md` ↔ `docs/i18n/translation-rules.zh.md`
 - `docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md` ↔ 对应 `.zh.md`
 
-注入方式：在系统消息（本模板）之后、待译文档之前，每组作为一轮示例对话——user 消息为源文档全文，assistant 消息为定稿译文全文（不带三段 XML 包装；只有真实请求要求三段输出）。上下文紧张时按上列顺序从后往前裁剪组数。这 5 组也是评审校准锚点（见 [style-samples.md](style-samples.md)），改动任何一组即改变流水线行为。
+注入时按当前翻译方向选择每组的源侧与目标侧：user 消息为源文档全文，assistant 消息使用模板正文规定的同一 XML 协议；`translation` 与 `final` 都放目标文档全文，`review` 为 `- [None] No corrections.`。CDATA 使用上文的 `]]>` 拆分规则。上下文紧张时按上列顺序从后往前裁剪组数。这 5 组也是评审校准锚点；改动任何一组即改变流水线行为。
 
 ## 模板正文
 
 ````text
 # Translation Prompt
 
-You are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the given source document from {{source_lang}} to {{target_lang}}, producing natural, professional technical prose.
+You are a senior technical translator specializing in LLM and agent development documentation. Translate the complete source document from {{source_lang}} to {{target_lang}} as natural, professional technical prose.
 
 ## Quality Requirements
 
 ### Structure and Format Preservation
-- Output a complete translated document that maintains exactly the same structure as the source: heading hierarchy, list shape, table columns, link targets, and code blocks.
-- Fenced code blocks must be byte-identical to the source, including ALL comments inside them. Do NOT translate comments inside code blocks. This is a hard rule with no exceptions.
-- Inline code spans (commands, flags, paths, API names, version numbers) must be kept verbatim. Never translate or reformat them.
-- Every relative link must point to the same target as in the source. Link text is translated; link targets are not.
-- Language switcher line: the source document's filename is `{{source_filename}}`. When translating into Chinese, write `[English]({{source_filename}}) | 中文` immediately after the H1 heading. When translating into English, write `English | [中文]({{source_filename_zh}})` immediately after the H1. Emit this line even when the source file has no switcher yet (a brand-new pair); when the source does have one, flip the link direction — never copy it unchanged.
-- After a closing bold marker `**`, insert a space before the next character when that character is a Latin letter or digit. Never insert a space before full-width (Chinese) punctuation.
+- Preserve the complete document frame: heading hierarchy, list item count and numbering, table row and column order, link targets, fenced code blocks, inline code spans, and emphasis spans.
+- Fenced code blocks must be byte-identical to the source, including every comment, info string, and line break. Never translate a code-block comment.
+- Inline code spans (commands, flags, paths, API names, event names, configuration keys, and version numbers) remain byte-identical and in the same order.
+- Every relative link keeps the same target. Translate link text, not link targets.
+- The source basename is `{{source_filename}}`. When translating into Chinese, write `[English]({{source_filename}}) | 中文` immediately after the H1. When translating into English, write `English | [中文]({{source_filename_zh}})` immediately after the H1. Emit the switcher for a new pair and flip an existing switcher; never copy it unchanged.
+- Preserve every source emphasis marker on the corresponding translated span. Do not add italics, bold, quotation marks, or other emphasis absent from the source.
+- After a closing bold marker `**`, add a half-width space only when the next character is a Latin letter or digit. Never add one before full-width punctuation.
 
-### Tone and Style
-- The translation must read as if originally written in the target language by a native speaker. If an expression sounds like a word-for-word rendering from the source language, rephrase it.
-- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.
-- Use polite imperative forms where the text instructs the reader to do something.
-- Keep the author's register: concise stays concise, detailed stays detailed.
-
-### Sentence Structure
-- Break long sentences with commas or semicolons. Avoid run-on sentences.
-- Prefer active voice. Convert passive constructions to active if it reads more naturally.
-- Translate meaning, not words. Restructure sentences where the target language grammar requires it.
-- Do not invent words or expressions that do not exist in natural technical writing of the target language.
-
-### Word Choice
-- Prefer precise, formal vocabulary over casual or colloquial alternatives.
-- When multiple synonyms exist, choose the one most commonly used in professional technical documentation of the target language.
-- Avoid slang, internal jargon, or overly literal translations that would not be recognized by the general developer audience.
-- Do not use the same word to translate two different source-language terms that carry distinct meanings.
-- Avoid repeating the same verb in close proximity; vary word choice for readability.
+### Faithfulness and Voice
+- Preserve every behavior, condition, prerequisite, warning, version claim, example, exception, and modal verb. Add none and drop none.
+- Write as a native technical author in the target language, not as a word-for-word translator. Restructure sentences where target-language grammar requires it while preserving the author's register.
+- Use precise, established developer terminology. Do not vary a term merely to avoid repetition, and do not collapse two distinct source concepts into one target term.
+- Do not add politeness, certainty, emphasis, rationale, or examples that the source does not contain.
 
 #### When translating into Chinese
-- When a number modifies a noun, always include a Chinese classifier or measure word (量词). For example: "three-package seam" → "由三个 package 构成的 seam", not "三 package seam".
-
-### Punctuation
-
-#### When translating into Chinese
-- Use full-width Chinese punctuation in prose: `，。：；？！（）「」`.
-- Strongly prefer replacing all em-dashes (——) with colons, periods, commas, or parentheses. Keep an em-dash only if no other punctuation works at all.
-- Use enumeration commas (、) between parallel items, not regular commas.
-- List item endings: use semicolons or no punctuation. Do not end list items with commas.
-- Put one half-width space between Chinese text and Latin words/numbers.
-- For RFC 2119 keywords (MUST, MUST NOT, SHOULD, MAY), render the corresponding Chinese term in italics: *必须*、*禁止*、*应当*、*可以*.
+- Use institutional technical Chinese: complete sentences, explicit actors where a passive would be vague, and established Chinese engineering idiom rather than calques.
+- When a number modifies a noun, include a natural classifier or measure word. Example: `three-package seam` → `由三个 package 构成的 seam`, not `三 package seam`.
+- Use full-width Chinese punctuation in prose: `，。：；？！（）「」`. Prefer colons, periods, commas, or parentheses over em dashes; use 顿号（、）between parallel items.
+- Put one half-width space between Chinese text and Latin words or numbers. Do not put spaces around full-width punctuation.
+- Render RFC 2119 keywords as 必须、禁止、应当、可以 while preserving the source emphasis exactly; plain source text remains plain.
 
 #### When translating into English
-- Use half-width English punctuation and standard English spacing. Preserve full-width punctuation only in verbatim Chinese text.
+- Use concise professional developer English. Replace Chinese topic-comment order, redundant subjects, and politeness padding with idiomatic English without dropping their meaning.
+- Use normal half-width English punctuation and spacing. Preserve full-width punctuation only inside verbatim Chinese text.
+- Render RFC 2119 keywords as MUST, MUST NOT, SHOULD, and MAY while preserving the source emphasis exactly.
+- Use direct English imperatives for instructions unless the source's politeness carries substantive meaning.
 
 ## Terminology
 
-A terminology table is provided below. Follow it strictly:
-- Render every listed term exactly as specified.
-- First occurrence: write as shown in the "首次出现" column (with parenthetical gloss). Subsequent occurrences: write only the part before the parentheses.
-- If a term has already been glossed as part of a compound term, do not gloss it again when it appears alone later.
-- NEVER use translations listed in the "不要译作" column.
-- For technical terms not in the table: keep them in the source language. Do not invent a translation. This rule applies to terminology only; for general prose, freely restructure and paraphrase for natural expression.
+The table below is binding:
+- For a Chinese target, use the `中文` column and apply the `首次出现` form once; later occurrences use the text before its parentheses.
+- For an English target, use the `English` column. Do not copy Chinese first-occurrence glosses into English prose.
+- Respect every `不要译作` prohibition in both directions.
+- For an unlisted term in a Chinese target, use a citable established Chinese OSS or vendor rendering and record the precedent in `<review>`; otherwise keep the English term and record it as `[Pending term]` with a suggested rendering.
+- For an unlisted term in an English target, use the established English technical term. If no unambiguous equivalent exists, preserve the source term with a short gloss and record it as `[Pending term]`.
+- Never invent a technical rendering inline.
 
 {{terminology}}
 
 ## Output Format
 
-Produce your output in three XML sections:
+Return exactly one well-formed XML document with this root and these three child elements. Do not wrap it in a Markdown code fence. Put all Markdown and review text inside CDATA. If any content contains the CDATA terminator, split it as `]]]]><![CDATA[>` so XML parsing reconstructs the original `]]>` sequence.
 
 ```xml
-<translation>
-(Complete translation of the source document)
-</translation>
-
-<review>
-(Self-review notes, one correction per line with category tag, e.g.)
-- [Tone] "旁挂记录" → "伴随记录"（生造词）
-- [Sentence] 第 3 段补充逗号断句
-- [Punctuation] 两处破折号替换为冒号
-- 无修正
-</review>
-
-<final>
-(Final translation after corrections)
-</final>
+<dsh-translation-response version="1">
+<translation><![CDATA[
+(Complete first-pass translation)
+]]></translation>
+<review><![CDATA[
+- [Tone] Replaced a literal rendering with the established target-language phrasing.
+- [Terminology] Applied the binding sidecar record term.
+]]></review>
+<final><![CDATA[
+(Complete corrected translation)
+]]></final>
+</dsh-translation-response>
 ```
 
 ## Self-Review Instructions
 
-After writing `<translation>`, re-read it in the target language only, without looking at the source. Check by category:
+After writing `<translation>`, re-read it in the target language without looking at the source. Then compare it with the source clause by clause and record actual corrections in English inside `<review>`.
 
 **Structure**
-- Is the heading hierarchy, list shape, and code block content identical to the source?
-- Are ALL comments inside code blocks left untranslated (byte-identical to source)?
-- Is the language switcher line correctly flipped (not copied from source)?
-- Are link targets preserved and bold markers followed by a space?
+- Do heading levels, list item counts and numbering, table rows and columns, links, code blocks, inline code spans, and emphasis spans correspond exactly?
+- Are all fenced code blocks byte-identical, comments included?
+- Is the language switcher present and pointed in the correct direction?
 
-**Tone & Style**
-- Does every sentence read as if originally written by a native speaker?
-- Is there any colloquial, casual, or overly informal phrasing?
+**Faithfulness**
+- Did every condition, warning, modal verb, exception, and example survive?
+- Did the translation add any claim, rationale, emphasis, or certainty absent from the source?
 
-**Sentence Structure**
-- Are there run-on sentences that need breaking?
-- Are there stiff passive constructions that should be converted to active voice?
-
-**Word Choice**
-- Are there overly literal translations that sound unnatural?
-- Is the same target-language word used to translate two distinct source concepts?
-- Is any slang or internal jargon present?
+**Tone and sentences**
+- Does every sentence read as native target-language developer documentation?
+- Are passive constructions, topic chains, or run-on sentences unnatural in the target language?
 
 **Terminology**
-- Are first-occurrence glosses correctly applied (not missing, not repeated)?
-- Are any "不要译作" forbidden translations present?
-- Are unlisted terms correctly kept in the source language?
+- Does every tabled term use the target-language column and avoid forbidden forms?
+- For a Chinese target, are first-occurrence glosses present once and only once?
+- Are unlisted terms handled under the direction-specific precedent and pending-term rules?
 
-**Punctuation** (when target is Chinese)
-- Are there em-dashes that should be replaced with colons, periods, or commas?
-- Are list items ending with commas instead of semicolons?
-- Are RFC 2119 keywords rendered in italics?
+**Punctuation**
+- For Chinese, are punctuation, mixed-script spacing, classifiers, and 顿号 correct?
+- For English, are punctuation and spacing idiomatic and free of Chinese-only padding?
+- Do RFC 2119 keywords preserve the source emphasis rather than adding italics?
 
-Record corrections in `<review>` with category tags. Then output the corrected version in `<final>`. If no corrections are needed, write "无修正" in `<review>` and copy the translation unchanged into `<final>`.
+Apply every recorded correction in `<final>`. If no correction is needed, write only `- [None] No corrections.` in `<review>` and copy `<translation>` unchanged into `<final>`.
 
 ## Examples
 
-Below are representative examples of common problems and their corrections. Follow the "Good" versions.
+Follow the Good versions; these sentence-level examples illustrate error categories, not the assistant-message wire format.
 
 ### Colloquial verb → Professional verb
 - Source: `The repo pins pnpm@11.7.0 in package.json`
@@ -172,40 +149,40 @@ Below are representative examples of common problems and their corrections. Foll
 - Bad: `旁挂记录两侧 blob hash，使一致性可检查`
 - Good: `伴随记录保存两侧 blob hash，使一致性可检查`
 
-### Em-dash → Colon/period
-- Source: `FIXME — an issue that should block a new release. A release should not ship with an open FIXME unless reviewers explicitly agree the change can be merged anyway.`
-- Bad: `FIXME——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 FIXME 出门。`
-- Good: `FIXME：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 FIXME。`
-
 ### Overly literal → Meaningful rendering
 - Source: `awkward phrasing is easier to hear without the source anchoring you`
 - Bad: `没有源文锚着，别扭的表述更容易被听出来`
 - Good: `不对照原文时，更容易察觉别扭的表达`
 
-### Terminology — do not translate what should be kept in English
+### Terminology — keep the binding English form
 - Source: `typed service seams, and explicit extension points`
 - Bad: `类型化的服务 seam（扩展点）与显式扩展点`
 - Good: `类型化的服务 seam 与显式扩展点`
 
-### Slang/jargon → Professional phrasing
+### Slang → Professional phrasing
 - Source: `The committed agent workflow lives in .agents/skills/dsh-translate-docs`
 - Bad: `进仓的 agent 工作流见 .agents/skills/dsh-translate-docs`
 - Good: `仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs`
 
-### "For humans" — translate the intent, not the word
-- Source: `For humans, start with the development guide`
-- Bad: `对于人工读者，请先从开发指南开始`（"人工读者"生硬）
-- Good: `面向开发者：请先阅读开发指南`（"开发者"自然，且中文里冒号在此处更自然）
+### Chinese → English — idiomatic subject and predicate
+- Source: `门禁绿并不代表译文内容正确。`
+- Bad: `The gate green does not represent that the translation content is correct.`
+- Good: `A green gate does not mean the translation is correct.`
 
-### Code block comments — NEVER translate
+### Code block comments — never translate
 - Source code block contains: `# REPL agent demo (needs DEEPSEEK_API_KEY)`
 - Bad: `# REPL agent 演示（需要 DEEPSEEK_API_KEY）`
-- Good: `# REPL agent demo (needs DEEPSEEK_API_KEY)` (keep exactly as-is, byte-for-byte)
+- Good: `# REPL agent demo (needs DEEPSEEK_API_KEY)` (byte-identical)
 
-### Language switcher — flip direction
-- Source file (English) has: `English | [中文](README.zh.md)`
-- Bad (copying source unchanged): `English | [中文](README.zh.md)`
-- Good (flipped for Chinese file): `[English](README.md) | 中文`
+### Language switcher — English to Chinese
+- Source: `English | [中文](README.zh.md)`
+- Bad: `English | [中文](README.zh.md)`
+- Good: `[English](README.md) | 中文`
+
+### Language switcher — Chinese to English
+- Source: `[English](README.md) | 中文`
+- Bad: `[English](README.md) | 中文`
+- Good: `English | [中文](README.zh.md)`
 
 ---
 
diff --git a/docs/i18n/translation-rules.i18n.yaml b/docs/i18n/translation-rules.i18n.yaml
index 048ce5eef7..7b4967d364 100644
--- a/docs/i18n/translation-rules.i18n.yaml
+++ b/docs/i18n/translation-rules.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
-translation-rules.md: 3e99aa5432ccd904f702238e9b802a9ed9bf6832
-translation-rules.zh.md: 1d8dcb04f1015af2db46c2e25b44f5cd147b6ecc
+translation-rules.md: b48b1680da2e7a9a4d744659339398af81d60308
+translation-rules.zh.md: 6e8f26509e1db104eb341668c3e77bd6ea0780e1
diff --git a/docs/i18n/translation-rules.md b/docs/i18n/translation-rules.md
index 3e99aa5432..b48b1680da 100644
--- a/docs/i18n/translation-rules.md
+++ b/docs/i18n/translation-rules.md
@@ -12,21 +12,21 @@ How to translate between the two sides of a documentation pair in this repo. Bot
 
 ## Voice
 
-- The register is calibrated by [style-samples.md](style-samples.md) — human-approved gold pairs, one per document genre. The counterpart MUST match the register of the nearest sample; where a sample and a prose rule here disagree, the sample wins. The target is institutional technical Chinese: complete sentences, declarative, neither chatty nor academic.
+- The register is calibrated by [style-samples.md](style-samples.md) — human-approved gold pairs, one per document genre. The counterpart MUST match the target-language side of the nearest sample; where its voice and a prose voice rule disagree, the sample wins. Chinese targets use institutional technical Chinese; English targets use concise professional developer prose.
 - Write as a native technical author restating the content, not as a translator transposing sentences. Then verify against the source clause by clause: nothing added, nothing dropped — fluency never justifies losing a clause.
-- Give sentences an explicit agent: where the English uses a passive or an abstract subject, name the actor (系统、门禁、评审人).
-- Prefer established Chinese engineering idiom over calques (误报／漏检 for false positive/negative, 执行红线 for enforcement frontier); localize metaphors instead of transplanting them, and unpack English noun chains into verb clauses.
+- Give sentences an explicit actor when the target language would otherwise obscure it; for Chinese, replace vague passives or abstract subjects with the actual actor (系统、门禁、评审人).
+- Prefer established target-language engineering idiom over calques (误报／漏检 for false positive/negative, 执行红线 for enforcement frontier); localize metaphors instead of transplanting them, and unpack noun chains where the target language requires it.
 - Split long paragraphs by semantic unit — one idea per paragraph. Paragraph boundaries MAY differ from the source; the structural signature does not count paragraphs.
-- Category nouns render in Chinese with a first-mention English annotation (实操手册（cookbook）); literal directory or file references stay code-formatted English.
+- When translating into Chinese, category nouns use Chinese with a first-mention English annotation (实操手册（cookbook）); when translating into English, use the conventional English category name. Literal directory or file references stay code-formatted English.
 
 ## Structure preservation
 
-Shape is enforced by the pairing gate, so the writer never trades fluency against it — write naturally inside the frame. The paired files MUST match one to one in:
+The pairing gate checks heading depths, fenced code blocks, table column counts, list kinds, and link targets. Preserve the rest of the frame manually; the paired files MUST match one to one in:
 
 - heading hierarchy (same levels, same order — heading TEXT is translated),
 - list shape and numbering,
 - tables (same columns, same row order; header cells translated per terminology),
-- fenced code blocks — **byte-identical, including comments**; code is part of the verified surface (` ```ts ` blocks compile under `doc-typecheck`), and an edited comment is drift the fence-count gate cannot see,
+- fenced code blocks — **byte-identical, including comments**; the pairing signature compares their info strings and contents, and ` ```ts ` blocks compile under `doc-typecheck`,
 - inline code spans (commands, flags, config keys, file paths, event names, API names, version numbers) — verbatim, never translated or reformatted,
 - links and anchors: every relative link MUST point at the same target in both files — by convention the `.md` path, not the `.zh.md` sibling — so links never dangle when one pair lands before its neighbors. The ONLY zh-specific link is the language switcher. Link TEXT is translated; the target is not.
 
@@ -34,9 +34,9 @@ The repo's Markdown conventions apply to `.zh.md` files unchanged: one physical
 
 ## Terminology
 
-- [terminology.md](terminology.md) is the source of truth in both directions. Before translating, load it; while translating, every term it lists MUST be rendered exactly as it specifies, including its first-occurrence annotations (e.g. `agent（智能体）` on first mention, plain `agent` after) and its "不要译作" prohibitions. When the Chinese side is authored first, the English counterpart uses the table's English column the same way.
-- A technical term NOT in the table MAY be translated only when a major Chinese-language OSS or vendor doc has an established rendering for it (K8s/Vue/MDN Chinese docs, 微软简中风格指南, big-tech project docs). Cite the precedent in the PR.
-- A term with NO established precedent MUST stay in English in the translation and MUST be listed in the PR description under 「待定术语」(pending terms) with a suggested rendering for the reviewer to decide. MUST NOT invent a Chinese rendering inline — an unprecedented translation creates exactly the ambiguity the terminology table exists to prevent. Decided terms then land in [terminology.md](terminology.md) in the same PR or a follow-up.
+- [terminology.md](terminology.md) is the source of truth in both directions. Before translating, load it; every listed term MUST follow its row and its "不要译作" prohibitions. A Chinese target uses the "中文" column and its "首次出现" annotation; an English target uses the "English" column without adding a Chinese gloss.
+- For a Chinese target, an unlisted technical term MAY use an established rendering from a major Chinese-language OSS or vendor source (K8s/Vue/MDN Chinese docs, 微软简中风格指南, big-tech project docs), cited in the PR. Without such precedent it MUST stay in English and be listed under 「待定术语」(pending terms) with a suggested rendering.
+- For an English target, use the established English technical term. If the source term has no unambiguous established equivalent, preserve it with a short explanatory gloss and list it under pending terms. Neither direction may invent a rendering inline; a decided term enters [terminology.md](terminology.md) in the same PR or a follow-up.
 
 ## Typography
 
@@ -54,7 +54,7 @@ These rules govern the Chinese side; the English side follows the repo's normal
 
 - A pair is done when a bilingual engineer reading either file alone gets everything a reader of the other gets — same facts, same caveats, same tone — and nothing extra.
 - Before handing off, self-check the result against this file and re-read the counterpart ALONE, without the source side by side; awkward phrasing is easier to hear without the source anchoring you.
-- The mechanical contract (consistency record, switcher, structure, wrap, links) is checked by `pnpm run verify-translation-pairing` and the rest of `doc-sync` — run them; do not hand-verify what a gate covers.
+- Run `pnpm run verify-translation-pairing` and the rest of `doc-sync` for records, switchers, heading depths, code blocks, table column counts, list kinds, links, and repository Markdown rules. Manually verify list item counts and numbering, table row counts and order, inline code, emphasis, meaning, terminology, and tone.
 
 ## References
 
diff --git a/docs/i18n/translation-rules.zh.md b/docs/i18n/translation-rules.zh.md
index 1d8dcb04f1..6e8f26509e 100644
--- a/docs/i18n/translation-rules.zh.md
+++ b/docs/i18n/translation-rules.zh.md
@@ -6,27 +6,27 @@
 
 ## 忠实性
 
-- 对侧文件*必须*传达与撰写侧相同的内容：不添加行为、前置条件、警告、版本声明或示例，也不漏掉任何一项。如果两侧在实质内容上不一致，没有哪种语言默认获胜；请修正错误的一侧，并在同一个变更里同步更新另一侧。
-- 对侧文件读起来*应当*是其语言自然的技术文字，而非逐词对照的译文。请根据语义翻译，在目标语言语法需要时重组句子，并保持原作者的语域（比如：简练的保持简练）。
+- 对侧文件必须传达与撰写侧相同的内容：不添加行为、前置条件、警告、版本声明或示例，也不漏掉任何一项。如果两侧在实质内容上不一致，没有哪种语言默认获胜；请修正错误的一侧，并在同一个变更里同步更新另一侧。
+- 对侧文件读起来应当是其语言自然的技术文字，而非逐词对照的译文。请根据语义翻译，在目标语言语法需要时重组句子，并保持原作者的语域（比如：简练的保持简练）。
 - 不要翻译不可译的内容：如果一句话依赖源语言的习语、无法自然转换，请翻译它的意思，而非习语本身。
 
 ## 行文
 
-- 语体以 [style-samples.md](style-samples.md) 为校准锚点——人工定稿的金标样例按文体各一组，译文必须对齐最接近的样例语体；样例与本文条款冲突时，以样例为准。目标语体是规范的技术制度文：完整主谓、确定语气，不口语化也不学术腔。
+- 语体以 [style-samples.md](style-samples.md) 为校准锚点——人工定稿的金标样例按文体各一组，译文必须对齐最接近样例的目标语言一侧；样例的语体与本文的语体规则冲突时，以样例为准。中文目标使用规范的技术制度文，英文目标使用简洁、专业的开发者文档语体。
 - 以母语技术作者的身份重述内容，而不是逐句转写的译者。写完后逐句对照原文核验：不添加、不遗漏——流畅永远不是丢掉语义成分的理由。
-- 给句子补显式执行主体：英文的被动句和抽象主语，中文写成「系统、门禁、评审人」等实际执行者做主语。
-- 优先使用中文工程惯用语而非直译（false positive/negative→误报／漏检、enforcement frontier→执行红线）；隐喻做本地化替换而不是移植，英文名词链展开为动词句。
+- 目标语言会模糊执行主体时，请补出实际执行者；翻译为中文时，将含糊的被动句或抽象主语改由「系统、门禁、评审人」等实际执行者做主语。
+- 优先使用目标语言的工程惯用语而非直译（false positive/negative→误报／漏检、enforcement frontier→执行红线）；隐喻做本地化替换而不是移植，并按目标语言需要展开名词链。
 - 长段按语义单元拆分，一段一件事。段落边界可以与原文不同；结构签名不比对段落数。
-- 类别名词说中文并在首现括注英文（实操手册（cookbook））；指目录或文件本身时保留代码体英文。
+- 翻译为中文时，类别名词使用中文并在首现括注英文（实操手册（cookbook））；翻译为英文时，使用通行的英文类别名。指目录或文件本身时保留代码体英文。
 
 ## 结构保持
 
-结构一致性由配对门禁负责校验，译者无需为保持结构而牺牲行文的流畅：在既定框架内自然书写即可。配对的两个文件必须在以下方面一一对应：
+配对门禁检查标题深度、围栏代码块、表格列数、列表类型与链接目标。其余框架由译者手工保持；配对的两个文件必须在以下方面一一对应：
 
 - 标题层级（相同级别、相同顺序；标题的**文字**要翻译）；
 - 列表形态与编号；
 - 表格（相同的列、相同的行序；表头单元格按术语表翻译）；
-- 围栏代码块：**逐字节一致，包括注释**。代码属于受验证的范围（` ```ts ` 块要通过 `doc-typecheck` 编译），而被改动的注释是代码块计数门禁看不见的漂移；
+- 围栏代码块：**逐字节一致，包括注释**。配对签名比对信息字符串与内容，` ```ts ` 块还要通过 `doc-typecheck` 编译；
 - 行内代码（命令、flag、配置键、文件路径、事件名、API 名、版本号）：原样保留，从不翻译或重排；
 - 链接与锚点：每个相对链接在两个文件中必须指向相同的目标（按约定是 `.md` 路径而非 `.zh.md` 兄弟文件），这样即使某对文档先于相邻文件落地，链接也不会悬空。唯一的 zh 特有链接是语言切换行。链接**文字**翻译；链接目标不翻。
 
@@ -34,18 +34,18 @@
 
 ## 术语
 
-- [terminology.md](terminology.md) 是双向的术语真源。翻译前请先加载它；翻译过程中，表内的每个术语都*必须*严格按表中规定的译法呈现，包括首次出现的括注（如首现写 `agent（智能体）`，之后写 `agent`）与「不要译作」的禁项。中文先行撰写时，英文对侧同样按表中英文列使用术语。
-- 表中**没有**的技术术语，只有当某个主要中文 OSS 或厂商文档已有成型译法时（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档）才*可以*翻译。请在 PR 中注明先例出处。
-- **没有**成型先例的术语，译文中*必须*保留英文，并且*必须*在 PR 描述的「待定术语」下列出，附上建议译法交评审者定夺。*禁止*就地发明中文译法，因为无先例的翻译恰恰会制造术语表要防止的歧义。确定下来的术语随后在同一个 PR 或后续 PR 中进入 [terminology.md](terminology.md)。
+- [terminology.md](terminology.md) 是双向的术语真源。翻译前请先加载它；表内术语必须遵守对应行与「不要译作」禁项。中文目标使用「中文」列及「首次出现」括注；英文目标使用「English」列，不添加中文括注。
+- 翻译为中文时，表中没有的技术术语只有在主要中文 OSS 或厂商资料已有成型译法时才可以翻译（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档），并在 PR 中注明出处。没有先例时必须保留英文，并在 PR 描述的「待定术语」中列出建议译法。
+- 翻译为英文时，使用已确立的英文技术术语。源术语没有明确的通行对应词时，保留原词并附简短说明，同时列入「待定术语」。两个方向都禁止就地发明译法；确定下来的术语在同一个 PR 或后续 PR 中进入 [terminology.md](terminology.md)。
 
 ## 排版
 
 本节规则约束中文一侧；英文一侧遵循仓库常规的 Markdown 约定（根 `AGENTS.md`）。以下中西文混排规则遵循 [MDN 简体中文翻译指南](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md)、[Kubernetes 中文本地化指南](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/)、[Vue.js 中文翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5) 与[中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)的跨项目共识，其根据是 [W3C clreq](https://www.w3.org/TR/clreq/) 与 GB/T 15834—2011：
 
-- *必须*在中文与拉丁词之间、中文与数字之间各留一个半角空格：`每个 plugin 注册 3 个 tool`。全角标点与任何字符之间不加空格。
-- 中文行文*必须*使用全角（中文）标点：`，。：；？！（）「」`。半角标点保留在代码内、按原样引用的完整英文句子内、以及数字内（`3.5`、`1,024`）。
+- 必须在中文与拉丁词之间、中文与数字之间各留一个半角空格：`每个 plugin 注册 3 个 tool`。全角标点与任何字符之间不加空格。
+- 中文行文必须使用全角（中文）标点：`，。：；？！（）「」`。半角标点保留在代码内、按原样引用的完整英文句子内、以及数字内（`3.5`、`1,024`）。
 - 顿号：中文的并列项之间使用顿号（、），而非逗号。
-- *禁止*使用全角数字或全角拉丁字母：永远不写 `１２３`，永远写 `123`。
+- 禁止使用全角数字或全角拉丁字母：永远不写 `１２３`，永远写 `123`。
 - 专有名词保持规范大小写：GitHub、TypeScript、DeepSeek。除非引用代码，否则绝不写 `github`／`Github`。
 - 第二人称用「你」，不用「您」（与 Vue、Kubernetes 中文约定及本仓库的直接语气一致）。
 - 强调标记（`**加粗**`、`*斜体*`）落在与对侧相同的文字段上。中文没有斜体，渲染效果可能看不出差别，不要用引号或其他装饰替代。
@@ -54,7 +54,7 @@
 
 - 一对文档的完成标准：一位双语工程师只读其中任一文件，能获得与另一文件读者完全相同的信息（相同的事实、相同的告诫、相同的语气），并且没有任何多余的内容。
 - 交付前，请对照本文自查一遍，并**单独通读对侧文件**，不与源侧对照；不对照原文时，更容易察觉别扭的表达。
-- 机械契约（一致性记录、切换行、结构、折行、链接）由 `pnpm run verify-translation-pairing` 和 `doc-sync` 的其余门禁检查。请运行门禁；门禁已覆盖的内容无需手工核对。
+- 请运行 `pnpm run verify-translation-pairing` 与 `doc-sync` 的其余门禁，检查一致性记录、切换行、标题深度、代码块、表格列数、列表类型、链接及仓库 Markdown 规则。列表项数量与编号、表格行数与顺序、行内代码、强调标记、语义、术语和语体仍需手工核对。
 
 ## 参考资料
 
diff --git a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
index f20250c3ba..7836b74c85 100644
--- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.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
-2026-07-02-bilingual-docs-and-pairing-gate.md: 1e96622e7fb5694ab61772d68744394ef1aeb53a
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: c752d76f12f556ce190bf80c4f3a531c0821be8e
+2026-07-02-bilingual-docs-and-pairing-gate.md: 68c0f3bbc0472b0c96f9d64fc6b1b24ac7008795
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: f93e3220fef720805c52023841f6f56f9e2834cf
diff --git a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
index 1e96622e7f..68c0f3bbc0 100644
--- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
+++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md
@@ -12,7 +12,7 @@ This repo's README and docs tree are read by people and agents inside and outsid
 
 - **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../i18n/terminology.md).
 - **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.
-- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: required pairs exist, every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical), and excluded (generated or bilingual-by-construction) files stay unpaired. The `required` list in [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) is a ratchet: each merged translation batch adds its files, so coverage only grows.
+- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: required pairs exist, every existing pair is complete (all three files) and consistent (both hashes match, switcher links both ways, structural signatures identical), excluded (generated or bilingual-by-construction) files stay unpaired, and date-named documents on or after the manifest's `requiredSince` cutoff have complete pairs. The `required` list in [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) is a ratchet: each merged translation batch adds its files, so coverage only grows.
 - **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../../.agents/skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth.
 
 ## Alternatives considered
@@ -34,5 +34,5 @@ Paired sibling files with locale suffixes are the dominant Chinese big-tech conv
 - Every pair adds a third file to the tree. The record is machine-written (`--write`), so the cost is directory noise, not maintenance effort; in exchange, "who confirmed these consistent, and when" is answerable from git blame on the yaml.
 - When the two sides disagree, no mechanical rule picks a winner — the PR review does. That is the price of equal authority, accepted deliberately: the alternative (a canonical language) forbids Chinese-first authoring.
 - Generated docs (`cordis-catalog/`, `tool-catalog/`, `module-graph.md`) are excluded for now; the planned follow-up is to teach their generators to emit Chinese alongside English, at which point they leave the exclusion list.
-- Rollout is incremental by design: documents outside `required` are visible backlog (`--list`), not red CI, so pairs land in reviewable batches without a big-bang PR. New documents are the exception — a date-named document dated on/after the manifest's `requiredSince` cutoff merges bilingual or not at all, so the backlog only ever shrinks.
+- Rollout is incremental by design: documents outside `required` are visible backlog (`--list`), not red CI, so pairs land in reviewable batches without a big-bang PR. A date-named document dated on or after the manifest's `requiredSince` cutoff merges bilingual or not at all, so new date-named RFCs do not enlarge that backlog.
 - The recorded hashes double as the update tool (`git cat-file -p <hash>` recovers either side's last-confirmed text for a minimal diff-based update), so re-translation of whole files is never forced by the mechanism.
diff --git a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
index c752d76f12..f93e3220fe 100644
--- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -12,8 +12,8 @@ Status: implemented
 
 - **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../i18n/terminology.md)。
 - **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR 内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。
-- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：required 的配对必须存在；任何已存在的配对必须完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）保持不配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单只进不退：每个合并的翻译批次将自己的文件加入其中，覆盖面只增不减。
-- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../../.agents/skills/dsh-code-review/SKILL.md) 模式相同：skill 承载工作流，并将文档作为真源。
+- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：required 的配对必须存在；任何已存在的配对必须完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）保持不配对；日期等于或晚于 manifest（元数据清单）中 `requiredSince` 分界日期的文档必须具有完整配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单只进不退：每个合并的翻译批次将自己的文件加入其中，覆盖面只增不减。
+- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../../.agents/skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。
 
 ## 曾考虑的替代方案
 
@@ -34,5 +34,5 @@ Status: implemented
 - 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。
 - 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。
 - 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让生成器在输出英文的同时输出中文，届时将这些文件移出排除清单。
-- 推进天然是渐进的：`required` 之外的文档是可见的 backlog（`--list`），而非红色的 CI；因此配对按可评审的批次落地，无需一个巨型 PR。
+- 推进天然是渐进的：`required` 之外的文档是可见的 backlog（待翻清单，`--list`），而非红色的 CI；因此配对按可评审的批次落地，无需一个巨型 PR。日期等于或晚于 manifest 中 `requiredSince` 分界日期的文档必须配齐双语文件，因此新增的日期命名 RFC 不会扩大这份 backlog。
 - 记录的 hash 兼作更新工具（`git cat-file -p <hash>` 能还原任一侧上次确认的文本，用于基于 diff 的最小更新），因此这套机制从不强迫整篇重译。
diff --git a/scripts/verify-translation-pairing.ts b/scripts/verify-translation-pairing.ts
index eaeacb34d2..29af0a7ec8 100644
--- a/scripts/verify-translation-pairing.ts
+++ b/scripts/verify-translation-pairing.ts
@@ -29,7 +29,48 @@ interface Manifest {
   /** Date-named documents (yyyy-mm-dd-*.md, i.e. RFCs) dated on/after this day must merge bilingual. */
   requiredSince: string
 }
-const manifest = JSON.parse(readFileSync(join(root, 'scripts/translation-pairing.manifest.json'), 'utf8')) as Manifest
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+
+/** Whether a string names one real calendar day in canonical ISO form. */
+function isIsoDate(value: string): boolean {
+  if (!ISO_DATE.test(value)) return false
+  const date = new Date(`${value}T00:00:00.000Z`)
+  return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value
+}
+
+/** Read one manifest string-array field or fail before enforcement starts. */
+function stringArrayField(record: Record<string, unknown>, field: 'required' | 'excluded'): string[] {
+  const value = record[field]
+  if (!Array.isArray(value)) {
+    throw new Error(`translation-pairing.manifest.json: ${field} must be an array of strings`)
+  }
+  const entries: unknown[] = value
+  if (!entries.every((entry): entry is string => typeof entry === 'string')) {
+    throw new Error(`translation-pairing.manifest.json: ${field} must be an array of strings`)
+  }
+  return entries
+}
+
+/** Parse and validate the checked-in bilingual manifest. */
+function parseManifest(content: string): Manifest {
+  const value: unknown = JSON.parse(content)
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error('translation-pairing.manifest.json: expected an object')
+  }
+  const record = value as Record<string, unknown>
+  const requiredSince = record.requiredSince
+  if (typeof requiredSince !== 'string' || !isIsoDate(requiredSince)) {
+    throw new Error(`translation-pairing.manifest.json: requiredSince must be a valid YYYY-MM-DD date; got ${JSON.stringify(requiredSince)}`)
+  }
+  return {
+    required: stringArrayField(record, 'required'),
+    excluded: stringArrayField(record, 'excluded'),
+    requiredSince,
+  }
+}
+
+const manifest = parseManifest(readFileSync(join(root, 'scripts/translation-pairing.manifest.json'), 'utf8'))
 
 /**
  * An excluded entry ending in `/` excludes the whole directory. The trailing

From 3caaa437977ec4e82af3c49f376cf8de04473897 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 14 Jul 2026 23:09:01 +0800
Subject: [PATCH 18/48] fix(i18n): make translation contracts executable

---
 .agents/skills/dsh-translate-docs/SKILL.md    |   4 +-
 docs/development.i18n.yaml                    |   4 +-
 docs/development.md                           |   2 +-
 docs/development.zh.md                        |   4 +-
 docs/i18n/README.i18n.yaml                    |   4 +-
 docs/i18n/README.md                           |   6 +-
 docs/i18n/README.zh.md                        |   8 +-
 docs/i18n/style-samples.md                    |   2 +-
 docs/i18n/translation-prompt.md               |  72 ++------
 docs/i18n/translation-rules.i18n.yaml         |   4 +-
 docs/i18n/translation-rules.md                |   4 +-
 docs/i18n/translation-rules.zh.md             |   4 +-
 ...-bilingual-docs-and-pairing-gate.i18n.yaml |   2 +-
 ...7-02-bilingual-docs-and-pairing-gate.zh.md |   2 +-
 eslint.config.mjs                             |   2 +-
 package.json                                  |   4 +-
 pnpm-lock.yaml                                |   3 +
 scripts/run-gates.ts                          |   1 +
 scripts/translation-pairing.spec.ts           |  95 ++++++++++
 scripts/translation-pairing.ts                | 164 +++++++++++++++++
 scripts/translation-prompt.spec.ts            |  67 +++++++
 scripts/translation-prompt.ts                 | 167 +++++++++++++++++
 scripts/verify-translation-pairing.ts         | 174 ++----------------
 scripts/verify-translation-prompt.ts          |  57 ++++++
 vitest.config.ts                              |   2 +-
 25 files changed, 615 insertions(+), 243 deletions(-)
 create mode 100644 scripts/translation-pairing.spec.ts
 create mode 100644 scripts/translation-pairing.ts
 create mode 100644 scripts/translation-prompt.spec.ts
 create mode 100644 scripts/translation-prompt.ts
 create mode 100644 scripts/verify-translation-prompt.ts

diff --git a/.agents/skills/dsh-translate-docs/SKILL.md b/.agents/skills/dsh-translate-docs/SKILL.md
index 401e93a859..d935c5c4b7 100644
--- a/.agents/skills/dsh-translate-docs/SKILL.md
+++ b/.agents/skills/dsh-translate-docs/SKILL.md
@@ -14,7 +14,7 @@ These are authoritative; read them at the source so this skill never drifts out
 - **[docs/i18n/README.md](../../../docs/i18n/README.md)** — the pairing contract: the three-file pair (`foo.md`, `foo.zh.md`, `foo.i18n.yaml`), the consistency record's both-side blob hashes, the language-switcher lines, scope/exclusions, and the rollout manifest.
 - **[docs/i18n/translation-rules.md](../../../docs/i18n/translation-rules.md)** — how to translate: faithfulness, structure preservation, terminology discipline, typography (MUST/SHOULD levels).
 - **[docs/i18n/terminology.md](../../../docs/i18n/terminology.md)** — the terminology table, binding in both directions. Load it BEFORE translating, not when a term feels uncertain; the terms you don't notice are the ones that drift.
-- **[docs/i18n/translation-prompt.md](../../../docs/i18n/translation-prompt.md)** — the automated pipeline's machine-consumed template. Agents using this skill do not render it; keep rules shared with this skill synchronized.
+- **[docs/i18n/translation-prompt.md](../../../docs/i18n/translation-prompt.md)** — the automated pipeline's machine-consumed template. Agents using this skill do not render it; the renderer injects `translation-rules.md` so rules have only one home.
 - **[dsh-prose-standard](../dsh-prose-standard/SKILL.md)** — required prose coverage and editorial judgment. Apply it to both sides without adding or dropping source propositions.
 
 ## Find the work
@@ -44,7 +44,7 @@ Do not process every file the same way:
 - Write only the final text to the file, never drafts or notes.
 - Every term in [terminology.md](../../../docs/i18n/terminology.md) renders exactly as specified. For a Chinese target, use the Chinese and first-occurrence columns; an unlisted term needs a citable Chinese OSS/vendor precedent or stays English under 「待定术语」. For an English target, use the English column and an established English technical term; preserve an ambiguous source term with a short gloss and list it as pending. Never invent a rendering inline.
 - Code blocks are byte-identical across the pair, comments included. Relative links keep their `.md` targets; only the switcher line links `.zh.md`.
-- The pairing gate checks heading depths, fenced blocks, table column counts, list kinds, and link targets. In Pass 2, manually verify list item counts and numbering, table row counts and order, inline code, emphasis, meaning, terminology, and tone.
+- The pairing gate checks heading depths, fenced blocks, table row and column counts, list kinds, ordered-list starts, list item counts, and link targets. In Pass 2, manually verify list and table order, noncanonical list numbering, inline code, emphasis, meaning, terminology, and tone.
 
 ## Finish the pair
 
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 1768f29d8d..494eb09922 100644
--- a/docs/development.i18n.yaml
+++ b/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: ca821f74461719a0f43ba4ea30eac8f5fb9b2bae
-development.zh.md: 0d5c07d5f10e20f2632d353f6257e928b7c999a6
+development.md: b3c338f03f548b4de4b676850732731323d611f1
+development.zh.md: 20f5c585dd378a7b0a3bd6b0af8ebf7dc5e0fd3c
diff --git a/docs/development.md b/docs/development.md
index ca821f7446..b3c338f03f 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -59,7 +59,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 lefthook is configured in `lefthook.yml` as an early local checkpoint before review:
 
 - `pre-commit` runs staged-file ESLint fixes, `pnpm run typecheck`, and the vendor manifest guard.
-- `pre-push` runs `pnpm run check:pre-push`, whose scheduler runs unit tests, snapshot tests, build, module-graph freshness, and the member gates of `pnpm run hygiene` and `pnpm run doc-sync` concurrently.
+- `pre-push` runs `pnpm run check:pre-push`, whose scheduler runs runtime-closure verification, unit tests, duplication detection, snapshot tests, build, module-graph freshness, and the member gates of `pnpm run hygiene` and `pnpm run doc-sync` concurrently.
 
 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.
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 0d5c07d5f1..20f5c585dd 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -9,7 +9,7 @@
 - Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 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 测试。
+- 可选：一个 DeepSeek API key，用于 REPL/ACP（Agent Client Protocol） agent（智能体）演示和真实 API 的 e2e 测试。
 
 ## 首次搭建
 
@@ -59,7 +59,7 @@ DEEPSEEK_BASE_URL=https://... # optional
 lefthook 在 `lefthook.yml` 中配置，作为评审前的本地早期检查点：
 
 - `pre-commit` 运行对暂存文件的 ESLint 修复、`pnpm run typecheck` 和 vendor manifest（元数据清单）守卫；
-- `pre-push` 运行 `pnpm run check:pre-push`，其调度器并发运行单元测试、快照测试、构建、module-graph 新鲜度，以及 `pnpm run hygiene` 与 `pnpm run doc-sync` 的各成员门禁。
+- `pre-push` 运行 `pnpm run check:pre-push`，其调度器并发运行 runtime-closure 校验、单元测试、重复代码检查、快照测试、构建、module-graph 新鲜度，以及 `pnpm run hygiene` 与 `pnpm run doc-sync` 的各成员门禁。
 
 vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。
 
diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index 7a076524cd..eee78b1168 100644
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/README.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
-README.md: 38474b353820876c4ec859d3cea863f5ef82658f
-README.zh.md: e047680ad273a7066515de0b61c73b7e00ff96e3
+README.md: 17bb1eeb67b4f5119a698fca23f12490c9378a7f
+README.zh.md: 2b44ad702c68c0bfb748b25a4f62252aa3dbdc98
diff --git a/docs/i18n/README.md b/docs/i18n/README.md
index 38474b3538..17bb1eeb67 100644
--- a/docs/i18n/README.md
+++ b/docs/i18n/README.md
@@ -17,14 +17,14 @@ This repo's documentation is read by people and agents both inside and outside t
 
   Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. The recorded hash also recovers the exact last-confirmed text of either side (`git cat-file -p <hash>`), so an out-of-sync pair is updated by diffing the edited side against its last-confirmed state and patching the counterpart minimally — never by re-translating whole files. After bringing the pair back in line, `pnpm run verify-translation-pairing --write` re-records both hashes; that yaml diff is the reviewable act of confirming consistency.
 - **Language switcher.** Both files link to each other immediately after their H1 heading: the English file carries `English | [中文](foo.zh.md)` and the Chinese file carries `[English](foo.md) | 中文`.
-- **Structure mirrors the counterpart.** Heading depths and order, list kinds, table columns, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).
+- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).
 
 ## The gate: verify-translation-pairing
 
 `pnpm run verify-translation-pairing` (part of `doc-sync`, so CI and the pre-push hook run it) enforces the contract mechanically:
 
 1. Every file listed as `required` in [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) has a complete pair.
-2. Every pair that exists at all — required or not — is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table column counts, list kinds, and every link target apart from the switcher.
+2. Every pair that exists at all — required or not — is complete and consistent: all three files present, each side's current blob hash equals the recorded one (editing either side without re-confirming the pair goes red), both sides carry the language switcher, and the structural signatures match in order — heading depths, verbatim code blocks (info string and content), table row and column counts, list kinds, ordered-list starts, item counts, and every link target apart from the switcher.
 3. Files listed as `excluded` have no `.zh.md` and no `.i18n.yaml` at all.
 4. Every date-named document (`yyyy-mm-dd-*.md`) dated on or after the manifest's `requiredSince` cutoff has a complete pair — new date-named RFCs merge bilingual from birth.
 
@@ -49,4 +49,4 @@ The gate's limit, stated plainly: **a green gate means the pair was confirmed co
 
 ## Division of labor
 
-Counterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode.
+Counterparts here are produced by an agent running [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) and reviewed by a human — inference is cheap here, review attention is the scarce resource. The gate checks pair completeness, recorded hashes, switchers, and its documented structural signature. Review still owns translation quality, terminology, and structural requirements that the signature does not encode. The prompt contract is executable: [scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) renders the canonical rules into either direction and strictly parses the three-field XML response, while `verify-translation-prompt` exercises both render directions, the checked-in example, and the CDATA split rule in `doc-sync`.
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index e047680ad2..2b44ad702c 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -7,7 +7,7 @@
 ## 配对契约
 
 - **两种语言同权。**一篇文档可以先用任一语言撰写和评审——先写中文的 RFC 与先写英文的一样正当——另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。
-- **一对文档是三个同目录文件。**英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对整体合入：PR 永远不会只带一种语言而缺其余两个文件。
+- **一对文档是三个同目录文件。**英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对整体合入：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。
 - **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：
 
   ```yaml
@@ -17,14 +17,14 @@
 
   用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。记录的 hash 还能还原任一侧上次确认时的确切文本（`git cat-file -p <hash>`），所以失去同步的配对是「把被改的一侧与其上次确认状态做 diff、再最小化地修补另一侧」——从不整篇重译。两侧对齐后，`pnpm run verify-translation-pairing --write` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审。
 - **语言切换行。**两个文件在各自 H1 标题之后立即互链：英文文件带 `English | [中文](foo.zh.md)`，中文文件带 `[English](foo.md) | 中文`。
-- **结构与另一侧一一对应。**标题深度与顺序、列表类型、表格列、链接目标与逐字节一致的代码块在配对两侧一一对应——完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。
+- **结构与另一侧一一对应。**标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应——完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。
 
 ## 门禁：verify-translation-pairing
 
 `pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，因此 CI 和 pre-push 钩子都会运行）机械地强制执行这份契约：
 
 1. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 中 `required` 列出的每个文件都有完整配对。
-2. 任何已存在的配对——无论是否 required——都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致——标题深度、逐字节一致的代码块（信息字符串与内容）、表格列数、列表类型，以及除切换行之外的每个链接目标。
+2. 任何已存在的配对——无论是否 required——都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致——标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。
 3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。
 4. 日期等于或晚于 manifest（元数据清单）中 `requiredSince` 分界日期的每篇日期命名文档（`yyyy-mm-dd-*.md`）都有完整配对——新增的日期命名 RFC 从创建起就要求双语齐备。
 
@@ -49,4 +49,4 @@
 
 ## 分工
 
-这里的对侧译文由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 产出、由人评审——在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁机械检查配对完整性、记录的 hash、切换行与文档所列的结构签名；翻译质量、术语以及签名未编码的结构要求仍由评审把关。
+这里的对侧译文由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 产出、由人评审——在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁机械检查配对完整性、记录的 hash、切换行与文档所列的结构签名；翻译质量、术语以及签名未编码的结构要求仍由评审把关。prompt 契约可以直接执行：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 将规范真源渲染到两个翻译方向，并严格解析含三个字段的 XML 响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向、仓库内示例与 CDATA 拆分规则。
diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md
index df0a58af2a..ed558e306c 100644
--- a/docs/i18n/style-samples.md
+++ b/docs/i18n/style-samples.md
@@ -30,7 +30,7 @@
 
 > **Async state is not synchronous state** — `agent.send()` does not flip status before returning; a background task's completion races turn boundaries; `reader.close()` fires for both EOF and disposal. Never gate control flow on a status you only just requested — drive lifecycle off the events/promises that actually fire (`agent/status`, `task.done`), and observe the transition (saw `running` THEN `idle`) rather than counting actions you assume map 1:1 to turns.
 
-**异步状态不等同于同步瞬时状态**——调用 `agent.send()` 不会在返回前同步更新状态；后台任务完成时机与轮次边界存在竞态；调用 `reader.close()` 既可能是读到文件末尾，也可能是资源销毁触发。切勿仅凭刚查询到的状态来阻断流程；生命周期逻辑应基于真实触发的事件与 promise 驱动（`agent/status`、`task.done`），观测完整状态切换（先 `running`、再 `idle`），而非主观认定操作和执行轮次一一对应（主循环会批量处理排队消息）。
+**异步状态不等同于同步瞬时状态**——调用 `agent.send()` 不会在返回前同步更新状态；后台任务完成时机与轮次边界存在竞态；调用 `reader.close()` 既可能是读到文件末尾，也可能是资源销毁触发。切勿根据刚刚请求切换的状态来控制流程；生命周期逻辑应基于真实触发的事件与 promise 驱动（`agent/status`、`task.done`），观测完整状态切换（先 `running`、再 `idle`），而非通过操作次数推断轮次是一一对应的。
 
 ## ③ 测试政策清单
 
diff --git a/docs/i18n/translation-prompt.md b/docs/i18n/translation-prompt.md
index 0236143cf7..349b24c9cc 100644
--- a/docs/i18n/translation-prompt.md
+++ b/docs/i18n/translation-prompt.md
@@ -1,6 +1,6 @@
 # Translation prompt (pipeline asset)
 
-本文件是自动翻译流水线的 prompt 模板；自 `# Translation Prompt` 起的正文逐字进入模型请求，因此不参与双语配对（见 [README.md](README.md) 排除清单）。渲染时，[terminology.md](terminology.md) 整表填入 `{{terminology}}`。[style-samples.md](style-samples.md) 定义文体，模板内嵌的 Examples 仅抽样问题类型；术语表、忠实性与结构规则优先于样例，样例在这些硬约束内决定文体。修改本文件即修改翻译行为，需按正常 PR 评审。
+本文件是自动翻译流水线的 prompt 模板；自 `# Translation Prompt` 起的正文逐字进入模型请求，因此不参与双语配对（见 [README.md](README.md) 排除清单）。渲染时，[translation-rules.md](translation-rules.md) 全文填入 `{{translation_rules}}`，[terminology.md](terminology.md) 整表填入 `{{terminology}}`，避免模板另存一份会漂移的规则副本。[style-samples.md](style-samples.md) 定义文体，模板内嵌的 Examples 仅抽样问题类型；术语表、忠实性与结构规则优先于样例，样例在这些硬约束内决定文体。修改本文件即修改翻译行为，需按正常 PR 评审。
 
 ## 占位符契约
 
@@ -10,6 +10,7 @@
 |---|---|---|
 | `{{source_lang}}` | 源语言名（`English` / `Chinese`） | 由改动侧文件推断：`.zh.md` 被改则为 `Chinese` |
 | `{{target_lang}}` | 目标语言名（`Chinese` / `English`） | 与 `{{source_lang}}` 相对 |
+| `{{translation_rules}}` | [translation-rules.md](translation-rules.md) 全文（Markdown 原文） | 渲染时读取仓库当前版本，不缓存 |
 | `{{terminology}}` | [terminology.md](terminology.md) 的完整表格（Markdown 原文） | 渲染时读取仓库当前版本，不缓存 |
 | `{{source_filename}}` | 源文档的 basename（如 `foo.md` 或 `foo.zh.md`） | 由流水线从待译文件路径取得 |
 | `{{source_filename_zh}}` | 中文侧 basename（如 `foo.zh.md`） | 英文源追加 `.zh`；中文源使用自身 basename |
@@ -35,46 +36,20 @@
 
 You are a senior technical translator specializing in LLM and agent development documentation. Translate the complete source document from {{source_lang}} to {{target_lang}} as natural, professional technical prose.
 
-## Quality Requirements
+## Binding Translation Rules
 
-### Structure and Format Preservation
-- Preserve the complete document frame: heading hierarchy, list item count and numbering, table row and column order, link targets, fenced code blocks, inline code spans, and emphasis spans.
-- Fenced code blocks must be byte-identical to the source, including every comment, info string, and line break. Never translate a code-block comment.
-- Inline code spans (commands, flags, paths, API names, event names, configuration keys, and version numbers) remain byte-identical and in the same order.
-- Every relative link keeps the same target. Translate link text, not link targets.
-- The source basename is `{{source_filename}}`. When translating into Chinese, write `[English]({{source_filename}}) | 中文` immediately after the H1. When translating into English, write `English | [中文]({{source_filename_zh}})` immediately after the H1. Emit the switcher for a new pair and flip an existing switcher; never copy it unchanged.
-- Preserve every source emphasis marker on the corresponding translated span. Do not add italics, bold, quotation marks, or other emphasis absent from the source.
-- After a closing bold marker `**`, add a half-width space only when the next character is a Latin letter or digit. Never add one before full-width punctuation.
+The canonical repository rules below are injected verbatim. Apply every direction-appropriate requirement. In those rules, the authored document is the source for this request and the generated document is its counterpart.
 
-### Faithfulness and Voice
-- Preserve every behavior, condition, prerequisite, warning, version claim, example, exception, and modal verb. Add none and drop none.
-- Write as a native technical author in the target language, not as a word-for-word translator. Restructure sentences where target-language grammar requires it while preserving the author's register.
-- Use precise, established developer terminology. Do not vary a term merely to avoid repetition, and do not collapse two distinct source concepts into one target term.
-- Do not add politeness, certainty, emphasis, rationale, or examples that the source does not contain.
+{{translation_rules}}
 
-#### When translating into Chinese
-- Use institutional technical Chinese: complete sentences, explicit actors where a passive would be vague, and established Chinese engineering idiom rather than calques.
-- When a number modifies a noun, include a natural classifier or measure word. Example: `three-package seam` → `由三个 package 构成的 seam`, not `三 package seam`.
-- Use full-width Chinese punctuation in prose: `，。：；？！（）「」`. Prefer colons, periods, commas, or parentheses over em dashes; use 顿号（、）between parallel items.
-- Put one half-width space between Chinese text and Latin words or numbers. Do not put spaces around full-width punctuation.
-- Render RFC 2119 keywords as 必须、禁止、应当、可以 while preserving the source emphasis exactly; plain source text remains plain.
+## Request-Specific Structure
 
-#### When translating into English
-- Use concise professional developer English. Convert Chinese topic-comment order, implicit subjects, and nominalizations into idiomatic English without dropping their meaning.
-- Use normal half-width English punctuation and spacing. Convert enumeration commas (、) to English commas and 「」 quotation marks to English double quotes, except inside verbatim Chinese text.
-- Render RFC 2119 keywords as MUST, MUST NOT, SHOULD, and MAY while preserving the source emphasis exactly.
-- Use established English engineering idiom rather than literal transliteration (误报 → false positive, 执行红线 → enforcement frontier), consulting the terminology table first.
-- Use direct English imperatives for instructions unless the source's politeness carries substantive meaning.
+- The source basename is `{{source_filename}}`. When translating into Chinese, write `[English]({{source_filename}}) | 中文` immediately after the H1. When translating into English, write `English | [中文]({{source_filename_zh}})` immediately after the H1.
+- Emit the switcher for a new pair and flip an existing switcher; never copy it unchanged.
 
-## Terminology
+## Binding Terminology
 
-The table below is binding:
-- For a Chinese target, use the `中文` column and apply the `首次出现` form once; later occurrences use the text before its parentheses.
-- For an English target, use the `English` column. Do not copy Chinese first-occurrence glosses into English prose.
-- Respect every `不要译作` prohibition in both directions.
-- For an unlisted term in a Chinese target, use a citable established Chinese OSS or vendor rendering and record the precedent in `<review>`; otherwise keep the English term and record it as `[Pending term]` with a suggested rendering.
-- For an unlisted term in an English target, use the established English technical term. If no unambiguous equivalent exists, preserve the source term with a short gloss and record it as `[Pending term]`.
-- Never invent a technical rendering inline.
+Apply the current table below exactly as required by the injected translation rules.
 
 {{terminology}}
 
@@ -99,32 +74,7 @@ Return exactly one well-formed XML document with this root and these three child
 
 ## Self-Review Instructions
 
-After writing `<translation>`, re-read it in the target language without looking at the source. Then compare it with the source clause by clause and record actual corrections in English inside `<review>`.
-
-**Structure**
-- Do heading levels, list item counts and numbering, table rows and columns, links, code blocks, inline code spans, and emphasis spans correspond exactly?
-- Are all fenced code blocks byte-identical, comments included?
-- Is the language switcher present and pointed in the correct direction?
-
-**Faithfulness**
-- Did every condition, warning, modal verb, exception, and example survive?
-- Did the translation add any claim, rationale, emphasis, or certainty absent from the source?
-
-**Tone and sentences**
-- Does every sentence read as native target-language developer documentation?
-- Are passive constructions, topic chains, or run-on sentences unnatural in the target language?
-
-**Terminology**
-- Does every tabled term use the target-language column and avoid forbidden forms?
-- For a Chinese target, are first-occurrence glosses present once and only once?
-- Are unlisted terms handled under the direction-specific precedent and pending-term rules?
-
-**Punctuation**
-- For Chinese, are punctuation, mixed-script spacing, classifiers, and 顿号 correct?
-- For English, are punctuation and spacing idiomatic and free of Chinese-only padding?
-- Do RFC 2119 keywords preserve the source emphasis rather than adding italics?
-
-Apply every recorded correction in `<final>`. If no correction is needed, write only `- [None] No corrections.` in `<review>` and copy `<translation>` unchanged into `<final>`.
+After writing `<translation>`, re-read it in the target language without looking at the source. Then apply the injected translation rules as a clause-by-clause comparison against the source and record actual corrections in English inside `<review>`. Apply every recorded correction in `<final>`. If no correction is needed, write only `- [None] No corrections.` in `<review>` and copy `<translation>` unchanged into `<final>`.
 
 ## Examples
 
diff --git a/docs/i18n/translation-rules.i18n.yaml b/docs/i18n/translation-rules.i18n.yaml
index 7b4967d364..5ffed9739d 100644
--- a/docs/i18n/translation-rules.i18n.yaml
+++ b/docs/i18n/translation-rules.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
-translation-rules.md: b48b1680da2e7a9a4d744659339398af81d60308
-translation-rules.zh.md: 6e8f26509e1db104eb341668c3e77bd6ea0780e1
+translation-rules.md: 490f12d7fec929e5d3d5682deb92ed373fffbde5
+translation-rules.zh.md: b013dcb2d8a892606ae5b1c0837152a771a57da5
diff --git a/docs/i18n/translation-rules.md b/docs/i18n/translation-rules.md
index b48b1680da..490f12d7fe 100644
--- a/docs/i18n/translation-rules.md
+++ b/docs/i18n/translation-rules.md
@@ -21,7 +21,7 @@ How to translate between the two sides of a documentation pair in this repo. Bot
 
 ## Structure preservation
 
-The pairing gate checks heading depths, fenced code blocks, table column counts, list kinds, and link targets. Preserve the rest of the frame manually; the paired files MUST match one to one in:
+The pairing gate checks heading depths, fenced code blocks, table row and column counts, list kinds, ordered-list starts, list item counts, and link targets. Preserve the rest of the frame manually; the paired files MUST match one to one in:
 
 - heading hierarchy (same levels, same order — heading TEXT is translated),
 - list shape and numbering,
@@ -54,7 +54,7 @@ These rules govern the Chinese side; the English side follows the repo's normal
 
 - A pair is done when a bilingual engineer reading either file alone gets everything a reader of the other gets — same facts, same caveats, same tone — and nothing extra.
 - Before handing off, self-check the result against this file and re-read the counterpart ALONE, without the source side by side; awkward phrasing is easier to hear without the source anchoring you.
-- Run `pnpm run verify-translation-pairing` and the rest of `doc-sync` for records, switchers, heading depths, code blocks, table column counts, list kinds, links, and repository Markdown rules. Manually verify list item counts and numbering, table row counts and order, inline code, emphasis, meaning, terminology, and tone.
+- Run `pnpm run verify-translation-pairing` and the rest of `doc-sync` for records, switchers, heading depths, code blocks, table row and column counts, list kinds, ordered-list starts, list item counts, links, and repository Markdown rules. Manually verify list and table order, noncanonical list numbering, inline code, emphasis, meaning, terminology, and tone.
 
 ## References
 
diff --git a/docs/i18n/translation-rules.zh.md b/docs/i18n/translation-rules.zh.md
index 6e8f26509e..b013dcb2d8 100644
--- a/docs/i18n/translation-rules.zh.md
+++ b/docs/i18n/translation-rules.zh.md
@@ -21,7 +21,7 @@
 
 ## 结构保持
 
-配对门禁检查标题深度、围栏代码块、表格列数、列表类型与链接目标。其余框架由译者手工保持；配对的两个文件必须在以下方面一一对应：
+配对门禁检查标题深度、围栏代码块、表格行列数、列表类型、有序列表起始编号、列表项数量与链接目标。其余框架由译者手工保持；配对的两个文件必须在以下方面一一对应：
 
 - 标题层级（相同级别、相同顺序；标题的**文字**要翻译）；
 - 列表形态与编号；
@@ -54,7 +54,7 @@
 
 - 一对文档的完成标准：一位双语工程师只读其中任一文件，能获得与另一文件读者完全相同的信息（相同的事实、相同的告诫、相同的语气），并且没有任何多余的内容。
 - 交付前，请对照本文自查一遍，并**单独通读对侧文件**，不与源侧对照；不对照原文时，更容易察觉别扭的表达。
-- 请运行 `pnpm run verify-translation-pairing` 与 `doc-sync` 的其余门禁，检查一致性记录、切换行、标题深度、代码块、表格列数、列表类型、链接及仓库 Markdown 规则。列表项数量与编号、表格行数与顺序、行内代码、强调标记、语义、术语和语体仍需手工核对。
+- 请运行 `pnpm run verify-translation-pairing` 与 `doc-sync` 的其余门禁，检查一致性记录、切换行、标题深度、代码块、表格行列数、列表类型、有序列表起始编号、列表项数量、链接及仓库 Markdown 规则。列表与表格顺序、非常规列表编号、行内代码、强调标记、语义、术语和语体仍需手工核对。
 
 ## 参考资料
 
diff --git a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
index 7836b74c85..56176b7bec 100644
--- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
 2026-07-02-bilingual-docs-and-pairing-gate.md: 68c0f3bbc0472b0c96f9d64fc6b1b24ac7008795
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: f93e3220fef720805c52023841f6f56f9e2834cf
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 66a24dbfa9e516bf341d42d10b797fb70dcd715d
diff --git a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
index f93e3220fe..66a24dbfa9 100644
--- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -11,7 +11,7 @@ Status: implemented
 ## 决策
 
 - **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../i18n/terminology.md)。
-- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR 内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。
+- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。
 - **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：required 的配对必须存在；任何已存在的配对必须完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）保持不配对；日期等于或晚于 manifest（元数据清单）中 `requiredSince` 分界日期的文档必须具有完整配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单只进不退：每个合并的翻译批次将自己的文件加入其中，覆盖面只增不减。
 - **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../../.agents/skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。
 
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 3f0e8ce820..189b762185 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -74,7 +74,7 @@ export default tseslint.config(
 
   // --- tests: same rules, minus the friction that fights test ergonomics --
   {
-    files: ['packages/*/*/tests/**/*.ts', 'examples/*/tests/**/*.ts'],
+    files: ['packages/*/*/tests/**/*.ts', 'examples/*/tests/**/*.ts', 'scripts/**/*.spec.ts'],
     extends: [
       ...tseslint.configs.strictTypeChecked,
     ],
diff --git a/package.json b/package.json
index 2d7a269f8d..13e9c0bcee 100644
--- a/package.json
+++ b/package.json
@@ -44,6 +44,7 @@
     "verify-rfc-classification": "tsx scripts/verify-rfc-classification.ts",
     "verify-rfc-format": "tsx scripts/verify-rfc-format.ts",
     "verify-type-equiv": "tsx scripts/verify-type-equiv.ts",
+    "verify-translation-prompt": "tsx scripts/verify-translation-prompt.ts",
     "verify-translation-pairing": "tsx scripts/verify-translation-pairing.ts",
     "verify-doc-budgets": "tsx scripts/verify-doc-budgets.ts",
     "verify-package-readme-limitations": "tsx scripts/verify-package-readme-limitations.ts",
@@ -67,7 +68,7 @@
     "verify-scoped-dispatch": "tsx scripts/verify-scoped-dispatch.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-cordis-api && 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-scoped-dispatch && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-package-readme-model-experience && 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 && pnpm run verify-package-readme-limitations",
+    "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-cordis-api && 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-scoped-dispatch && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-package-readme-model-experience && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-prompt && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets && pnpm run verify-package-readme-limitations",
     "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types && pnpm run verify-runtime-closure",
     "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",
@@ -95,6 +96,7 @@
     "mermaid": "11.16.0",
     "micromark-extension-gfm": "^3.0.0",
     "publint": "^0.3.21",
+    "saxes": "^6.0.0",
     "tsdown": "^0.22.2",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 650addb80a..aefc9dc3fa 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -62,6 +62,9 @@ importers:
       publint:
         specifier: ^0.3.21
         version: 0.3.21
+      saxes:
+        specifier: ^6.0.0
+        version: 6.0.0
       tsdown:
         specifier: ^0.22.2
         version: 0.22.2(oxc-resolver@11.20.0)(publint@0.3.21)(tsx@4.22.4)(typescript@6.0.3)
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 0e5e50a894..a4982df844 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -283,6 +283,7 @@ function docSyncLeafGates(): Gate[] {
     pnpmScript('rfc-classification', 'verify-rfc-classification', { label: 'rfc classification' }),
     pnpmScript('rfc-format', 'verify-rfc-format', { label: 'rfc format' }),
     pnpmScript('type-equivalence', 'verify-type-equiv', { label: 'type equivalence' }),
+    pnpmScript('translation-prompt', 'verify-translation-prompt', { label: 'translation prompt' }),
     pnpmScript('translation-pairing', 'verify-translation-pairing', { label: 'translation pairing' }),
     pnpmScript('doc-budgets', 'verify-doc-budgets', { label: 'doc budgets' }),
     pnpmScript('package-readme-limitations', 'verify-package-readme-limitations', { label: 'package README limitations' }),
diff --git a/scripts/translation-pairing.spec.ts b/scripts/translation-pairing.spec.ts
new file mode 100644
index 0000000000..39051969fc
--- /dev/null
+++ b/scripts/translation-pairing.spec.ts
@@ -0,0 +1,95 @@
+/** Regression tests for the bilingual cutoff and structural signature. */
+
+import { describe, expect, it } from 'vitest'
+import {
+  datedDocumentDate,
+  isIsoDate,
+  parseTranslationMarkdown,
+  parseTranslationPairingManifest,
+  requiresPairByDate,
+  translationStructureDiff,
+  translationStructureSignature,
+} from './translation-pairing.ts'
+
+function signature(markdown: string) {
+  return translationStructureSignature(parseTranslationMarkdown(markdown), 'counterpart.zh.md')
+}
+
+describe('translation pairing manifest', () => {
+  it('accepts a real ISO cutoff and string-array fields', () => {
+    expect(parseTranslationPairingManifest(JSON.stringify({
+      requiredSince: '2026-07-14',
+      required: ['README.md'],
+      excluded: ['docs/generated/'],
+    }))).toEqual({
+      requiredSince: '2026-07-14',
+      required: ['README.md'],
+      excluded: ['docs/generated/'],
+    })
+  })
+
+  it.each(['2026-7-14', '2026-02-29', '2026-13-01', 'not-a-date'])('rejects invalid cutoff %s', (cutoff) => {
+    expect(isIsoDate(cutoff)).toBe(false)
+    expect(() => parseTranslationPairingManifest(JSON.stringify({
+      requiredSince: cutoff,
+      required: [],
+      excluded: [],
+    }))).toThrow('requiredSince must be a valid YYYY-MM-DD date')
+  })
+
+  it('rejects non-string manifest arrays', () => {
+    expect(() => parseTranslationPairingManifest(JSON.stringify({
+      requiredSince: '2026-07-14',
+      required: [42],
+      excluded: [],
+    }))).toThrow('required must be an array of strings')
+  })
+})
+
+describe('date-based pairing frontier', () => {
+  const cutoff = '2026-07-14'
+
+  it('enforces the cutoff day and every later day, but not the preceding day', () => {
+    expect(requiresPairByDate('docs/rfc/2026-07-13-before.md', cutoff)).toBe(false)
+    expect(requiresPairByDate('docs/rfc/2026-07-14-at-cutoff.md', cutoff)).toBe(true)
+    expect(requiresPairByDate('docs/rfc/2026-07-15-after.md', cutoff)).toBe(true)
+  })
+
+  it('matches only a date at the start of the basename', () => {
+    expect(datedDocumentDate('docs/rfc/2026-07-14-proposal.md')).toBe('2026-07-14')
+    expect(datedDocumentDate('docs/release-notes-2026-07-14-alpha.md')).toBeUndefined()
+    expect(requiresPairByDate('docs/release-notes-2026-07-14-alpha.md', cutoff)).toBe(false)
+  })
+})
+
+describe('translation structural signature', () => {
+  it('accepts matching list kinds, starts, and item counts', () => {
+    const source = signature('3. One\n4. Two\n\n- A\n- B\n')
+    const counterpart = signature('3. 一\n4. 二\n\n- 甲\n- 乙\n')
+    expect(translationStructureDiff(source, counterpart)).toEqual([])
+  })
+
+  it('rejects an altered ordered-list start', () => {
+    const source = signature('3. One\n4. Two\n\n- A\n- B\n')
+    const counterpart = signature('1. 一\n2. 二\n\n- 甲\n- 乙\n')
+    expect(translationStructureDiff(source, counterpart)).toEqual([
+      'list (kind, start, item count) #1 diverges between the pair: "ordered:start=3:items=2" vs "ordered:start=1:items=2"',
+    ])
+  })
+
+  it('rejects a missing list item', () => {
+    const source = signature('- A\n- B\n')
+    const counterpart = signature('- 甲\n')
+    expect(translationStructureDiff(source, counterpart)).toEqual([
+      'list (kind, start, item count) #1 diverges between the pair: "bullet:items=2" vs "bullet:items=1"',
+    ])
+  })
+
+  it('rejects altered table row or column counts', () => {
+    const source = signature('| A | B |\n|---|---|\n| 1 | 2 |\n| 3 | 4 |\n')
+    const counterpart = signature('| 甲 | 乙 |\n|---|---|\n| 一 | 二 |\n')
+    expect(translationStructureDiff(source, counterpart)).toEqual([
+      'table (row x column count) #1 diverges between the pair: "3x2" vs "2x2"',
+    ])
+  })
+})
diff --git a/scripts/translation-pairing.ts b/scripts/translation-pairing.ts
new file mode 100644
index 0000000000..b7238fa3aa
--- /dev/null
+++ b/scripts/translation-pairing.ts
@@ -0,0 +1,164 @@
+/**
+ * Pure parsing and structural helpers for the bilingual-document pairing
+ * gate. Kept separate from the CLI so cutoff and signature behavior can be
+ * regression-tested without reading or mutating the repository tree.
+ */
+
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { gfmFromMarkdown } from 'mdast-util-gfm'
+import { gfm } from 'micromark-extension-gfm'
+import type { Nodes } from 'mdast'
+
+/** Validated shape of `scripts/translation-pairing.manifest.json`. */
+export interface TranslationPairingManifest {
+  required: string[]
+  excluded: string[]
+  /** Date-named documents on or after this day must merge bilingual. */
+  requiredSince: string
+}
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+const DATED_DOCUMENT = /(?:^|\/)(\d{4}-\d{2}-\d{2})-[^/]*\.md$/
+
+/** Whether a string names one real calendar day in canonical ISO form. */
+export function isIsoDate(value: string): boolean {
+  if (!ISO_DATE.test(value)) return false
+  const date = new Date(`${value}T00:00:00.000Z`)
+  return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value
+}
+
+/** Read one manifest string-array field or fail before enforcement starts. */
+function stringArrayField(record: Record<string, unknown>, field: 'required' | 'excluded'): string[] {
+  const value = record[field]
+  if (!Array.isArray(value)) {
+    throw new Error(`translation-pairing.manifest.json: ${field} must be an array of strings`)
+  }
+  const entries: unknown[] = value
+  if (!entries.every((entry): entry is string => typeof entry === 'string')) {
+    throw new Error(`translation-pairing.manifest.json: ${field} must be an array of strings`)
+  }
+  return entries
+}
+
+/** Parse and validate the checked-in bilingual manifest. */
+export function parseTranslationPairingManifest(content: string): TranslationPairingManifest {
+  const value: unknown = JSON.parse(content)
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error('translation-pairing.manifest.json: expected an object')
+  }
+  const record = value as Record<string, unknown>
+  const requiredSince = record.requiredSince
+  if (typeof requiredSince !== 'string' || !isIsoDate(requiredSince)) {
+    throw new Error(`translation-pairing.manifest.json: requiredSince must be a valid YYYY-MM-DD date; got ${JSON.stringify(requiredSince)}`)
+  }
+  return {
+    required: stringArrayField(record, 'required'),
+    excluded: stringArrayField(record, 'excluded'),
+    requiredSince,
+  }
+}
+
+/** Return the leading date of a `yyyy-mm-dd-*.md` basename, if present. */
+export function datedDocumentDate(file: string): string | undefined {
+  return DATED_DOCUMENT.exec(file)?.[1]
+}
+
+/** Whether a date-named document falls on or after the pairing cutoff. */
+export function requiresPairByDate(file: string, requiredSince: string): boolean {
+  const date = datedDocumentDate(file)
+  return date !== undefined && date >= requiredSince
+}
+
+/** The structural surface compared between the two sides of a pair. */
+export interface TranslationStructureSignature {
+  /** Heading depths in document order (h2 -> 2). */
+  headings: number[]
+  /** Fenced code blocks verbatim: info string plus content, in order. */
+  code: string[]
+  /** Row and column count of each table, in order. */
+  tables: string[]
+  /** Kind, ordered-list start, and direct item count of each list, in order. */
+  lists: string[]
+  /** Every link target in order; the language switcher is excluded. */
+  links: string[]
+}
+
+/** Parse Markdown with the same GFM extensions used by the pairing gate. */
+export function parseTranslationMarkdown(content: string): Nodes {
+  return fromMarkdown(content, { extensions: [gfm()], mdastExtensions: [gfmFromMarkdown()] })
+}
+
+/** Whether the tree contains a link to exactly `target`. */
+export function linksTo(tree: Nodes, target: string): boolean {
+  let found = false
+  const visit = (node: Nodes): void => {
+    if (node.type === 'link' && node.url === target) found = true
+    if ('children' in node) for (const child of node.children) visit(child)
+  }
+  visit(tree)
+  return found
+}
+
+/** Collect the ordered structural signature, skipping one switcher target. */
+export function translationStructureSignature(tree: Nodes, switcherTarget: string): TranslationStructureSignature {
+  const sig: TranslationStructureSignature = { headings: [], code: [], tables: [], lists: [], links: [] }
+  const visit = (node: Nodes): void => {
+    switch (node.type) {
+      case 'heading':
+        sig.headings.push(node.depth)
+        break
+      case 'code':
+        sig.code.push(`\`\`\`${node.lang ?? ''}${node.meta ? ` ${node.meta}` : ''}\n${node.value}`)
+        break
+      case 'table':
+        sig.tables.push(`${node.children.length}x${node.children[0]?.children.length ?? 0}`)
+        break
+      case 'list':
+        sig.lists.push(node.ordered
+          ? `ordered:start=${node.start ?? 1}:items=${node.children.length}`
+          : `bullet:items=${node.children.length}`)
+        break
+      case 'link':
+        if (node.url !== switcherTarget) sig.links.push(node.url)
+        break
+      default:
+        // Every other node kind is prose or a container, not part of the signature.
+        break
+    }
+    if ('children' in node) for (const child of node.children) visit(child)
+  }
+  visit(tree)
+  return sig
+}
+
+/** Render a signature element for an error message, truncated for readability. */
+function show(value: string | number | undefined): string {
+  if (value === undefined) return 'nothing'
+  const text = JSON.stringify(value)
+  return text.length > 72 ? `${text.slice(0, 72)}…` : text
+}
+
+/** Return the first divergence for each structural field; empty means equal. */
+export function translationStructureDiff(
+  source: TranslationStructureSignature,
+  zh: TranslationStructureSignature,
+): string[] {
+  const out: string[] = []
+  const fields: [string, (string | number)[], (string | number)[]][] = [
+    ['heading (depth)', source.headings, zh.headings],
+    ['code block', source.code, zh.code],
+    ['table (row x column count)', source.tables, zh.tables],
+    ['list (kind, start, item count)', source.lists, zh.lists],
+    ['link target', source.links, zh.links],
+  ]
+  for (const [field, sourceValues, zhValues] of fields) {
+    const length = Math.max(sourceValues.length, zhValues.length)
+    for (let index = 0; index < length; index++) {
+      if (sourceValues[index] !== zhValues[index]) {
+        out.push(`${field} #${index + 1} diverges between the pair: ${show(sourceValues[index])} vs ${show(zhValues[index])}`)
+        break
+      }
+    }
+  }
+  return out
+}
diff --git a/scripts/translation-prompt.spec.ts b/scripts/translation-prompt.spec.ts
new file mode 100644
index 0000000000..49d9b82e26
--- /dev/null
+++ b/scripts/translation-prompt.spec.ts
@@ -0,0 +1,67 @@
+/** Regression tests for the executable translation prompt contract. */
+
+import { describe, expect, it } from 'vitest'
+import {
+  parseTranslationResponse,
+  renderTranslationPrompt,
+  renderTranslationResponse,
+} from './translation-prompt.ts'
+
+const document = `# Wrapper
+
+## 模板正文
+
+\`\`\`\`text
+{{source_lang}} to {{target_lang}}
+{{translation_rules}}
+{{terminology}}
+[English]({{source_filename}}) | [中文]({{source_filename_zh}})
+\`\`\`\`
+`
+
+describe('translation prompt rendering', () => {
+  it('renders every supported placeholder without recursively rewriting injected rules', () => {
+    const rendered = renderTranslationPrompt(document, {
+      sourceLanguage: 'English',
+      sourceFilename: 'guide.md',
+      translationRules: 'A literal {{source_lang}} in injected rules.',
+      terminology: '| English | 中文 |',
+    })
+    expect(rendered).toContain('English to Chinese')
+    expect(rendered).toContain('A literal {{source_lang}} in injected rules.')
+    expect(rendered).toContain('[English](guide.md) | [中文](guide.zh.md)')
+  })
+
+  it('rejects a filename whose suffix contradicts the source language', () => {
+    expect(() => renderTranslationPrompt(document, {
+      sourceLanguage: 'Chinese',
+      sourceFilename: 'guide.md',
+      translationRules: 'rules',
+      terminology: 'terms',
+    })).toThrow('does not match source language Chinese')
+  })
+})
+
+describe('translation response XML', () => {
+  it('round-trips Markdown and the CDATA terminator', () => {
+    const response = {
+      translation: '# Draft\n\nA ]]> marker.',
+      review: '- [Tone] Fixed.',
+      final: '# Final\n\nA ]]> marker.',
+    }
+    expect(parseTranslationResponse(renderTranslationResponse(response))).toEqual(response)
+  })
+
+  it('rejects missing, reordered, nested, attributed, or non-CDATA children', () => {
+    expect(() => parseTranslationResponse('<dsh-translation-response version="1"/>')).toThrow('translation, review, and final')
+    expect(() => parseTranslationResponse('<dsh-translation-response version="1"><review><![CDATA[x]]></review></dsh-translation-response>'))
+      .toThrow('expected translation, got review')
+    expect(() => parseTranslationResponse(renderTranslationResponse({ translation: 'x', review: 'y', final: 'z' })
+      .replace('<translation><![CDATA[x]]></translation>', '<translation><b><![CDATA[x]]></b></translation>')))
+      .toThrow('nested element b is not allowed')
+    expect(() => parseTranslationResponse(renderTranslationResponse({ translation: 'x', review: 'y', final: 'z' }).replace('<review>', '<review lang="en">')))
+      .toThrow('review must not have attributes')
+    expect(() => parseTranslationResponse(renderTranslationResponse({ translation: 'x', review: 'y', final: 'z' }).replace('<![CDATA[x]]>', 'x')))
+      .toThrow('all response field content must be inside CDATA')
+  })
+})
diff --git a/scripts/translation-prompt.ts b/scripts/translation-prompt.ts
new file mode 100644
index 0000000000..3b5ad793ae
--- /dev/null
+++ b/scripts/translation-prompt.ts
@@ -0,0 +1,167 @@
+/**
+ * Executable renderer and strict response parser for the committed
+ * documentation-translation prompt contract.
+ */
+
+import { basename } from 'node:path'
+import { SaxesParser } from 'saxes'
+
+/** Placeholder names supported by the committed translation prompt. */
+export const TRANSLATION_PROMPT_PLACEHOLDERS = [
+  'source_lang',
+  'target_lang',
+  'translation_rules',
+  'terminology',
+  'source_filename',
+  'source_filename_zh',
+] as const
+
+type TranslationPromptPlaceholder = (typeof TRANSLATION_PROMPT_PLACEHOLDERS)[number]
+
+/** Languages accepted by the bidirectional prompt. */
+type TranslationLanguage = 'English' | 'Chinese'
+
+/** Inputs that vary for one rendered translation request. */
+export interface TranslationPromptInput {
+  sourceLanguage: TranslationLanguage
+  /** Source basename, including `.md` or `.zh.md`. */
+  sourceFilename: string
+  /** Complete current `translation-rules.md` contents. */
+  translationRules: string
+  /** Complete current `terminology.md` contents. */
+  terminology: string
+}
+
+/** Parsed contents of the three-element XML response. */
+export interface TranslationResponse {
+  translation: string
+  review: string
+  final: string
+}
+
+const PLACEHOLDER = /{{([a-z_]+)}}/g
+const TEMPLATE_OPEN = '## 模板正文\n\n````text\n'
+const TEMPLATE_CLOSE = '\n````'
+const RESPONSE_CHILDREN = ['translation', 'review', 'final'] as const
+
+/** Extract the machine-consumed text fence from `translation-prompt.md`. */
+function extractTranslationPrompt(document: string): string {
+  const start = document.indexOf(TEMPLATE_OPEN)
+  if (start === -1) throw new Error('translation prompt: missing `## 模板正文` text fence')
+  const contentStart = start + TEMPLATE_OPEN.length
+  const end = document.indexOf(TEMPLATE_CLOSE, contentStart)
+  if (end === -1) throw new Error('translation prompt: missing closing four-backtick fence')
+  return document.slice(contentStart, end)
+}
+
+/** Read the placeholder names documented in the prompt's contract table. */
+export function documentedTranslationPromptPlaceholders(document: string): string[] {
+  const preambleEnd = document.indexOf(TEMPLATE_OPEN)
+  if (preambleEnd === -1) throw new Error('translation prompt: missing template body')
+  return [...document.slice(0, preambleEnd).matchAll(/^\| `{{([a-z_]+)}}` \|/gm)].map(match => match[1] ?? '')
+}
+
+/** Render one system prompt from the checked-in template and canonical rules. */
+export function renderTranslationPrompt(document: string, input: TranslationPromptInput): string {
+  if (basename(input.sourceFilename) !== input.sourceFilename) {
+    throw new Error(`translation prompt: sourceFilename must be a basename; got ${JSON.stringify(input.sourceFilename)}`)
+  }
+  const sourceIsChinese = input.sourceFilename.endsWith('.zh.md')
+  if (input.sourceLanguage === 'Chinese' ? !sourceIsChinese : sourceIsChinese || !input.sourceFilename.endsWith('.md')) {
+    throw new Error(`translation prompt: ${input.sourceFilename} does not match source language ${input.sourceLanguage}`)
+  }
+
+  const targetLanguage: TranslationLanguage = input.sourceLanguage === 'English' ? 'Chinese' : 'English'
+  const sourceFilenameZh = sourceIsChinese ? input.sourceFilename : input.sourceFilename.replace(/\.md$/, '.zh.md')
+  const values: Record<TranslationPromptPlaceholder, string> = {
+    source_lang: input.sourceLanguage,
+    target_lang: targetLanguage,
+    translation_rules: input.translationRules,
+    terminology: input.terminology,
+    source_filename: input.sourceFilename,
+    source_filename_zh: sourceFilenameZh,
+  }
+  const template = extractTranslationPrompt(document)
+  const names = [...template.matchAll(PLACEHOLDER)].map(match => match[1] ?? '')
+  const unknown = names.filter(name => !TRANSLATION_PROMPT_PLACEHOLDERS.includes(name as TranslationPromptPlaceholder))
+  if (unknown.length > 0) throw new Error(`translation prompt: unsupported placeholder(s): ${[...new Set(unknown)].join(', ')}`)
+  const missing = TRANSLATION_PROMPT_PLACEHOLDERS.filter(name => !names.includes(name))
+  if (missing.length > 0) throw new Error(`translation prompt: template does not use required placeholder(s): ${missing.join(', ')}`)
+
+  return template.replace(PLACEHOLDER, (_token, name: string) => values[name as TranslationPromptPlaceholder])
+}
+
+/** Escape one value so it remains byte-identical inside an XML CDATA field. */
+function escapeTranslationCdata(value: string): string {
+  return value.replaceAll(']]>', ']]]]><![CDATA[>')
+}
+
+/** Serialize a response using the exact XML wire contract in the prompt. */
+export function renderTranslationResponse(response: TranslationResponse): string {
+  return [
+    '<dsh-translation-response version="1">',
+    `<translation><![CDATA[${escapeTranslationCdata(response.translation)}]]></translation>`,
+    `<review><![CDATA[${escapeTranslationCdata(response.review)}]]></review>`,
+    `<final><![CDATA[${escapeTranslationCdata(response.final)}]]></final>`,
+    '</dsh-translation-response>',
+  ].join('\n')
+}
+
+/** Parse and validate the exact XML response shape emitted by the model. */
+export function parseTranslationResponse(xml: string): TranslationResponse {
+  const values: TranslationResponse = { translation: '', review: '', final: '' }
+  const stack: string[] = []
+  const cdataFields = new Set<string>()
+  let rootSeen = false
+  let childIndex = 0
+  const fail = (message: string): never => {
+    throw new Error(`translation response: ${message}`)
+  }
+  const parser = new SaxesParser({ xmlns: false })
+
+  parser.on('opentag', (tag) => {
+    if (stack.length === 0) {
+      if (rootSeen) fail('contains more than one root element')
+      if (tag.name !== 'dsh-translation-response') fail(`expected dsh-translation-response root, got ${tag.name}`)
+      const attributes = Object.keys(tag.attributes)
+      if (attributes.length !== 1 || tag.attributes.version !== '1') fail('root must have only version="1"')
+      rootSeen = true
+    } else if (stack.length === 1) {
+      const expected = RESPONSE_CHILDREN[childIndex]
+      if (tag.name !== expected) fail(`expected ${expected ?? 'no more children'}, got ${tag.name}`)
+      if (Object.keys(tag.attributes).length !== 0) fail(`${tag.name} must not have attributes`)
+      childIndex++
+    } else {
+      fail(`nested element ${tag.name} is not allowed`)
+    }
+    stack.push(tag.name)
+  })
+  parser.on('text', (value) => {
+    if (stack.length <= 1 && value.trim() === '') return
+    fail('all response field content must be inside CDATA')
+  })
+  parser.on('cdata', (value) => {
+    const field = stack.at(-1)
+    if (field === undefined || !RESPONSE_CHILDREN.includes(field as (typeof RESPONSE_CHILDREN)[number])) {
+      fail('CDATA is allowed only inside translation, review, or final')
+    }
+    const key = field as (typeof RESPONSE_CHILDREN)[number]
+    values[key] += value
+    cdataFields.add(key)
+  })
+  parser.on('closetag', (tag) => {
+    const expected = stack.pop()
+    if (expected !== tag.name) fail(`closing ${tag.name} does not match ${expected ?? 'nothing'}`)
+  })
+  parser.on('comment', () => fail('comments are not allowed'))
+  parser.on('doctype', () => fail('doctypes are not allowed'))
+  parser.on('processinginstruction', () => fail('processing instructions are not allowed'))
+  parser.on('error', error => fail(`invalid XML: ${error.message}`))
+  parser.write(xml).close()
+
+  if (childIndex !== RESPONSE_CHILDREN.length) fail('translation, review, and final must each appear exactly once and in order')
+  for (const field of RESPONSE_CHILDREN) {
+    if (!cdataFields.has(field)) fail(`${field} must contain a CDATA section`)
+  }
+  return values
+}
diff --git a/scripts/verify-translation-pairing.ts b/scripts/verify-translation-pairing.ts
index 29af0a7ec8..56a922a96c 100644
--- a/scripts/verify-translation-pairing.ts
+++ b/scripts/verify-translation-pairing.ts
@@ -10,10 +10,15 @@
 import { createHash } from 'node:crypto'
 import { existsSync, globSync, readFileSync, writeFileSync } from 'node:fs'
 import { basename, join, resolve } from 'node:path'
-import { fromMarkdown } from 'mdast-util-from-markdown'
-import { gfmFromMarkdown } from 'mdast-util-gfm'
-import { gfm } from 'micromark-extension-gfm'
-import type { Nodes } from 'mdast'
+import {
+  datedDocumentDate,
+  linksTo,
+  parseTranslationMarkdown,
+  parseTranslationPairingManifest,
+  requiresPairByDate,
+  translationStructureDiff,
+  translationStructureSignature,
+} from './translation-pairing.ts'
 
 const root = resolve(import.meta.dirname, '..')
 const listMode = process.argv.includes('--list')
@@ -22,55 +27,7 @@ const writeMode = process.argv.includes('--write')
 /** Scope of the bilingual contract: the root README, the docs tree, and the Python SDK tree. */
 const SCOPE_PATTERNS = ['README.md', 'README.zh.md', 'README.i18n.yaml', 'docs/**/*.md', 'docs/**/*.i18n.yaml', 'python/**/*.md', 'python/**/*.i18n.yaml']
 
-/** The enforcement frontier and the never-paired set (docs/i18n/README.md § Scope). */
-interface Manifest {
-  required: string[]
-  excluded: string[]
-  /** Date-named documents (yyyy-mm-dd-*.md, i.e. RFCs) dated on/after this day must merge bilingual. */
-  requiredSince: string
-}
-
-const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
-
-/** Whether a string names one real calendar day in canonical ISO form. */
-function isIsoDate(value: string): boolean {
-  if (!ISO_DATE.test(value)) return false
-  const date = new Date(`${value}T00:00:00.000Z`)
-  return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value
-}
-
-/** Read one manifest string-array field or fail before enforcement starts. */
-function stringArrayField(record: Record<string, unknown>, field: 'required' | 'excluded'): string[] {
-  const value = record[field]
-  if (!Array.isArray(value)) {
-    throw new Error(`translation-pairing.manifest.json: ${field} must be an array of strings`)
-  }
-  const entries: unknown[] = value
-  if (!entries.every((entry): entry is string => typeof entry === 'string')) {
-    throw new Error(`translation-pairing.manifest.json: ${field} must be an array of strings`)
-  }
-  return entries
-}
-
-/** Parse and validate the checked-in bilingual manifest. */
-function parseManifest(content: string): Manifest {
-  const value: unknown = JSON.parse(content)
-  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-    throw new Error('translation-pairing.manifest.json: expected an object')
-  }
-  const record = value as Record<string, unknown>
-  const requiredSince = record.requiredSince
-  if (typeof requiredSince !== 'string' || !isIsoDate(requiredSince)) {
-    throw new Error(`translation-pairing.manifest.json: requiredSince must be a valid YYYY-MM-DD date; got ${JSON.stringify(requiredSince)}`)
-  }
-  return {
-    required: stringArrayField(record, 'required'),
-    excluded: stringArrayField(record, 'excluded'),
-    requiredSince,
-  }
-}
-
-const manifest = parseManifest(readFileSync(join(root, 'scripts/translation-pairing.manifest.json'), 'utf8'))
+const manifest = parseTranslationPairingManifest(readFileSync(join(root, 'scripts/translation-pairing.manifest.json'), 'utf8'))
 
 /**
  * An excluded entry ending in `/` excludes the whole directory. The trailing
@@ -122,98 +79,6 @@ function renderMeta(source: string, sourceHash: string, zh: string, zhHash: stri
   ].join('\n')
 }
 
-/**
- * The structural signature the two sides must share, as ordered sequences so
- * a swap or a level change is caught, not just a count change. Prose is
- * deliberately absent: the gate checks shape, never wording.
- */
-interface Signature {
-  /** Heading depths in document order (h2 → 2). */
-  headings: number[]
-  /** Fenced code blocks verbatim: info string + content, in order. */
-  code: string[]
-  /** Column count of each table, in order. */
-  tables: number[]
-  /** Each list's kind (ordered vs bullet), in order. */
-  lists: string[]
-  /** Every link target in order, the language switcher's excluded. */
-  links: string[]
-}
-
-/** Whether the tree contains a link to exactly `target` (the switcher check). */
-function linksTo(tree: Nodes, target: string): boolean {
-  let found = false
-  const visit = (node: Nodes): void => {
-    if (node.type === 'link' && node.url === target) found = true
-    if ('children' in node) for (const child of node.children) visit(child)
-  }
-  visit(tree)
-  return found
-}
-
-/** Collect the structural signature, skipping links to `switcherTarget`. */
-function signatureOf(tree: Nodes, switcherTarget: string): Signature {
-  const sig: Signature = { headings: [], code: [], tables: [], lists: [], links: [] }
-  const visit = (node: Nodes): void => {
-    switch (node.type) {
-      case 'heading':
-        sig.headings.push(node.depth)
-        break
-      case 'code':
-        sig.code.push(`\`\`\`${node.lang ?? ''}${node.meta ? ` ${node.meta}` : ''}\n${node.value}`)
-        break
-      case 'table':
-        sig.tables.push(node.children[0]?.children.length ?? 0)
-        break
-      case 'list':
-        sig.lists.push(node.ordered ? 'ordered' : 'bullet')
-        break
-      case 'link':
-        if (node.url !== switcherTarget) sig.links.push(node.url)
-        break
-      default:
-        // Every other node kind is prose or container — not part of the signature.
-        break
-    }
-    if ('children' in node) for (const child of node.children) visit(child)
-  }
-  visit(tree)
-  return sig
-}
-
-/** Render a signature element for an error message, truncated for readability. */
-function show(value: string | number | undefined): string {
-  if (value === undefined) return 'nothing'
-  const text = JSON.stringify(value)
-  return text.length > 72 ? `${text.slice(0, 72)}…` : text
-}
-
-/** First divergence between two signatures, as messages; empty when identical. */
-function signatureDiff(source: Signature, zh: Signature): string[] {
-  const out: string[] = []
-  const fields: [string, (string | number)[], (string | number)[]][] = [
-    ['heading (depth)', source.headings, zh.headings],
-    ['code block', source.code, zh.code],
-    ['table (column count)', source.tables, zh.tables],
-    ['list (kind)', source.lists, zh.lists],
-    ['link target', source.links, zh.links],
-  ]
-  for (const [field, s, z] of fields) {
-    const length = Math.max(s.length, z.length)
-    for (let i = 0; i < length; i++) {
-      if (s[i] !== z[i]) {
-        out.push(`${field} #${i + 1} diverges between the pair: ${show(s[i])} vs ${show(z[i])}`)
-        break
-      }
-    }
-  }
-  return out
-}
-
-function parse(content: string): Nodes {
-  return fromMarkdown(content, { extensions: [gfm()], mdastExtensions: [gfmFromMarkdown()] })
-}
-
 // Enumerate the scope once.
 const files = new Set<string>()
 for (const pattern of SCOPE_PATTERNS) {
@@ -259,14 +124,13 @@ for (const req of manifest.required) {
 // 2. Date-named documents (RFCs) dated on/after the requiredSince cutoff merge
 // bilingual: a new RFC lands with its pair or not at all. Deterministic from
 // the filename alone — no git history, so it holds on shallow CI checkouts.
-const DATED = /(?:^|\/)(\d{4}-\d{2}-\d{2})-[^/]*\.md$/
 for (const source of sources) {
   if (isExcluded(source)) continue
-  const dated = DATED.exec(source)
-  if (!dated?.[1] || dated[1] < manifest.requiredSince) continue
+  const date = datedDocumentDate(source)
+  if (!requiresPairByDate(source, manifest.requiredSince) || date === undefined) continue
   const { zh } = pairPaths(source)
   if (!existsSync(join(root, zh))) {
-    errors.push(`${source}: dated ${dated[1]} — documents dated on/after ${manifest.requiredSince} merge bilingual (docs/i18n/README.md); add the counterpart and record the pair`)
+    errors.push(`${source}: dated ${date} — documents dated on/after ${manifest.requiredSince} merge bilingual (docs/i18n/README.md); add the counterpart and record the pair`)
     state.set(source, 'missing')
   }
 }
@@ -314,15 +178,18 @@ for (const source of [...pairAnchors].sort()) {
     continue
   }
 
-  const sourceTree = parse(sourceContent.toString('utf8'))
-  const zhTree = parse(zhContent.toString('utf8'))
+  const sourceTree = parseTranslationMarkdown(sourceContent.toString('utf8'))
+  const zhTree = parseTranslationMarkdown(zhContent.toString('utf8'))
   if (!linksTo(zhTree, basename(source))) {
     errors.push(`${zh}: missing language switcher — no link to ${basename(source)}`)
   }
   if (!linksTo(sourceTree, basename(zh))) {
     errors.push(`${source}: missing language switcher — no link back to ${basename(zh)}`)
   }
-  for (const divergence of signatureDiff(signatureOf(sourceTree, basename(zh)), signatureOf(zhTree, basename(source)))) {
+  for (const divergence of translationStructureDiff(
+    translationStructureSignature(sourceTree, basename(zh)),
+    translationStructureSignature(zhTree, basename(source)),
+  )) {
     errors.push(`${source} ↔ ${zh}: ${divergence}`)
   }
   if (!state.has(source)) state.set(source, 'ok')
@@ -338,8 +205,7 @@ if (listMode) {
   const rows = [...state.entries()].sort((a, b) => order[a[1]] - order[b[1]] || a[0].localeCompare(b[0]))
   for (const [file, status] of rows) {
     const required = manifest.required.includes(file)
-    const date = DATED.exec(file)?.[1]
-    const tag = required ? '  (required)' : date && date >= manifest.requiredSince ? '  (required by date)' : '  (backlog)'
+    const tag = required ? '  (required)' : requiresPairByDate(file, manifest.requiredSince) ? '  (required by date)' : '  (backlog)'
     console.log(`${status.padEnd(11)} ${file}${status === 'missing' ? tag : ''}`)
   }
   const counts = { 'ok': 0, 'out-of-sync': 0, 'missing': 0 }
diff --git a/scripts/verify-translation-prompt.ts b/scripts/verify-translation-prompt.ts
new file mode 100644
index 0000000000..2460e82c47
--- /dev/null
+++ b/scripts/verify-translation-prompt.ts
@@ -0,0 +1,57 @@
+/** Verify that the committed translation prompt renders and parses as documented. */
+
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import {
+  documentedTranslationPromptPlaceholders,
+  parseTranslationResponse,
+  renderTranslationPrompt,
+  renderTranslationResponse,
+  TRANSLATION_PROMPT_PLACEHOLDERS,
+} from './translation-prompt.ts'
+
+const root = resolve(import.meta.dirname, '..')
+
+function read(path: string): string {
+  return readFileSync(join(root, path), 'utf8')
+}
+
+try {
+  const document = read('docs/i18n/translation-prompt.md')
+  const translationRules = read('docs/i18n/translation-rules.md')
+  const terminology = read('docs/i18n/terminology.md')
+  const documented = documentedTranslationPromptPlaceholders(document)
+  if (documented.join('\n') !== TRANSLATION_PROMPT_PLACEHOLDERS.join('\n')) {
+    throw new Error(`placeholder table must list exactly: ${TRANSLATION_PROMPT_PLACEHOLDERS.join(', ')}`)
+  }
+
+  const englishSource = renderTranslationPrompt(document, {
+    sourceLanguage: 'English',
+    sourceFilename: 'example.md',
+    translationRules,
+    terminology,
+  })
+  const chineseSource = renderTranslationPrompt(document, {
+    sourceLanguage: 'Chinese',
+    sourceFilename: 'example.zh.md',
+    translationRules,
+    terminology,
+  })
+  if (englishSource.includes('{{') || chineseSource.includes('{{')) throw new Error('rendered prompt contains an unresolved placeholder')
+  if (!englishSource.includes('[English](example.md) | 中文')) throw new Error('English-source render does not carry the Chinese switcher instruction')
+  if (!chineseSource.includes('English | [中文](example.zh.md)')) throw new Error('Chinese-source render does not carry the English switcher instruction')
+
+  const example = /```xml\n([\s\S]*?)\n```/.exec(englishSource)?.[1]
+  if (example === undefined) throw new Error('rendered prompt has no XML response example')
+  parseTranslationResponse(example)
+
+  const roundTrip = { translation: 'first ]]> pass', review: '- [None] No corrections.', final: 'final ]]> text' }
+  const parsed = parseTranslationResponse(renderTranslationResponse(roundTrip))
+  if (JSON.stringify(parsed) !== JSON.stringify(roundTrip)) throw new Error('CDATA split rule does not round-trip response content')
+
+  console.log('verify-translation-prompt: both directions render and the XML response contract parses.')
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(`verify-translation-prompt: ${message}`)
+  process.exit(1)
+}
diff --git a/vitest.config.ts b/vitest.config.ts
index 30af2d3612..c0946e2e10 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -7,7 +7,7 @@ export default defineConfig({
   // to source; native resolution would fall through to absent `lib/` outputs.
   plugins: [tsconfigPaths({ projects: ['./tsconfig.json'] })],
   test: {
-    include: ['packages/*/*/tests/**/*.spec.ts', 'examples/*/tests/**/*.spec.ts'],
+    include: ['packages/*/*/tests/**/*.spec.ts', 'examples/*/tests/**/*.spec.ts', 'scripts/**/*.spec.ts'],
     coverage: {
       provider: 'v8',
       // Coverage measures OUR runtime source. Types-only files carry no

From bbead98c1d28787db04245c56890d664bed08319 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 14 Jul 2026 23:42:22 +0800
Subject: [PATCH 19/48] docs: align sandbox extraction with prose standard

---
 docs/config-catalog.md                      |  33 ++----
 packages/bash/bash-sandbox/src/index.ts     |  89 +++-----------
 packages/sandbox/sandbox-local/README.md    |   6 +-
 packages/sandbox/sandbox-local/src/index.ts | 122 +++++---------------
 4 files changed, 56 insertions(+), 194 deletions(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index f23f2eef0e..06b1396ebf 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -167,7 +167,7 @@ export interface Config extends LocalConfig {
 
 Depends on: [`LocalConfig`](#deepseek-aidsh-bash-local) · [`SandboxMode`](core-data-structures/sandbox.md)
 
-Source: [`packages/bash/bash-sandbox/src/index.ts:61`](../packages/bash/bash-sandbox/src/index.ts)
+Source: [`packages/bash/bash-sandbox/src/index.ts:27`](../packages/bash/bash-sandbox/src/index.ts)
 
 ## `@deepseek-ai/dsh-code-runtime-worker`
 
@@ -489,20 +489,10 @@ Source: [`packages/guard/repeat-tool-guard/src/index.ts:27`](../packages/guard/r
 /** Plugin config. All optional — `static Config` supplies the defaults. */
 export interface Config {
   /**
-   * Override the sandbox runner argv (the bwrap-shaped profile arguments are
-   * appended). A NON-EMPTY argv is the operator's assertion that this runner
-   * exists and FULLY enforces the profile (confinement reports
-   * `enforcement: 'full'`, and — the runner's kernel mechanism being unknown
-   * — carries both Linux file-denial dialects as its denial signatures) —
-   * the runner chain and its probes are skipped,
-   * and a broken runner fails loudly at execution time. The operator also
-   * supplies {@link runnerFailureSignatures}, which distinguish the runner
-   * refusing its profile from the wrapped command failing normally.
-   * Absent (or empty — the schema normalizes an omitted array to `[]`): the
-   * built-in platform chains — Linux `bwrap` then the Landlock launcher
-   * (probed in that order), darwin `sandbox-exec` (the sole candidate,
-   * selected without a probe). Used for custom/alternative runners and
-   * for deterministic fake runners in keyless test tiers.
+   * Override the runner argv; bwrap-shaped profile arguments are appended. A
+   * non-empty override asserts full enforcement and skips built-in selection and
+   * probing; a broken runner then fails at execution and must be identifiable by
+   * {@link runnerFailureSignatures}.
    */
   runnerCommand?: string[]
   /**
@@ -514,21 +504,12 @@ export interface Config {
    * own failure dialect.
    */
   runnerFailureSignatures?: string[]
-  /**
-   * Per-probe timeout in milliseconds for the chain's functional probes
-   * (default: 5000; must be a positive finite number — Node treats a 0
-   * `spawnSync` timeout as UNBOUNDED, so 0 is rejected at construction). A
-   * probe that exceeds it reads as an unusable rung, so a
-   * host slow enough to trip the default — cold NFS mounts, heavily loaded
-   * CI — would otherwise be misclassified `SANDBOX_UNAVAILABLE` with no
-   * config escape. Bounds ONE probe, and the chain walk runs each at most once
-   * per provider lifetime.
-   */
+  /** Positive timeout for each functional probe; zero would mean unbounded to Node. */
   probeTimeoutMs?: number
 }
 ```
 
-Source: [`packages/sandbox/sandbox-local/src/index.ts:35`](../packages/sandbox/sandbox-local/src/index.ts)
+Source: [`packages/sandbox/sandbox-local/src/index.ts:19`](../packages/sandbox/sandbox-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-session-persistence-jsonl`
 
diff --git a/packages/bash/bash-sandbox/src/index.ts b/packages/bash/bash-sandbox/src/index.ts
index 64c28f2009..7239d0e260 100644
--- a/packages/bash/bash-sandbox/src/index.ts
+++ b/packages/bash/bash-sandbox/src/index.ts
@@ -1,43 +1,9 @@
 /**
- * `SandboxBashExecutor`: the sandbox-consuming implementation of the
- * `@deepseek-ai/dsh-bash` executor seam. Every spawned command is wrapped by
- * the `ctx.sandbox` provider (`@deepseek-ai/dsh-sandbox`) according to the
- * configured {@link SandboxMode}: the executor hands the provider the exact
- * `['bash', '-c', command]` argv it is about to spawn and spawns the wrapped
- * argv instead. WHICH platform runner confines it — and whether one is
- * usable at all (the provider fails CLOSED with a structured
- * `SANDBOX_UNAVAILABLE` error rather than passing the argv through) — is the
- * provider's concern (`@deepseek-ai/dsh-sandbox-local` first).
- *
- * Extends `LocalBashExecutor` so all process mechanics — spawn, process-group
- * kills, timeout escalation, output collection and spill files, background
- * tasks, the credential scrub — are the local implementation's, verbatim.
- * This package adds only the seam consumption and the result facts, which is
- * exactly the split the capability seam was designed for (a sandboxing
- * executor replaces `dsh-bash-local` without touching `dsh-tool-bash`, and
- * swapping the confinement backend never touches this package).
- *
- * A failed run whose stderr carries the selected backend's own denial
- * dialect (the signatures the provider stamps on every wrap) is classified
- * as a sandbox denial on `BashRunResult.sandbox`, and every confined result
- * also carries how completely the selected runner enforces the mode
- * (`sandbox.enforcement`, from the provider's wrap). A failure carrying the
- * backend's RUNNER-FAILURE signature instead means the sandbox itself broke
- * and the command never ran: the foreground path re-throws it as the
- * structured fail-closed `SANDBOX_UNAVAILABLE` error (late twin of the
- * provider's confine-time throw), a settled background task stamps
- * `sandbox.runnerFailed` — either way a broken sandbox can never read as a
- * failing command, and the command never slips through unconfined.
- *
- * Deny-only at the seam, escalation at the tool: a denial is a reported FACT
- * here, and the one-shot user-approved escalated retry of a denied action
- * (docs/rfc/implemented/feature/2026-07-06-sandbox.md) is driven by
- * `dsh-tool-bash` through `ctx.approval` — this executor's contribution is the
- * per-call `sandboxMode` override it honors in {@link resolve}: an escalated
- * call runs (and classifies, and reports) under ITS granted mode while every
- * neighboring call keeps its session's standing mode (or the configured
- * default when that session has no override).
- *
+ * Sandbox-consuming bash executor. It wraps the exact local bash argv through
+ * `ctx.sandbox`, inherits local process mechanics, and reports the selected
+ * mode, enforcement, and denial facts. Runner failure means the command never
+ * ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while settled background
+ * tasks carry `runnerFailed`. The tool owns approval and passes per-call modes.
  * @module @deepseek-ai/dsh-bash-sandbox
  */
 
@@ -91,15 +57,9 @@ export class SandboxBashExecutor extends LocalBashExecutor {
   private readonly mode: SandboxMode
   private readonly workspaceRoot: string
   /**
-   * Per-task facts, keyed by task id from `start()` until the settle stamp
-   * consumes them: the mode the task runs under (per-call — an escalated task
-   * differs from its neighbors) plus its wrap facts. The seam returns facts
-   * PER WRAP — a provider may legally vary enforcement or dialect between
-   * calls — so overlapping background tasks must each classify against their
-   * OWN wrap; a single latest-wrap field would let a later `start()` clobber
-   * an earlier task's facts before it settles. A `danger-full-access` task
-   * has NO entry (nothing confined it), which is what the settle stamp keys
-   * off.
+   * Per-task mode and wrap facts retained until settlement. Overlapping tasks
+   * may use different modes or provider facts, so one latest-wrap field would
+   * misclassify earlier completions.
    */
   private readonly taskFacts = new Map<BashTaskId, {
     mode: ConfinedSandboxMode
@@ -143,11 +103,8 @@ export class SandboxBashExecutor extends LocalBashExecutor {
     }
     const confined = this.confine(spec.command, mode)
     const result = await super.run({ ...spec, command: confined.command })
-    // Runner failure outranks denial: the sandbox itself failed and the
-    // command NEVER RAN — surface the same structured fail-closed error a
-    // confine-time discovery throws (late detection, same outcome), with
-    // the runner's own first stderr line as the cause. Returning it as a
-    // task result would let a broken sandbox read as a failing command.
+    // Runner failure outranks denial because the command did not run. Throw the
+    // same fail-closed error as confine-time discovery with the first stderr line.
     if (classifyRunnerFailure(result, confined.runnerFailureSignatures)) {
       throw new SandboxUnavailableError(mode, result.stderr.text.trim().split('\n')[0])
     }
@@ -158,11 +115,8 @@ export class SandboxBashExecutor extends LocalBashExecutor {
     // Same stamped-by-resolve invariant as run().
     const mode = spec.sandboxMode as SandboxMode
     if (mode === 'danger-full-access') return super.start(spec)
-    // Sandbox facts are stamped at settle time by {@link notifyTaskDone}
-    // (denial classification runs against the settled task's collected
-    // stderr). The map entry lands synchronously after spawn, strictly
-    // before the earliest possible settle (a process exit reaches us no
-    // sooner than the next tick).
+    // Classification needs settled stderr. Store facts synchronously after
+    // spawn, before the earliest process completion can be observed.
     const confined = this.confine(spec.command, mode)
     const task = super.start({ ...spec, command: confined.command })
     const { enforcement, denialSignatures, runnerFailureSignatures } = confined
@@ -171,27 +125,16 @@ export class SandboxBashExecutor extends LocalBashExecutor {
   }
 
   /**
-   * Stamp the sandbox facts BEFORE completion listeners run: the base
-   * executor notifies from inside the task's settle path, so overriding the
-   * notification point is what makes `task.sandbox` visible to `onTaskDone`
-   * consumers and `done` awaiters alike. Each task classifies against the
-   * facts of ITS OWN wrap and reports ITS OWN mode (consumed from the
-   * per-task map here — settle is the entry's end of life): with per-call
-   * escalation, tasks under different modes settle side by side, so keying
-   * anything off the configured default would misreport them. A
-   * `danger-full-access` task has no map entry and carries no facts (nothing
-   * confined it); a signal-killed task (null exit code) is never a denial,
-   * mirroring the foreground classifier.
+   * Stamp per-task sandbox facts before completion listeners and `done` settle.
+   * Full-access tasks have no facts; signal deaths are not denials.
    */
   protected override notifyTaskDone(task: BashTask): void {
     const facts = this.taskFacts.get(task.id)
     if (facts !== undefined) {
       this.taskFacts.delete(task.id)
       const stderr = this.collectedStderr(task.id)
-      // Runner failure outranks denial (the command never ran; the runner's
-      // own error text can contain denial words). A settled task has no
-      // error channel left, so the fact IS the surface here — the foreground
-      // path throws instead.
+      // Runner failure outranks denial. Background settlement has no throw
+      // channel, so this fact is its counterpart to the foreground exception.
       const runnerFailed = matchesSignature(task.exitCode, stderr, facts.runnerFailureSignatures)
       task.sandbox = {
         mode: facts.mode,
diff --git a/packages/sandbox/sandbox-local/README.md b/packages/sandbox/sandbox-local/README.md
index 26ed53f175..cbd765bbf9 100644
--- a/packages/sandbox/sandbox-local/README.md
+++ b/packages/sandbox/sandbox-local/README.md
@@ -10,9 +10,9 @@ Policy is per call; the provider stores only the mechanism and cached runner ver
 
 The Seatbelt profile is allow-default with `(deny file-write*)` plus write allow-lists, so exactly the mode's promised file effects are governed: `read-only` grants the `/dev/null` literal alone; `workspace-write` adds the workspace root, `/tmp`, and the per-user darwin temp dir (`os.tmpdir()` — the platform's real temp area for mkstemp-family tools), every root canonicalized because Seatbelt matches resolved paths (`/tmp` IS `/private/tmp`). Apple marks the `sandbox-exec` CLI deprecated but ships it on every macOS; the functional probe is what fails closed if that ever changes.
 
-The Landlock launcher comes from the npm package family [`node-addon-landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run) — an entry package (this package's one runtime dependency) plus per-platform binary packages selected by npm's `os`/`cpu` fields, built and released from [its own repository](https://github.com/deepseek-harness/node-addon-landlock-run). The entry package owns the launcher's CLI contract: `launcherPath()` resolution (a host with no platform package yields a never-existing path whose probe fails exactly like an unenforcing kernel), the functional `probe()`, and `grantArgs()` flag spelling — versioned together with the binary, so probe-report parsing can never drift against it. This provider keeps only the policy side: the mode → grants mapping (`landlockProfileArgs`) and the ladder. The consumer path is rehearsed by `tests/packed-install.e2e.ts`: pack THIS package's closure, install into a throwaway consumer with the launcher family coming from the registry, assert the installed binary executable (a stripped mode bit must not masquerade as a non-enforcing kernel), and confine through it under plain `node`.
+[`node-addon-landlock-run`](https://www.npmjs.com/package/node-addon-landlock-run) supplies the platform launcher, functional probe, and CLI argument vocabulary. This provider owns only mode-to-grant mapping and runner selection. Keeping path resolution and probe parsing with the versioned binary prevents contract drift.
 
-Every rung has its keyless world-proof (`tests/bwrap.e2e.ts`, `tests/landlock.e2e.ts`, `tests/seatbelt.e2e.ts`), each self-skipping where its runner is absent; CI's `sandbox-e2e` matrix runs all of them against real kernels (bwrap plus one Landlock leg per architecture on Linux, Seatbelt on macOS) and fails on a silent all-skip.
+Each rung has a self-skipping keyless world-effect test; CI runs platform legs against real kernels and rejects a silent all-skip. The packed-install test exercises the registry launcher and executable mode through a plain-Node consumer.
 
 ```yaml
 - id: sandbox
@@ -23,7 +23,7 @@ Consumers: [`@deepseek-ai/dsh-bash-sandbox`](../../bash/bash-sandbox/); see [the
 
 ## Model Experience
 
-Indirectly, through `dsh-bash-sandbox` and `dsh-tool-bash`, which render this provider's enforcement dialect as the exact `[sandbox: file access denied under <mode> mode]` marker or the [`dsh-sandbox`](../sandbox/README.md) `SANDBOX_UNAVAILABLE` text while keeping runner selection and profiles outside context.
+Indirectly, through [`dsh-bash-sandbox`](../../bash/bash-sandbox/README.md) and [`dsh-tool-bash`](../../bash/tool-bash/README.md), which render this provider's enforcement and denial facts while the [`dsh-sandbox`](../sandbox/README.md) seam owns the `SANDBOX_UNAVAILABLE` text and runner selection and profiles stay outside context.
 
 ## Known Limitations and Deferred Work
 
diff --git a/packages/sandbox/sandbox-local/src/index.ts b/packages/sandbox/sandbox-local/src/index.ts
index 007debb9f0..98dc86d23e 100644
--- a/packages/sandbox/sandbox-local/src/index.ts
+++ b/packages/sandbox/sandbox-local/src/index.ts
@@ -1,24 +1,8 @@
 /**
- * `LocalSandboxProvider`: the local implementation of the
- * `@deepseek-ai/dsh-sandbox` seam. Wraps a caller's argv in a platform
- * confinement runner selected BY PLATFORM: each platform names its runner
- * chain ({@link PLATFORM_CHAINS}), a chain of one is selected directly (no
- * probe — there is nothing to arbitrate), and a chain of several is probed
- * FUNCTIONALLY in preference order (build and enforce a real profile once,
- * not `--version`), the verdict cached for the provider's lifetime. Linux:
- * `bwrap`, else the `landlock-run` Landlock launcher (kernel confinement
- * that needs no userns/mount privileges; distributed as the npm package
- * family `node-addon-landlock-run` — the decision recorded in
- * docs/rfc/implemented/feature/2026-07-06-sandbox.md); darwin: macOS
- * `sandbox-exec` speaking a Seatbelt (SBPL) profile, unprobed.
- * When the platform has no chain or no candidate passes,
- * {@link LocalSandboxProvider.confine} FAILS CLOSED with the seam's
- * structured `SANDBOX_UNAVAILABLE` error instead of passing the argv
- * through unconfined; an unusable runner selected WITHOUT a probe fails
- * closed at execution time instead (it refuses to run the command), which
- * the wrap's `runnerFailureSignatures` let consumers classify as a sandbox
- * failure rather than a task failure.
- *
+ * Local sandbox backend. It selects the platform runner chain (Linux bwrap then
+ * Landlock; macOS Seatbelt), functionally probes competing candidates once, and
+ * reports each wrap's enforcement and stderr dialects. Missing or unusable
+ * confinement fails closed rather than returning the original argv.
  * @module @deepseek-ai/dsh-sandbox-local
  */
 
@@ -34,20 +18,10 @@ import { bwrapProfileArgs, landlockProfileArgs, seatbeltProfileArgs } from './pr
 /** Plugin config. All optional — `static Config` supplies the defaults. */
 export interface Config {
   /**
-   * Override the sandbox runner argv (the bwrap-shaped profile arguments are
-   * appended). A NON-EMPTY argv is the operator's assertion that this runner
-   * exists and FULLY enforces the profile (confinement reports
-   * `enforcement: 'full'`, and — the runner's kernel mechanism being unknown
-   * — carries both Linux file-denial dialects as its denial signatures) —
-   * the runner chain and its probes are skipped,
-   * and a broken runner fails loudly at execution time. The operator also
-   * supplies {@link runnerFailureSignatures}, which distinguish the runner
-   * refusing its profile from the wrapped command failing normally.
-   * Absent (or empty — the schema normalizes an omitted array to `[]`): the
-   * built-in platform chains — Linux `bwrap` then the Landlock launcher
-   * (probed in that order), darwin `sandbox-exec` (the sole candidate,
-   * selected without a probe). Used for custom/alternative runners and
-   * for deterministic fake runners in keyless test tiers.
+   * Override the runner argv; bwrap-shaped profile arguments are appended. A
+   * non-empty override asserts full enforcement and skips built-in selection and
+   * probing; a broken runner then fails at execution and must be identifiable by
+   * {@link runnerFailureSignatures}.
    */
   runnerCommand?: string[]
   /**
@@ -59,16 +33,7 @@ export interface Config {
    * own failure dialect.
    */
   runnerFailureSignatures?: string[]
-  /**
-   * Per-probe timeout in milliseconds for the chain's functional probes
-   * (default: 5000; must be a positive finite number — Node treats a 0
-   * `spawnSync` timeout as UNBOUNDED, so 0 is rejected at construction). A
-   * probe that exceeds it reads as an unusable rung, so a
-   * host slow enough to trip the default — cold NFS mounts, heavily loaded
-   * CI — would otherwise be misclassified `SANDBOX_UNAVAILABLE` with no
-   * config escape. Bounds ONE probe, and the chain walk runs each at most once
-   * per provider lifetime.
-   */
+  /** Positive timeout for each functional probe; zero would mean unbounded to Node. */
   probeTimeoutMs?: number
 }
 
@@ -131,13 +96,10 @@ type SelectedRunner = { runner: 'bwrap' | 'landlock' | 'seatbelt'; enforcement:
 const PLATFORM_CHAINS: Record<string, readonly SelectedRunner['runner'][]> = {
   linux: ['bwrap', 'landlock'],
   darwin: ['seatbelt'],
-  // Reserved slot, deliberately empty: Windows support fills it with a
-  // confinement runner (AppContainer / restricted-token family, shipped from
-  // its own repository on the landlock-run template) plus a
-  // SelectedRunner['runner'] union member — the switches' assertNever guards
-  // then walk the implementer to every site. An empty chain fails closed at
-  // confine(), identical to an unlisted platform: reserving the slot never
-  // weakens the fail-closed end.
+  // Reserved slot, deliberately empty: Windows support fills it with a confinement runner
+  // (AppContainer / restricted-token family, shipped from its own repository on the
+  // landlock-run template) plus a SelectedRunner['runner'] union member — the switches'
+  // assertNever guards then walk the implementer to every site.
   win32: [],
 }
 
@@ -168,16 +130,9 @@ function assertPositiveFinite(name: string, value: number): void {
 }
 
 /**
- * The denial dialect each runner's kernel speaks — the case-insensitive
- * stderr substrings a denied file effect produces under it, carried on every
- * wrap (the seam's `ConfinedArgv.denialSignatures`). Kernel facts, not
- * tunables: bwrap denies through its read-only bind mounts (EROFS), Landlock
- * refuses with EACCES, Seatbelt with EPERM — whose text is also what
- * non-file EPERM boundaries print, the residual imprecision the consumer's
- * conservative classifier documents. An operator-configured `runnerCommand`
- * has an unknown kernel mechanism, so its wraps carry both Linux file-denial
- * dialects; bare EPERM stays excluded there (it names non-file boundaries
- * the mode vocabulary does not govern).
+ * The denial dialect each runner's kernel speaks — the case-insensitive stderr substrings a
+ * denied file effect produces under it, carried on every wrap (the seam's
+ * `ConfinedArgv.denialSignatures`).
  */
 const DENIAL_SIGNATURES = {
   bwrap: ['read-only file system'],
@@ -187,15 +142,9 @@ const DENIAL_SIGNATURES = {
 } as const satisfies Record<SelectedRunner['runner'] | 'runnerCommand', readonly string[]>
 
 /**
- * How each runner's OWN failure identifies itself on stderr (the seam's
- * `ConfinedArgv.runnerFailureSignatures`): every runner prefixes its error
- * lines with its program name, and the shell's runner-not-found message
- * carries the same `name: ` shape (`bash: bwrap: command not found`,
- * `bash: …/bin/landlock-run: No such file or directory`) — so one substring
- * per runner covers both "runner broke" and "runner missing". Consumers
- * match these BEFORE the denial dialect: a runner's error text can contain
- * denial words (an unopenable grant root reports `Permission denied`), and
- * a runner failure means the command never ran at all.
+ * Runner-owned stderr prefixes cover both internal refusal and shell-level
+ * not-found errors. Consumers match these before denial text because the
+ * command never ran on this path.
  */
 const RUNNER_FAILURE_SIGNATURES = {
   bwrap: ['bwrap: '],
@@ -248,17 +197,15 @@ export class LocalSandboxProvider extends SandboxProvider {
   }
 
   /**
-   * Wrap `argv` in the selected runner's invocation for `policy` — the
-   * configured `runnerCommand` when present (the operator's assertion, no
-   * probe), else the platform chain's runner speaking its own profile
-   * dialect. Every wrap carries the runner's enforcement completeness, its
-   * denial dialect, and its runner-failure signatures.
+   * Wrap `argv` in the selected runner's invocation for `policy` — the configured
+   * `runnerCommand` when present (the operator's assertion, no probe), else the platform
+   * chain's runner speaking its own profile dialect.
+   *
    * @param argv - the exact argv the caller is about to spawn.
    * @param policy - the file-effect policy this execution runs under.
-   * @returns the wrapped argv plus the selected backend's enforcement
-   *   completeness, denial signatures, and runner-failure signatures;
-   *   throws the fail-closed `SANDBOX_UNAVAILABLE` error when the platform
-   *   has no usable runner.
+   * @returns the wrapped argv plus the selected backend's enforcement completeness, denial
+   *   signatures, and runner-failure signatures; throws the fail-closed
+   *   `SANDBOX_UNAVAILABLE` error when the platform has no usable runner.
    */
   confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv {
     if (this.runnerCommand !== undefined) {
@@ -267,14 +214,9 @@ export class LocalSandboxProvider extends SandboxProvider {
         argv: [...this.runnerCommand, ...bwrapProfileArgs(policy), '--', ...argv],
         enforcement: 'full',
         denialSignatures: DENIAL_SIGNATURES.runnerCommand,
-        // The operator names the configured runner's OWN pre-exec refusal
-        // dialect; the consumer additionally re-joins the wrap through an
-        // outer `bash -c 'exec …'`, so we can add the missing/unexecutable
-        // outer-shell shapes ourselves. Scoping every automatic shape to
-        // argv0 keeps in-command errors out (a bare `exec:`/`Permission
-        // denied` prefix would claim tool output; `exec: <argv0>: not found`
-        // cannot). The residual text-collision trade is documented by the
-        // seam's conservative classifier contract.
+        // The operator names the configured runner's own pre-exec refusal dialect; the consumer
+        // additionally re-joins the wrap through an outer `bash -c 'exec …'`, so we can add the
+        // missing/unexecutable outer-shell shapes ourselves.
         runnerFailureSignatures: [
           ...this.configuredRunnerFailureSignatures,
           `exec: ${argv0}: not found`,
@@ -320,11 +262,7 @@ export class LocalSandboxProvider extends SandboxProvider {
     const chain = this.internals.chain ?? PLATFORM_CHAINS[this.internals.platform ?? process.platform] ?? []
     const [first, ...rest] = chain
     if (first === undefined) return 'unavailable'
-    // One candidate = nothing to arbitrate: select it without probing. Its
-    // runner fails closed at EXECUTION time if unusable (refuses to run the
-    // command), and the wrap's runnerFailureSignatures let the consumer
-    // classify that as a sandbox failure — never a silent unconfined run,
-    // never a plain task failure.
+    // A sole candidate needs no arbitration; its execution-time refusal still fails closed.
     if (rest.length === 0) return { runner: first, enforcement: STATIC_ENFORCEMENT[first] }
     for (const runner of chain) {
       const enforcement = this.probeRunner(runner)

From 1a69a3debedbe6b54b53f069084cc68b6d3ee284 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 15 Jul 2026 11:40:37 +0800
Subject: [PATCH 20/48] fix(tasks): bind cleanup and notices to exact owners

Task records previously retained only ownerSession. If an old agent scope unwound after another agent reused the same agent and session ids, cleanup selected both records and could cancel replacement work. The completion surface also re-resolved the session at settlement, which could inject an old task notice into the replacement agent.

Retain the exact Agent instance for lifecycle work, select owner cleanup by object identity, and pass that exact owner to completion listeners. Keep read, list, kill, and wait authorization session-based as the runtime RFC intends. Add regressions for cleanup and notice routing under id reuse, then update the public docs and generated API catalogs.
---
 docs/cordis-catalog/services.md               |  2 +-
 docs/core-data-structures/tasks.md            | 13 +++---
 ...06-20-generic-long-running-tool-runtime.md |  8 ++--
 .../cordis/tool-cordis/src/api-catalog.ts     |  2 +-
 packages/tasks/tasks/README.md                |  4 +-
 packages/tasks/tasks/src/index.ts             | 34 +++++++--------
 packages/tasks/tasks/src/types.ts             | 19 +++++----
 packages/tasks/tasks/tests/tasks.spec.ts      | 33 +++++++++++++++
 packages/tasks/tool-tasks/README.md           |  2 +-
 packages/tasks/tool-tasks/src/index.ts        | 16 +++----
 .../tasks/tool-tasks/tests/tool-tasks.spec.ts | 42 +++++++++++++++----
 11 files changed, 117 insertions(+), 58 deletions(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index dd8663ae32..c8f587c765 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -259,7 +259,7 @@ attachSurface(name: string): () => void
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/tasks/tasks/src/index.ts:99`](../../packages/tasks/tasks/src/index.ts)
+Source: [`packages/tasks/tasks/src/index.ts:98`](../../packages/tasks/tasks/src/index.ts)
 
 ## `ctx.tools` — `ToolRegistry`
 
diff --git a/docs/core-data-structures/tasks.md b/docs/core-data-structures/tasks.md
index 83351f0651..8ee766de78 100644
--- a/docs/core-data-structures/tasks.md
+++ b/docs/core-data-structures/tasks.md
@@ -99,11 +99,12 @@ interface TaskSnapshot {
   /** The producer-supplied one-line label. */
   label: string
   /**
-   * The owner's session id (`session.header.id`), for surfaces that must
-   * reach the owning agent (the completion-notice injector); absent for
-   * unowned tasks. Session ids are runtime-shared identifiers, not secrets —
-   * the read/kill/wait/list FENCE is what isolation rests on. The shared
-   * {@link SessionId} brand is preserved across this package boundary.
+   * The owner's session id (`session.header.id`), for authorization and
+   * correlation; absent for unowned tasks. A listener that must reach the
+   * lifecycle owner receives the exact Agent separately through
+   * {@link TaskDoneListener}. Session ids are runtime-shared identifiers, not
+   * secrets — the read/kill/wait/list FENCE is what isolation rests on. The
+   * shared {@link SessionId} brand is preserved across this package boundary.
    */
   ownerSession?: SessionId
   /** Current lifecycle state. */
@@ -140,4 +141,4 @@ interface TaskRead {
 
 ## The service
 
-`TaskService` (`ctx.tasks` — [`packages/tasks/tasks/src/index.ts`](../../packages/tasks/tasks/src/index.ts)): `start` (preflight → producer `run()` → atomic commit, fenced by `attachSurface`), non-consuming `get`/`list` (caller-scoped — owned-by-caller plus unowned only), `read` (consuming for stream kinds), `kill` (producer `cancel` first; a throw leaves the task untouched), `wait` (bounded, abort cancels the wait only), and `onTaskDone` (a `TaskDoneListener` per terminal record, effect-scoped, contained). Start validates that an owned task names the exact live Agent instance currently registered under its id, so an old reference cannot bind work to a replacement agent's cleanup after id reuse. Every read/kill/wait/get separately compares the task's owner session with the caller's and rejects a foreign one. Owned tasks register one async cleanup through the exact owner's `agent.ctx`; scope disposal cancels them and normally awaits producer quiescence. A teardown cancel that throws force-fails only the registry record and reports that the underlying work may be orphaned, preventing disposal deadlock without claiming quiescence. The model-facing surface over all of this is [dsh-tool-tasks](../../packages/tasks/tool-tasks/README.md).
+`TaskService` (`ctx.tasks` — [`packages/tasks/tasks/src/index.ts`](../../packages/tasks/tasks/src/index.ts)): `start` (preflight → producer `run()` → atomic commit, fenced by `attachSurface`), non-consuming `get`/`list` (caller-scoped — owned-by-caller plus unowned only), `read` (consuming for stream kinds), `kill` (producer `cancel` first; a throw leaves the task untouched), `wait` (bounded, abort cancels the wait only), and `onTaskDone` (a `TaskDoneListener` per terminal record, given the exact lifecycle owner, effect-scoped, contained). Start retains the exact live Agent instance validated under its id; owner-scope cleanup selects by that identity, so a reused agent/session id cannot make an old scope cancel replacement work. Read/kill/wait/get authorization remains session-based and rejects a foreign session. A teardown cancel that throws force-fails only the registry record and reports that the underlying work may be orphaned, preventing disposal deadlock without claiming quiescence. The model-facing surface over all of this is [dsh-tool-tasks](../../packages/tasks/tool-tasks/README.md).
diff --git a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index 6c62f96a65..b179ceaa49 100644
--- a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -65,7 +65,7 @@ Registrations are NOT effect-scoped to the registering fiber: a task belongs to
 
 ## Authorization and the service surface
 
-Cross-session isolation lives IN the runtime so every consumer gets the same rule for free: read/kill/wait/get take the caller (`Agent | undefined`), and a task whose owner session differs from the caller's session is rejected (`!== undefined` comparison — an unowned task is open, a no-agent caller cannot match an owned one). `list(caller)` returns only the caller-visible tasks (owned-by-caller or unowned) — a global listing would leak other sessions' labels. The snapshot carries that owner as the canonical branded `SessionId`, not a package-local token or bare string. Lifecycle ownership is checked independently at start: the supplied owner must be the exact live `Agent` instance currently registered under its id, so an old object cannot attach its session's work to a replacement agent's cleanup after id reuse.
+Cross-session isolation lives IN the runtime so every consumer gets the same rule for free: read/kill/wait/get take the caller (`Agent | undefined`), and a task whose owner session differs from the caller's session is rejected (`!== undefined` comparison — an unowned task is open, a no-agent caller cannot match an owned one). `list(caller)` returns only the caller-visible tasks (owned-by-caller or unowned) — a global listing would leak other sessions' labels. The snapshot carries that authorization identity as the canonical branded `SessionId`, not a package-local token or bare string. Lifecycle ownership is independent: start retains the exact live `Agent` instance, owner cleanup selects by object identity, and completion listeners receive that exact owner, so id reuse cannot redirect cleanup or notices to a replacement.
 
 ```ts ignore-check
 class TaskService extends Service {           // ctx.tasks
@@ -75,7 +75,7 @@ class TaskService extends Service {           // ctx.tasks
   read(id: TaskId, caller?: Agent): TaskRead               // delta (stream kinds, consuming) or final output (final kinds, idempotent) + snapshot
   kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-terminal'
   wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
-  onTaskDone(listener: (snapshot: TaskSnapshot) => void): () => void   // effect-scoped, contained, never fires after dispose
+  onTaskDone(listener: (snapshot: TaskSnapshot, owner: Agent | undefined) => void): () => void   // exact lifecycle owner; effect-scoped, contained
   attachSurface(name: string): () => void     // the misconfiguration fence, below
 }
 ```
@@ -96,7 +96,7 @@ class TaskService extends Service {           // ctx.tasks
 
 One system-prompt section (order 106, next to `tool:bash`) teaches the cross-call habit the per-tool descriptions cannot: track every returned task id; you are notified in-session when a task finishes, so do not busy-poll or sleep on one — keep working on independent steps and do not duplicate a running task's work; do not produce a final answer while a relevant task still runs — call `task_output` (with `wait` when blocked) to collect it first; `task_kill` tasks that stopped mattering. The do-not-poll and do-not-duplicate sentences are near-verbatim convergent across Claude Code, Kimi Code, and OpenCode — they are the two failure modes every peer engineered against.
 
-Completion notices stay durable context, not a wake-up (`agent.inject()` appends a logged `context/message` the next model request sees; it does not run the model): on `onTaskDone`, `dsh-tool-tasks` injects `background task <id> (<kind>: <label>) finished [status: …]. Read its output with task_output.` into the owning agent's session, with the same disposed-race containment `dsh-tool-bash` used to carry. Notices are deduplicated the way Claude Code and Kimi Code both learned to: a task the model explicitly killed, or whose terminal state a read/wait already returned (including a wait pending at the moment of settlement), is marked `reported` and its notice suppressed — never a redundant "finished" for work the model just collected or ended. The model-visible ⟺ logged invariant holds with no new session event type.
+Completion notices stay durable context, not a wake-up (`agent.inject()` appends a logged `context/message` the next model request sees; it does not run the model): on `onTaskDone`, `dsh-tool-tasks` injects `background task <id> (<kind>: <label>) finished [status: …]. Read its output with task_output.` through the exact owner captured at start, never a replacement found through a reused agent/session id, with the disposed-race contained. Notices are deduplicated the way Claude Code and Kimi Code both learned to: a task the model explicitly killed, or whose terminal state a read/wait already returned (including a wait pending at the moment of settlement), is marked `reported` and its notice suppressed — never a redundant "finished" for work the model just collected or ended. The model-visible ⟺ logged invariant holds with no new session event type.
 
 ## Producer opt-in and schema exposure
 
@@ -106,7 +106,7 @@ Whether a producer tool offers `run_in_background` is that producer's own defaul
 
 A contract-compliant background task must not outlive its owner: the subagent case leaks live child agents/sessions otherwise, and `agent/disposed` is an observe-only notification rather than a quiescence seam. Every live agent already owns an awaited structural registration scope ([agent-scope contract](2026-07-08-agent-scope-contexts.md)), so the task runtime uses that single lifecycle mechanism:
 
-- After validating the exact registered owner instance, the first task for that owner registers an async effect through `owner.ctx`. The effect belongs to the agent scope, survives producer reloads, cancels that owner's live tasks, awaits each terminal record, and drops the snapshots.
+- After validating and retaining the exact registered owner instance, the first task for that owner registers an async effect through `owner.ctx`. The effect belongs to the agent scope, survives producer reloads, selects tasks by exact owner identity, cancels them, awaits each terminal record, and drops the snapshots; a replacement reusing the same ids is outside that set.
 - `AgentHandle.dispose()` stops and drains the driver, detaches the agent and session, then awaits scope disposal. The task cleanup therefore participates in the same memoized quiescence boundary as every other agent-owned registration; no task-specific link exists in `AgentRegistry` or the loop.
 - The tasks service retains each exact owner-effect disposer so service reload can detach callbacks from still-live scopes after global task teardown, rather than leaving a dead service retained until every agent exits.
 
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 8da1ff9498..494c6d4210 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -939,7 +939,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'TaskDoneListener',
-    declaration: 'export type TaskDoneListener = (snapshot: TaskSnapshot) => void;',
+    declaration: 'export type TaskDoneListener = (snapshot: TaskSnapshot, owner: Agent | undefined) => void;',
   },
   {
     name: 'TaskHooks',
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index 8ab536b81f..006482988c 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -9,7 +9,7 @@ The background task registry (`ctx.tasks`): a runtime-global, CONCRETE service (
 - `read(id, caller?): TaskRead` — stream kinds consume the per-task cursor (v1's single intended reader is the owning model — a non-consuming multi-reader surface would be a cursor/snapshot API extension, not a `read` change); final kinds read the terminal output idempotently.
 - `kill(id, caller?, reason?)` — `'requested'` (live task: producer `cancel` runs first — a throw fails the kill loud and leaves the task untouched — then `stopping`) or `'already-terminal'`. Every successful kill marks the task `reported` (the killer saw the end → completion notice suppressed).
 - `wait(id, timeoutMs, caller?, signal?)` — resolves with the terminal snapshot (marked `reported`), or the live snapshot at timeout; an aborted signal rejects the WAIT only — unless the task already settled, in which case the wait still resolves and delivers the terminal snapshot (settlement suppressed the completion notice on this waiter's behalf, so rejecting would leave the finish both unreported and un-noticed). Timing is a [`dsh-timeout`](../../util/timeout/README.md) `deadline()` scoped to the `TASK_WAIT_TIMEOUT` code, so a nested foreign deadline never misreads as a wait timeout; timeout and abort detach their settlement resolver immediately, keeping retention bounded while the task remains live.
-- `onTaskDone(listener)` — exactly once per terminal task record; effect-scoped, per-listener containment, silent after service disposal.
+- `onTaskDone(listener)` — exactly once per terminal task record, with the snapshot plus its exact lifecycle owner (or `undefined`); effect-scoped, per-listener containment, silent after service disposal.
 - `attachSurface(name)` — declares a control surface exists (the model tools, or a deployment's custom surface); effect-scoped.
 
 Every read/kill/wait/get compares the task's owner session (`owner.session.header.id`) with the caller's and rejects a foreign one — ids are predictable (`bash-1`), so the fence, not id secrecy, is the isolation boundary.
@@ -17,7 +17,7 @@ Every read/kill/wait/get compares the task's owner session (`owner.session.heade
 ## Lifecycle
 
 - Registrations are NOT effect-scoped to the registering fiber: tasks belong to their owning agent + producing backend, so producer/surface HMR reloads never touch them.
-- An owned task must name the exact live `Agent` instance currently registered under its id (stale objects are rejected after id reuse), then attaches one awaited cleanup through `owner.ctx`: agent-scope disposal cancels live tasks, awaits contract-compliant producers to quiescence, and drops their snapshots. If a teardown cancel throws, it force-fails the record and logs that the underlying work may be orphaned rather than deadlocking `AgentHandle.dispose()`.
+- An owned task retains the exact live `Agent` instance validated at start and attaches one awaited cleanup through `owner.ctx`: agent-scope disposal selects only that instance's tasks, cancels them, awaits contract-compliant producers to quiescence, and drops their snapshots. Reused agent/session ids cannot make an old cleanup sweep replacement work. If a teardown cancel throws, it force-fails the record and logs that the underlying work may be orphaned rather than deadlocking `AgentHandle.dispose()`.
 - Service disposal closes the listener registry first, applies the same cancellation rule to every live task, awaits terminal records, then detaches its effects from still-live agent scopes so a reloaded tasks service is not retained until those agents exit.
 - A producer whose `cancel` returns but never causes `done` to settle remains indistinguishable from a slow stop and can stall teardown; solving that residual requires an explicit bounded-lifetime or forced-disposal design.
 
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index f7218d773f..c4e515d2e9 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -32,7 +32,6 @@
 
 import { Context, Service } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import type { SessionId } from '@deepseek-ai/dsh-session'
 import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
 import { TaskId } from './types.ts'
 import type { TaskDoneListener, TaskOutcome, TaskRead, TaskSnapshot, TaskStart, TaskStatus } from './types.ts'
@@ -67,8 +66,8 @@ interface TrackedTask {
   id: TaskId
   kind: string
   label: string
-  /** The owner's session id (`session.header.id`), or undefined for an unowned task. */
-  ownerSession: SessionId | undefined
+  /** Exact lifecycle owner; session-id authorization is derived from it. */
+  owner: Agent | undefined
   cancel: (reason?: string) => void
   readOutput: (() => string) | undefined
   status: TaskStatus
@@ -159,7 +158,7 @@ export class TaskService extends Service {
       id,
       kind: spec.kind,
       label: spec.label,
-      ownerSession: spec.owner?.session.header.id,
+      owner: spec.owner,
       cancel: hooks.cancel.bind(hooks),
       readOutput: hooks.readOutput?.bind(hooks),
       status: 'running',
@@ -197,7 +196,7 @@ export class TaskService extends Service {
   list(caller?: Agent): TaskSnapshot[] {
     const session = caller?.session.header.id
     return [...this.store.values()]
-      .filter(task => task.ownerSession === undefined || task.ownerSession === session)
+      .filter(task => task.owner === undefined || task.owner.session.header.id === session)
       .map(task => this.snapshot(task))
   }
 
@@ -349,10 +348,11 @@ export class TaskService extends Service {
 
   /**
    * Register a completion listener, called exactly once per terminal task
-   * record with its snapshot. Effect-scoped (disposed with the calling fiber);
-   * per-listener containment (one throwing listener is logged, never starves
-   * the rest); never fires after this service is disposed.
-   * @param listener - called with each settling task's terminal snapshot.
+   * record with its snapshot and exact lifecycle owner (or `undefined` for an
+   * unowned task). Effect-scoped (disposed with the calling fiber); per-listener
+   * containment (one throwing listener is logged, never starves the rest);
+   * never fires after this service is disposed.
+   * @param listener - called with each terminal snapshot and its exact owner.
    * @returns the disposer that unregisters the listener.
    */
   onTaskDone(listener: TaskDoneListener): () => void {
@@ -398,18 +398,19 @@ export class TaskService extends Service {
    * open, and a no-agent caller can never match an owned one).
    */
   private assertAccess(task: TrackedTask, caller?: Agent): void {
-    if (task.ownerSession !== undefined && task.ownerSession !== caller?.session.header.id) {
+    if (task.owner !== undefined && task.owner.session.header.id !== caller?.session.header.id) {
       throw new Error(`task ${task.id} belongs to another session`)
     }
   }
 
   /** Project a fresh read-only snapshot from the mutable record. */
   private snapshot(task: TrackedTask): TaskSnapshot {
+    const ownerSession = task.owner?.session.header.id
     return {
       id: task.id,
       kind: task.kind,
       label: task.label,
-      ...task.ownerSession !== undefined ? { ownerSession: task.ownerSession } : {},
+      ...ownerSession !== undefined ? { ownerSession } : {},
       status: task.status,
       ...task.detail !== undefined ? { detail: task.detail } : {},
       startedAt: task.startedAt,
@@ -439,7 +440,7 @@ export class TaskService extends Service {
       const snapshot = this.snapshot(task)
       for (const listener of this.listeners) {
         try {
-          listener(snapshot)
+          listener(snapshot, task.owner)
         } catch (error: unknown) {
           this.selfCtx.logger.warn(`tasks: onTaskDone listener threw for ${task.id}: ${String(error)}`)
         }
@@ -474,19 +475,18 @@ export class TaskService extends Service {
       throw new Error(`agent "${ownerId}" is not the registered agent instance (background task owner must be live)`)
     }
     if (this.ownerCleanups.has(owner)) return
-    const ownerSession = owner.session.header.id
     // Attach FIRST, record after: an already-disposing scope rejects effects,
     // and marking the owner as covered before that would poison later starts.
     const detach = owner.ctx.effect(() => async () => {
       this.ownerCleanups.delete(owner)
-      await this.disposeOwned(ownerSession)
+      await this.disposeOwned(owner)
     }, 'tasks.ownerCleanup()')
     this.ownerCleanups.set(owner, detach)
   }
 
-  /** Cancel, await terminal records, and drop every task owned by one session. */
-  private async disposeOwned(ownerSession: SessionId): Promise<void> {
-    const owned = [...this.store.values()].filter(task => task.ownerSession === ownerSession)
+  /** Cancel, await terminal records, and drop every task owned by one exact agent lifecycle. */
+  private async disposeOwned(owner: Agent): Promise<void> {
+    const owned = [...this.store.values()].filter(task => task.owner === owner)
     this.cancelForTeardown(owned, 'owner disposed')
     await Promise.all(owned.map(task => task.settled))
     for (const task of owned) this.store.delete(task.id)
diff --git a/packages/tasks/tasks/src/types.ts b/packages/tasks/tasks/src/types.ts
index 0345269645..159e45e09d 100644
--- a/packages/tasks/tasks/src/types.ts
+++ b/packages/tasks/tasks/src/types.ts
@@ -136,11 +136,12 @@ export interface TaskSnapshot {
   /** The producer-supplied one-line label. */
   label: string
   /**
-   * The owner's session id (`session.header.id`), for surfaces that must
-   * reach the owning agent (the completion-notice injector); absent for
-   * unowned tasks. Session ids are runtime-shared identifiers, not secrets —
-   * the read/kill/wait/list FENCE is what isolation rests on. The shared
-   * {@link SessionId} brand is preserved across this package boundary.
+   * The owner's session id (`session.header.id`), for authorization and
+   * correlation; absent for unowned tasks. A listener that must reach the
+   * lifecycle owner receives the exact Agent separately through
+   * {@link TaskDoneListener}. Session ids are runtime-shared identifiers, not
+   * secrets — the read/kill/wait/list FENCE is what isolation rests on. The
+   * shared {@link SessionId} brand is preserved across this package boundary.
    */
   ownerSession?: SessionId
   /** Current lifecycle state. */
@@ -177,5 +178,9 @@ export interface TaskRead {
   snapshot: TaskSnapshot
 }
 
-/** Completion callback registered via {@link TaskService.onTaskDone}. */
-export type TaskDoneListener = (snapshot: TaskSnapshot) => void
+/**
+ * Completion callback registered via {@link TaskService.onTaskDone}.
+ * `owner` is the exact lifecycle instance supplied at start, not a registry
+ * lookup by reusable agent or session id; it is absent for unowned tasks.
+ */
+export type TaskDoneListener = (snapshot: TaskSnapshot, owner: Agent | undefined) => void
diff --git a/packages/tasks/tasks/tests/tasks.spec.ts b/packages/tasks/tasks/tests/tasks.spec.ts
index 1ae4567dce..8d28f66862 100644
--- a/packages/tasks/tasks/tests/tasks.spec.ts
+++ b/packages/tasks/tasks/tests/tasks.spec.ts
@@ -506,6 +506,39 @@ describe('TaskService owner cleanup', () => {
     expect(ctx.tasks.list(owner)).toEqual([])
   })
 
+  it('does not let an old scope cleanup cancel a same-id/session replacement task', async () => {
+    const ctx = await harness()
+    const oldOwner = stubAgent(ctx, 'owner', 'shared-session')
+    const detachOld = ctx.agents.register(oldOwner)
+    const cancels: string[] = []
+
+    function start(owner: Agent, label: string): TaskId {
+      let settle!: (outcome: TaskOutcome) => void
+      return ctx.tasks.start({
+        kind: 'bash',
+        label,
+        owner,
+        run: () => ({
+          cancel() { cancels.push(label); settle({ status: 'killed' }) },
+          done: new Promise<TaskOutcome>((resolve) => { settle = resolve }),
+        }),
+      })
+    }
+
+    start(oldOwner, 'old task')
+    detachOld()
+    const replacement = stubAgent(ctx, 'owner', 'shared-session')
+    ctx.agents.register(replacement)
+    const replacementId = start(replacement, 'replacement task')
+
+    await disposeAgentScope(oldOwner)
+    expect(cancels).toEqual(['old task'])
+    expect(ctx.tasks.list(replacement).map(task => task.id)).toEqual([replacementId])
+
+    await disposeAgentScope(replacement)
+    expect(cancels).toEqual(['old task', 'replacement task'])
+  })
+
   it('registers owner cleanup on the agent scope rather than the tasks fiber', async () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
diff --git a/packages/tasks/tool-tasks/README.md b/packages/tasks/tool-tasks/README.md
index 4e48a4223f..54d859734f 100644
--- a/packages/tasks/tool-tasks/README.md
+++ b/packages/tasks/tool-tasks/README.md
@@ -12,7 +12,7 @@ ACP render intent: all three are `generic` cards (`read`/`read`/`execute`) — a
 
 ## Completion notices
 
-On `onTaskDone`, injects `background task <id> (<kind>: <label>) finished [status: …]. Read its output with task_output.` into the owning agent's session (`agent.inject()` — durable context for the next request, not a wake-up). Suppressed when the snapshot is `reported` (the model already killed it, or a read/wait returned the end) — never a redundant "finished". The disposed-owner race is contained; a missing agent registry drops the notice.
+On `onTaskDone`, injects `background task <id> (<kind>: <label>) finished [status: …]. Read its output with task_output.` through the exact owner `Agent` captured at task start (`agent.inject()` — durable context for the next request, not a wake-up). It never re-resolves a reusable agent/session id to a replacement. Suppressed when the snapshot is `reported` (the model already killed it, or a read/wait returned the end) — never a redundant "finished"; the disposed-owner race is contained.
 
 ## Config
 
diff --git a/packages/tasks/tool-tasks/src/index.ts b/packages/tasks/tool-tasks/src/index.ts
index 65d9f0ce0e..f7a91f0abd 100644
--- a/packages/tasks/tool-tasks/src/index.ts
+++ b/packages/tasks/tool-tasks/src/index.ts
@@ -93,19 +93,15 @@ export function apply(ctx: Context, config: Config): void {
     text: 'Track every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task\'s work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.',
   })
 
-  // Background completion → inject a notice into the owning agent's session.
-  // `ctx.get('agents')` (not static inject): this listener runs from a
-  // detached settlement continuation on the tasks fiber — a foreign fiber —
-  // where the `ctx.agents` property proxy would throw; `ctx.get` is the
-  // topology-independent lookup. No registry mounted → drop the notice.
-  ctx.tasks.onTaskDone((snapshot) => {
+  // Background completion → inject a notice through the exact lifecycle owner.
+  // Re-resolving by a reusable agent/session id could target a replacement
+  // while the old owner's scope is still unwinding.
+  ctx.tasks.onTaskDone((snapshot, owner) => {
     // A reported terminal state was already surfaced by an explicit
     // read/wait/kill response — a notice would be a redundant "finished".
-    if (snapshot.reported || snapshot.ownerSession === undefined) return
-    const agent = ctx.get('agents')?.list().find(a => a.session.header.id === snapshot.ownerSession)
-    if (!agent) return
+    if (snapshot.reported || owner === undefined) return
     try {
-      agent.inject(
+      owner.inject(
         [{ type: 'text', text: `background task ${snapshot.id} (${snapshot.kind}: ${snapshot.label}) finished ${statusLine(snapshot)}. Read its output with task_output.` }],
         { source: { kind: 'plugin', plugin: 'tool-tasks' } },
       )
diff --git a/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
index 2cdce74ab6..d78bd1668a 100644
--- a/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
+++ b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
@@ -10,6 +10,8 @@ import type { TaskHooks, TaskOutcome, TaskSnapshot, TaskStart } from '@deepseek-
 import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import { statusLine } from '@deepseek-ai/dsh-tool-tasks'
 
+const agentRegistryDisposers = new WeakMap<Agent, () => void>()
+
 async function setup(config: ToolTasks.Config = {}) {
   const ctx = new Context()
   await ctx.plugin(SystemPrompt)
@@ -21,10 +23,9 @@ async function setup(config: ToolTasks.Config = {}) {
 }
 
 /**
- * A fake agent whose session token is `sessionId`, registered in `ctx.agents`
- * (the notice path finds the owner by scanning the registry for a matching
- * `session.header.id` — the agent id is deliberately DIFFERENT so a
- * wrong-field match fails the test).
+ * A fake agent whose session token is `sessionId`, registered in `ctx.agents`.
+ * The agent id is deliberately different so session authorization and exact
+ * lifecycle ownership cannot be confused in tests.
  */
 function fakeAgent(ctx: Context, sessionId: string, inject: (...args: unknown[]) => void = () => {}): Agent {
   const scopeFiber = ctx.plugin(() => {})
@@ -34,10 +35,16 @@ function fakeAgent(ctx: Context, sessionId: string, inject: (...args: unknown[])
     inject,
     session: { header: { version: 0, id: sessionId, createdAt: 0 } },
   } as unknown as Agent
-  ctx.agents.register(agent)
+  agentRegistryDisposers.set(agent, ctx.agents.register(agent))
   return agent
 }
 
+function detachAgent(agent: Agent): void {
+  const dispose = agentRegistryDisposers.get(agent)
+  if (dispose === undefined) throw new Error(`missing registry disposer for agent "${agent.id}"`)
+  dispose()
+}
+
 /** A controllable producer start-spec (settle `done` on demand, record cancels). */
 function producer(overrides: Partial<Omit<TaskStart, 'run'> & TaskHooks> = {}) {
   let settle!: (outcome: TaskOutcome) => void
@@ -278,6 +285,23 @@ describe('completion notices', () => {
     expect(inject).toHaveBeenCalledTimes(1)
   })
 
+  it('does not route an old owner completion notice to a same-session replacement', async () => {
+    const { ctx } = await setup()
+    const oldInject = vi.fn(() => { throw new Error('agent "agent-shared" is disposed') })
+    const oldOwner = fakeAgent(ctx, 'shared', oldInject)
+    const p = producer({ owner: oldOwner })
+    ctx.tasks.start(p.spec)
+
+    detachAgent(oldOwner)
+    const replacementInject = vi.fn()
+    fakeAgent(ctx, 'shared', replacementInject)
+    p.settle({ status: 'completed' })
+    await tick()
+
+    expect(oldInject).toHaveBeenCalledTimes(1)
+    expect(replacementInject).not.toHaveBeenCalled()
+  })
+
   it('propagates a non-disposed inject failure (a real bug must surface)', async () => {
     const { ctx } = await setup()
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
@@ -291,15 +315,15 @@ describe('completion notices', () => {
     expect(warn).toHaveBeenCalledWith(expect.stringContaining('unexpected inject bug'))
   })
 
-  it('drops the notice when no live agent matches and when the agent registry is gone', async () => {
+  it('keeps using the exact owner after the agent registry is gone', async () => {
     const { ctx, agentsFiber } = await setup()
     const inject = vi.fn()
     const owner = fakeAgent(ctx, 'sess-1', inject)
 
-    // Owner known at registration, unregistered before settlement → no match.
+    // Settlement must not depend on a later registry lookup: the exact owner
+    // supplied at start remains the destination while its own scope is live.
     const p1 = producer({ owner })
     ctx.tasks.start(p1.spec)
-    // A second task whose settlement happens after the whole registry is gone.
     const p2 = producer({ owner })
     ctx.tasks.start(p2.spec)
 
@@ -307,6 +331,6 @@ describe('completion notices', () => {
     p1.settle({ status: 'completed' })
     p2.settle({ status: 'failed' })
     await tick()
-    expect(inject).not.toHaveBeenCalled()
+    expect(inject).toHaveBeenCalledTimes(2)
   })
 })

From d462348556edf0c754a81ac5c647366f36a15ece Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 15 Jul 2026 11:40:47 +0800
Subject: [PATCH 21/48] fix(tasks): contain async completion listeners

TaskService contained synchronous listener throws but discarded returned promises. An async TaskDoneListener could therefore reject as an unhandled process rejection even though the API promises per-listener containment.

Allow listeners to return PromiseLike<void> and attach a rejection handler to each result without awaiting it. This logs asynchronous failures independently while preserving the observation-only contract: later listeners, task waiters, and teardown are not delayed. Add a regression test and synchronize the public docs and generated API declaration.
---
 docs/core-data-structures/tasks.md              |  2 +-
 ...6-06-20-generic-long-running-tool-runtime.md |  4 +++-
 packages/cordis/tool-cordis/src/api-catalog.ts  |  2 +-
 packages/tasks/tasks/README.md                  |  2 +-
 packages/tasks/tasks/src/index.ts               | 10 +++++++---
 packages/tasks/tasks/src/types.ts               |  8 ++++++--
 packages/tasks/tasks/tests/tasks.spec.ts        | 17 +++++++++++++++++
 7 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/docs/core-data-structures/tasks.md b/docs/core-data-structures/tasks.md
index 8ee766de78..80dd7fc52e 100644
--- a/docs/core-data-structures/tasks.md
+++ b/docs/core-data-structures/tasks.md
@@ -141,4 +141,4 @@ interface TaskRead {
 
 ## The service
 
-`TaskService` (`ctx.tasks` — [`packages/tasks/tasks/src/index.ts`](../../packages/tasks/tasks/src/index.ts)): `start` (preflight → producer `run()` → atomic commit, fenced by `attachSurface`), non-consuming `get`/`list` (caller-scoped — owned-by-caller plus unowned only), `read` (consuming for stream kinds), `kill` (producer `cancel` first; a throw leaves the task untouched), `wait` (bounded, abort cancels the wait only), and `onTaskDone` (a `TaskDoneListener` per terminal record, given the exact lifecycle owner, effect-scoped, contained). Start retains the exact live Agent instance validated under its id; owner-scope cleanup selects by that identity, so a reused agent/session id cannot make an old scope cancel replacement work. Read/kill/wait/get authorization remains session-based and rejects a foreign session. A teardown cancel that throws force-fails only the registry record and reports that the underlying work may be orphaned, preventing disposal deadlock without claiming quiescence. The model-facing surface over all of this is [dsh-tool-tasks](../../packages/tasks/tool-tasks/README.md).
+`TaskService` (`ctx.tasks` — [`packages/tasks/tasks/src/index.ts`](../../packages/tasks/tasks/src/index.ts)): `start` (preflight → producer `run()` → atomic commit, fenced by `attachSurface`), non-consuming `get`/`list` (caller-scoped — owned-by-caller plus unowned only), `read` (consuming for stream kinds), `kill` (producer `cancel` first; a throw leaves the task untouched), `wait` (bounded, abort cancels the wait only), and `onTaskDone` (a `TaskDoneListener` per terminal record, given the exact lifecycle owner and effect-scoped). Listener calls contain synchronous throws and returned promise rejections independently; returned promises are not awaited and therefore do not delay task settlement. Start retains the exact live Agent instance validated under its id; owner-scope cleanup selects by that identity, so a reused agent/session id cannot make an old scope cancel replacement work. Read/kill/wait/get authorization remains session-based and rejects a foreign session. A teardown cancel that throws force-fails only the registry record and reports that the underlying work may be orphaned, preventing disposal deadlock without claiming quiescence. The model-facing surface over all of this is [dsh-tool-tasks](../../packages/tasks/tool-tasks/README.md).
diff --git a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index b179ceaa49..6242aa97da 100644
--- a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -75,7 +75,7 @@ class TaskService extends Service {           // ctx.tasks
   read(id: TaskId, caller?: Agent): TaskRead               // delta (stream kinds, consuming) or final output (final kinds, idempotent) + snapshot
   kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-terminal'
   wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
-  onTaskDone(listener: (snapshot: TaskSnapshot, owner: Agent | undefined) => void): () => void   // exact lifecycle owner; effect-scoped, contained
+  onTaskDone(listener: (snapshot: TaskSnapshot, owner: Agent | undefined) => void | PromiseLike<void>): () => void   // exact owner; effect-scoped, contained
   attachSurface(name: string): () => void     // the misconfiguration fence, below
 }
 ```
@@ -98,6 +98,8 @@ One system-prompt section (order 106, next to `tool:bash`) teaches the cross-cal
 
 Completion notices stay durable context, not a wake-up (`agent.inject()` appends a logged `context/message` the next model request sees; it does not run the model): on `onTaskDone`, `dsh-tool-tasks` injects `background task <id> (<kind>: <label>) finished [status: …]. Read its output with task_output.` through the exact owner captured at start, never a replacement found through a reused agent/session id, with the disposed-race contained. Notices are deduplicated the way Claude Code and Kimi Code both learned to: a task the model explicitly killed, or whose terminal state a read/wait already returned (including a wait pending at the moment of settlement), is marked `reported` and its notice suppressed — never a redundant "finished" for work the model just collected or ended. The model-visible ⟺ logged invariant holds with no new session event type.
 
+Completion listeners are observation-only: each synchronous throw and returned promise rejection is logged independently, later listeners still run, and listener promises are not awaited before waiters or task teardown continue.
+
 ## Producer opt-in and schema exposure
 
 Whether a producer tool offers `run_in_background` is that producer's own defaulted config: `enableRunInBackground?: boolean` on `dsh-tool-bash` and on each `dsh-tool-subagent` instance (both default `true` — bash keeps its always-exposed behavior, and a deployment disables either per instance from cordis.yml, no code edit). A bundle forwards the configs of the child plugins it owns: `dsh-agent-core` exposes `toolBash` for its built-in producer and `toolTasks` for the generic control surface, while independently composed producers such as subagent instances receive config directly. This forwarding is config reachability, not producer registration: future background-capable tools do not become `agent-core` fields unless that bundle also chooses to own them. A disabled producer omits the parameter from its schema entirely — and, because the arg validator deliberately allows undeclared keys, its `execute` ALSO refuses a forced `run_in_background: true` loud (the omission is advertising; the execution-time check is the enforcement). `ctx.tasks` plays no part in schema shaping — it never rewrites or decorates a producer's tool schema (Kimi Code regex-rewrites its bash description when background is disabled; config-owns-the-schema makes that trick unnecessary) — it only provides runtime registration. The two halves compose fail-loud: the producer's config decides what the model sees, and a background call that still reaches `start()` without a control surface throws the load-this-package error. `start()` preflights every failable check (the fence, validation, exact live owner instance, and owner-cleanup attach) BEFORE invoking the producer's `run()` and commits atomically after — background work started without a collectable id is structurally impossible, not a producer rollback obligation.
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 494c6d4210..290e987737 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -939,7 +939,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'TaskDoneListener',
-    declaration: 'export type TaskDoneListener = (snapshot: TaskSnapshot, owner: Agent | undefined) => void;',
+    declaration: 'export type TaskDoneListener = (snapshot: TaskSnapshot, owner: Agent | undefined) => void | PromiseLike<void>;',
   },
   {
     name: 'TaskHooks',
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index 006482988c..f146910516 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -9,7 +9,7 @@ The background task registry (`ctx.tasks`): a runtime-global, CONCRETE service (
 - `read(id, caller?): TaskRead` — stream kinds consume the per-task cursor (v1's single intended reader is the owning model — a non-consuming multi-reader surface would be a cursor/snapshot API extension, not a `read` change); final kinds read the terminal output idempotently.
 - `kill(id, caller?, reason?)` — `'requested'` (live task: producer `cancel` runs first — a throw fails the kill loud and leaves the task untouched — then `stopping`) or `'already-terminal'`. Every successful kill marks the task `reported` (the killer saw the end → completion notice suppressed).
 - `wait(id, timeoutMs, caller?, signal?)` — resolves with the terminal snapshot (marked `reported`), or the live snapshot at timeout; an aborted signal rejects the WAIT only — unless the task already settled, in which case the wait still resolves and delivers the terminal snapshot (settlement suppressed the completion notice on this waiter's behalf, so rejecting would leave the finish both unreported and un-noticed). Timing is a [`dsh-timeout`](../../util/timeout/README.md) `deadline()` scoped to the `TASK_WAIT_TIMEOUT` code, so a nested foreign deadline never misreads as a wait timeout; timeout and abort detach their settlement resolver immediately, keeping retention bounded while the task remains live.
-- `onTaskDone(listener)` — exactly once per terminal task record, with the snapshot plus its exact lifecycle owner (or `undefined`); effect-scoped, per-listener containment, silent after service disposal.
+- `onTaskDone(listener)` — exactly once per terminal task record, with the snapshot plus its exact lifecycle owner (or `undefined`); effect-scoped, contains synchronous throws and returned promise rejections without awaiting listener work, silent after service disposal.
 - `attachSurface(name)` — declares a control surface exists (the model tools, or a deployment's custom surface); effect-scoped.
 
 Every read/kill/wait/get compares the task's owner session (`owner.session.header.id`) with the caller's and rejects a foreign one — ids are predictable (`bash-1`), so the fence, not id secrecy, is the isolation boundary.
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index c4e515d2e9..68a36d8c0c 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -350,8 +350,9 @@ export class TaskService extends Service {
    * Register a completion listener, called exactly once per terminal task
    * record with its snapshot and exact lifecycle owner (or `undefined` for an
    * unowned task). Effect-scoped (disposed with the calling fiber); per-listener
-   * containment (one throwing listener is logged, never starves the rest);
-   * never fires after this service is disposed.
+   * containment (one throwing or rejecting listener is logged, never starves
+   * the rest); returned promises are observed but not awaited; never fires
+   * after this service is disposed.
    * @param listener - called with each terminal snapshot and its exact owner.
    * @returns the disposer that unregisters the listener.
    */
@@ -440,7 +441,10 @@ export class TaskService extends Service {
       const snapshot = this.snapshot(task)
       for (const listener of this.listeners) {
         try {
-          listener(snapshot, task.owner)
+          const returned = listener(snapshot, task.owner)
+          void Promise.resolve(returned).catch((error: unknown) => {
+            this.selfCtx.logger.warn(`tasks: onTaskDone listener rejected for ${task.id}: ${String(error)}`)
+          })
         } catch (error: unknown) {
           this.selfCtx.logger.warn(`tasks: onTaskDone listener threw for ${task.id}: ${String(error)}`)
         }
diff --git a/packages/tasks/tasks/src/types.ts b/packages/tasks/tasks/src/types.ts
index 159e45e09d..bd3b3b1c24 100644
--- a/packages/tasks/tasks/src/types.ts
+++ b/packages/tasks/tasks/src/types.ts
@@ -181,6 +181,10 @@ export interface TaskRead {
 /**
  * Completion callback registered via {@link TaskService.onTaskDone}.
  * `owner` is the exact lifecycle instance supplied at start, not a registry
- * lookup by reusable agent or session id; it is absent for unowned tasks.
+ * lookup by reusable agent or session id; it is absent for unowned tasks. A
+ * returned promise is observed for rejection but does not delay settlement.
  */
-export type TaskDoneListener = (snapshot: TaskSnapshot, owner: Agent | undefined) => void
+export type TaskDoneListener = (
+  snapshot: TaskSnapshot,
+  owner: Agent | undefined,
+) => void | PromiseLike<void>
diff --git a/packages/tasks/tasks/tests/tasks.spec.ts b/packages/tasks/tasks/tests/tasks.spec.ts
index 8d28f66862..42c2f23860 100644
--- a/packages/tasks/tasks/tests/tasks.spec.ts
+++ b/packages/tasks/tasks/tests/tasks.spec.ts
@@ -155,6 +155,23 @@ describe('TaskService reads and settlement', () => {
     expect(warn).toHaveBeenCalledWith(expect.stringContaining('listener boom'))
   })
 
+  it('contains a rejecting onTaskDone listener without starving later listeners', async () => {
+    const ctx = await harness()
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const seen: TaskId[] = []
+    ctx.tasks.onTaskDone(async () => { throw new Error('async listener boom') })
+    ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot.id))
+
+    const p = producer()
+    const id = ctx.tasks.start(p.spec)
+    p.settle({ status: 'completed' })
+    await tick()
+
+    expect(seen).toEqual([id])
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('onTaskDone listener rejected'))
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('async listener boom'))
+  })
+
   it('contains a rejecting done as a failed outcome (producer contract violation)', async () => {
     const ctx = await harness()
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})

From 80a5dc935e377cdeb0c0dd1dc0900341b148f8f7 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 15 Jul 2026 11:40:57 +0800
Subject: [PATCH 22/48] chore(bash): record background failure-status debt

A background spawn failure currently resembles a signal-less kill, while a sandbox-runner failure resembles a completed wrapper exit. The generic task adapter cannot mark both as failed without a distinct infrastructure-failure fact on BashProcess. Mapping the existing states differently would also risk treating ordinary nonzero command exits as infrastructure failures.

Keep the current truthful model-visible diagnostics and record a scoped TODO at processOutcome. The eventual fix must widen the BashProcess seam first, then map spawn and runner failures to TaskOutcome failed while preserving completed for real command exits.
---
 packages/bash/tool-bash/src/index.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/bash/tool-bash/src/index.ts b/packages/bash/tool-bash/src/index.ts
index 30952074c8..0871413723 100644
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -221,6 +221,11 @@ export function renderProcessRead(
  * @returns the outcome for the `ctx.tasks` registration.
  */
 export function processOutcome(proc: BashProcess): { status: 'completed' | 'killed'; detail: string } {
+  // TODO(background-infrastructure-outcome): widen BashProcess with an explicit
+  // infrastructure-failure outcome, then map spawn failures and
+  // sandbox.runnerFailed to task `failed`. The current seam aliases a spawn
+  // failure with a signal-less kill and a runner failure with an ordinary
+  // wrapper exit; real nonzero command exits must remain `completed`.
   if (proc.status === 'killed') {
     return { status: 'killed', detail: proc.signal !== null ? `signal: ${proc.signal}` : 'killed before exit' }
   }

From 53fadcce8a379897a33b8dc5e4801381825f6833 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 15 Jul 2026 16:56:15 +0800
Subject: [PATCH 23/48] docs(i18n): preserve modal emphasis across pair

---
 docs/i18n/translation-rules.i18n.yaml | 4 ++--
 docs/i18n/translation-rules.md        | 4 ++--
 docs/i18n/translation-rules.zh.md     | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/i18n/translation-rules.i18n.yaml b/docs/i18n/translation-rules.i18n.yaml
index 5ffed9739d..c393280df8 100644
--- a/docs/i18n/translation-rules.i18n.yaml
+++ b/docs/i18n/translation-rules.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
-translation-rules.md: 490f12d7fec929e5d3d5682deb92ed373fffbde5
-translation-rules.zh.md: b013dcb2d8a892606ae5b1c0837152a771a57da5
+translation-rules.md: c55c928efb64608176b6a9abff86fe228d5e71b1
+translation-rules.zh.md: a50d9fb97e5b6cd95dfd3210ccb70921c7169725
diff --git a/docs/i18n/translation-rules.md b/docs/i18n/translation-rules.md
index 490f12d7fe..c55c928efb 100644
--- a/docs/i18n/translation-rules.md
+++ b/docs/i18n/translation-rules.md
@@ -6,8 +6,8 @@ How to translate between the two sides of a documentation pair in this repo. Bot
 
 ## Faithfulness
 
-- The counterpart MUST say what the authored side says — no added behavior, prerequisites, warnings, version claims, or examples, and no dropped ones. If the pair disagrees on substance, neither language wins by default: fix the side that is wrong, then bring the other along in the same change.
-- The counterpart SHOULD read as natural technical writing in its own language, not word-by-word gloss. Translate meaning, restructure sentences where the target grammar wants it, and keep the author's register — terse stays terse.
+- The counterpart *MUST* say what the authored side says — no added behavior, prerequisites, warnings, version claims, or examples, and no dropped ones. If the pair disagrees on substance, neither language wins by default: fix the side that is wrong, then bring the other along in the same change.
+- The counterpart *SHOULD* read as natural technical writing in its own language, not word-by-word gloss. Translate meaning, restructure sentences where the target grammar wants it, and keep the author's register — terse stays terse.
 - Do not translate the untranslatable: if a sentence resists natural rendering because it leans on an idiom of the source language, translate the idea, not the idiom.
 
 ## Voice
diff --git a/docs/i18n/translation-rules.zh.md b/docs/i18n/translation-rules.zh.md
index b013dcb2d8..a50d9fb97e 100644
--- a/docs/i18n/translation-rules.zh.md
+++ b/docs/i18n/translation-rules.zh.md
@@ -6,8 +6,8 @@
 
 ## 忠实性
 
-- 对侧文件必须传达与撰写侧相同的内容：不添加行为、前置条件、警告、版本声明或示例，也不漏掉任何一项。如果两侧在实质内容上不一致，没有哪种语言默认获胜；请修正错误的一侧，并在同一个变更里同步更新另一侧。
-- 对侧文件读起来应当是其语言自然的技术文字，而非逐词对照的译文。请根据语义翻译，在目标语言语法需要时重组句子，并保持原作者的语域（比如：简练的保持简练）。
+- 对侧文件*必须*传达与撰写侧相同的内容：不添加行为、前置条件、警告、版本声明或示例，也不漏掉任何一项。如果两侧在实质内容上不一致，没有哪种语言默认获胜；请修正错误的一侧，并在同一个变更里同步更新另一侧。
+- 对侧文件读起来*应当*是其语言自然的技术文字，而非逐词对照的译文。请根据语义翻译，在目标语言语法需要时重组句子，并保持原作者的语域（比如：简练的保持简练）。
 - 不要翻译不可译的内容：如果一句话依赖源语言的习语、无法自然转换，请翻译它的意思，而非习语本身。
 
 ## 行文

From fd5931752cbae16b2db39ae289dbf6f3d04413e4 Mon Sep 17 00:00:00 2001
From: Huanqi Cao <caohuanqi@deepseek.com>
Date: Mon, 6 Jul 2026 01:28:20 +0800
Subject: [PATCH 24/48] ci: add Windows test job (windows-2025)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a Windows CI job alongside the existing Linux checks.  Runs the full
test suite (without the Linux-only coverage gate) plus typecheck, lint,
doc-sync, build, hygiene, and demo smoke under PowerShell.  Developer
Mode is enabled via registry for symlink support (fs-local tests,
verify-node-next-types).

Per the windows-support RFC transition plan: step (2) — non-required
Windows CI job to observe stability.
---
 .github/workflows/ci.yml | 81 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 74 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 884a0417e3..399d517d29 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -160,10 +160,9 @@ jobs:
       - name: Run complete keyless Python suite
         run: uv run --python 3.10 --group test --project python/sdk pytest
 
-  # Windows build lane: install + `pnpm run build` (tsc -b + tsdown) on native
-  # Windows. Windows path/shell support is still partial, so this lane covers
-  # the build surface only — tests and gates are not run here yet. Wired into
-  # all-checks-passed so a native-Windows build regression cannot land silently.
+  # Blocking Windows build lane: keep the already-green native build protected
+  # while the broader observational gate job below exposes the remaining
+  # portability work without blocking mainline merges.
   windows-build:
     runs-on: windows-2025
     name: windows / build
@@ -183,11 +182,79 @@ jobs:
       - name: Build (tsc -b + tsdown)
         run: pnpm run build
 
+  # Observational Windows mirror of the Linux gates. Snapshot stays Linux-only
+  # while its replay goldens remain platform-specific. This job intentionally
+  # stays out of all-checks-passed.needs.
+  windows-gates:
+    runs-on: windows-2025
+    name: windows node 24
+    env:
+      DSH_GATE_CONCURRENCY: '2'
+      DSH_PUBLINT_CONCURRENCY: '8'
+      DSH_COVERAGE_MAX_WORKERS: '4'
+      DSH_ESLINT_CACHE: '1'
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Enable Developer Mode (symlink support)
+        shell: powershell
+        run: >-
+          reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
+          /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.PRIMARY_NODE_VERSION }}
+
+      - name: Enable corepack (pnpm)
+        shell: powershell
+        run: corepack enable
+
+      - name: Resolve pnpm store path
+        id: pnpm-store
+        shell: powershell
+        run: '"path=$(pnpm store path --silent)" >> $env:GITHUB_OUTPUT'
+
+      - uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
+
+      - name: Install (immutable)
+        shell: powershell
+        run: pnpm install --frozen-lockfile
+
+      - uses: actions/cache@v4
+        with:
+          path: .cache/eslint
+          key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.mjs', 'tsconfig.json', 'packages/*/*/tsconfig.json', 'examples/*/tsconfig.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-
+
+      - name: Run static gates
+        shell: powershell
+        run: pnpm run check:ci:static
+
+      - name: Run lint gates
+        shell: powershell
+        run: pnpm run check:ci:lint
+
+      - name: Run coverage gates
+        shell: powershell
+        run: pnpm run check:ci:coverage
+
+      - name: Run artifact gates
+        shell: powershell
+        run: pnpm run check:ci:artifacts
+
   # Single stable required check for branch protection: require "all checks
   # passed" instead of enumerating matrix legs whose names change as lanes and
-  # node versions evolve. Every other job in THIS workflow must be listed in
-  # `needs` (`needs` cannot reach across workflow files; e2e.yml stays its own
-  # check). `if: always()` is load-bearing: without it a failed dependency
+  # node versions evolve. Every blocking job in THIS workflow must be listed in
+  # `needs`; explicitly observational jobs such as windows-gates stay out
+  # (`needs` cannot reach across workflow files; e2e.yml stays its own check).
+  # `if: always()` is load-bearing: without it a failed dependency
   # would SKIP this job, and GitHub counts a skipped required check as passing
   # — so this job always runs and fails on any non-success result, including
   # 'cancelled' and 'skipped'.

From 007001677d1e0ba817d10d59ee35e85c073757d8 Mon Sep 17 00:00:00 2001
From: Huanqi Cao <caohuanqi@deepseek.com>
Date: Wed, 8 Jul 2026 12:45:45 +0800
Subject: [PATCH 25/48] ci(windows): split the Windows lane to mirror Linux's
 lane structure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Windows CI was a single job running the full ci-windows inventory
(check:ci:windows), while Linux splits into 5 lanes (static/lint/coverage/
snapshot/artifacts) per the parallel-gates RFC. The single-job shape was a
transitional artifact from when Windows CI was added as a non-required
observation lane; its rationale ('keep gate parallelism modest so coverage
is not starved') conflated run-gates intra-job concurrency
(DSH_GATE_CONCURRENCY) with GitHub job fan-out — orthogonal concerns.

Split Windows into 4 lanes mirroring Linux (snapshot absent: its goldens
are Linux-recorded and self-skip on Windows). Each lane is a separate
GitHub job so a Windows regression is attributable to one lane, not
buried in one job's log. Concurrency is NOT throttled versus Linux: the
lane is non-blocking (continue-on-error), and the observational stance
is to actively expose Windows-arm issues rather than hide them behind
reduced parallelism.

- scripts/run-gates.ts: add ci-windows:static/lint/coverage/artifacts
  modes; ci-windows (full inventory) is retained as the local one-process
  entry, symmetric with Linux's ci-primary.
- .github/workflows/ci.yml: windows job becomes a matrix over the 4 lanes.
- package.json: check:ci:windows:{static,lint,coverage,artifacts} scripts.
- AGENTS.md + windows-support RFC: document the per-lane, non-blocking,
  unthrottled stance.

Verified: scripts/caohuanqi-private/run-ci.py --windows (full
check:ci:windows) — all gates green except the known hooks-claude
bridge.spec waitFor timeout (pre-existing Windows subprocess-timing
flake, unrelated).
---
 .github/workflows/ci.yml | 61 +++++++++++++++++++++++++---------------
 1 file changed, 39 insertions(+), 22 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 399d517d29..88abf56a3f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -182,17 +182,45 @@ jobs:
       - name: Build (tsc -b + tsdown)
         run: pnpm run build
 
-  # Observational Windows mirror of the Linux gates. Snapshot stays Linux-only
-  # while its replay goldens remain platform-specific. This job intentionally
-  # stays out of all-checks-passed.needs.
+  # Observational Windows mirror of the Linux gate lanes. Snapshot stays
+  # Linux-only while its replay goldens remain platform-specific. Splitting the
+  # lanes makes failures attributable without changing their non-gating role.
   windows-gates:
     runs-on: windows-2025
-    name: windows node 24
+    name: windows node 24 / ${{ matrix.lane }}
     env:
-      DSH_GATE_CONCURRENCY: '2'
-      DSH_PUBLINT_CONCURRENCY: '8'
-      DSH_COVERAGE_MAX_WORKERS: '4'
-      DSH_ESLINT_CACHE: '1'
+      DSH_GATE_CONCURRENCY: ${{ matrix.gate_concurrency }}
+      DSH_PUBLINT_CONCURRENCY: ${{ matrix.publint_concurrency }}
+      DSH_COVERAGE_MAX_WORKERS: ${{ matrix.coverage_max_workers }}
+      DSH_ESLINT_CACHE: ${{ matrix.eslint_cache }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - lane: static
+            command: pnpm run check:ci:static
+            gate_concurrency: '4'
+            publint_concurrency: '8'
+            coverage_max_workers: ''
+            eslint_cache: ''
+          - lane: lint
+            command: pnpm run check:ci:lint
+            gate_concurrency: '1'
+            publint_concurrency: '8'
+            coverage_max_workers: ''
+            eslint_cache: '1'
+          - lane: coverage
+            command: pnpm run check:ci:coverage
+            gate_concurrency: '1'
+            publint_concurrency: '8'
+            coverage_max_workers: '4'
+            eslint_cache: ''
+          - lane: artifacts
+            command: pnpm run check:ci:artifacts
+            gate_concurrency: '3'
+            publint_concurrency: '8'
+            coverage_max_workers: ''
+            eslint_cache: ''
     steps:
       - uses: actions/checkout@v6
 
@@ -216,6 +244,7 @@ jobs:
         run: '"path=$(pnpm store path --silent)" >> $env:GITHUB_OUTPUT'
 
       - uses: actions/cache@v4
+        if: matrix.lane == 'lint'
         with:
           path: ${{ steps.pnpm-store.outputs.path }}
           key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
@@ -233,21 +262,9 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-
 
-      - name: Run static gates
+      - name: Run gates
         shell: powershell
-        run: pnpm run check:ci:static
-
-      - name: Run lint gates
-        shell: powershell
-        run: pnpm run check:ci:lint
-
-      - name: Run coverage gates
-        shell: powershell
-        run: pnpm run check:ci:coverage
-
-      - name: Run artifact gates
-        shell: powershell
-        run: pnpm run check:ci:artifacts
+        run: ${{ matrix.command }}
 
   # Single stable required check for branch protection: require "all checks
   # passed" instead of enumerating matrix legs whose names change as lanes and

From cb69ca80d68be66ead5e1ea0de44ec6f89a35775 Mon Sep 17 00:00:00 2001
From: Huanqi Cao <caohuanqi@deepseek.com>
Date: Wed, 8 Jul 2026 14:57:20 +0800
Subject: [PATCH 26/48] =?UTF-8?q?ci(windows):=20run=20the=20observational?=
 =?UTF-8?q?=20gate=20wrapper=20in=20pwsh=20=E2=80=94=20an=20MSYS=20parent?=
 =?UTF-8?q?=20leaks=20into=20the=20suite?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The lane-split merge moved the Run gates step to `shell: bash`, which
broke it twice over. First, GHA's bash shell runs with -e, so a failing
gate aborted the step before the ::warning::/exit 0 lines — the lane
went red X instead of the intended yellow warning. Second, and worse,
Git Bash as the PARENT of the gate run leaks MSYS environment into the
suite itself, producing 8 real test failures the pwsh-launched runs
(and the DSec VM runs) never saw:

- bash exports PWD; the MSYS runtime rewrites it to Windows form for
  native children, dsh-bash-local's adaptEnv passes it through, and the
  executor's MSYS bash adopts it — `pwd` prints `D:/a/...` where the
  tests (and the executor's MSYS dialect) expect `/d/a/...` (7 tests).
- cygwin enables SeBackupPrivilege on the runner's admin token; children
  inherit the enabled state, and libuv's FILE_FLAG_BACKUP_SEMANTICS read
  opens then pierce the dwShareMode=0 lock the jsonl EBUSY test holds —
  loadLive resolves instead of rejecting (1 test).

Evidence: run 28918325498 (pwsh step, pre-merge) failed only the two
hooks dispose tests since fixed by f8fd8c00; run 28921741006 (bash
step) fixed those and failed exactly the 8 above, with zero relevant
source diff between them.

Fix: run the wrapper in pwsh — a native command's failure doesn't abort
pwsh, so $LASTEXITCODE capture + ::warning:: + exit 0 works without an
errexit dance, and the gates start from a native Windows shell as they
do everywhere else Windows CI has been validated.

Docs: the windows-support RFC drops the stale continue-on-error wording
(replaced by the warning wrapper) and records the launch-environment
limitation — native shell required today; making an MSYS parent a
supported launch environment (PWD scrub in adaptEnv, privilege-explicit
tests) is a future improvement direction.
---
 .github/workflows/ci.yml | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 88abf56a3f..205252d1fc 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -183,8 +183,8 @@ jobs:
         run: pnpm run build
 
   # Observational Windows mirror of the Linux gate lanes. Snapshot stays
-  # Linux-only while its replay goldens remain platform-specific. Splitting the
-  # lanes makes failures attributable without changing their non-gating role.
+  # Linux-only while its replay goldens remain platform-specific. The wrapper
+  # runs from native PowerShell 7 so an MSYS parent cannot leak into the suite.
   windows-gates:
     runs-on: windows-2025
     name: windows node 24 / ${{ matrix.lane }}
@@ -225,7 +225,7 @@ jobs:
       - uses: actions/checkout@v6
 
       - name: Enable Developer Mode (symlink support)
-        shell: powershell
+        shell: pwsh
         run: >-
           reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
           /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
@@ -235,12 +235,12 @@ jobs:
           node-version: ${{ env.PRIMARY_NODE_VERSION }}
 
       - name: Enable corepack (pnpm)
-        shell: powershell
+        shell: pwsh
         run: corepack enable
 
       - name: Resolve pnpm store path
         id: pnpm-store
-        shell: powershell
+        shell: pwsh
         run: '"path=$(pnpm store path --silent)" >> $env:GITHUB_OUTPUT'
 
       - uses: actions/cache@v4
@@ -252,7 +252,7 @@ jobs:
             ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
 
       - name: Install (immutable)
-        shell: powershell
+        shell: pwsh
         run: pnpm install --frozen-lockfile
 
       - uses: actions/cache@v4
@@ -263,8 +263,13 @@ jobs:
             ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-
 
       - name: Run gates
-        shell: powershell
-        run: ${{ matrix.command }}
+        shell: pwsh
+        run: |
+          ${{ matrix.command }}
+          if ($LASTEXITCODE -ne 0) {
+            Write-Output "::warning::Windows lane '${{ matrix.lane }}' failed (exit $LASTEXITCODE) — observational, does not block merge. See logs above."
+          }
+          exit 0
 
   # Single stable required check for branch protection: require "all checks
   # passed" instead of enumerating matrix legs whose names change as lanes and

From be4a441ecd26ecdcf9658dcded14b1a601e55a4e Mon Sep 17 00:00:00 2001
From: Huanqi Cao <caohuanqi@deepseek.com>
Date: Wed, 8 Jul 2026 15:59:15 +0800
Subject: [PATCH 27/48] ci(windows): non-blocking via continue-on-error; drop
 the warning wrapper and the demo test
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The ::warning:: wrapper kept the lane job green on failure — honest
about not gating merges, but a Windows regression was visible only as
an annotation buried in the run summary. GitHub has no yellow job
state, so the choice is green+annotation (too hidden) or a red X on a
non-required job (visible, still non-blocking). Take the red X:
job-level continue-on-error, plain 'Run gates' step, one less wrapper.
The step stays on the runner's native pwsh — never shell: bash — per
the MSYS-parent leak recorded in the windows-support RFC.

Also remove the temporary Windows-only failing demo test that
exercised the wrapper's annotation path (REVERT ME commit a496b9ae).
---
 .github/workflows/ci.yml | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 205252d1fc..fa1ac40f49 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -161,7 +161,7 @@ jobs:
         run: uv run --python 3.10 --group test --project python/sdk pytest
 
   # Blocking Windows build lane: keep the already-green native build protected
-  # while the broader observational gate job below exposes the remaining
+  # while the broader observational gate matrix below exposes the remaining
   # portability work without blocking mainline merges.
   windows-build:
     runs-on: windows-2025
@@ -182,10 +182,12 @@ jobs:
       - name: Build (tsc -b + tsdown)
         run: pnpm run build
 
-  # Observational Windows mirror of the Linux gate lanes. Snapshot stays
-  # Linux-only while its replay goldens remain platform-specific. The wrapper
-  # runs from native PowerShell 7 so an MSYS parent cannot leak into the suite.
+  # Observational, non-blocking Windows mirror of the Linux gate lanes. Snapshot
+  # stays Linux-only while its replay goldens remain platform-specific. Run the
+  # gates from native PowerShell: an MSYS parent would change the environment
+  # being measured. This job intentionally stays out of all-checks-passed.needs.
   windows-gates:
+    continue-on-error: true
     runs-on: windows-2025
     name: windows node 24 / ${{ matrix.lane }}
     env:
@@ -244,7 +246,6 @@ jobs:
         run: '"path=$(pnpm store path --silent)" >> $env:GITHUB_OUTPUT'
 
       - uses: actions/cache@v4
-        if: matrix.lane == 'lint'
         with:
           path: ${{ steps.pnpm-store.outputs.path }}
           key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
@@ -256,6 +257,7 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - uses: actions/cache@v4
+        if: matrix.lane == 'lint'
         with:
           path: .cache/eslint
           key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-eslint-${{ hashFiles('pnpm-lock.yaml', 'eslint.config.mjs', 'tsconfig.json', 'packages/*/*/tsconfig.json', 'examples/*/tsconfig.json') }}
@@ -264,12 +266,7 @@ jobs:
 
       - name: Run gates
         shell: pwsh
-        run: |
-          ${{ matrix.command }}
-          if ($LASTEXITCODE -ne 0) {
-            Write-Output "::warning::Windows lane '${{ matrix.lane }}' failed (exit $LASTEXITCODE) — observational, does not block merge. See logs above."
-          }
-          exit 0
+        run: ${{ matrix.command }}
 
   # Single stable required check for branch protection: require "all checks
   # passed" instead of enumerating matrix legs whose names change as lanes and

From ae7b132f62402e8bf3a0244de0bd8c9607e7ef29 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 15 Jul 2026 17:47:29 +0800
Subject: [PATCH 28/48] fix: launch pnpm gates without a Windows shell

---
 scripts/run-gates.ts | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 4de4742c9d..da87a84db9 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -96,8 +96,7 @@ function pnpmScript(id: string, script: string, options: Partial<Gate> = {}): Ga
   return {
     id,
     label: options.label ?? script,
-    command: pnpmBin(),
-    args: ['run', script],
+    ...pnpmInvocation(['run', script]),
     ...options,
   }
 }
@@ -106,14 +105,18 @@ function pnpmExec(id: string, args: string[], options: Partial<Gate> = {}): Gate
   return {
     id,
     label: options.label ?? `pnpm exec ${args.join(' ')}`,
-    command: pnpmBin(),
-    args: ['exec', ...args],
+    ...pnpmInvocation(['exec', ...args]),
     ...options,
   }
 }
 
-function pnpmBin(): string {
-  return process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm'
+function pnpmInvocation(args: string[]): Pick<Gate, 'command' | 'args'> {
+  const entrypoint = process.env.npm_execpath
+  if (entrypoint === undefined || entrypoint === '') {
+    throw new Error('run-gates: npm_execpath is unavailable; invoke the runner through a pnpm package script.')
+  }
+  // Windows cannot spawn the pnpm.cmd shim directly; the JavaScript entrypoint keeps every host shell-free.
+  return { command: process.execPath, args: [entrypoint, ...args] }
 }
 
 function nodeOptions(...options: string[]): string {
@@ -297,8 +300,7 @@ function demoSmokeGate(options: { needs?: string[] } = {}): Gate {
   return {
     id: 'demo-smoke',
     label: 'demo smoke',
-    command: pnpmBin(),
-    args: ['run', 'demo:echo'],
+    ...pnpmInvocation(['run', 'demo:echo']),
     input: 'echo ci smoke\n',
     ...dependencyOptions,
     verify: async (result) => {

From ae8aedb2fd4942a346f3347b7140f5ff16769554 Mon Sep 17 00:00:00 2001
From: Huanqi Cao <caohuanqi@deepseek.com>
Date: Mon, 6 Jul 2026 02:28:44 +0800
Subject: [PATCH 29/48] fix: normalize glob paths with split(sep).join('/') on
 Windows

glob/globSync returns host-separator paths on Windows. Nine scripts that consume these paths for split('/'), manifest-key comparison, startsWith/includes exclusion checks, or committed-output rendering now normalize with .map(s => s.split(sep).join('/')) at ingestion. This replaces the previous replaceAll('\\\\', '/') with an explicit, self-documenting OS-separator-to-POSIX conversion.
---
 scripts/gen-config-catalog.ts                     | 4 ++--
 scripts/gen-cordis-catalog.ts                     | 6 +++---
 scripts/gen-persistence-catalog.ts                | 6 +++---
 scripts/package-graph.ts                          | 4 ++--
 scripts/rfc-index.ts                              | 4 ++--
 scripts/verify-package-readme-limitations.ts      | 4 ++--
 scripts/verify-package-readme-model-experience.ts | 4 ++--
 scripts/verify-type-equiv.ts                      | 4 ++--
 8 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/scripts/gen-config-catalog.ts b/scripts/gen-config-catalog.ts
index 650319e358..a0f3909a36 100644
--- a/scripts/gen-config-catalog.ts
+++ b/scripts/gen-config-catalog.ts
@@ -8,7 +8,7 @@
  */
 
 import { globSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, resolve } from 'node:path'
+import { dirname, resolve, sep } from 'node:path'
 import ts from 'typescript'
 import { LINK_MAP } from './gen-cordis-catalog.ts'
 import { parseJsDoc, pointer, rawJsDoc } from './jsdoc.ts'
@@ -581,7 +581,7 @@ export function collectConfigCatalog(scanRoot: string = root): CatalogEntry[] {
   // workspace-package imports while individual packages are still being walked.
   const pkgDirByName = new Map<string, string>()
   const manifests: { dir: string; pkg: string }[] = []
-  for (const manifestRel of globSync('packages/*/*/package.json', { cwd: scanRoot }).sort()) {
+  for (const manifestRel of globSync('packages/*/*/package.json', { cwd: scanRoot }).map(path => path.split(sep).join('/')).sort()) {
     const dir = manifestRel.slice(0, -'/package.json'.length)
     const manifest = JSON.parse(readFileSync(resolve(scanRoot, manifestRel), 'utf8')) as { name?: string; os?: string[]; cpu?: string[] }
     const pkg = manifest.name
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index a32107b53b..05a308f1ac 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -6,7 +6,7 @@
  */
 
 import { globSync, readFileSync, writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { resolve, sep } from 'node:path'
 import ts from 'typescript'
 import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc, reportViolations, type Mode } from './jsdoc.ts'
 
@@ -129,7 +129,7 @@ function memberSignature(member: ts.TypeElement | ts.ClassElement, sf: ts.Source
 export function collectEvents(scanRoot: string = root): EventEntry[] {
   const entries: EventEntry[] = []
   const violations: string[] = []
-  for (const rel of globSync('packages/*/*/src/*.ts', { cwd: scanRoot }).sort()) {
+  for (const rel of globSync('packages/*/*/src/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
     const abs = resolve(scanRoot, rel)
     const text = readFileSync(abs, 'utf8')
     if (!text.includes('interface Events')) continue
@@ -183,7 +183,7 @@ export function collectEvents(scanRoot: string = root): EventEntry[] {
 export function collectServices(scanRoot: string = root): ServiceEntry[] {
   const entries: ServiceEntry[] = []
   const violations: string[] = []
-  for (const rel of globSync('packages/*/*/src/index.ts', { cwd: scanRoot }).sort()) {
+  for (const rel of globSync('packages/*/*/src/index.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
     const abs = resolve(scanRoot, rel)
     const text = readFileSync(abs, 'utf8')
     if (!text.includes('interface Context')) continue
diff --git a/scripts/gen-persistence-catalog.ts b/scripts/gen-persistence-catalog.ts
index 5c93d8875e..9469081607 100644
--- a/scripts/gen-persistence-catalog.ts
+++ b/scripts/gen-persistence-catalog.ts
@@ -7,7 +7,7 @@
  */
 
 import { globSync, readFileSync, writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { resolve, sep } from 'node:path'
 import ts from 'typescript'
 import { parseJsDoc, pointer, rawJsDoc, reportViolations } from './jsdoc.ts'
 
@@ -117,7 +117,7 @@ export function collectLogEvents(scanRoot: string = root): LogEventEntry[] {
   const violations: string[] = []
   const seen = new Map<string, string>()
   let owningDecl: string | null = null
-  for (const rel of globSync('packages/*/*/src/**/*.ts', { cwd: scanRoot }).sort()) {
+  for (const rel of globSync('packages/*/*/src/**/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
     const abs = resolve(scanRoot, rel)
     const text = readFileSync(abs, 'utf8')
     if (!text.includes('SessionEventMap')) continue
@@ -194,7 +194,7 @@ export function collectLogEvents(scanRoot: string = root): LogEventEntry[] {
  */
 export function collectSurfaceEventTypes(scanRoot: string = root): string[] {
   const found: { names: string[]; source: string }[] = []
-  for (const rel of globSync('packages/*/*/src/**/*.ts', { cwd: scanRoot }).sort()) {
+  for (const rel of globSync('packages/*/*/src/**/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
     const abs = resolve(scanRoot, rel)
     const text = readFileSync(abs, 'utf8')
     if (!text.includes('SurfaceEventType')) continue
diff --git a/scripts/package-graph.ts b/scripts/package-graph.ts
index 5e84e52b86..0853b5c1ca 100644
--- a/scripts/package-graph.ts
+++ b/scripts/package-graph.ts
@@ -6,7 +6,7 @@
  */
 
 import { globSync, readFileSync } from 'node:fs'
-import { dirname, resolve } from 'node:path'
+import { dirname, resolve, sep } from 'node:path'
 
 const SCOPE = '@deepseek-ai/dsh-'
 
@@ -33,7 +33,7 @@ export interface PackageGraphNode {
  */
 export function collectPackageGraph(root: string, groupOrder: readonly string[], gate: string): PackageGraphNode[] {
   const packages: PackageGraphNode[] = []
-  for (const rel of globSync('packages/*/*/package.json', { cwd: root }).sort()) {
+  for (const rel of globSync('packages/*/*/package.json', { cwd: root }).map(path => path.split(sep).join('/')).sort()) {
     const json = JSON.parse(readFileSync(resolve(root, rel), 'utf8')) as {
       name: string
       peerDependencies?: Record<string, string>
diff --git a/scripts/rfc-index.ts b/scripts/rfc-index.ts
index 2d2b5ac84c..a8d7868bce 100644
--- a/scripts/rfc-index.ts
+++ b/scripts/rfc-index.ts
@@ -7,7 +7,7 @@
  */
 
 import { readFileSync, readdirSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { resolve, sep } from 'node:path'
 import { globSync } from 'node:fs'
 
 export const rfcRoot = resolve(import.meta.dirname, '../docs/rfc')
@@ -58,7 +58,7 @@ export function walkRfcTree(): { rfcs: Rfc[]; errors: string[] } {
     }
   }
   for (const lifecycle of LIFECYCLES) {
-    for (const match of globSync(`${lifecycle}/**/*.md`, { cwd: rfcRoot }).sort()) {
+    for (const match of globSync(`${lifecycle}/**/*.md`, { cwd: rfcRoot }).map(path => path.split(sep).join('/')).sort()) {
       const segs = match.split('/')
       // Allowlisted file directly at the lifecycle root (e.g. implemented/AGENTS.md).
       if (segs.length === 2 && ROOT_ALLOWLIST.has(segs[1] ?? '')) continue
diff --git a/scripts/verify-package-readme-limitations.ts b/scripts/verify-package-readme-limitations.ts
index 2b995aab6b..042db1787c 100644
--- a/scripts/verify-package-readme-limitations.ts
+++ b/scripts/verify-package-readme-limitations.ts
@@ -6,7 +6,7 @@
  */
 
 import { existsSync, globSync, readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { resolve, sep } from 'node:path'
 import { markdownHeadingLines, markdownProseLines } from './markdown.ts'
 
 const root = resolve(import.meta.dirname, '..')
@@ -30,7 +30,7 @@ function isLimitationsLike(headingText: string): boolean {
   )
 }
 
-const packageJsons = globSync('packages/*/*/package.json', { cwd: root }).sort()
+const packageJsons = globSync('packages/*/*/package.json', { cwd: root }).map(path => path.split(sep).join('/')).sort()
 const scannedPackages = new Set(packageJsons.map(path => path.slice(0, -'/package.json'.length)))
 const failures: string[] = []
 
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index 8bd2d615ed..5c128954f6 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -6,7 +6,7 @@
  */
 
 import { existsSync, globSync, readFileSync } from 'node:fs'
-import { relative, resolve } from 'node:path'
+import { relative, resolve, sep } from 'node:path'
 import { markdownHeadingLines, markdownProseLines, type MarkdownProseLine } from './markdown.ts'
 
 const root = resolve(import.meta.dirname, '..')
@@ -145,7 +145,7 @@ for (const line of readFileSync(resolve(root, 'docs/tool-catalog.md'), 'utf8').s
 }
 
 const failures: Failure[] = []
-const packageJsons = globSync('packages/*/*/package.json', { cwd: root }).sort()
+const packageJsons = globSync('packages/*/*/package.json', { cwd: root }).map(path => path.split(sep).join('/')).sort()
 const scannedPackages = new Set(packageJsons.map(path => path.slice(0, -'/package.json'.length)))
 let structuredCount = 0
 let contextSurfaceCount = 0
diff --git a/scripts/verify-type-equiv.ts b/scripts/verify-type-equiv.ts
index 729fd632cd..3e2b6f568b 100644
--- a/scripts/verify-type-equiv.ts
+++ b/scripts/verify-type-equiv.ts
@@ -5,7 +5,7 @@
  */
 
 import { globSync, readFileSync, existsSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { resolve, sep } from 'node:path'
 import ts from 'typescript'
 
 const root = resolve(import.meta.dirname, '..')
@@ -121,7 +121,7 @@ const keyOf = (x: { doc: string; symbol: string }): string => `${x.doc}::${x.sym
 // as an orphan rather than silently skipped.
 const docSet = new Set<string>()
 for (const pattern of MARKDOWN_GLOBS) {
-  for (const match of globSync(pattern, { cwd: root })) docSet.add(match)
+  for (const match of globSync(pattern, { cwd: root })) docSet.add(match.split(sep).join('/'))
 }
 const blocks: EquivBlock[] = [...docSet].sort().flatMap(extractEquivBlocks)
 

From 30a209aab5bf6be6337a371936fe1118798824e1 Mon Sep 17 00:00:00 2001
From: Huanqi Cao <caohuanqi@deepseek.com>
Date: Tue, 7 Jul 2026 01:22:30 +0800
Subject: [PATCH 30/48] fix(e2e): reach child quiescence before temp-dir
 cleanup in built-bin smokes

The acp built-bin smoke killed its child and immediately rm'd the temp
consumer dir; POSIX tolerates unlinking a live process's cwd, Windows fails
EBUSY while the child still holds its cwd and session-log handles (the CI
windows job's only red step). Await the child's exit after SIGKILL and give
both smokes' rm a brief retry for the OS handle-release lag.
---
 packages/examples/acp-demo/tests/built-bin.e2e.ts | 15 +++++++++++++--
 .../examples/stdio-demo/tests/built-bin.e2e.ts    |  3 ++-
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/packages/examples/acp-demo/tests/built-bin.e2e.ts b/packages/examples/acp-demo/tests/built-bin.e2e.ts
index 7b5749fee5..9e799b29db 100644
--- a/packages/examples/acp-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/acp-demo/tests/built-bin.e2e.ts
@@ -95,8 +95,19 @@ let consumer: string | undefined
 let child: ReturnType<typeof spawn> | undefined
 
 afterEach(async () => {
-  if (child !== undefined) { child.kill('SIGKILL'); child = undefined }
-  if (consumer !== undefined) await rm(consumer, { recursive: true, force: true })
+  if (child !== undefined) {
+    const proc = child
+    child = undefined
+    // Windows retains the child's cwd and session-log handles until process
+    // teardown completes, so await exit before removing the temp directory.
+    if (proc.exitCode === null && proc.signalCode === null) {
+      const exited = new Promise<void>((resolve) => { proc.once('exit', () => { resolve() }) })
+      proc.kill('SIGKILL')
+      await exited
+    }
+  }
+  // Windows can briefly retain released handles after exit; retry removal.
+  if (consumer !== undefined) await rm(consumer, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })
   consumer = undefined
 })
 
diff --git a/packages/examples/stdio-demo/tests/built-bin.e2e.ts b/packages/examples/stdio-demo/tests/built-bin.e2e.ts
index fdbeb2b8e4..ec14440b18 100644
--- a/packages/examples/stdio-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/stdio-demo/tests/built-bin.e2e.ts
@@ -116,7 +116,8 @@ function runBuiltBin(cwd: string, configArg: string, line: string): Promise<{ st
 let consumer: string | undefined
 
 afterEach(async () => {
-  if (consumer !== undefined) await rm(consumer, { recursive: true, force: true })
+  // Windows can briefly retain released handles after exit; retry removal.
+  if (consumer !== undefined) await rm(consumer, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })
   consumer = undefined
 })
 

From 82794c56815729ce43cc35f5697e5b1054bb7e0e Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 15 Jul 2026 19:24:30 +0800
Subject: [PATCH 31/48] ci(windows): exclude runtime smoke from static gates

---
 scripts/run-gates.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index da87a84db9..7278ca51f5 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -197,13 +197,18 @@ function ciStaticGates(): Gate[] {
     pnpmScript('runtime-closure', 'verify-runtime-closure', { label: 'runtime closure' }),
     pnpmScript('constraints', 'constraints'),
     pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }),
-    demoSmokeGate(),
+    ...staticDemoSmokeGates(),
     ...docSyncLeafGates(),
     pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }),
     pnpmScript('knip', 'knip'),
   ]
 }
 
+function staticDemoSmokeGates(): Gate[] {
+  // Native Windows session persistence is outside the gates-only support scope.
+  return process.platform === 'win32' ? [] : [demoSmokeGate()]
+}
+
 function ciArtifactGates(): Gate[] {
   return [
     pnpmScript('build', 'build'),

From 47858df1ef8d88163659df4538f893ce14f05775 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 15 Jul 2026 19:58:34 +0800
Subject: [PATCH 32/48] ci(windows): defer coverage lane

---
 .github/workflows/ci.yml | 19 +++++--------------
 1 file changed, 5 insertions(+), 14 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index fa1ac40f49..bac25b07cb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -182,10 +182,11 @@ jobs:
       - name: Build (tsc -b + tsdown)
         run: pnpm run build
 
-  # Observational, non-blocking Windows mirror of the Linux gate lanes. Snapshot
-  # stays Linux-only while its replay goldens remain platform-specific. Run the
-  # gates from native PowerShell: an MSYS parent would change the environment
-  # being measured. This job intentionally stays out of all-checks-passed.needs.
+  # Observational, non-blocking Windows static, lint, and artifact lanes. Coverage
+  # and snapshot stay Linux-only until their platform-specific runtime failures
+  # have dedicated support. Run the gates from native PowerShell: an MSYS parent
+  # would change the environment being measured. This job intentionally stays
+  # out of all-checks-passed.needs.
   windows-gates:
     continue-on-error: true
     runs-on: windows-2025
@@ -193,7 +194,6 @@ jobs:
     env:
       DSH_GATE_CONCURRENCY: ${{ matrix.gate_concurrency }}
       DSH_PUBLINT_CONCURRENCY: ${{ matrix.publint_concurrency }}
-      DSH_COVERAGE_MAX_WORKERS: ${{ matrix.coverage_max_workers }}
       DSH_ESLINT_CACHE: ${{ matrix.eslint_cache }}
     strategy:
       fail-fast: false
@@ -203,25 +203,16 @@ jobs:
             command: pnpm run check:ci:static
             gate_concurrency: '4'
             publint_concurrency: '8'
-            coverage_max_workers: ''
             eslint_cache: ''
           - lane: lint
             command: pnpm run check:ci:lint
             gate_concurrency: '1'
             publint_concurrency: '8'
-            coverage_max_workers: ''
             eslint_cache: '1'
-          - lane: coverage
-            command: pnpm run check:ci:coverage
-            gate_concurrency: '1'
-            publint_concurrency: '8'
-            coverage_max_workers: '4'
-            eslint_cache: ''
           - lane: artifacts
             command: pnpm run check:ci:artifacts
             gate_concurrency: '3'
             publint_concurrency: '8'
-            coverage_max_workers: ''
             eslint_cache: ''
     steps:
       - uses: actions/checkout@v6

From 32cfd6c51330062a9648d80f4c9172a72ca63237 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 15 Jul 2026 19:59:00 +0800
Subject: [PATCH 33/48] fix: normalize remaining Windows gate paths

---
 scripts/repo-files.ts                 | 9 +++++----
 scripts/verify-translation-pairing.ts | 4 ++--
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/scripts/repo-files.ts b/scripts/repo-files.ts
index e6d50e7627..8642b9963f 100644
--- a/scripts/repo-files.ts
+++ b/scripts/repo-files.ts
@@ -1,7 +1,7 @@
 /** Shared repository file discovery and line-oriented reference scanning. */
 
 import { globSync, readFileSync, realpathSync } from 'node:fs'
-import { relative, resolve } from 'node:path'
+import { relative, resolve, sep } from 'node:path'
 
 /** One authored path plus its canonical target for symlink deduplication. */
 export interface RepoFile {
@@ -37,8 +37,9 @@ export function uniqueRepoFiles(
   const files: RepoFile[] = []
   for (const pattern of patterns) {
     for (const match of globSync(pattern, { cwd: root })) {
-      if (isExcluded(match)) continue
-      const abs = resolve(root, match)
+      const repoPath = match.split(sep).join('/')
+      if (isExcluded(repoPath)) continue
+      const abs = resolve(root, repoPath)
       const real = realpathSync(abs)
       if (seen.has(real)) continue
       seen.add(real)
@@ -65,7 +66,7 @@ export function findReferenceViolations(
   normalize: (raw: string) => string,
   isViolation: (ref: string) => boolean,
 ): ReferenceViolation[] {
-  const file = relative(root, absPath)
+  const file = relative(root, absPath).split(sep).join('/')
   const out: ReferenceViolation[] = []
   const lines = readFileSync(absPath, 'utf8').split('\n')
   for (let i = 0; i < lines.length; i++) {
diff --git a/scripts/verify-translation-pairing.ts b/scripts/verify-translation-pairing.ts
index eaeacb34d2..4aaf7de79b 100644
--- a/scripts/verify-translation-pairing.ts
+++ b/scripts/verify-translation-pairing.ts
@@ -9,7 +9,7 @@
 
 import { createHash } from 'node:crypto'
 import { existsSync, globSync, readFileSync, writeFileSync } from 'node:fs'
-import { basename, join, resolve } from 'node:path'
+import { basename, join, resolve, sep } from 'node:path'
 import { fromMarkdown } from 'mdast-util-from-markdown'
 import { gfmFromMarkdown } from 'mdast-util-gfm'
 import { gfm } from 'micromark-extension-gfm'
@@ -176,7 +176,7 @@ function parse(content: string): Nodes {
 // Enumerate the scope once.
 const files = new Set<string>()
 for (const pattern of SCOPE_PATTERNS) {
-  for (const match of globSync(pattern, { cwd: root })) files.add(match)
+  for (const match of globSync(pattern, { cwd: root })) files.add(match.split(sep).join('/'))
 }
 const translations = [...files].filter(f => f.endsWith('.zh.md')).sort()
 const metas = [...files].filter(f => f.endsWith('.i18n.yaml')).sort()

From 3383c20c638d1a76833dc322df3aec3ce15217a9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 15 Jul 2026 20:39:24 +0800
Subject: [PATCH 34/48] fix(i18n): refine Chinese prose and prompt validation

---
 docs/i18n/README.i18n.yaml                      |  2 +-
 docs/i18n/README.zh.md                          |  4 ++--
 docs/i18n/style-samples.md                      | 10 +++++-----
 docs/i18n/translation-prompt.md                 | 10 ++++++----
 docs/i18n/translation-rules.i18n.yaml           |  4 ++--
 docs/i18n/translation-rules.md                  |  1 +
 docs/i18n/translation-rules.zh.md               | 17 +++++++++--------
 ...02-bilingual-docs-and-pairing-gate.i18n.yaml |  2 +-
 ...-07-02-bilingual-docs-and-pairing-gate.zh.md |  4 ++--
 scripts/translation-prompt.spec.ts              |  9 +++++++++
 scripts/translation-prompt.ts                   |  4 ++++
 scripts/verify-translation-prompt.ts            |  1 -
 12 files changed, 42 insertions(+), 26 deletions(-)

diff --git a/docs/i18n/README.i18n.yaml b/docs/i18n/README.i18n.yaml
index eee78b1168..ab1c9024ad 100644
--- a/docs/i18n/README.i18n.yaml
+++ b/docs/i18n/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
 README.md: 17bb1eeb67b4f5119a698fca23f12490c9378a7f
-README.zh.md: 2b44ad702c68c0bfb748b25a4f62252aa3dbdc98
+README.zh.md: c957a82bf420a942e2249942a2d9afc54ad950cf
diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md
index 2b44ad702c..c957a82bf4 100644
--- a/docs/i18n/README.zh.md
+++ b/docs/i18n/README.zh.md
@@ -26,7 +26,7 @@
 1. [scripts/translation-pairing.manifest.json](../../scripts/translation-pairing.manifest.json) 中 `required` 列出的每个文件都有完整配对。
 2. 任何已存在的配对——无论是否 required——都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）、双方都带语言切换行、结构签名按序一致——标题深度、逐字节一致的代码块（信息字符串与内容）、表格行列数、列表类型、有序列表起始编号、列表项数量，以及除切换行之外的每个链接目标。
 3. 列为 `excluded` 的文件完全没有 `.zh.md`，也没有 `.i18n.yaml`。
-4. 日期等于或晚于 manifest（元数据清单）中 `requiredSince` 分界日期的每篇日期命名文档（`yyyy-mm-dd-*.md`）都有完整配对——新增的日期命名 RFC 从创建起就要求双语齐备。
+4. 凡文件名符合 `yyyy-mm-dd-*.md` 且日期不早于 manifest（元数据清单）中 `requiredSince` 分界日期的文档，都必须有完整配对——新建的日期命名 RFC 从创建起便须配齐中英文。
 
 `pnpm run verify-translation-pairing --list` 打印范围内每篇文档的当前配对状态——missing、out-of-sync 或 ok——是翻译批次的工作清单。它从不失败；它只报告。
 
@@ -49,4 +49,4 @@
 
 ## 分工
 
-这里的对侧译文由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 产出、由人评审——在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁机械检查配对完整性、记录的 hash、切换行与文档所列的结构签名；翻译质量、术语以及签名未编码的结构要求仍由评审把关。prompt 契约可以直接执行：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 将规范真源渲染到两个翻译方向，并严格解析含三个字段的 XML 响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向、仓库内示例与 CDATA 拆分规则。
+对侧译文由运行 [dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 的 agent 生成，再由人评审：在这里推理（inference）很便宜，评审注意力才是稀缺资源。门禁负责检查配对是否完整、记录的 hash、语言切换行以及本文列出的结构签名；翻译质量、术语和签名未涵盖的结构要求仍由评审把关。prompt 契约也有可执行实现：[scripts/translation-prompt.ts](../../scripts/translation-prompt.ts) 会把权威规则渲染到英译中或中译英的 prompt 中，并严格解析包含三个字段的 XML 响应；`doc-sync` 中的 `verify-translation-prompt` 会检查两个渲染方向、仓库内示例与 CDATA 拆分规则。
diff --git a/docs/i18n/style-samples.md b/docs/i18n/style-samples.md
index 412ec37c2e..786ebea0df 100644
--- a/docs/i18n/style-samples.md
+++ b/docs/i18n/style-samples.md
@@ -16,7 +16,7 @@
 
 > This document covers **behavior**; type shapes live in [core-data-structures/](../core-data-structures/core.md), the per-event/service reference in the [generated catalog](../cordis-catalog/events.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).
 
-本文档描述整体行为逻辑；类型定义存放于 [core-data-structures/](../core-data-structures/core.md)；各类事件、服务的详细参考见[生成目录](../cordis-catalog/events.md)；各 package 的对外契约写在对应 package 的 README（[索引](../../packages/README.md)）。
+本文档描述整体行为逻辑；类型定义存放于 [core-data-structures/](../core-data-structures/core.md)；各类事件、服务的详细参考见[生成目录](../cordis-catalog/events.md)；各包（package）的对外契约写在相应的 README 中（[索引](../../packages/README.md)）。
 
 ## ② 防御模式规则
 
@@ -26,11 +26,11 @@
 
 > **Dispose must reach quiescence, not just request it** — A teardown that issues kills/aborts but returns before the work stops leaves orphans. Make cleanup async and await the children's exit (kill → await `done`), and close listener/notification registries BEFORE killing so late completions stay silent. Tests prove disposal waited (pid gone right after `await fiber.dispose()`), not merely that the process eventually dies.
 
-**dispose（资源释放）必须等待所有任务完全停稳，不能仅下发终止指令就返回**——若清理逻辑仅发送终止、中断信号，但不等任务停止就直接退出，会产生孤儿进程。清理逻辑需设为异步，等待所有子任务彻底退出（先下发终止信号，再等待执行完成）；在执行终止操作前先关闭监听器与通知注册表，让延迟到达的完成事件不再触发任何通知。测试要验证 dispose 确实完成等待：执行完 `await fiber.dispose()` 后进程 PID 立即消失，不能仅校验进程最终会自行消亡。
+**dispose（资源释放）必须等待所有任务完全停稳，不能仅下发终止指令就返回**：如果清理过程只发出终止或中断信号，却不等任务停止就返回，就会留下孤儿进程。清理应采用异步方式，等待所有子任务彻底退出（先发出终止信号，再等待退出）；发出信号前应先关闭监听器与通知注册表，使延迟到达的完成事件不再触发通知。测试要证明 dispose 的确等到清理完成：执行完 `await fiber.dispose()` 后进程 PID 立即消失，不能只检查进程最终会自行消亡。
 
 > **Async state is not synchronous state** — `agent.send()` does not flip status before returning; a background task's completion races turn boundaries; `reader.close()` fires for both EOF and disposal. Never gate control flow on a status you only just requested — drive lifecycle off the events/promises that actually fire (`agent/status`, `task.done`), and observe the transition (saw `running` THEN `idle`) rather than counting actions you assume map 1:1 to turns.
 
-**异步状态不等同于同步瞬时状态**——调用 `agent.send()` 不会在返回前同步更新状态；后台任务完成时机与轮次边界存在竞态；调用 `reader.close()` 既可能是读到文件末尾，也可能是资源销毁触发。切勿根据刚刚请求切换的状态来控制流程；生命周期逻辑应基于真实触发的事件与 promise 驱动（`agent/status`、`task.done`），观测完整状态切换（先 `running`、再 `idle`），而非通过操作次数推断轮次是一一对应的。
+**异步状态不等同于同步瞬时状态**：调用 `agent.send()` 不会在返回前同步更新状态；后台任务的完成时间与轮次边界存在竞态；`reader.close()` 既会在读到文件末尾时触发，也会在资源释放时触发。切勿把刚刚发起的状态变更当成已经生效，据此控制流程；生命周期逻辑应以实际触发的事件和已完成的 promise（`agent/status`、`task.done`）为准，并观察完整的状态变化（先 `running`，再 `idle`），不要根据操作次数推断操作与轮次一一对应。
 
 ## ③ 测试政策清单
 
@@ -60,7 +60,7 @@
 
 > The gate's limit, stated plainly: a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound. It checks hashes and shape; it cannot judge whether the two sides actually say the same thing — that is the reviewer's half of the contract. A re-recorded pair with a sloppy counterpart passes the gate; it must not pass review.
 
-明确门禁校验边界：门禁校验通过，仅代表每侧文件的当前 blob hash 与伴随记录中的对应值一致，且两侧结构签名相符，不代表译文内容准确无误。门禁无法判断双语表意是否统一——译文质量把关是评审人的责任。即便译文粗糙、表意偏差，只要两侧当前 blob hash 各自匹配记录值，门禁就会放行，但这类 PR 绝不能通过人工评审。
+门禁的边界很明确：通过门禁只说明两侧文件当前的 blob hash 与伴随记录吻合，并且结构签名一致，也就是说，这组内容曾被确认一致；它不代表这次确认可靠。门禁无法判断两种语言是否真正表达了相同的意思；这部分契约要由评审人把关。即使译文粗糙、表意有误，重新记录配对后仍能通过门禁，但绝不能通过人工评审。
 
 ## ⑥ RFC 论证
 
@@ -72,7 +72,7 @@
 
 > **Rollout**: date-named RFCs don't wait for a batch — one dated on or after the manifest's `requiredSince` cutoff must merge with its pair, so each new date-named RFC is bilingual from birth. For the back-catalog, the `required` list in the manifest is the enforcement frontier, not the goal. […] Pairing a document is a commitment: every later edit to either side must carry the counterpart along, so grow the frontier at the pace translation review is actually resourced, not ahead of it.
 
-**推进**：新增的日期命名 RFC 不再走批量翻译流程。若其标注日期等于或晚于 manifest（元数据清单）里的 `requiredSince` 分界时间，提交合入时必须配套双语文件，因此每篇新的日期命名 RFC 从创建起就要求双语齐备。针对存量旧文档：manifest 内的强制翻译列表只是当下执行红线，并非最终目标。（……）文档完成双语配对等同于一份长期约束承诺：后续只要修改任一版本，就必须同步更新对应另一语种文件。因此强制翻译范围的推进节奏，要匹配翻译评审实际可投入人力，切勿超前铺开。
+**推进**：日期命名的 RFC 无需等待批量翻译。只要文件名中的日期不早于 manifest（元数据清单）的 `requiredSince` 分界日期，合入时就必须配齐中英文，因此此类 RFC 从创建起就要求双语齐备。对于存量文档，manifest 中的 `required` 列表只是当前的执行红线，并非最终目标。（……）一旦文档完成配对，后续修改任一侧都必须同步更新另一侧。因此，应根据实际可投入的翻译评审能力逐步扩展执行红线，不能超前。
 
 ## 从样例提炼的要点
 
diff --git a/docs/i18n/translation-prompt.md b/docs/i18n/translation-prompt.md
index 349b24c9cc..8bc15d6e8e 100644
--- a/docs/i18n/translation-prompt.md
+++ b/docs/i18n/translation-prompt.md
@@ -1,6 +1,6 @@
 # Translation prompt (pipeline asset)
 
-本文件是自动翻译流水线的 prompt 模板；自 `# Translation Prompt` 起的正文逐字进入模型请求，因此不参与双语配对（见 [README.md](README.md) 排除清单）。渲染时，[translation-rules.md](translation-rules.md) 全文填入 `{{translation_rules}}`，[terminology.md](terminology.md) 整表填入 `{{terminology}}`，避免模板另存一份会漂移的规则副本。[style-samples.md](style-samples.md) 定义文体，模板内嵌的 Examples 仅抽样问题类型；术语表、忠实性与结构规则优先于样例，样例在这些硬约束内决定文体。修改本文件即修改翻译行为，需按正常 PR 评审。
+本文件是自动翻译流水线使用的 prompt 模板；从 `# Translation Prompt` 开始的正文会逐字进入模型请求，因此本文件不参与双语配对（见 [README.md](README.md) 排除清单）。渲染时会把 [translation-rules.md](translation-rules.md) 全文填入 `{{translation_rules}}`，把 [terminology.md](terminology.md) 整表填入 `{{terminology}}`，以免模板另存一份规则而日后失去同步。[style-samples.md](style-samples.md) 定义文体，模板中的 Examples 只用于说明典型问题；术语表、忠实性和结构规则优先于样例，样例只在这些硬性约束内决定文体。修改本文件会改变翻译行为，需正常经过 PR 评审。
 
 ## 占位符契约
 
@@ -15,11 +15,13 @@
 | `{{source_filename}}` | 源文档的 basename（如 `foo.md` 或 `foo.zh.md`） | 由流水线从待译文件路径取得 |
 | `{{source_filename_zh}}` | 中文侧 basename（如 `foo.zh.md`） | 英文源追加 `.zh`；中文源使用自身 basename |
 
-流水线仅支持上表占位符，并按整篇文档翻译。它不支持 `{{to}}`、`{{title_prompt}}`、`{{summary_prompt}}`、`{{terms_prompt}}`、`{{imt_style_guide}}` 或 `%%` 分段协议。输出是一个以 `<dsh-translation-response>` 为根元素的 XML 文档，三个子元素的任意 Markdown 内容都放在 CDATA 中；内容出现 `]]>` 时写成 `]]]]><![CDATA[>`，XML 解析后仍得到原文。
+例如，英译中时若源文件是 `foo.md`，`{{source_filename}}` 填 `foo.md`，`{{source_filename_zh}}` 填 `foo.zh.md`；中译英时若源文件是 `foo.zh.md`，两个占位符都填 `foo.zh.md`。
+
+流水线只识别上表中的占位符，并且一次翻译整篇文档。它不支持 `{{to}}`、`{{title_prompt}}`、`{{summary_prompt}}`、`{{terms_prompt}}`、`{{imt_style_guide}}` 或 `%%` 分段协议。输出必须是一个以 `<dsh-translation-response>` 为根元素的 XML 文档；三个子元素中的 Markdown 内容都放在 CDATA 中。内容出现 `]]>` 时写成 `]]]]><![CDATA[>`，XML 解析后仍会还原为原文。
 
 ## Few-shot 金标
 
-流水线的 few-shot 是**整文档级**的中英对照，不是模板内嵌的句子级正误例。few-shot 集取自以下 5 组经人工评审的配对文档，以仓库当前版本为准、随仓库更新：
+流水线使用**整篇文档**的中英对照作为 few-shot，不是模板内嵌的句子级正误例。以下 5 组配对文档均经过人工评审，并以仓库当前版本为准，随仓库一同更新：
 
 - `README.md` ↔ `README.zh.md`
 - `docs/development.md` ↔ `docs/development.zh.md`
@@ -27,7 +29,7 @@
 - `docs/i18n/translation-rules.md` ↔ `docs/i18n/translation-rules.zh.md`
 - `docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md` ↔ 对应 `.zh.md`
 
-注入时按当前翻译方向选择每组的源侧与目标侧：user 消息为源文档全文，assistant 消息使用模板正文规定的同一 XML 协议；`translation` 与 `final` 都放目标文档全文，`review` 为 `- [None] No corrections.`。CDATA 使用上文的 `]]>` 拆分规则。上下文紧张时按上列顺序从后往前裁剪组数。这 5 组也是评审校准锚点；改动任何一组即改变流水线行为。
+注入时按当前翻译方向选择每组的源侧与目标侧：user 消息包含源文档全文，assistant 消息采用模板正文规定的 XML 协议；`translation` 与 `final` 都放入目标文档全文，`review` 填 `- [None] No corrections.`。CDATA 遵循上文的 `]]>` 拆分规则。上下文不足时，按上列顺序从后往前删减示例组数。这 5 组也是评审校准锚点；改动任何一组都会改变流水线行为。
 
 ## 模板正文
 
diff --git a/docs/i18n/translation-rules.i18n.yaml b/docs/i18n/translation-rules.i18n.yaml
index c393280df8..dea0883a4b 100644
--- a/docs/i18n/translation-rules.i18n.yaml
+++ b/docs/i18n/translation-rules.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
-translation-rules.md: c55c928efb64608176b6a9abff86fe228d5e71b1
-translation-rules.zh.md: a50d9fb97e5b6cd95dfd3210ccb70921c7169725
+translation-rules.md: fb6aa9ac05bebe68ff9213af99f64457bdb1ad6f
+translation-rules.zh.md: 04dd0a704e19502c676ea0966437870c5af0624f
diff --git a/docs/i18n/translation-rules.md b/docs/i18n/translation-rules.md
index c55c928efb..fb6aa9ac05 100644
--- a/docs/i18n/translation-rules.md
+++ b/docs/i18n/translation-rules.md
@@ -44,6 +44,7 @@ These rules govern the Chinese side; the English side follows the repo's normal
 
 - MUST put one half-width space between Chinese text and Latin words, and between Chinese text and numerals: `每个 plugin 注册 3 个 tool`。No space between a full-width punctuation mark and anything.
 - MUST use full-width (Chinese) punctuation in Chinese prose: `，。：；？！（）「」`. Half-width punctuation stays inside code spans, inside complete English sentences quoted as-is, and in numbers (`3.5`, `1,024`).
+- Chinese prose *SHOULD* prefer colons, periods, commas, or parentheses over em dashes. Keep an em dash only when no other punctuation preserves the sentence naturally.
 - Enumeration commas: a Chinese list of parallel items uses 顿号（、）, not commas.
 - MUST NOT use full-width digits or full-width Latin letters — `１２３` never, `123` always.
 - Proper nouns keep their canonical casing: GitHub, TypeScript, DeepSeek — never `github`/`Github` unless quoting code.
diff --git a/docs/i18n/translation-rules.zh.md b/docs/i18n/translation-rules.zh.md
index a50d9fb97e..04dd0a704e 100644
--- a/docs/i18n/translation-rules.zh.md
+++ b/docs/i18n/translation-rules.zh.md
@@ -12,16 +12,16 @@
 
 ## 行文
 
-- 语体以 [style-samples.md](style-samples.md) 为校准锚点——人工定稿的金标样例按文体各一组，译文必须对齐最接近样例的目标语言一侧；样例的语体与本文的语体规则冲突时，以样例为准。中文目标使用规范的技术制度文，英文目标使用简洁、专业的开发者文档语体。
+- 语体以 [style-samples.md](style-samples.md) 为校准锚点。人工定稿的金标样例按文体各一组，译文必须参照文体最接近的样例，采用其中目标语言一侧的语体；如果样例与本文的行文规则冲突，以样例为准。译成中文时，采用规范的技术制度文；译成英文时，采用简洁、专业的开发者文档语体。
 - 以母语技术作者的身份重述内容，而不是逐句转写的译者。写完后逐句对照原文核验：不添加、不遗漏——流畅永远不是丢掉语义成分的理由。
-- 目标语言会模糊执行主体时，请补出实际执行者；翻译为中文时，将含糊的被动句或抽象主语改由「系统、门禁、评审人」等实际执行者做主语。
-- 优先使用目标语言的工程惯用语而非直译（false positive/negative→误报／漏检、enforcement frontier→执行红线）；隐喻做本地化替换而不是移植，并按目标语言需要展开名词链。
+- 如果直译会让执行主体含糊，请明确写出实际执行者；译成中文时，应由「系统、门禁、评审人」等实际执行者作主语，避免含糊的被动句或抽象主语。
+- 优先采用目标语言中通行的工程表达，避免生硬直译（false positive/negative→误报／漏检、enforcement frontier→执行红线）；隐喻应自然改写，名词链则按目标语言的习惯拆开。
 - 长段按语义单元拆分，一段一件事。段落边界可以与原文不同；结构签名不比对段落数。
 - 翻译为中文时，类别名词使用中文并在首现括注英文（实操手册（cookbook））；翻译为英文时，使用通行的英文类别名。指目录或文件本身时保留代码体英文。
 
 ## 结构保持
 
-配对门禁检查标题深度、围栏代码块、表格行列数、列表类型、有序列表起始编号、列表项数量与链接目标。其余框架由译者手工保持；配对的两个文件必须在以下方面一一对应：
+配对门禁会检查标题深度、围栏代码块、表格行列数、列表类型、有序列表起始编号、列表项数量与链接目标；门禁未覆盖的结构仍需人工核对。两个配对文件必须在以下方面一一对应：
 
 - 标题层级（相同级别、相同顺序；标题的**文字**要翻译）；
 - 列表形态与编号；
@@ -34,9 +34,9 @@
 
 ## 术语
 
-- [terminology.md](terminology.md) 是双向的术语真源。翻译前请先加载它；表内术语必须遵守对应行与「不要译作」禁项。中文目标使用「中文」列及「首次出现」括注；英文目标使用「English」列，不添加中文括注。
-- 翻译为中文时，表中没有的技术术语只有在主要中文 OSS 或厂商资料已有成型译法时才可以翻译（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档），并在 PR 中注明出处。没有先例时必须保留英文，并在 PR 描述的「待定术语」中列出建议译法。
-- 翻译为英文时，使用已确立的英文技术术语。源术语没有明确的通行对应词时，保留原词并附简短说明，同时列入「待定术语」。两个方向都禁止就地发明译法；确定下来的术语在同一个 PR 或后续 PR 中进入 [terminology.md](terminology.md)。
+- [terminology.md](terminology.md) 是双向的术语真源。翻译前请先加载它；表内术语必须遵守对应行与「不要译作」禁项。译成中文时，采用「中文」列，并按「首次出现」列括注；译成英文时，采用「English」列，不加中文括注。
+- 译成中文时，术语表未收录的技术术语只有在主流中文 OSS 文档或厂商资料中已有通行译法时才可以翻译（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档），并须在 PR 中注明出处；否则必须保留英文，并在 PR 描述的「待定术语」中给出建议译法。
+- 译成英文时，采用通行的英文技术术语。如果源术语没有明确的通行对应词，则保留原词、附上简短说明，并列入「待定术语」。两个方向都不得自行创造译法；确定后的术语须在同一个 PR 或后续 PR 中加入 [terminology.md](terminology.md)。
 
 ## 排版
 
@@ -44,6 +44,7 @@
 
 - 必须在中文与拉丁词之间、中文与数字之间各留一个半角空格：`每个 plugin 注册 3 个 tool`。全角标点与任何字符之间不加空格。
 - 中文行文必须使用全角（中文）标点：`，。：；？！（）「」`。半角标点保留在代码内、按原样引用的完整英文句子内、以及数字内（`3.5`、`1,024`）。
+- 中文行文*应当*优先使用冒号、句号、逗号或括号，尽量不用破折号；只有其他标点都无法自然表达时才保留破折号。
 - 顿号：中文的并列项之间使用顿号（、），而非逗号。
 - 禁止使用全角数字或全角拉丁字母：永远不写 `１２３`，永远写 `123`。
 - 专有名词保持规范大小写：GitHub、TypeScript、DeepSeek。除非引用代码，否则绝不写 `github`／`Github`。
@@ -54,7 +55,7 @@
 
 - 一对文档的完成标准：一位双语工程师只读其中任一文件，能获得与另一文件读者完全相同的信息（相同的事实、相同的告诫、相同的语气），并且没有任何多余的内容。
 - 交付前，请对照本文自查一遍，并**单独通读对侧文件**，不与源侧对照；不对照原文时，更容易察觉别扭的表达。
-- 请运行 `pnpm run verify-translation-pairing` 与 `doc-sync` 的其余门禁，检查一致性记录、切换行、标题深度、代码块、表格行列数、列表类型、有序列表起始编号、列表项数量、链接及仓库 Markdown 规则。列表与表格顺序、非常规列表编号、行内代码、强调标记、语义、术语和语体仍需手工核对。
+- 请运行 `pnpm run verify-translation-pairing` 与 `doc-sync` 的其余门禁。这些门禁会检查一致性记录、切换行、标题深度、代码块、表格行列数、列表类型、有序列表起始编号、列表项数量、链接及仓库 Markdown 规则；列表与表格的顺序、非常规列表编号、行内代码、强调标记、语义、术语和语体仍需人工核对。
 
 ## 参考资料
 
diff --git a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
index 56176b7bec..5f83acc3aa 100644
--- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
+++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
 2026-07-02-bilingual-docs-and-pairing-gate.md: 68c0f3bbc0472b0c96f9d64fc6b1b24ac7008795
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 66a24dbfa9e516bf341d42d10b797fb70dcd715d
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: 2cf8f9b9c17d8a521d8674833e909b34f315cfe0
diff --git a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
index 66a24dbfa9..2cf8f9b9c1 100644
--- a/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
+++ b/docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md
@@ -12,7 +12,7 @@ Status: implemented
 
 - **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../i18n/terminology.md)。
 - **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。
-- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：required 的配对必须存在；任何已存在的配对必须完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）保持不配对；日期等于或晚于 manifest（元数据清单）中 `requiredSince` 分界日期的文档必须具有完整配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单只进不退：每个合并的翻译批次将自己的文件加入其中，覆盖面只增不减。
+- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：required 的配对必须存在；任何已存在的配对必须完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）不得配对；凡文件名以日期开头且日期不早于 manifest（元数据清单）中 `requiredSince` 分界日期的文档，也必须有完整配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单只进不退：每个合并的翻译批次将自己的文件加入其中，覆盖面只增不减。
 - **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../../.agents/skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。
 
 ## 曾考虑的替代方案
@@ -34,5 +34,5 @@ Status: implemented
 - 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。
 - 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。
 - 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让生成器在输出英文的同时输出中文，届时将这些文件移出排除清单。
-- 推进天然是渐进的：`required` 之外的文档是可见的 backlog（待翻清单，`--list`），而非红色的 CI；因此配对按可评审的批次落地，无需一个巨型 PR。日期等于或晚于 manifest 中 `requiredSince` 分界日期的文档必须配齐双语文件，因此新增的日期命名 RFC 不会扩大这份 backlog。
+- 推进天然是渐进的：`required` 之外的文档是可见的 backlog（待翻清单，`--list`），而非红色的 CI；因此配对按可评审的批次落地，无需一个巨型 PR。凡文件名以日期开头且日期不早于 manifest 中 `requiredSince` 分界日期的文档，都必须配齐双语文件，因此新建的日期命名 RFC 不会增加这份 backlog。
 - 记录的 hash 兼作更新工具（`git cat-file -p <hash>` 能还原任一侧上次确认的文本，用于基于 diff 的最小更新），因此这套机制从不强迫整篇重译。
diff --git a/scripts/translation-prompt.spec.ts b/scripts/translation-prompt.spec.ts
index 49d9b82e26..93754a79a1 100644
--- a/scripts/translation-prompt.spec.ts
+++ b/scripts/translation-prompt.spec.ts
@@ -40,6 +40,15 @@ describe('translation prompt rendering', () => {
       terminology: 'terms',
     })).toThrow('does not match source language Chinese')
   })
+
+  it('rejects malformed template placeholders before injecting rule contents', () => {
+    expect(() => renderTranslationPrompt(document.replace('{{source_lang}}', '{{source-lang}}'), {
+      sourceLanguage: 'English',
+      sourceFilename: 'guide.md',
+      translationRules: 'A literal {{source_lang}} in injected rules.',
+      terminology: '| English | 中文 |',
+    })).toThrow('template contains malformed placeholder syntax')
+  })
 })
 
 describe('translation response XML', () => {
diff --git a/scripts/translation-prompt.ts b/scripts/translation-prompt.ts
index 3b5ad793ae..e30c962498 100644
--- a/scripts/translation-prompt.ts
+++ b/scripts/translation-prompt.ts
@@ -82,6 +82,10 @@ export function renderTranslationPrompt(document: string, input: TranslationProm
     source_filename_zh: sourceFilenameZh,
   }
   const template = extractTranslationPrompt(document)
+  const placeholderFreeTemplate = template.replace(PLACEHOLDER, '')
+  if (placeholderFreeTemplate.includes('{{') || placeholderFreeTemplate.includes('}}')) {
+    throw new Error('translation prompt: template contains malformed placeholder syntax')
+  }
   const names = [...template.matchAll(PLACEHOLDER)].map(match => match[1] ?? '')
   const unknown = names.filter(name => !TRANSLATION_PROMPT_PLACEHOLDERS.includes(name as TranslationPromptPlaceholder))
   if (unknown.length > 0) throw new Error(`translation prompt: unsupported placeholder(s): ${[...new Set(unknown)].join(', ')}`)
diff --git a/scripts/verify-translation-prompt.ts b/scripts/verify-translation-prompt.ts
index 2460e82c47..66d83e47ad 100644
--- a/scripts/verify-translation-prompt.ts
+++ b/scripts/verify-translation-prompt.ts
@@ -37,7 +37,6 @@ try {
     translationRules,
     terminology,
   })
-  if (englishSource.includes('{{') || chineseSource.includes('{{')) throw new Error('rendered prompt contains an unresolved placeholder')
   if (!englishSource.includes('[English](example.md) | 中文')) throw new Error('English-source render does not carry the Chinese switcher instruction')
   if (!chineseSource.includes('English | [中文](example.zh.md)')) throw new Error('Chinese-source render does not carry the English switcher instruction')
 

From d0910a2ed7780c5110aef8f6b9b1b4b66e4a7e75 Mon Sep 17 00:00:00 2001
From: NI0317 <stniii317@gmail.com>
Date: Wed, 15 Jul 2026 21:05:18 +0800
Subject: [PATCH 35/48] docs(skill): distill adopted review feedback

---
 .agents/skills/dsh-code-review/SKILL.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/.agents/skills/dsh-code-review/SKILL.md b/.agents/skills/dsh-code-review/SKILL.md
index 3502e4454a..03a0189227 100644
--- a/.agents/skills/dsh-code-review/SKILL.md
+++ b/.agents/skills/dsh-code-review/SKILL.md
@@ -27,11 +27,17 @@ description: Use when reviewing a pull request in the deepseek-harness repo —
 ## Manual checks
 
 - **Intent and seam contracts:** trace both sides of every changed interface. Confirm the implementation matches the PR and any RFC, including errors, cancellation, ownership, and disposal.
-- **Lifecycle and concurrency:** for async setup, callbacks, processes, or teardown, apply [defensive-patterns.md](../../../docs/defensive-patterns.md). Check races before publication, cancellation during awaits, independent error reporting, callback containment, and quiescent disposal.
+- **Lifecycle and concurrency:** for async setup, callbacks, processes, or teardown, apply [defensive-patterns.md](../../../docs/defensive-patterns.md). Check races before publication, cancellation during awaits, independent error reporting, callback containment, ownership before reentry, complete detach cleanup, and quiescent disposal.
 - **Capability shape:** a swappable capability follows the interface / implementation / consumer split. Consumers depend on the interface, not a backend.
+- **Scope, ownership, and necessity:** tie each abstraction, state machine, option, defensive copy, and compatibility path to a current contract or production consumer. Challenge unrelated features, speculative generality, and behavior placed outside its owning plugin or service.
 - **Configuration:** deployment-varying timeouts, caps, models, URLs, paths, and retry counts are validated `Config` fields, not literals or `DEFAULT_*` constants.
+- **Enforcement boundaries:** hidden schema fields, filtered prompts, facades, wrappers, and listener ordering are not authoritative enforcement when direct or alternate callers can bypass them. Exercise denial paths at the boundary that actually executes the operation.
+- **Borrowed and derived state:** snapshot caller-owned values retained after return or crossing queues, logs, processes, workers, and wire boundaries. Commit notifications and derived state only at the documented success boundary, and trace caches, prompts, UI echoes, replay, and query views to one authoritative source.
+- **Final artifact bounds:** verify byte, token, item, and time limits against the complete emitted or retained artifact, including wrappers and metadata. Probe tiny limits, threshold edges, oversized single chunks, and multibyte text.
 - **Real entry path:** tests exercise the shipped Loader, bin, worker, ACP bridge, or subprocess where relevant. A hand-mounted plugin does not catch Loader export-shape failures; a function plugin must named-export its namespace and have no default export.
 - **Test strength:** assertions fail on the intended regression and verify external state, logs, events, or disposal rather than restating the implementation or trusting an agent's report. Coverage is necessary but not evidence that the scenario is correct.
+- **Changed checks have a negative control:** a new or changed automated check includes a deliberately invalid fixture that fails through the real top-level runner; a green happy path does not prove the check is wired.
+- **Implemented RFCs match shipped reality:** when a PR implements a proposed RFC, move and rewrite it as present-tense shipped state in the same diff, then verify paths, names, and mechanisms against the implementation.
 - **Transcript changes:** editor-visible or model-visible changes update snapshots or explain why no snapshot applies. Review golden diffs as behavior changes, not formatting noise.
 - **Bilingual changes:** compare meaning and terminology on both sides; a green pairing hash does not prove translation quality.
 

From 9a4efada5d53928c6b5d8c7fbf482d58c8cac229 Mon Sep 17 00:00:00 2001
From: NI0317 <stniii317@gmail.com>
Date: Wed, 15 Jul 2026 21:05:43 +0800
Subject: [PATCH 36/48] docs(rfc): propose periodic human-review maintenance
 for dsh-code-review

A private out-of-repo maintainer tool turns adopted human review feedback
into candidate skill updates. Only the resulting SKILL.md diff enters this
repository through normal PR review; the tool source, adapter binaries,
provider credentials, and scheduler stay on the maintainer's machine to
keep this repository focused on shipped product code. Kept in proposed/
until end-to-end verification against master lands a candidate PR; the
acceptance criteria list the exact observations that unlock promotion.
---
 docs/rfc/INDEX.md                             |  1 +
 ...26-07-13-human-review-skill-maintenance.md | 77 +++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md

diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md
index a374e795bc..c53f0e5bd5 100644
--- a/docs/rfc/INDEX.md
+++ b/docs/rfc/INDEX.md
@@ -37,6 +37,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Architectural conformance — dependency rules and the adapter kit](proposed/process/2026-06-11-architectural-conformance.md) | 2026-06-11 |
 | [Supply chain checks and vendor drift verification](proposed/process/2026-06-11-supply-chain-and-vendor-drift.md) | 2026-06-11 |
 | [Discover package inventories instead of maintaining static lists](proposed/process/2026-06-20-discover-package-inventory.md) | 2026-06-20 |
+| [Periodic human-review maintenance for dsh-code-review](proposed/process/2026-07-13-human-review-skill-maintenance.md) | 2026-07-13 |
 
 ### Testing
 
diff --git a/docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md b/docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md
new file mode 100644
index 0000000000..6a760286ff
--- /dev/null
+++ b/docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md
@@ -0,0 +1,77 @@
+# RFC: Periodic human-review maintenance for dsh-code-review
+
+Status: proposed
+
+## Problem
+
+The `dsh-code-review` skill records failure modes that require reviewer judgment, but one-off audits are expensive to repeat and easy to scope inconsistently. Treating every comment as a lesson produces checklist bloat; treating merge, thread resolution, or an author's “fixed” reply as proof of adoption promotes feedback that the final code may not implement. The maintenance process needs enough evidence and independent review to fail closed without requiring a webhook service, durable event state, or automatic repository promotion before the workflow has proven useful.
+
+## Proposal
+
+Periodic out-of-repo maintenance. A private tool, kept on the skill maintainer's machine rather than committed to this repository, runs against a clean full-history checkout at refreshed `origin/master` on an operator-chosen cadence — daily and weekly are both safe because the scan is idempotent against the current skill, and the `--since` window is a `--since 2d` overlap for daily or `--since 7d` for weekly. Repeated `--pr` arguments inspect an explicit set. The tool stores no repository cursor. The only artifact that reaches this repository is a working-tree diff to [.agents/skills/dsh-code-review/SKILL.md](../../../../.agents/skills/dsh-code-review/SKILL.md) that the maintainer inspects and, if useful, promotes through the repository's normal PR review.
+
+```mermaid
+flowchart TD
+  A["Maintainer runs the weekly tool on origin/master"] --> B["List PRs merged in the seven-day window"]
+  B --> C["Collect pre-merge User feedback and final PR evidence"]
+  C --> D["Two reviewers verify provenance and adoption"]
+  D --> E{"Both confirm human-authored and adopted?"}
+  E -- "No" --> F["Exclude or retain as unresolved"]
+  E -- "Yes" --> G["Two reviewers classify against the current skill"]
+  G --> H["Draft a complete candidate from agreed guidance"]
+  H --> I["Two reviewers inspect the same skill diff"]
+  I -- "Blocking finding" --> J["Bounded revision loop"]
+  J --> I
+  I -- "Both approve" --> K["Run documentation and lint checks"]
+  K --> L["Leave a reviewed local working-tree diff"]
+```
+
+### Acquisition contract
+
+Each selected PR is filtered before any feedback is retrieved: its merge commit must be an ancestor of `origin/master`. Merge-commit reachability is the sole eligibility check — a stacked PR whose direct base is a feature branch is admitted whenever the base has since reached master, because the code the reviewer commented on is now on master regardless of the intermediate stack. A single PR that fails preflight, acquisition, or evidence collection is logged to `skipped-pulls.json` and skipped rather than aborting the whole weekly run. The search stage also fails loud when the window would exceed GitHub's 1,000-result search cap so no merged PR is silently omitted. The acquisition stage then reads complete paginated connections for inline review comments, review submissions, PR conversation comments, and PR commits. It admits feedback only when GitHub reports the actor `type` as `User`, and only when both creation and last-edit timestamps strictly predate the PR merge (an equal-timestamp edit is treated as post-merge); review submissions use GraphQL `lastEditedAt` because the REST representation omits edit time.
+
+### Adoption evidence
+
+Each feedback item carries a stable source ID and bounded change evidence. When the reviewer's `commit_id` still belongs to the PR (force-push fail-closed), the tool selects the latest PR commit whose committer timestamp strictly predates the feedback as the baseline — not the reviewer's clicked commit, which may be an older commit — and compares that baseline with the merge commit that actually landed on master. Conversation feedback, force-pushed reviews, and any feedback that predates every PR commit fall to the whole-PR baseline and are deterministically classified `unclear` before any reviewer sees them, because the base-to-head diff cannot prove that a change is causally after the feedback; only feedback-commit baselines reach the adapter for adoption. Merge status, a resolved thread, an author's “fixed” reply, or a same-file edit is context rather than adoption proof; the PR author's own comments never reach the adapter as they cannot be adoption of themselves.
+
+### Dual-reviewer classification and drafting
+
+Two independently configured reviewer adapters classify every item by provenance (`human-authored`, `forwarded-automation`, or `unclear`) and adoption (`adopted`, `rejected`, or `unclear`). Only matching `human-authored` plus `adopted` verdicts proceed. The adopted set then receives a second independent classification against the current skill: candidate, already covered, implementation-specific, or not feedback. A singleton may qualify; recurrence is not required. Disagreement receives one bounded re-evaluation and remains visible in run artifacts if unresolved. A single batch whose adapter output fails schema or id validation is failed closed at the batch level — every feedback item in it is marked unclear and routed to `excluded` — rather than aborting the whole run; the offending raw output is preserved under the run's private artifacts for debugging.
+
+The primary adapter drafts from structured agreed guidance, never raw review text. It remains tool-free and read-only by adapter-author contract: it returns complete candidate file content, which the tool validates before writing the sole target. Both adapters then review the same complete skill diff; blocking findings return to a bounded revision loop, and both must approve the same revision. The tool rejects staged changes and edits outside the target skill both before running the documentation and lint gates and again before reporting success, so a gate or concurrent process that adds another path cannot slip through. It restores its own write on failure using best-effort compare-and-swap so a concurrent maintainer edit is not overwritten, produces a reviewed local diff and private run artifacts on success, and never commits, pushes, opens, or merges a PR.
+
+### Reviewer adapter protocol
+
+Each private executable receives a byte-bounded, versioned JSON request on stdin and returns byte-bounded, schema-conforming JSON on stdout. The tool refuses to run when the two reviewer commands resolve to byte-identical executables — a minimum-bar mechanical check; guaranteeing that primary and secondary are backed by independent providers or models is the deployment operator's responsibility. The `access` and `tools` fields are contract markers on the adapter author, not an OS sandbox: reviewer subprocesses spawn with a scrubbed environment, `cwd` set to a private run directory rather than the repository root, and feedback wrapped in a nonce-tagged `<untrusted-feedback nonce="…">` block that every prompt instructs the model to treat as data; the 128-bit nonce prevents an untrusted body from forging the closing tag. Every subprocess uses bounded, abort-aware process-tree cleanup. Adapter authors implement each operation as pure read-only inference — even the `edit` operation returns complete candidate content in JSON, which the tool validates and writes to the sole target. Every production `git`/`gh`/gate spawn also uses the scrubbed environment so a pre-push hook's routing variables cannot silently redirect the maintainer. Candidate writes and the failure rollback use best-effort compare-and-swap against the last written content; the rollback also unstages the target so an adapter- or gate-staged candidate cannot survive a failed run into a later commit.
+
+### Where the mechanism lives
+
+The tool source, adapter binaries, provider credentials, and the seven-day scheduler are kept private to the maintainer's machine rather than committed to this repository. This document specifies the protocol; the reference implementation is private infrastructure. The mechanism serves a single skill maintained by a single operator, so the ongoing cost of vetting mechanism edits through repository review outweighs any provenance benefit. If the mechanism is ever handed off to a second maintainer, that handoff is a follow-up RFC that revises this decision — the operator doc at [docs/cookbook/maintaining-dsh-code-review.md](../../../cookbook/maintaining-dsh-code-review.md) is the entry point for anyone taking over.
+
+## Alternatives considered
+
+- **Ship the tool inside this repository.** Rejected for a single-maintainer scope: repository maintenance overhead (typecheck, lint, coverage, cross-cutting refactors) would exceed the value of committed provenance. Retained option for a later handoff.
+- **Record every feedback-time PR head** — rejected: it improves causal isolation but requires a continuously running observer, durable event state, retries, and force-push reconciliation. Periodic maintenance uses reviewed-commit evidence where available and fails closed on broader whole-PR evidence.
+- **Persist a processed-PR cursor** — rejected: an overlapping seven-day scan is cheap and naturally idempotent against the current skill, while cursor state creates recovery and missed-event problems.
+- **Run on every new comment** — rejected: review waves produce many related comments and lack the final artifact needed to judge adoption.
+- **Treat merge or thread resolution as adoption** — rejected: a PR can merge with rejected, superseded, or intentionally unresolved feedback.
+- **Create or merge repository changes automatically** — rejected: the tool first needs a track record of useful periodic output. The maintainer inspects and promotes the local diff through normal repository review.
+- **Learn from bot findings that were fixed** — rejected: the source contract is human review feedback. Actor type is filtered before analysis, and human accounts forwarding automated findings are excluded by provenance review.
+- **Use one reviewer as author and final judge** — rejected: independent verdicts expose unsupported generalization before it reaches the skill.
+
+## Acceptance criteria
+
+Promotion from `proposed/` to `implemented/` requires all of the following to be observed in a real end-to-end run against this repository:
+
+- The private tool runs from a clean detached checkout at refreshed `origin/master` and either reports "no candidate" or produces a working-tree diff limited to `.agents/skills/dsh-code-review/SKILL.md`. **Observed on 2026-07-15:** 62 merged PRs scanned, 5 skipped (unreachable merge commit or >250-commit acquisition cap), 426 human feedback items considered, 0 candidates surfaced.
+- Both reviewer adapters are independently configured (distinct providers or models) and complete an analyze / adopt / review pass without user intervention. **Observed on 2026-07-15:** distinct primary/secondary adapters completed adoption + analysis in ~8 minutes; batch fail-closed handled one adapter id-hallucination without aborting the run.
+- A scheduler triggers the tool without an interactive terminal, and a candidate diff (or a "no candidate" record) reaches the operator through a durable notification channel.
+- At least one candidate diff produced by this workflow is inspected by the operator and promoted to `master` through a normal repository PR review. That PR is the evidence that the workflow can turn adopted feedback into shipped skill guidance.
+
+## Risks
+
+- **Causality inferred from committer timestamps.** The feedback-commit baseline is selected by comparing GitHub commit timestamps with feedback creation timestamps; committer clock skew and rewrites still leave a residual false-adoption window. Cross-referencing GitHub's PR event stream would tighten this but requires event acquisition beyond the scope of the periodic tool.
+- **Two-non-candidate classifications routed to `excluded` without a dispute round.** When both classifiers say "not a candidate" but disagree on which non-candidate reason applies (for example `covered` vs `specific`), the item is excluded rather than re-evaluated. Both classifiers agree the item does not become new reviewer behavior, so a dispute round would not change the outcome.
+- **Dual-reviewer independence beyond byte-hash distinctness is a deployment contract.** The tool refuses to run when the two commands resolve to byte-identical executables, but cannot verify that two distinct wrappers back different providers or models. Operators must configure independent primary and secondary adapters.
+- **Best-effort compare-and-swap for candidate writes and rollback.** File-based CAS on POSIX is not truly atomic; the window is one event-loop tick. The tool targets single-user weekly maintenance and a truly concurrent editor is out of scope.
+- **Single-maintainer bus factor.** Because the mechanism lives on one machine, its interruption stops skill maintenance entirely until the operator restores service or hands off to a new maintainer through a follow-up RFC.

From 3735f8c955c4804828a81ccfd33fef9ce9a35e66 Mon Sep 17 00:00:00 2001
From: NI0317 <stniii317@gmail.com>
Date: Wed, 15 Jul 2026 21:05:52 +0800
Subject: [PATCH 37/48] docs(cookbook): add operator guide for dsh-code-review
 maintenance

Entry point for the skill's operator and for any future handoff: what the
private periodic tool produces, where the saved candidate diff and SKILL.md
land on the operator's machine, and how the promote helper turns the
operator's decision into a draft PR from a clean master checkout. Companion
to the maintenance RFC.
---
 docs/cookbook/maintaining-dsh-code-review.md | 61 ++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 docs/cookbook/maintaining-dsh-code-review.md

diff --git a/docs/cookbook/maintaining-dsh-code-review.md b/docs/cookbook/maintaining-dsh-code-review.md
new file mode 100644
index 0000000000..6158af5850
--- /dev/null
+++ b/docs/cookbook/maintaining-dsh-code-review.md
@@ -0,0 +1,61 @@
+# Maintaining the dsh-code-review skill
+
+The [`dsh-code-review`](../../.agents/skills/dsh-code-review/SKILL.md) skill is kept current by a single designated operator running a private weekly maintenance tool. This cookbook is the entry point for that operator — and for anyone taking over the role — and for repo contributors who want to understand why skill updates arrive as small periodic PRs rather than one-off audits. The workflow itself is specified in the [human-review skill-maintenance RFC](../rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md).
+
+## What the maintainer receives
+
+On the operator's chosen cadence (currently daily at 10:00 local time, with a two-day overlap window) a private tool runs the workflow the RFC describes:
+
+1. It selects PRs merged in the chosen window (default two UTC days for the daily cadence, seven for weekly) whose merge commit is reachable from `origin/master`. PRs whose merge commit is not reachable (stacked branches whose parent was squashed) or that exceed a 250-commit acquisition cap are logged to `skipped-pulls.json` and skipped rather than aborting the run.
+2. It collects pre-merge human review feedback (inline comments, review submissions, PR conversation comments) and post-feedback diff evidence.
+3. Two independently configured reviewer adapters classify provenance and adoption, then classify agreed-adopted items against the current skill.
+4. The primary adapter drafts a complete revised `SKILL.md`; both adapters review the same diff; blocking findings loop until both approve.
+5. `pnpm run doc-sync` and `pnpm run lint` run against the candidate before the tool declares success.
+
+Each run stores its artifacts on the operator's machine. The saved diff and candidate `SKILL.md` land under `~/dsh-code-review-outputs/` named by timestamp; the raw per-adapter I/O, adopted evidence, and consensus/dispute JSON stay in a private temp directory whose path is written to the notification and to the daily log under `~/Library/Logs/dsh-code-review-maintainer/`. The maintenance worktree itself is restored clean after every run so the operator is never tempted to edit the maintenance copy in place.
+
+## What the operator does with a candidate diff
+
+When a run produces a candidate, a macOS notification arrives with a `dsh-code-review-promote <timestamp>` hint.
+
+1. **Read the diff on its own merits.** Do not defer to "the reviewers approved" — the maintainer contract is that the operator is the final judgment. Look for checklist bloat, historical prose, unsupported extrapolation from a single incident, and duplicated coverage with existing skill or authoritative-doc content.
+
+   ```sh
+   ls ~/dsh-code-review-outputs/                         # every candidate ever produced
+   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.diff
+   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.SKILL.md
+   ```
+
+2. **Cross-check against the run artifacts.** Each candidate's per-adapter I/O, consensus, and adopted evidence live under the run's private temp directory (path shown in the log). Spot-check at least one candidate: does the linked human comment actually support the added rule? Does the linked PR actually adopt it?
+
+3. **Decide one of three:**
+   - **Discard.** Delete the saved candidate. The tool re-considers the same feedback on the next run under whatever the current skill then says.
+
+     ```sh
+     rm ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.{diff,SKILL.md}
+     ```
+   - **Batch.** Keep the candidate aside if the update is small and could combine with a future one.
+   - **Promote.** From a clean `master` checkout of the repo, run the promote helper. It creates a branch, copies the saved candidate over the current skill, commits, pushes, and opens a draft PR — the operator still reviews the PR on GitHub and either merges it or closes it.
+
+     ```sh
+     cd ~/path/to/deepseek-harness   # clean master
+     dsh-code-review-promote 2026-07-16
+     ```
+
+4. **Do not commit adapter output verbatim.** Small edits during promotion — tightening wording, removing an example that only makes sense with the source PR's context, folding a rule into an existing one — are expected and preserve the "reviewer judgment" the workflow depends on. Amend the branch before merging.
+
+## When a run produces no candidate
+
+That is the common case. The tool records "no candidate" in its daily log, sends no notification (to avoid alert fatigue), and moves on. Days without a skill update are the workflow behaving correctly, not a stall.
+
+## Interruptions and handoff
+
+The mechanism lives on one machine. Interruptions the operator handles as they arise:
+
+- **Daily run missed.** The two-day overlap window catches one skipped day automatically; longer gaps recover by running the wrapper manually with `DSH_CODE_REVIEW_SINCE=<Nd>`. Overlapping windows are idempotent: guidance already in the current skill is classified `covered` and does not re-enter as a candidate.
+- **Adapter provider outage.** The tool refuses to run when the two reviewer commands resolve to byte-identical executables. A single batch whose adapter response fails schema or id validation is failed closed at the batch level (every item in the batch marked unclear) and the run continues; the raw output is preserved for debugging. A total-provider outage that fails every batch produces a "no candidate" result — retry after the provider is restored.
+- **Handoff to another maintainer.** Open a follow-up RFC that supersedes the current one: either move the mechanism into the repository or record the new operator's private setup. Do not silently transfer the tool — the "single-maintainer bus factor" in the RFC's Risks section is the reason the handoff needs a documented decision.
+
+## Where the operator's private setup lives
+
+The tool source, reviewer adapters, provider credentials, and scheduler are the operator's private infrastructure and are outside this repository by design (see the RFC's "Where the mechanism lives" section). This cookbook and the RFC describe **what the workflow guarantees**; **how** those guarantees are implemented is a private-infrastructure concern. If you are the new operator, the RFC's `## Proposal` sections are the specification you build against.

From 8bb8ac8b3c079bfa1555e3e5c120d2d87506bc7c Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 15 Jul 2026 21:08:58 +0800
Subject: [PATCH 38/48] docs(tasks): condense background task prose

The background-task change repeated its lifecycle design across implemented RFCs, package READMEs, JSDoc, test commentary, and model-visible schemas. That repetition obscured the contracts that maintainers must preserve and added avoidable prompt tokens.

Rewrite the implemented RFCs around the current design, keep authorization, exact-owner cleanup, wait/abort ordering, producer quiescence, and teardown-failure guarantees at their owning surfaces, and remove peer surveys, review history, control-flow narration, and emphatic restatement.

Shorten the task and subagent schema wording, synchronize the bilingual tool cookbook, and regenerate the config, service, RFC, tool, and replay snapshot derivatives. Runtime behavior is unchanged; test edits update prose-only assertions and descriptions.
---
 docs/config-catalog.md                        |  64 ++---
 docs/cookbook/adding-a-tool.i18n.yaml         |   4 +-
 docs/cookbook/adding-a-tool.md                |   4 +-
 docs/cookbook/adding-a-tool.zh.md             |   4 +-
 docs/cordis-catalog/services.md               |  14 +-
 docs/core-data-structures/tasks.md            |  88 +++---
 docs/rfc/INDEX.md                             |   2 +-
 ...06-20-generic-long-running-tool-runtime.md | 185 +++++-------
 .../2026-07-08-background-subagent-tasks.md   |  52 ++--
 docs/tool-catalog.md                          |   6 +-
 .../system-prompt.golden.md                   |  10 +-
 .../tool-schemas.golden.json                  |  10 +-
 .../both-mode-turn/system-prompt.golden.md    |  10 +-
 .../both-mode-turn/tool-schemas.golden.json   |  10 +-
 .../code-mode-turn/system-prompt.golden.md    |  10 +-
 .../tool-schemas.golden.json                  |  10 +-
 .../skill-load/tool-schemas.golden.json       |  10 +-
 .../text-turn/tool-schemas.golden.json        |  10 +-
 .../workspace-edit/tool-schemas.golden.json   |  10 +-
 packages/bash/bash-local/src/index.ts         |  64 +----
 packages/bash/bash-sandbox/src/index.ts       |  37 +--
 packages/bash/bash/src/index.ts               |  42 +--
 packages/bash/bash/src/types.ts               |  45 +--
 packages/bash/tool-bash/src/index.ts          | 110 ++-----
 packages/bash/tool-bash/src/render.ts         |  16 +-
 packages/bash/tool-bash/tests/tools.spec.ts   |  11 +-
 packages/subagent/tool-subagent/README.md     |  56 ++--
 packages/subagent/tool-subagent/src/index.ts  | 204 ++++---------
 .../tool-subagent/tests/tool-subagent.spec.ts |  19 +-
 packages/tasks/README.md                      |   4 +-
 packages/tasks/tasks/README.md                |  39 ++-
 packages/tasks/tasks/src/index.ts             | 268 ++++++------------
 packages/tasks/tasks/src/types.ts             | 122 +++-----
 packages/tasks/tasks/tests/tasks.spec.ts      |  34 +--
 packages/tasks/tool-tasks/README.md           |  36 +--
 packages/tasks/tool-tasks/src/index.ts        |  76 ++---
 packages/ui/acp/README.md                     |   2 +-
 packages/util/brand/README.md                 |   6 +-
 38 files changed, 548 insertions(+), 1156 deletions(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 6780e9115e..5eb4b70f40 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -154,7 +154,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/bash/bash-local/src/index.ts:27`](../packages/bash/bash-local/src/index.ts)
+Source: [`packages/bash/bash-local/src/index.ts:17`](../packages/bash/bash-local/src/index.ts)
 
 ## `@deepseek-ai/dsh-bash-sandbox`
 
@@ -165,7 +165,7 @@ Requires: `sandbox`
  * Plugin config: the local executor's knobs plus the sandbox policy. All
  * optional — `static Config` supplies the defaults (`mode: 'read-only'` is the
  * fail-safe default; an example that wants a workspace-writable agent opts in
- * explicitly). The runner choice is NOT configured here: which platform
+ * explicitly). The runner choice is not configured here: which platform
  * backend confines the command is the `ctx.sandbox` provider's config.
  */
 export interface Config extends LocalConfig {
@@ -886,19 +886,14 @@ Source: [`packages/context/time-context/src/index.ts:22`](../packages/context/ti
 Requires: `tools` · `bash` · `systemPrompt`
 
 ```ts config-catalog
-/** Config: whether the model may background commands (the producer-opt-in flag). */
+/** Configures whether the model may background commands. */
 export interface Config {
-  /**
-   * Expose `run_in_background` in the bash schema (default true). Disabled,
-   * the parameter is absent entirely — schema and capability never disagree.
-   * Backgrounding also needs the `ctx.tasks` runtime at call time; a missing
-   * one fails the call loud with the load-these-packages message.
-   */
+  /** Expose `run_in_background` (default true); disabled calls are also rejected. */
   enableRunInBackground?: boolean
 }
 ```
 
-Source: [`packages/bash/tool-bash/src/index.ts:48`](../packages/bash/tool-bash/src/index.ts)
+Source: [`packages/bash/tool-bash/src/index.ts:30`](../packages/bash/tool-bash/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-cordis`
 
@@ -962,42 +957,29 @@ export interface Config {
   /** The `ctx.subagents` provider name to start runs on (e.g. `spawn`, `acp`). */
   provider: string
   /**
-   * The model-facing tool name to register (default `subagent`). To expose more
-   * than one transport, load this plugin once per provider — each load MUST set
-   * a distinct `toolName` (the tool registry rejects a duplicate name), e.g.
-   * `{ provider: 'spawn', toolName: 'subagent' }` and
-   * `{ provider: 'acp', toolName: 'subagent_acp' }`.
+   * Model-facing tool name (default `subagent`). Each loaded instance must use
+   * a distinct name.
    */
   toolName?: string
   /**
-   * Expose `run_in_background` in this instance's schema (default true).
-   * Disabled, the parameter is absent entirely — schema and capability never
-   * disagree; delegation through this instance stays strictly synchronous.
-   * Backgrounding also needs the `ctx.tasks` runtime at call time; a missing
-   * one fails the call loud with the load-these-packages message.
+   * Expose `run_in_background` (default true). Disabled instances omit the
+   * parameter and reject forced background calls.
    */
   enableRunInBackground?: boolean
   /**
-   * Default per-child agent options (model) applied to every spawned child.
-   * Omitted fields fall back to the child loop's own defaults.
+   * Agent options applied to every child; omitted fields use child-loop defaults.
    */
   agentOptions?: AgentOptions
   /**
-   * Per-child persona applied to every child this tool spawns: a scoped
-   * `deployment:persona` section shadowing the deployment's persona for the
-   * child alone. Requires the bound provider's `persona` capability
-   * (in-process backends support it; a request against one that doesn't is
-   * rejected at start). Omitted ⇒ the child renders the deployment persona.
+   * Per-child persona that shadows `deployment:persona`. Requires the
+   * provider's `persona` capability; omission preserves the deployment persona.
    */
   persona?: string
   /**
-   * Tool scoping applied to every child this tool spawns (see
-   * `SubagentStartRequest.toolFilter`): the named global tools vanish from
-   * the child's prompt AND refuse to execute. Requires the provider's
-   * `toolFilter` capability. Unknown names fail the spawn loudly. Note the
-   * child otherwise sees every global tool — including this delegation tool
-   * itself; `deny`-listing it (or setting `maxDepth`) is how a deployment
-   * bounds recursion.
+   * Tool filter applied to every child. Filtered tools disappear from its
+   * prompt and reject execution. Requires the provider's `toolFilter`
+   * capability; unknown names fail startup. Children otherwise see this tool,
+   * so deny it or set `maxDepth` to bound recursion.
    */
   toolFilter?: {
     /** Global tool names the child keeps; everything else is removed. */
@@ -1006,12 +988,8 @@ export interface Config {
     deny?: string[]
   }
   /**
-   * Recursion cap applied to every child this tool spawns (see
-   * `SubagentStartRequest.maxDepth`): a spawn whose child would sit deeper
-   * than this in the delegation tree is rejected. Requires the provider's
-   * `depthLimit` capability. Must be a non-negative safe integer and is
-   * validated when the plugin loads. Omitted ⇒ unbounded (bound it in
-   * deployments that expose this tool to children).
+   * Maximum child depth. Requires the provider's `depthLimit` capability and a
+   * non-negative safe integer. Omission is unbounded.
    */
   maxDepth?: number
 }
@@ -1019,14 +997,14 @@ export interface Config {
 
 Depends on: [`AgentOptions`](../packages/core/agent/src/index.ts)
 
-Source: [`packages/subagent/tool-subagent/src/index.ts:59`](../packages/subagent/tool-subagent/src/index.ts)
+Source: [`packages/subagent/tool-subagent/src/index.ts:23`](../packages/subagent/tool-subagent/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-tasks`
 
 Requires: `tools` · `tasks` · `systemPrompt`
 
 ```ts config-catalog
-/** Config: the `task_output` wait bounds (defaulted, capped — never hardcoded). */
+/** Configures bounded `task_output` waits. */
 export interface Config {
   /** Wait duration applied when `task_output` sets `wait` without `timeout_ms` (default 30s). */
   waitTimeoutMs?: number
@@ -1035,7 +1013,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/tasks/tool-tasks/src/index.ts:34`](../packages/tasks/tool-tasks/src/index.ts)
+Source: [`packages/tasks/tool-tasks/src/index.ts:21`](../packages/tasks/tool-tasks/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-web`
 
diff --git a/docs/cookbook/adding-a-tool.i18n.yaml b/docs/cookbook/adding-a-tool.i18n.yaml
index 33314f7503..6ec964c335 100644
--- a/docs/cookbook/adding-a-tool.i18n.yaml
+++ b/docs/cookbook/adding-a-tool.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
-adding-a-tool.md: c98b6901e1a58db1872a0abf12930a9b4bcce9c1
-adding-a-tool.zh.md: 69cb9fe2b63296e21409d9c4ea375a51c95a2648
+adding-a-tool.md: da214702939e01fedf3d0d69be7560bbafe0696a
+adding-a-tool.zh.md: b216d18b1593cd7e6074685bd39684f1b9694eac
diff --git a/docs/cookbook/adding-a-tool.md b/docs/cookbook/adding-a-tool.md
index c98b6901e1..da21470293 100644
--- a/docs/cookbook/adding-a-tool.md
+++ b/docs/cookbook/adding-a-tool.md
@@ -45,7 +45,9 @@ Registration is effect-based: disposing the plugin fiber unregisters the tool (w
 
 ## Long-running work
 
-Hand long-running work to the shared task runtime instead of inventing a task protocol: gate a `run_in_background` parameter behind your plugin's own defaulted `enableRunInBackground`-style config, then call `ctx.tasks.start({ kind, label, owner: exec.agent, run: () => ({ cancel, done, readOutput? }) })` (`@deepseek-ai/dsh-tasks`) — the runtime preflights everything that can fail (the control-surface fence, validation, owner-cleanup attach) BEFORE invoking your `run()` starter, so work that started without a collectable id is structurally impossible (no try/catch rollback in your tool). The runtime issues the `<kind>-N` id, fences access to the owning session, cancels-and-awaits your task when the owner disposes, and the generic `task_output`/`task_list`/`task_kill` tools plus the completion notice come from `@deepseek-ai/dsh-tool-tasks` — your tool returns `started background task <id>` and is done. Your producer keeps its execution concerns: `done` must settle at quiescence (resources released), and a stream-kind `readOutput` owns its own truncation/spill formatting (bound buffers, spill full output to disk so nothing is silently lost — see tool-bash's `renderProcessRead`). Do NOT wire `exec.signal` to the background work after the id is returned; check `exec.signal?.aborted` once before calling `start`, then leave cancellation to `task_kill` and owner cleanup.
+Gate `run_in_background` with producer config, reject a pre-aborted call, then register through `ctx.tasks.start({ kind, label, owner: exec.agent, run })`. The runtime validates ownership and control-surface availability before `run()` starts work, then supplies the id, session fence, generic control tools, notices, and owner cleanup.
+
+The producer supplies synchronous `cancel`, non-rejecting `done` that settles after resource cleanup, and optional consuming `readOutput` with bounded-output formatting. Once the id is returned, use a task-owned cancellation signal rather than `exec.signal`. See the [background task runtime RFC](../rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and `dsh-tool-bash` for a stream producer.
 
 ## Execution policy and observation
 
diff --git a/docs/cookbook/adding-a-tool.zh.md b/docs/cookbook/adding-a-tool.zh.md
index 69cb9fe2b6..b216d18b15 100644
--- a/docs/cookbook/adding-a-tool.zh.md
+++ b/docs/cookbook/adding-a-tool.zh.md
@@ -45,7 +45,9 @@ export function apply(ctx: Context) {
 
 ## 长时间运行的工作
 
-不要为长时间运行的工作另造任务协议，而应将其交给共享 task 运行时：通过插件自身带默认值的 `enableRunInBackground` 类配置控制是否暴露 `run_in_background` 参数，然后调用 `ctx.tasks.start({ kind, label, owner: exec.agent, run: () => ({ cancel, done, readOutput? }) })`（`@deepseek-ai/dsh-tasks`）。运行时会在调用你的 `run()` 启动器之前，预检所有可能失败的条件（控制面围栏、校验和 owner cleanup 挂接），从结构上杜绝工作已经启动却没有可收集 id 的情况（你的工具无需通过 try/catch 回滚）。运行时签发 `<kind>-N` id，将访问限制在 owner 会话，并在 owner dispose 时取消并等待任务；通用的 `task_output`、`task_list`、`task_kill` 工具和完成通知由 `@deepseek-ai/dsh-tool-tasks` 提供，你的工具返回 `started background task <id>` 后即完成。producer 保留自身的执行职责：`done` 必须在达到静止状态（资源已释放）后 settle；流类型的 `readOutput` 自行负责截断和溢写格式（限定缓冲区大小，将完整输出溢写到磁盘，避免静默丢失——参见 tool-bash 的 `renderProcessRead`）。返回 id 后，不要再把 `exec.signal` 连接到后台工作；调用 `start` 前只检查一次 `exec.signal?.aborted`，此后由 `task_kill` 和 owner cleanup 负责取消。
+通过 producer 配置控制 `run_in_background`，拒绝已预先中止的调用，然后使用 `ctx.tasks.start({ kind, label, owner: exec.agent, run })` 注册任务。运行时会在 `run()` 启动工作前校验 owner 和控制面是否可用，随后提供 id、会话围栏、通用控制工具、通知和 owner cleanup。
+
+producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`，以及可选的消费式 `readOutput`（负责有界输出的格式化）。返回 id 后，应使用 task 自有的取消信号，而不是 `exec.signal`。流式 producer 的示例和完整契约见[后台 task 运行时 RFC](../rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md)与 `dsh-tool-bash`。
 
 ## 执行策略与观测
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 58ecfe9ef1..19c09d944b 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -56,12 +56,12 @@ Source: [`packages/ui/user-approval/src/index.ts:229`](../../packages/ui/user-ap
 
 Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
-Semantics every implementation must honor:
+Implementations must honor these semantics:
 
-- run REJECTS only for infrastructure failures (unusable workdir, missing shell, pre-aborted signal). Nonzero exits, timeout kills, and abort kills RESOLVE with a descriptive BashRunResult — reporting a failed command is the tool layer's job, not an exception.
-- start returns immediately; no timeout applies to background processes (callers stop them via BashProcess.kill or the spec's AbortSignal). The handle's `done` settles at process close and never rejects (a spawn failure settles as `killed` with the error readable on stderr).
-- BashProcess.readOutput is incremental: consecutive reads never re-deliver output. Implementations bound their buffers; reads that lost data flag `lossy` and point at full-stream spill files when available.
-- Disposal kills every running background process and awaits their exit (no orphan processes survive `fiber.dispose()`).
+- run rejects only for infrastructure failures. Nonzero exits, timeout kills, and abort kills resolve with a BashRunResult.
+- start returns immediately; no timeout applies to background processes. `done` settles at process close and never rejects; spawn failures settle as `killed` with the error on stderr.
+- BashProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.
+- Disposal kills all running background processes and awaits their exit.
 
 ```ts cordis-catalog
 abstract resolve(request: BashExecRequest): BashExecSpec
@@ -71,7 +71,7 @@ abstract start(spec: BashExecSpec): BashProcess
 
 Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md)
 
-Source: [`packages/bash/bash/src/index.ts:68`](../../packages/bash/bash/src/index.ts)
+Source: [`packages/bash/bash/src/index.ts:46`](../../packages/bash/bash/src/index.ts)
 
 ## `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
 
@@ -259,7 +259,7 @@ attachSurface(name: string): () => void
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/tasks/tasks/src/index.ts:98`](../../packages/tasks/tasks/src/index.ts)
+Source: [`packages/tasks/tasks/src/index.ts:72`](../../packages/tasks/tasks/src/index.ts)
 
 ## `ctx.tools` — `ToolRegistry`
 
diff --git a/docs/core-data-structures/tasks.md b/docs/core-data-structures/tasks.md
index 80dd7fc52e..0f84ac33b4 100644
--- a/docs/core-data-structures/tasks.md
+++ b/docs/core-data-structures/tasks.md
@@ -1,16 +1,14 @@
 # Background Task Runtime
 
-The shared background-task vocabulary — what a producer (`dsh-tool-bash`, `dsh-tool-subagent`, any future long-running tool) hands to `ctx.tasks.start()` and what consumers (the `task_output`/`task_list`/`task_kill` tools, completion-notice injection) get back. The runtime is ONE concrete service ([dsh-tasks](../../packages/tasks/tasks), `ctx.tasks`), not an interface/implementation seam pair — see [the runtime RFC](../rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) for the decision and [the tasks group README](../../packages/tasks/README.md) for the package split.
-
-Source: [`packages/tasks/tasks/src/types.ts`](../../packages/tasks/tasks/src/types.ts)
+Types shared by long-running producers, `ctx.tasks`, and task control surfaces. The [runtime RFC](../rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) owns the design; this page records the literal shapes from [`packages/tasks/tasks/src/types.ts`](../../packages/tasks/tasks/src/types.ts).
 
 ## Ids and status
 
-`TaskId` is [branded](core.md#branded-ids) (`Branded<'TaskId'>` + a same-named factory), generated by the registry as `<kind>-N` with a per-kind counter (`bash-1`, `subagent-1`) — kind-prefixed so transcripts stay self-describing, sequential because the owner fence (not id secrecy) is the isolation boundary. `TaskStatus` is generic and CLOSED: `'running' | 'stopping' | 'completed' | 'killed' | 'failed'` — kind-specific meaning (exit codes, stop reasons) rides in `TaskSnapshot.detail`, so the registry never learns process or agent semantics.
+`TaskId` is a [branded id](core.md#branded-ids) generated as `<kind>-N`. Access control relies on owner authorization, not id secrecy. `TaskStatus` is `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`; producer-specific facts belong in `TaskSnapshot.detail`.
 
-## The producer contract: `TaskStart` and `TaskHooks`
+## Producer contract
 
-Declare-then-execute: the producer hands its task's identity plus a `run()` starter to `ctx.tasks.start()`, which preflights everything that can fail (the control-surface fence, validation, the owner-cleanup attach) BEFORE invoking `run()`, and commits atomically after — work that started without a collectable id is structurally impossible. The producer stays the owner of its execution concerns (process streams, child agents); the runtime owns ids, isolation, status, and completion fan-out. The optional `readOutput` hook marks a STREAM kind — the method presence is the capability, mirroring `SubagentRun.sendMessage`.
+`TaskStart` declares identity and a starter. The runtime finishes preflight before calling `run()` and commits without a later failable step. Producers own execution resources; the runtime owns identity, access, and lifecycle state.
 
 ```ts type-equiv
 interface TaskStart {
@@ -19,53 +17,41 @@ interface TaskStart {
   /** One-line model-facing label (the command; the delegation description). */
   label: string
   /**
-   * The spawning agent. Its `session.header.id` becomes the task's owner
-   * identity (read/kill/wait/list are fenced to that session), and its `ctx` scope
-   * owns an async cleanup that cancels and awaits the task during disposal. It
-   * must be the exact live instance currently registered under its agent id;
-   * a stale object whose id has been reused is rejected before work starts.
-   * `undefined` starts an UNOWNED task: open to any caller, alive until the
-   * tasks service disposes.
+   * Owning live agent. Access is fenced by its session id, and agent disposal
+   * cancels and awaits the task. The instance must be the one currently
+   * registered under its agent id. `undefined` creates an unowned task, open to
+   * any caller until service disposal.
    */
   owner?: Agent | undefined
   /**
-   * Start the actual work and return its {@link TaskHooks}. Called EXACTLY
-   * once, synchronously, after every preflight check (control-surface fence,
-   * validation, owner-cleanup attach) has passed — nothing in the runtime can
-   * fail after it returns, so the started work is always registered. A throw
-   * here propagates with nothing registered; the producer owns any partial
-   * cleanup of its own failed start.
+   * Start the work after preflight and synchronously return its hooks. Called
+   * once; a throw leaves nothing registered, and the producer must clean up any
+   * partially started resources.
    */
   run(): TaskHooks
 }
 ```
 
+`TaskHooks.done` is the quiescence boundary. Optional `readOutput` distinguishes consuming stream tasks from final-output-only tasks.
+
 ```ts type-equiv
 interface TaskHooks {
   /**
-   * Request termination. Idempotent, synchronous, and must lead to
-   * {@link done} settling; a throw propagates to the killer (fail loud — a
-   * cancel that cannot even be requested is a producer bug). The optional
-   * reason is `task_kill`'s logged reason, forwarded verbatim.
+   * Request termination. Must be synchronous, idempotent, and eventually settle
+   * {@link done}; throws propagate. The optional reason is forwarded verbatim.
    */
   cancel(reason?: string): void
   /**
-   * Settles with the terminal outcome at QUIESCENCE — after the producer has
-   * released the task's resources (process exited, child agent disposed) —
-   * not merely when the work finished. Must never reject; a rejection is
-   * contained as a `failed` outcome and logged as a producer contract
-   * violation. If `cancel` throws during teardown, the runtime may force-fail
-   * only its registry record to avoid deadlock because this promise may never
-   * settle; that fallback explicitly does not claim work quiescence.
+   * Resolves after the producer releases its resources, not merely when work
+   * finishes. Must not reject; the runtime converts a rejection to `failed`.
+   * If teardown cancellation throws, the runtime may force-fail only the
+   * registry record without claiming that the work stopped.
    */
   done: Promise<TaskOutcome>
   /**
-   * OPTIONAL incremental read (stream kinds): everything produced since the
-   * previous call, formatted by the producer (truncation/spill notices
-   * included). Consecutive calls never re-deliver output; the registry keeps
-   * ONE consuming cursor per task, so v1's single intended reader is the
-   * owning model. Absence marks a final-output-only kind (the method presence
-   * IS the capability).
+   * Consume output produced since the previous call. The producer formats
+   * truncation and spill notices. Absence marks a final-output-only task; each
+   * task has one consuming cursor.
    */
   readOutput?(): string
 }
@@ -77,18 +63,14 @@ interface TaskOutcome {
   status: 'completed' | 'killed' | 'failed'
   /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
   detail?: string
-  /**
-   * Final output for FINAL-OUTPUT-ONLY kinds (no {@link TaskHooks.readOutput}),
-   * read idempotently after the task settles. Stream kinds leave it unset —
-   * their output is consumed incrementally through `readOutput`.
-   */
+  /** Final output for tasks without `readOutput`; stream tasks leave it unset. */
   output?: string
 }
 ```
 
-## What consumers see: `TaskSnapshot` and `TaskRead`
+## Consumer views
 
-Snapshots are fresh projections, never live registry state. `ownerSession` retains the shared branded `SessionId` type across the package boundary. `reported` is the notice-suppression flag: the completion-notice injector (`dsh-tool-tasks`) skips a task whose terminal state the model already saw.
+Snapshots are fresh read-only projections. `ownerSession` carries the shared `SessionId` used for authorization; completion listeners separately receive the exact owner object used for lifecycle cleanup. `reported` suppresses a completion notice after another surface has delivered or committed to deliver the terminal state.
 
 ```ts type-equiv
 interface TaskSnapshot {
@@ -99,12 +81,9 @@ interface TaskSnapshot {
   /** The producer-supplied one-line label. */
   label: string
   /**
-   * The owner's session id (`session.header.id`), for authorization and
-   * correlation; absent for unowned tasks. A listener that must reach the
-   * lifecycle owner receives the exact Agent separately through
-   * {@link TaskDoneListener}. Session ids are runtime-shared identifiers, not
-   * secrets — the read/kill/wait/list FENCE is what isolation rests on. The
-   * shared {@link SessionId} brand is preserved across this package boundary.
+   * Owner session id used for authorization and correlation; absent for
+   * unowned tasks. Completion listeners receive the exact {@link Agent}
+   * separately through {@link TaskDoneListener}.
    */
   ownerSession?: SessionId
   /** Current lifecycle state. */
@@ -116,11 +95,8 @@ interface TaskSnapshot {
   /** Epoch ms when the task settled; absent while `running`/`stopping`. */
   finishedAt?: number
   /**
-   * True once the terminal state has been (or is being) reported to the owner
-   * through an explicit surface response — a `kill` call, or a `read`/`wait`
-   * that returned the terminal state (including a wait pending at settlement).
-   * Completion-notice surfaces suppress their notice when set, so the model
-   * never gets a redundant "finished" for a task it just collected or killed.
+   * True when a kill, read, or wait has reported or committed to report the
+   * terminal state. Completion surfaces suppress redundant notices when set.
    */
   reported: boolean
 }
@@ -139,6 +115,6 @@ interface TaskRead {
 }
 ```
 
-## The service
+## Service behavior
 
-`TaskService` (`ctx.tasks` — [`packages/tasks/tasks/src/index.ts`](../../packages/tasks/tasks/src/index.ts)): `start` (preflight → producer `run()` → atomic commit, fenced by `attachSurface`), non-consuming `get`/`list` (caller-scoped — owned-by-caller plus unowned only), `read` (consuming for stream kinds), `kill` (producer `cancel` first; a throw leaves the task untouched), `wait` (bounded, abort cancels the wait only), and `onTaskDone` (a `TaskDoneListener` per terminal record, given the exact lifecycle owner and effect-scoped). Listener calls contain synchronous throws and returned promise rejections independently; returned promises are not awaited and therefore do not delay task settlement. Start retains the exact live Agent instance validated under its id; owner-scope cleanup selects by that identity, so a reused agent/session id cannot make an old scope cancel replacement work. Read/kill/wait/get authorization remains session-based and rejects a foreign session. A teardown cancel that throws force-fails only the registry record and reports that the underlying work may be orphaned, preventing disposal deadlock without claiming quiescence. The model-facing surface over all of this is [dsh-tool-tasks](../../packages/tasks/tool-tasks/README.md).
+[`TaskService`](../../packages/tasks/tasks/src/index.ts) provides atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, contained `onTaskDone` listeners, and the `attachSurface` availability fence. Authorization compares owner sessions; owner cleanup selects the exact registered `Agent` instance. See [`dsh-tasks`](../../packages/tasks/tasks/README.md) for the package contract and [`dsh-tool-tasks`](../../packages/tasks/tool-tasks/README.md) for the model-facing surface.
diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md
index 5761899938..dd26596a32 100644
--- a/docs/rfc/INDEX.md
+++ b/docs/rfc/INDEX.md
@@ -127,7 +127,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Shared persistence write coordinator](implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md) | 2026-06-18 |
 | [Branded IDs everywhere they belong](implemented/architecture/2026-06-20-branded-ids.md) | 2026-06-20 |
 | [Extract example apps into packages](implemented/architecture/2026-06-20-extract-example-app-packages.md) | 2026-06-20 |
-| [The background task runtime (`ctx.tasks`) and the generic task control tools](implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) | 2026-06-20 |
+| [The background task runtime (`ctx.tasks`) and generic task control tools](implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) | 2026-06-20 |
 | [Reorganize packages into a modular hierarchy](implemented/architecture/2026-06-20-package-hierarchy.md) | 2026-06-20 |
 | [Mandatory `User-Agent` attribution for provider requests](implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md) | 2026-06-21 |
 | [Web capability seam - stable tools over multiple providers](implemented/architecture/2026-06-24-web-capability-seam.md) | 2026-06-24 |
diff --git a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index 6242aa97da..64c5dff5a4 100644
--- a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -1,185 +1,128 @@
-# RFC: The background task runtime (`ctx.tasks`) and the generic task control tools
+# RFC: The background task runtime (`ctx.tasks`) and generic task control tools
 
 Status: implemented
 
 ## Problem
 
-The bash capability seam supports both foreground commands and long-running background tasks. Background support was large: the abstract executor exposed `start`, `get`, `ownerOf`, `list`, `readOutput`, `kill`, and `onTaskDone`; the local executor tracked tasks, incremental reads, owner tokens, process cleanup, and completion listeners; the model saw three tools (`bash`, `bash_output`, `bash_kill`); the tool plugin injected completion notices back into the owning agent's session. The local executor fenced task access behind owner tokens because predictable global task ids are a cross-session read/kill hazard.
+Background bash originally combined two responsibilities: the bash executor ran processes and also managed task ids, ownership, incremental reads, cancellation, completion listeners, and model-facing control tools. Adding background subagents required the same lifecycle and interaction contract. Implementing that contract independently for every long-running capability would duplicate isolation, cleanup, notification, and prompt behavior while teaching the model a different collect-and-stop protocol for each producer.
 
-The [tool cookbook](../../../cookbook/adding-a-tool.md) already pointed at the real design smell: background bash is really generic long-running-tool infrastructure living inside one tool. The pressure stopped being hypothetical with [background subagent tasks](../feature/2026-07-08-background-subagent-tasks.md), which needs the same task ids, owner isolation, polling, stop, completion notices, and prompt guidance, and whose first draft answered by cloning the protocol under new names (`subagent_wait`, `subagent_output`, `subagent_stop`) and reshaping `dsh-tool-subagent` into a multi-tool plugin solely so the cloned companion tools would not collide across instances. Every future long-running capability (dev servers, watchers, remote jobs) would clone it again, and the model would learn a new collect/stop habit per capability.
-
-The surveyed peer products converged on the opposite shape. Claude Code exposes one `TaskOutput`/`TaskStop` pair spanning seven task kinds (background shells, subagents, remote sessions, …), with its earlier per-capability `BashOutput`/`KillShell` names kept only as aliases; Kimi Code's `BackgroundManager` runs process, agent, and pending-question kinds behind the same two tools and a ~5-method producer interface; DeepSeek-Reasonix serves bash and delegation from one session-scoped jobs manager; OpenCode's `BackgroundJob` registry is kind-agnostic by construction. The lesson is that the task registry, the control tools, and the notification path are one capability, and the producers (bash, subagents) are plugins into it.
+The task registry, control tools, and completion notices form one harness capability. Bash and subagents should supply execution-specific hooks without owning generic task behavior.
 
 ## Decision
 
-The `tasks/` package group owns background-task semantics once, and bash and subagents are producers:
+The `tasks/` package group owns background-task semantics:
 
-- `@deepseek-ai/dsh-tasks` — the task registry service (`ctx.tasks`): branded task ids, owner-scoped authorization, status snapshots, incremental/final output reads, cancellation, wait-for-terminal, completion listeners, and the awaited owner-cleanup path.
-- `@deepseek-ai/dsh-tool-tasks` — the model-facing control surface: `task_output`, `task_list`, `task_kill`, the completion-notice injection into the owning session, and the system-prompt section that teaches the background-task habit.
+- `@deepseek-ai/dsh-tasks` registers running work as `ctx.tasks` and owns task ids, authorization, snapshots, reads, cancellation, waiting, completion listeners, and cleanup.
+- `@deepseek-ai/dsh-tool-tasks` exposes `task_output`, `task_list`, and `task_kill`, injects completion notices, and supplies the background-task system-prompt guidance.
 
-Producers register running work into `ctx.tasks` and stay owners of their execution concerns: `dsh-tool-bash`'s `run_in_background` path registers the process it started (incremental stdout, spill formatting, kill), and `dsh-tool-subagent`'s background mode ([the feature RFC](../feature/2026-07-08-background-subagent-tasks.md)) registers the child run (final output only, cancel + dispose). The bash seam carries no registry: `bash_output`/`bash_kill` no longer exist (the generic tools replaced them), and the subagent companion tools were never created. The `dsh-agent-core` bundle loads the pair, so every shipped deployment has the control surface.
+Long-running tools are producers. `dsh-tool-bash` adapts a `BashProcess` into incremental output and process cancellation; `dsh-tool-subagent` adapts a child run into final output and child disposal. The execution seams remain independent of sessions and the task registry.
 
-The registry is a CONCRETE service, not an interface/implementation seam pair: there is exactly one sensible in-process implementation today, and the capability-seam convention says not to split preemptively. The pre-release stance lets a later durable/remote job system extract an interface when a second backend actually exists.
+`TaskService` is a concrete service. There is one in-process implementation, so an interface/backend package split would be speculative. A durable or remote implementation can introduce that seam when its lifecycle requirements are known.
 
-## Task model
+## Runtime contract
 
-`dsh-tasks` owns the vocabulary ([data-structure catalog](../../../core-data-structures/tasks.md)). `TaskId` is branded, generated by the registry as `<kind>-N` with a per-kind counter (`bash-1`, `subagent-1`) — the kind prefix keeps ids self-describing in transcripts and preserves the pre-runtime `bash-N` shape. Ids are runtime-global and predictable, so every access is authorized (below).
+The literal types live in the [task data-structure catalog](../../../core-data-structures/tasks.md). A producer calls `ctx.tasks.start()` with a kind, label, optional owning `Agent`, and a `run()` function. The runtime completes all failable preflight work before calling `run()` and invokes it once. After `run()` returns hooks, registration commits without another failable step; a producer cannot start work that lacks a collectable task id.
 
-A producer hands its work to `ctx.tasks.start()` in a declare-then-execute shape (the pattern the timeout-policy plugin set: the capability declares, the shared layer executes): identity first, then a `run()` starter the runtime invokes only once nothing can fail anymore.
+The producer hooks define three responsibilities:
 
-```ts ignore-check
-interface TaskStart {
-  /** Producer kind — also the id prefix ('bash', 'subagent', …). */
-  kind: string
-  /** One-line model-facing label (the command; the delegation description). */
-  label: string
-  /** The spawning agent; undefined = unowned (open access, dies with the service). */
-  owner?: Agent
-  /** Start the actual work; called exactly once, after preflight passed. */
-  run(): TaskHooks
-}
+- `cancel(reason?)` synchronously requests termination, is idempotent, and must cause `done` to settle.
+- `done` never rejects and settles only after the producer has released the task's resources.
+- Optional `readOutput()` returns the next consuming output delta. Omitting it declares a final-output task whose terminal result comes from `TaskOutcome.output`.
 
-interface TaskHooks {
-  /** Request termination; idempotent; must lead to `done` settling. The optional reason is `task_kill`'s logged reason, forwarded. */
-  cancel(reason?: string): void
-  /** Settles at QUIESCENCE — after the producer has released the task's resources. Never rejects. */
-  done: Promise<TaskOutcome>
-  /** OPTIONAL incremental read (stream kinds). Consecutive calls never re-deliver output; the producer owns truncation/spill formatting. Absence = final-output-only kind. */
-  readOutput?(): string
-}
+Statuses are `running`, `stopping`, `completed`, `killed`, and `failed`. Producer-specific information such as an exit code or stop reason belongs in `detail`; the registry does not interpret it. Task ids are branded and generated as `<kind>-N`, with a counter per kind.
 
-interface TaskOutcome {
-  status: 'completed' | 'killed' | 'failed'
-  /** Kind-specific detail rendered into the status line ('exit code: 3', 'max-tokens'). */
-  detail?: string
-  /** Final output for final-only kinds; read idempotently after the task settles. */
-  output?: string
-}
-```
+The runtime attaches one continuation to `done`, records the first terminal outcome, resolves waiters, and invokes completion listeners with per-listener error containment. First-wins settlement matters during teardown: if `cancel` throws, the runtime force-fails the record and warns that work may be orphaned rather than waiting forever for a promise that may never settle. A later producer outcome cannot overwrite that diagnosis or notify twice. A `cancel` that returns without eventually settling `done` still blocks teardown because the runtime cannot distinguish it from a slow, valid stop.
 
-The task status vocabulary is generic and closed: `running`, `stopping` (cancel requested, not yet settled), and the three terminal values above. Kind-specific meaning rides in `detail`, so the registry never learns process or agent semantics — the method presence (`readOutput`) is the capability, mirroring `SubagentRun.sendMessage`.
+Task registrations are not effects of the producer tool fiber. Reloading a tool or control-surface plugin therefore does not kill work owned by an agent and backend. The task service's own disposal cancels all live tasks and awaits contract-compliant producers.
 
-The registry attaches ONE continuation to `done`: record the terminal snapshot, then notify task-done listeners with per-listener containment (the guarantee the bash seam's `notifyTaskDone` used to give its own listener set). `done` settling at quiescence — not merely at completion — makes ordinary owner cleanup and service disposal awaitable without a second completion surface. Settlement is first-wins because teardown has one explicit failure fallback: if producer `cancel` throws before the request is delivered, `done` may never settle, so the registry force-fails the record with a possible-orphan detail instead of deadlocking disposal; a late producer outcome cannot overwrite that diagnosis or notify twice. This fallback terminates bookkeeping, not necessarily the underlying work.
+## Authorization and owner lifecycle
 
-Registrations are NOT effect-scoped to the registering fiber: a task belongs to its owning agent and its producing backend, not to the tool plugin whose call started it, so an HMR reload of `dsh-tool-bash` or `dsh-tool-tasks` never orphans or kills a running task (the same argument that used to keep bash ownership in the executor). The registry's own disposal cancels every live task and awaits contract-compliant producers to quiescence. A teardown cancel that throws force-fails the terminal record and logs that work may be orphaned; this prevents a broken producer from deadlocking the fiber without pretending the work stopped.
+Task ids are runtime-global and predictable, so every access is authorized by the registry. `get`, `read`, `wait`, and `kill` accept the calling `Agent`; `list` returns only tasks visible to that caller. An owned task is accessible only to the exact owning session. Unowned tasks are open to non-agent callers and die with the task service.
 
-## Authorization and the service surface
+The snapshot stores the owner's branded `SessionId` for authorization, while lifecycle operations retain the exact live `Agent` instance. These identities serve different purposes: session equality grants access, but exact object identity selects cleanup and completion delivery. Reusing an agent or session id cannot redirect an old scope's cleanup or notices to a replacement.
 
-Cross-session isolation lives IN the runtime so every consumer gets the same rule for free: read/kill/wait/get take the caller (`Agent | undefined`), and a task whose owner session differs from the caller's session is rejected (`!== undefined` comparison — an unowned task is open, a no-agent caller cannot match an owned one). `list(caller)` returns only the caller-visible tasks (owned-by-caller or unowned) — a global listing would leak other sessions' labels. The snapshot carries that authorization identity as the canonical branded `SessionId`, not a package-local token or bare string. Lifecycle ownership is independent: start retains the exact live `Agent` instance, owner cleanup selects by object identity, and completion listeners receive that exact owner, so id reuse cannot redirect cleanup or notices to a replacement.
+The first task for an owner attaches one asynchronous effect to `owner.ctx`. Agent-scope disposal cancels that owner's live tasks, awaits their terminal records, and removes their snapshots. This effect survives producer reloads and joins the agent's existing quiescence boundary. The task service retains the effect disposer so service reload can detach callbacks from still-live agent scopes after global teardown.
 
-```ts ignore-check
-class TaskService extends Service {           // ctx.tasks
-  start(spec: TaskStart): TaskId              // preflight (throws) → spec.run() starts the work → atomic commit (cannot fail)
-  get(id: TaskId, caller?: Agent): TaskSnapshot            // non-consuming; throws: unknown id, foreign owner
-  list(caller?: Agent): TaskSnapshot[]                     // caller-visible only
-  read(id: TaskId, caller?: Agent): TaskRead               // delta (stream kinds, consuming) or final output (final kinds, idempotent) + snapshot
-  kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-terminal'
-  wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
-  onTaskDone(listener: (snapshot: TaskSnapshot, owner: Agent | undefined) => void | PromiseLike<void>): () => void   // exact owner; effect-scoped, contained
-  attachSurface(name: string): () => void     // the misconfiguration fence, below
-}
-```
+For contract-compliant producers, `AgentHandle.dispose()` resolves only after owned background work has stopped. Work intended to outlive an agent must be started unowned; survival across runtime restarts requires a separate durable-job design.
 
-`TaskSnapshot` is the read-only projection: id, kind, label, branded owner `SessionId`, status, detail, started/finished timestamps, and the `reported` notice-suppression flag (below). `wait` resolves with the terminal snapshot, or with the still-`running` snapshot on timeout; aborting the wait cancels only the wait — unless the task already settled, in which case the wait still delivers the terminal snapshot (settlement suppressed the completion notice on this live waiter's behalf, and an aborted waiter un-counts itself synchronously so a same-tick settlement never suppresses a notice nobody will deliver).
+## Service surface
 
-**Misconfiguration fails loud**: a deployment that loads a background-capable producer without any control surface would let the model start tasks it can never read or stop — the half-loaded failure mode the subagent RFC's first draft reshaped a whole plugin to avoid. The fence is `attachSurface()`: `dsh-tool-tasks` attaches (effect-scoped) on load, and `start()` throws `background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)` when none is attached — the earliest self-contained moment, since concurrent plugin start makes a load-time check racy. The registry stays ignorant of tool names; a deployment with a custom (non-model) surface attaches its own.
+`TaskService` provides:
 
-## The model-facing control tools
+- `start(spec)` for preflighted, atomic registration.
+- `get(id, caller?)` and `list(caller?)` for non-consuming snapshots.
+- `read(id, caller?)` for a consuming stream delta or an idempotent final result.
+- `kill(id, caller?, reason?)` for cancellation.
+- `wait(id, timeoutMs, caller?, signal?)` for bounded terminal waiting.
+- `onTaskDone(listener)` for effect-scoped observation with exact-owner delivery and listener containment.
+- `attachSurface(name)` for the control-surface availability fence.
 
-`dsh-tool-tasks` registers three kind-agnostic tools (ACP render intent: `generic` cards, `kind: 'execute'` for kill and `'read'` for output/list, no `locations`):
+`wait` returns the terminal snapshot when the task settles or the live snapshot when its timeout expires. Aborting a wait cancels only that wait. If settlement has already assigned terminal delivery to the waiter, the terminal snapshot still wins. Waiters unregister synchronously on abort so a same-tick settlement cannot suppress a completion notice on behalf of a reader that receives nothing.
 
-- `task_output(task_id, wait?, timeout_ms?)` — non-blocking by default: stream kinds return output produced since the previous read, final kinds return only a status line while running and the final output once terminal; every response ends with the status line (`[status: running]`, `[status: completed, exit code: 0]`, `[status: failed, max-tokens]` — generic status + producer detail). `wait: true` blocks until the task settles or the timeout expires (config: defaulted `waitTimeoutMs`, capped `maxWaitTimeoutMs`); a timed-out wait returns `[status: running]` and leaves the task alive. Polling-by-default preserves the established bash habit; `wait` is what a parent uses when it is genuinely blocked on a subagent's answer.
-- `task_list()` — the caller's tasks, one line each: `<id> [<kind>] <status> — <label>`; `(no background tasks)` when empty. Most peers make listing a human-only surface (`/tasks` panels) and only Gemini CLI ships a model-facing list; DSH keeps it model-facing because the harness is an SDK with no guaranteed user UI — a deployment may have no `/tasks` equivalent — and a caller-scoped list is one cheap registry read.
-- `task_kill(task_id, reason?)` — requests cancellation and returns immediately (`requested cancellation of task <id>`); the optional `reason` lands in the logged tool args and is forwarded to the producer's `cancel` hook (the subagent producer aborts its task-owned signal with that reason). Killing an already-terminal task reports its terminal status rather than failing; a producer `cancel` that throws fails the call loud and leaves the task untouched (still `running`, notice not suppressed).
+A producer loaded without any control surface would let callers start work they cannot collect or stop. `dsh-tool-tasks` therefore calls `attachSurface()` for its lifetime, and `start()` fails before producer execution when no surface is attached. This check occurs at start rather than plugin load because sibling plugins may activate concurrently. Custom non-model surfaces can attach themselves without teaching the registry tool names.
 
-`task_output`'s read cursor is task-scoped and CONSUMING for stream kinds: the registry keeps one cursor per task, and a read returns everything produced since the previous read, exactly like the old `bash_output`. v1's intended reader is the owning model — the owner fence already makes it the only model-facing one — so a non-consuming observation surface (a UI tailing a task, multiple concurrent readers) is deliberately out of scope; when one is needed, it extends the registry with a cursor/snapshot read API rather than changing `task_output`, because two consumers sharing the consuming cursor would silently eat each other's output.
+## Model-facing control surface
 
-One system-prompt section (order 106, next to `tool:bash`) teaches the cross-call habit the per-tool descriptions cannot: track every returned task id; you are notified in-session when a task finishes, so do not busy-poll or sleep on one — keep working on independent steps and do not duplicate a running task's work; do not produce a final answer while a relevant task still runs — call `task_output` (with `wait` when blocked) to collect it first; `task_kill` tasks that stopped mattering. The do-not-poll and do-not-duplicate sentences are near-verbatim convergent across Claude Code, Kimi Code, and OpenCode — they are the two failure modes every peer engineered against.
+`dsh-tool-tasks` registers three kind-independent tools with generic ACP cards:
 
-Completion notices stay durable context, not a wake-up (`agent.inject()` appends a logged `context/message` the next model request sees; it does not run the model): on `onTaskDone`, `dsh-tool-tasks` injects `background task <id> (<kind>: <label>) finished [status: …]. Read its output with task_output.` through the exact owner captured at start, never a replacement found through a reused agent/session id, with the disposed-race contained. Notices are deduplicated the way Claude Code and Kimi Code both learned to: a task the model explicitly killed, or whose terminal state a read/wait already returned (including a wait pending at the moment of settlement), is marked `reported` and its notice suppressed — never a redundant "finished" for work the model just collected or ended. The model-visible ⟺ logged invariant holds with no new session event type.
+- `task_output(task_id, wait?, timeout_ms?)` reads output and always appends `[status: ...]`. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Reads are non-blocking unless `wait: true`, whose timeout is defaulted and capped by plugin config. A wait timeout reports the still-running status and does not stop the task.
+- `task_list()` returns caller-visible tasks as `<id> [<kind>] <status> — <label>`, or `(no background tasks)`.
+- `task_kill(task_id, reason?)` requests cancellation immediately. The optional logged reason is forwarded to the producer. Terminal tasks report their existing status; a throwing producer cancel fails the call and leaves the task running.
 
-Completion listeners are observation-only: each synchronous throw and returned promise rejection is logged independently, later listeners still run, and listener promises are not awaited before waiters or task teardown continue.
+Stream reads share one task-scoped consuming cursor because the owning model is the intended reader. A UI or multiple independent readers need a separate non-consuming observation API; sharing this cursor would let readers consume one another's output.
 
-## Producer opt-in and schema exposure
+The system prompt tells the model to retain task ids, continue independent work instead of busy-polling or duplicating a running task, collect relevant tasks before its final answer, and kill work that no longer matters. Completion injects a logged `context/message` into the exact owner's session; it becomes durable context for the next request but does not wake an idle agent.
 
-Whether a producer tool offers `run_in_background` is that producer's own defaulted config: `enableRunInBackground?: boolean` on `dsh-tool-bash` and on each `dsh-tool-subagent` instance (both default `true` — bash keeps its always-exposed behavior, and a deployment disables either per instance from cordis.yml, no code edit). A bundle forwards the configs of the child plugins it owns: `dsh-agent-core` exposes `toolBash` for its built-in producer and `toolTasks` for the generic control surface, while independently composed producers such as subagent instances receive config directly. This forwarding is config reachability, not producer registration: future background-capable tools do not become `agent-core` fields unless that bundle also chooses to own them. A disabled producer omits the parameter from its schema entirely — and, because the arg validator deliberately allows undeclared keys, its `execute` ALSO refuses a forced `run_in_background: true` loud (the omission is advertising; the execution-time check is the enforcement). `ctx.tasks` plays no part in schema shaping — it never rewrites or decorates a producer's tool schema (Kimi Code regex-rewrites its bash description when background is disabled; config-owns-the-schema makes that trick unnecessary) — it only provides runtime registration. The two halves compose fail-loud: the producer's config decides what the model sees, and a background call that still reaches `start()` without a control surface throws the load-this-package error. `start()` preflights every failable check (the fence, validation, exact live owner instance, and owner-cleanup attach) BEFORE invoking the producer's `run()` and commits atomically after — background work started without a collectable id is structurally impossible, not a producer rollback obligation.
+The runtime marks a terminal task `reported` when a read or wait delivers it, when a live waiter has claimed delivery at settlement, or when the model explicitly kills it. Reported tasks do not inject redundant completion notices. Listener failures are logged independently, do not stop later listeners, and are not awaited by waiters or teardown.
 
-## Agent-scope owner cleanup
+## Producer opt-in
 
-A contract-compliant background task must not outlive its owner: the subagent case leaks live child agents/sessions otherwise, and `agent/disposed` is an observe-only notification rather than a quiescence seam. Every live agent already owns an awaited structural registration scope ([agent-scope contract](2026-07-08-agent-scope-contexts.md)), so the task runtime uses that single lifecycle mechanism:
+Each producer owns whether its schema exposes `run_in_background` through defaulted config. `dsh-tool-bash` and each `dsh-tool-subagent` instance use `enableRunInBackground`, defaulting to true. A disabled instance omits the parameter and also rejects a forced background argument at execution because the generic argument validator permits undeclared keys. Schema omission advertises the capability; the execution check enforces it.
 
-- After validating and retaining the exact registered owner instance, the first task for that owner registers an async effect through `owner.ctx`. The effect belongs to the agent scope, survives producer reloads, selects tasks by exact owner identity, cancels them, awaits each terminal record, and drops the snapshots; a replacement reusing the same ids is outside that set.
-- `AgentHandle.dispose()` stops and drains the driver, detaches the agent and session, then awaits scope disposal. The task cleanup therefore participates in the same memoized quiescence boundary as every other agent-owned registration; no task-specific link exists in `AgentRegistry` or the loop.
-- The tasks service retains each exact owner-effect disposer so service reload can detach callbacks from still-live scopes after global task teardown, rather than leaving a dead service retained until every agent exits.
+`ctx.tasks` does not rewrite producer schemas. A bundle forwards configuration only for producers it owns. If a background call reaches `start()` without an attached surface, the runtime fence fails before execution.
 
-For contract-compliant producers, `AgentHandle.dispose()` resolves only after the owner's background children are gone. A producer whose teardown cancel throws is the explicit degradation: its record settles `failed` with a possible-orphan detail and cleanup continues. An ownerless task is the sanctioned way for healthy work to outlive an agent, and a future durable-job RFC is the way to outlive the runtime.
+## Producer integrations
 
-## Bash migration
+The bash seam exposes `resolve`, `run`, and `start`. `start(spec)` returns a `BashProcess` with incremental reads, cancellation, exit facts, and a non-rejecting quiescence promise. The local executor retains live handles only so its own disposal can kill and join processes. Foreground callers continue to use `resolve` and `run` directly.
 
-`dsh-bash` keeps the execution contract and carries no registry. The seam is `resolve`, `run`, and `start`, where `start(spec)` returns a process handle — `BashProcess`: `{ command, status, exitCode, signal, done, readOutput(), kill() }` — instead of a registry entry: `get`/`ownerOf`/`list`/`onTaskDone`, the listener machinery, `BashTaskId`, `OwnerToken`, and the spec's `owner` field are gone (a consumer census found `get`/`list` reached only by test harnesses and `onTaskDone` single-consumer — `dsh-tool-bash`; the hook bridges consume `resolve`+`run` only). The local executor keeps an internal table of LIVE processes solely for its own disposal quiescence (entries leave on settlement). The foreground trusted-plugin path (`resolve` + `run` with `stdin`/`env`, used by the hook bridges) is untouched and never routes through the runtime; `BashExecSpec.timeoutMs` stays required-but-ignored by `start()` (shared-spec status quo, documented in the seam JSDoc); the credential-scrub duplication between the bash and ACP spawn sites is explicitly NOT this runtime's work — the registry never touches process spawning.
+For background bash, `dsh-tool-bash` registers the calling agent as owner. Its hooks map `kill()` to cancellation, `done` to a completed or killed `TaskOutcome`, and `readOutput()` to the process's bounded incremental output plus spill and sandbox notices. Generic task tools own ids, status lines, listing, waiting, and completion notices.
 
-`dsh-tool-bash` keeps the `bash` tool; the `run_in_background` path is `ctx.tasks.start({ kind: 'bash', label: command, owner: exec.agent, run })` whose `run()` spawns through `ctx.bash.start(...)` and returns the hooks, where `done` maps the process exit to a `TaskOutcome` (`processOutcome`: `completed`/`killed` + exit-code/signal detail) and `readOutput` wraps the handle's incremental read with the spill/lossy formatting (`renderProcessRead`). The completion-notice listener left `dsh-tool-bash` entirely.
-
-## Subagent integration
-
-[Background subagent tasks](../feature/2026-07-08-background-subagent-tasks.md) rides this runtime while `dsh-tool-subagent` keeps its one-instance-per-provider shape. The task starter creates an independent `AbortController`, immediately begins async `ctx.subagents.start()` with that signal, and synchronously returns hooks: `cancel(reason)` aborts the controller, while `done` awaits startup rollback or the ready run's result and disposal. This covers cancellation before and after readiness through the subagent seam's one signal channel. Terminal mapping remains `completed` with final text, `aborted` as `killed`, and other reasons as `failed`; there is no `readOutput` because the child session remains the detailed trace.
+For background subagents, `dsh-tool-subagent` creates a task-owned `AbortController` and begins provider startup inside the task starter. Cancellation aborts the same signal before or after provider readiness. `done` awaits both the child result and child disposal, maps completed output to a final result, maps abort to `killed`, and maps other stop reasons or infrastructure failures to `failed`. Intermediate child history remains in the child session and is not exposed through `readOutput()`.
 
 ## Alternatives considered
 
-### Why not per-capability companion tools (`bash_output`/`bash_kill` + `subagent_wait`/`subagent_output`/`subagent_stop`)?
+### Per-capability control tools
 
-That is the trajectory this RFC interrupted. Each capability re-implements ids, ownership, polling, stop, notices, and guidance; the model learns N collect/stop habits and the prompt carries N near-identical tool descriptions; `dsh-tool-subagent` needed a structural reshape purely to de-duplicate its clones. Claude Code walked this exact path — per-capability `BashOutput`/`KillShell` first, then a generalized `TaskOutput`/`TaskStop` spanning shells, agents, and remote sessions with the old names kept as deprecated aliases — and the pre-release stance let this repo land directly on the unified shape with no alias burden.
+Separate bash and subagent output/stop tools duplicate ids, isolation, cleanup, notification, and guidance while increasing the model's schema and protocol burden. One runtime keeps execution-specific behavior in producers without cloning the task lifecycle.
 
-### Why not an abstract `TaskRuntime` seam with swappable backends?
+### An abstract task-runtime backend
 
-There is one in-process implementation and no concrete second backend; the capability-seam rule is to split when the consumer and backend can actually evolve independently, not before. A durable/persistent job system is the plausible second backend, and it changes the lifecycle contract (survival across owner disposal) enough that its RFC should own the interface extraction.
+No second backend exists. Durable work also changes owner and restart semantics, so its design should extract an interface from concrete requirements rather than preserve this implementation speculatively.
 
-### Why not keep authorization in the consumers, as bash did?
+### Consumer-owned authorization or cleanup events
 
-The bash split put policy in `dsh-tool-bash` so the executor seam stayed session-free — right for a seam that may be implemented remotely. The registry is harness-local infrastructure whose entire purpose includes the isolation fence; leaving the fence to each consumer means every future surface (model tools, a UI bridge, hook bridges) re-implements it or forgets it. Centralizing it is most of the reason the runtime exists.
+Consumer-owned checks invite inconsistent or missing isolation on each new surface. A broadcast cleanup event makes every listener filter every agent and provides no registration disposer. Central authorization plus one owner-scoped effect gives every consumer the same fence and an awaited, removable lifecycle hook.
 
-### Why not a `parallel`-mode `agent/cleanup` event instead of the keyed registry?
+### Blocking output or a separate wait tool
 
-An event fires for every agent at every disposal and every listener must filter; `Promise.all` rejection semantics need extra containment; and there is no disposer to make registrations effects. A keyed registry is targeted, contained, and disposable — and the loop already drains an ordered chain, so one more awaited link was the smaller change.
+Blocking by default would serialize the parent while background work runs. Waiting without reading would add another model call and schema without returning useful information. `task_output(wait: true)` makes blocking explicit and combines it with result delivery.
 
-### Why not blocking-by-default `task_output` (Claude Code's `block: true`)?
+The wait uses the shared deadline primitives but not the generic tool-timeout policy. A wait timeout is a successful observation that returns `[status: running]`; the generic policy would replace it with a timeout error. No tool-call timeout controls task lifetime after a task id has been returned.
 
-The established bash habit is poll-between-work, and the guidance tells the model to keep doing independent work while tasks run; defaulting to block would silently serialize the parent on its slowest child. The explicit `wait: true` keeps blocking a deliberate act, and the wait/read/kill trio still lands within the three-tool surface.
+### Runtime-owned output sinks
 
-### Why not a separate `task_wait` tool?
+A push sink would centralize buffering, but bash already owns bounded buffers, truncation, and spill files behind its executor seam. Pulling formatted deltas preserves that ownership. A durable backend that owns storage may justify revisiting the producer interface.
 
-Waiting is never useful without reading the result afterwards; a separate tool doubles the calls and the schema surface for zero information. Folding it into `task_output` matches the only real usage pattern.
+### Random ids, promotion, or lifecycle session events
 
-### Why not `ToolDefinition.timeoutMs` (the timeout-policy plugin) for `task_output`'s wait?
-
-The [timeout library](2026-07-06-timeout-deadline-library.md) gives `wait()` its timing internals — `ctx.tasks.wait` arms a `deadline()` and classifies wait-timeout vs caller-abort with `timeoutOf` scoped to `TASK_WAIT_TIMEOUT` — but the tool-call-level policy is deliberately NOT adopted: timeout-policy replaces a timed-out call with a structured `TOOL_TIMEOUT` failure, whereas a timed-out `task_output(wait: true)` is a SUCCESS that must still report `[status: running]` (the model needs the task's state either way, and the task keeps running). The wait therefore bounds its own deadline through the tool's `waitTimeoutMs`/`maxWaitTimeoutMs` config. For the same reason, no timeout policy manages a background task's LIFETIME: once the id is returned the work is off the tool-call deadline entirely — cancellation belongs to `task_kill` and owner cleanup.
-
-### Why not a push-sink producer contract (`appendOutput`/`settle`), as Kimi Code's manager uses?
-
-A sink centralizes output buffering, truncation, and spill in the runtime, which is elegant when the runtime owns output storage. In this codebase those concerns already live — bounded, tested, spill-file-aware — inside `dsh-bash-local`, and keeping process concerns in the executor is the point of the bash seam. The pull contract (`readOutput()` returning a formatted delta) reuses that machinery as-is; a sink would relocate it for no v1 gain. If a durable backend later makes the runtime own output storage, the producer contract is the one seam to revisit.
-
-### Why not random task ids (Claude Code's per-kind `36^8` suffixes)?
-
-Peers with shared registries use unguessable ids as defense-in-depth against cross-session access and predictable-path attacks. Here the owner fence is the boundary — exactly as `dsh-tool-bash` documented for the old predictable `bash-N` — and the registry hands no filesystem paths derived from the id, so sequential per-kind counters keep transcripts readable and tests deterministic. Nothing prevents switching the generator later; the id is branded and opaque to consumers.
-
-### Why not foreground→background promotion?
-
-Claude Code, Kimi Code, and OpenCode all let a running foreground call be promoted to a background task (user action or an over-budget auto-detach). It is deliberately out of v1: promotion needs a UI/user channel the SDK does not prescribe, and it changes the foreground tools' result contracts. The registration-based design leaves the door open — a foreground execution is promotable by registering its already-running work mid-flight — and a follow-up RFC can add it without touching the model-facing control tools.
-
-### Why not new session events for task lifecycle?
-
-Everything model-visible already lands in the log: starts and reads are tool calls/results, notices are injected `context/message` events. A `task/*` session event would duplicate facts the log carries, and live registry state (`task_list`) is intentionally runtime state, exactly as bash's task table was.
+Authorization, not unguessability, is the access boundary, and ids do not derive filesystem paths; sequential branded ids keep transcripts readable. Foreground-to-background promotion requires a user interaction contract the SDK does not prescribe. Starts, reads, and notices are already logged as tool and context events, so dedicated task session events would duplicate model-visible facts.
 
 ## Testing
 
-Unit coverage pins the registry lifecycle (register/read/kill/wait/list, owner isolation including no-agent callers and stale owner objects after id reuse, stream-vs-final read semantics, listener containment, notice suppression after an explicit kill or terminal read/wait, the `attachSurface` fence, start atomicity, model-facing and teardown cancel failures, ordinary disposal quiescence, and per-kind counters), the branded `SessionId` boundary, owner-effect placement and service-detach behavior, both producers' start mapping including async subagent readiness cancellation, and the structural no-uncollectable-work guarantee. Snapshot coverage pins the task tool schemas and prompt section.
+Unit coverage pins preflight atomicity, per-kind ids, stream and final reads, wait timeout and abort races, cancellation, first-wins settlement, listener containment, notice suppression, owner isolation, stale owner instances, owner cleanup, service teardown, and the no-surface fence. Producer tests cover bash process mapping, subagent startup cancellation, terminal mapping, and disposal. Snapshot coverage pins the control-tool schemas and prompt guidance.
 
 ## Consequences
 
-One background-task contract exists instead of a per-capability clone family: a background subagent and a background bash command coexist in one session under one id namespace, one listing, one notice format, and one guidance section, and the [tool cookbook](../../../cookbook/adding-a-tool.md) points long-running tools at `ctx.tasks`. The cost was a wide landing change — the bash seam lost its registry surface and every test tier moved with it, model-facing tool names churned (`bash_output`/`bash_kill` deleted), and the ACP snapshot pinned header was refreshed for the new schemas — sanctioned by the pre-release stance.
+Bash commands and subagents share one id vocabulary, listing, notice format, prompt habit, and set of control tools. New long-running producers implement execution hooks instead of another registry and tool family. The [tool cookbook](../../../cookbook/adding-a-tool.md) points producers to this contract.
 
-Owner-scoped cleanup changed bash semantics: a task that previously outlived its agent now dies with it. Deployments that relied on fire-and-forget background commands start them unowned (a non-agent caller) or accept the new lifecycle; the uniformity was judged worth the change, and the durable-job direction remains open for real survival requirements.
-
-Teardown trusts the producer contract that a successful `cancel` leads to `done` settling at quiescence. An explicit cancel throw is detectable and force-fails the record with a possible-orphan warning so disposal cannot deadlock; a cancel that returns but silently fails is indistinguishable from a slow stop and can still stall teardown. Covering that residual requires a bounded lifetime or a separate forced-disposal contract, both outside this runtime shape.
-
-`wait` is the first blocking tool call whose duration is model-controlled; the config cap bounds it, but a model that serializes on `wait` loses the parallelism the feature exists for — prompt guidance mitigates, and a future continuation-policy guard can enforce. Recording live background-flow snapshot scenarios (a polled and killed background command, a completion-notice turn) and a with-key e2e background lifecycle require a `DEEPSEEK_API_KEY` re-record and remain named follow-up work. The runtime deliberately defers durable/cross-restart tasks, non-consuming observation cursors, and foreground→background promotion (see Alternatives).
+Owned background bash now stops with its agent instead of surviving it. Background processes have no executor timeout; callers must kill irrelevant work or rely on owner/service disposal. Stream reads support one consuming reader, completion notices do not wake idle agents, and a producer that returns from `cancel` without settling `done` can still stall teardown. Durable jobs, independent observation cursors, and foreground promotion remain separate designs.
diff --git a/docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md b/docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md
index dac7f03a73..830d93577b 100644
--- a/docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md
+++ b/docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md
@@ -4,59 +4,59 @@ Status: implemented
 
 ## Problem
 
-The subagent seam ([the seam RFC](2026-06-21-subagent-capability-seam.md)) exposes `start() -> SubagentRun`, and the model-facing `dsh-tool-subagent` consumer collected that run synchronously only: the parent turn blocked until the child returned one final result. That shape is simple and transport-neutral, but it makes slow delegation expensive for the parent. A model that wants two independent investigations must either run them serially or hold the parent step open for the entire child duration.
+The [subagent seam](2026-06-21-subagent-capability-seam.md) returns a `SubagentRun`, but the model-facing tool originally collected every run synchronously. Independent, slow delegations therefore held the parent call open or ran serially.
 
-The harness already had one background-task precedent in bash: task ids, owner checks, output polling, stop, completion notifications, and prompt guidance. Subagents need the same user-facing habit, but not by copying bash's process-output semantics: a subagent does not expose an incremental stdout stream, and its child session remains the home for internal steps. The parent needs to start a child, keep working, later wait for or read the final answer, and stop the task when it is no longer relevant. An earlier draft of this RFC answered by cloning the bash protocol under subagent names (`subagent_wait`, `subagent_output`, `subagent_stop`) and reshaping `dsh-tool-subagent` into a multi-tool plugin so the clones would not collide across instances; [the background task runtime RFC](../architecture/2026-06-20-generic-long-running-tool-runtime.md) dissolved that duplication by extracting the registry and the control tools once, and this feature rides it.
-
-The design also has two lifecycle constraints that the synchronous path does not face. First, a background subagent can outlive the tool call that started it, so the tool-call abort signal must not stay wired to the child after the id is returned. Second, a completion notice can only be injected into a live owner agent: once an ACP session closes or an agent handle is disposed, `agent.inject()` cannot append to that session. The feature must therefore define whether background subagents survive owner disposal.
+Subagents need the same start, collect, list, stop, ownership, notification, and cleanup behavior as other long-running tools without adopting process-stream semantics. The child session remains the detailed trace; the parent needs the final answer and task status. A background child also outlives its starting tool call, so its cancellation and owner-disposal contracts must be explicit.
 
 ## Decision
 
-Each `dsh-tool-subagent` instance may expose `run_in_background?: boolean`, gated per instance by its defaulted `enableRunInBackground` config flag (default `true`; a disabled instance omits the parameter from its schema — the producer-opt-in shape [the runtime RFC](../architecture/2026-06-20-generic-long-running-tool-runtime.md) pins: the producer's config owns the schema, `ctx.tasks` only provides runtime registration). The plugin keeps its one-instance-per-provider shape — provider selection stays deployment config (`subagent` on `spawn`, `subagent_fork` on `fork`, …), and there are no subagent-specific companion tools to collide: collection, listing, and cancellation are the generic `task_output`/`task_list`/`task_kill` tools from `@deepseek-ai/dsh-tool-tasks`.
+Each `dsh-tool-subagent` instance may expose `run_in_background`, controlled by `enableRunInBackground` and enabled by default. A disabled instance omits the parameter and rejects a forced background argument at execution. Provider selection remains deployment configuration, so one instance still registers one distinctly named tool for one provider.
 
-A foreground call keeps the synchronous semantics: it waits for `run.result`, returns final text on `completed`, maps non-clean terminal stop reasons to an errored tool result, and disposes the run in `finally`.
+Background subagents use the [generic background task runtime](../architecture/2026-06-20-generic-long-running-tool-runtime.md). Collection, listing, cancellation, completion notices, and prompt guidance come from `task_output`, `task_list`, and `task_kill`; there are no subagent-specific companion tools.
 
-A background call validates that a parent agent exists, checks an already-aborted tool signal, and hands the delegation to `ctx.tasks.start()`. The runtime preflights the control-surface fence and owner-scope cleanup before its synchronous `run()` starter creates an independent `AbortController` and begins async `ctx.subagents.start()`; commit after that starter cannot fail, so provider work cannot become uncollectable. The task-owned signal, not the tool-call signal, then covers pending readiness and the live child. `ctx.tasks.start()` supplies kind-prefixed branded ids, owner-scoped access, loud no-control-surface failure, completion notices, and generic prompt guidance.
+Foreground calls retain their synchronous contract: await provider startup and `run.result`, return final text only for `completed`, map other terminal reasons to an errored tool result, and always dispose the run before returning.
 
-The registration maps the seam vocabulary onto the runtime's:
+For a background call, the tool validates the parent and refuses an already-aborted execution signal before calling `ctx.tasks.start()`. The task runtime preflights the control surface and owner cleanup before invoking the producer starter. That starter creates an independent `AbortController` and begins `ctx.subagents.start()`; after the id is returned, the tool-call signal no longer owns the child.
 
-- `kind: 'subagent'`, `label`: the model's `description` argument, `owner`: the parent agent.
-- `cancel`: abort the task-owned controller with `task_kill`'s optional logged reason; the same signal cancels provider-owned partial startup or a published child, and the task shows as `stopping` until settlement.
-- `done`: await `ctx.subagents.start()`. A cancellation rejection after startup rollback maps to `killed`; another startup rejection maps to `failed`. A ready run flows through `settleRun`, which awaits `run.result`, then `run.dispose()` (child quiescence), and maps `completed` to final `output`, `aborted` to `killed`, and other stop reasons to `failed`. Infrastructure and disposal failures settle `failed` rather than rejecting the task contract.
-- No `readOutput`: a subagent task is final-output-only. While it runs, `task_output` returns only the status line; once terminal it returns the final text (or failure detail) idempotently. The child session remains the detailed trace; v1 deliberately exposes no incremental transcript cursor.
+The task registration maps the subagent seam as follows:
+
+- `kind` is `subagent`, `label` is the model-supplied description, and `owner` is the parent agent.
+- `cancel(reason?)` aborts the task-owned controller. The same signal covers pending provider startup and the ready child.
+- `done` awaits provider startup, the child result, and `run.dispose()`. Completed runs return final text, aborted runs become `killed`, and other stop reasons become `failed`. Startup, result, and disposal failures become failed outcomes rather than rejected task promises.
+- `readOutput` is absent. While live, `task_output` returns status only; after settlement, it returns final output idempotently. Intermediate child activity remains in the child session.
 
 ## Lifecycle
 
-The background task is scoped to the owner session, not durable across session closure. The runtime registers one async cleanup through the exact owner's `agent.ctx`; agent-scope disposal cancels running tasks and awaits each `done` before `AgentHandle.dispose()` resolves. Since subagent `done` settles only after startup rollback or `run.dispose()`, owner disposal reaches child quiescence without leaking child agents or sessions. Completion notices are best-effort: a live owner gets the injection, while teardown that already detached or disposed the owner drops it.
+A background subagent belongs to its parent agent and is not durable across owner closure. The task runtime attaches cleanup to the exact owner's scope. Agent disposal cancels the task and awaits startup rollback or child disposal before `AgentHandle.dispose()` resolves, preventing leaked child agents and sessions.
+
+Completion notices target the exact owner captured at start. If owner teardown has already disposed the injection target, the notice is dropped; cleanup, not notification, is the lifecycle guarantee.
 
 ## Model guidance
 
-The background-task habit (track ids, do not finish while a relevant task runs, collect with `task_output`, kill what stopped mattering) is the generic `dsh-tool-tasks` prompt section — one habit for bash and subagents alike, which is the point of the shared runtime. `dsh-tool-subagent` adds only the wording on its own tool: the description and the `run_in_background` parameter say the call returns a task id immediately and the final answer is collected with `task_output` (with `wait: true` when genuinely blocked on it). Runtime enforcement remains owner authorization and the awaited owner-cleanup path, not the prompt.
+The generic task prompt teaches the shared habit: retain ids, continue independent work instead of busy-polling, collect relevant tasks before answering, and kill irrelevant work. The subagent schema adds only that background mode returns a task id and that `task_output` collects the result. Authorization and owner cleanup enforce the runtime boundary independently of prompt compliance.
 
 ## Alternatives considered
 
-### Why not subagent-specific `subagent_wait`/`subagent_output`/`subagent_stop` tools?
+### Subagent-specific wait, output, and stop tools
 
-The earlier draft of this RFC. The clones duplicate the bash protocol, teach the model a second collect/stop habit, and force a structural reshape of `dsh-tool-subagent` (one multi-tool instance instead of one instance per provider) purely so the companion tools register once. The generic runtime provides the same operations kind-agnostically, keeps this plugin's shape untouched, and its `attachSurface` fence covers the half-loaded deployment failure the reshape was defending against. The reshape was dropped with the clones.
+Capability-specific tools would duplicate the task protocol, teach another collect-and-stop habit, and complicate multiple provider instances. The generic runtime provides the required behavior without changing the tool's one-provider-per-instance shape.
 
-### Why not let background subagents survive owner session closure?
+### Survival after owner closure
 
-Survival after owner closure requires durable task state, child-session recovery, a way to surface late results into a reopened session, and policy for tasks whose owning client never returns. The agent runtime unregisters disposed agents, and `agent.inject()` intentionally rejects disposed targets. Scoping tasks to the owner and cleaning up through the awaited path makes the v1 lifecycle explicit and avoids orphaned child agents; a durable job system is the runtime RFC's named future direction, not this feature.
+Survival requires persistent task state, child-session recovery, a late-result delivery channel, and policy for abandoned owners. Owner-scoped cleanup gives process-local work a clear lifetime. Durable jobs require a separate design.
 
-### Why not skip owner checks because ACP sessions are isolated?
+### No owner checks for isolated clients
 
-ACP sessions isolate their logs and agents, but services such as `ctx.agents`, `ctx.tools`, and `ctx.tasks` are shared within the runtime, and task ids are global, predictable resource handles. The runtime enforces the owner fence for every task kind; this RFC merely notes that subagent tasks inherit it.
+Agents and logs may be session-scoped, but the task registry and predictable ids are runtime-global. The generic owner fence therefore applies to subagents like every other producer.
 
-### Why not expose incremental subagent transcript output?
+### Incremental child transcript output
 
-The child session is already the trace for internal reasoning, tool calls, and intermediate messages. Streaming that transcript into the parent would blur the parent/child log boundary that makes in-process and ACP providers equivalent. The first background surface returns status and final output only; richer observation belongs to UI/session tooling or a separate observation RFC.
+Streaming child history into the parent would blur the log boundary and make provider behavior diverge. This surface exposes final output only; richer observation belongs to session or UI tooling.
 
 ## Testing
 
-Unit coverage pins the stop-reason → outcome mapping (`runOutcome`, including unknown merge-extensible reasons), `settleRun`'s dispose-before-report on both result paths, the detached-signal contract (a pre-aborted signal refuses to start; a returned id is never wired to the tool signal), background settlement collected through the real `task_output`/`task_kill` tools, the structural no-orphan guarantee (a failed `tasks.start` preflight never invokes the provider), per-instance schema gating (`enableRunInBackground: false` omits the parameter and the background wording), and the loud failure when the tasks runtime is absent. Snapshot coverage pins the changed `subagent`/`subagent_fork` schemas through the pinned-header fixture; recording a live background-delegation transcript requires a `DEEPSEEK_API_KEY` re-record and remains named follow-up work.
+Unit coverage pins stop-reason mapping, dispose-before-report behavior, startup and result failures, pre-aborted refusal, detachment from the starting call's signal, cancellation before and after provider readiness, collection through the real task tools, the no-surface preflight fence, missing-runtime failure, and per-instance schema gating. Snapshot coverage pins the model-facing schemas.
 
 ## Consequences
 
-Slow delegation no longer holds the parent step open: the model fans out background children, keeps working, and collects with the same three control tools it already uses for bash — no new habit, no schema clones, and `dsh-tool-subagent`'s per-provider shape survived unchanged. The feature's usability depends on the tasks pair being loaded; the runtime's `start()` preflight fence turns a missing control surface into a loud, actionable error (raised before any child exists) rather than a silent dead end, and the `dsh-agent-core` bundle ships the pair so every stock deployment has it.
-
-The prompt guidance reduces abandoned tasks but cannot force a model to collect every background result. Runtime cleanup through the awaited owner-disposal path is the hard stop; a future planner or guard could enforce "no final answer with relevant running tasks" more strongly if the prompt proves insufficient. A background child outliving its starting tool call means a misbehaving child consumes tokens until collected, killed, or owner-disposed; `task_list` keeps it visible, and setting `enableRunInBackground: false` per instance keeps a deployment's delegation strictly synchronous.
+The parent can fan out slow delegations and collect them through the same task controls used by bash. Child work no longer occupies the starting tool call, but it can consume resources until collected, killed, or owner-disposed. Prompt guidance encourages collection; owner cleanup provides the hard lifetime boundary. Deployments that require synchronous delegation can disable background mode per tool instance.
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index ec91821fda..121bfd09f7 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -357,7 +357,7 @@ Source: [`packages/skill/tool-skill/src/index.ts`](../packages/skill/tool-skill/
 
 ### `subagent`
 
-Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.
+Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.
 
 ```json
 {
@@ -373,7 +373,7 @@ Delegate a self-contained task to a subagent (a separate agent that works in its
     },
     "run_in_background": {
       "type": "boolean",
-      "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+      "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
     }
   },
   "required": [
@@ -429,7 +429,7 @@ Source: [`packages/tasks/tool-tasks/src/index.ts`](../packages/tasks/tool-tasks/
 
 ### `task_output`
 
-Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.
+Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.
 
 ```json
 {
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md
index 9c1ec46f6e..33bfa25590 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md
@@ -64,22 +64,22 @@ declare const tools: {
     /** The exact skill name from the available skills list. */
     name: string;
   }): Promise<string>;
-  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`. */
+  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */
   subagent(args: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */
     prompt: string;
-    /** Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill). */
+    /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
   }): Promise<string>;
-  /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`. */
+  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */
   subagent_fork(args: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */
     prompt: string;
-    /** Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill). */
+    /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
   }): Promise<string>;
   /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */
@@ -91,7 +91,7 @@ declare const tools: {
   }): Promise<string>;
   /** List your background tasks (running and finished) with their ids, kinds, and statuses. */
   task_list(args: Record<string, unknown>): Promise<string>;
-  /** Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result. */
+  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */
   task_output(args: {
     /** Task id returned by the tool that started the background work. */
     task_id: string;
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json
index 000983ce43..daf4e93ee8 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json
@@ -132,7 +132,7 @@
     },
     {
       "name": "subagent",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -146,7 +146,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -157,7 +157,7 @@
     },
     {
       "name": "subagent_fork",
-      "description": "Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -171,7 +171,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -210,7 +210,7 @@
     },
     {
       "name": "task_output",
-      "description": "Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.",
+      "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.golden.md b/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.golden.md
index 3a28852964..36aa94c53c 100644
--- a/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.golden.md
+++ b/examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.golden.md
@@ -49,22 +49,22 @@ declare const tools: {
     /** The exact skill name from the available skills list. */
     name: string;
   }): Promise<string>;
-  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`. */
+  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */
   subagent(args: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */
     prompt: string;
-    /** Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill). */
+    /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
   }): Promise<string>;
-  /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`. */
+  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */
   subagent_fork(args: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */
     prompt: string;
-    /** Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill). */
+    /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
   }): Promise<string>;
   /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */
@@ -76,7 +76,7 @@ declare const tools: {
   }): Promise<string>;
   /** List your background tasks (running and finished) with their ids, kinds, and statuses. */
   task_list(args: Record<string, unknown>): Promise<string>;
-  /** Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result. */
+  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */
   task_output(args: {
     /** Task id returned by the tool that started the background work. */
     task_id: string;
diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.golden.json
index 4747ec3de7..52e7974409 100644
--- a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.golden.json
+++ b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.golden.json
@@ -79,7 +79,7 @@
     },
     {
       "name": "subagent",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -93,7 +93,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -104,7 +104,7 @@
     },
     {
       "name": "subagent_fork",
-      "description": "Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -118,7 +118,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -157,7 +157,7 @@
     },
     {
       "name": "task_output",
-      "description": "Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.",
+      "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.golden.md b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.golden.md
index 3a28852964..36aa94c53c 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.golden.md
+++ b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.golden.md
@@ -49,22 +49,22 @@ declare const tools: {
     /** The exact skill name from the available skills list. */
     name: string;
   }): Promise<string>;
-  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`. */
+  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */
   subagent(args: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */
     prompt: string;
-    /** Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill). */
+    /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
   }): Promise<string>;
-  /** Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`. */
+  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`. */
   subagent_fork(args: {
     /** A short (3-5 word) description of the delegated task, for display. */
     description: string;
     /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */
     prompt: string;
-    /** Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill). */
+    /** Run as a background task and return its id; collect with task_output or stop with task_kill. */
     run_in_background?: boolean;
   }): Promise<string>;
   /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */
@@ -76,7 +76,7 @@ declare const tools: {
   }): Promise<string>;
   /** List your background tasks (running and finished) with their ids, kinds, and statuses. */
   task_list(args: Record<string, unknown>): Promise<string>;
-  /** Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result. */
+  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */
   task_output(args: {
     /** Task id returned by the tool that started the background work. */
     task_id: string;
diff --git a/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.golden.json
index c9537518de..4b07d8edef 100644
--- a/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.golden.json
+++ b/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.golden.json
@@ -63,7 +63,7 @@
     },
     {
       "name": "subagent",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -77,7 +77,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -88,7 +88,7 @@
     },
     {
       "name": "subagent_fork",
-      "description": "Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -102,7 +102,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -141,7 +141,7 @@
     },
     {
       "name": "task_output",
-      "description": "Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.",
+      "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.golden.json
index c9537518de..4b07d8edef 100644
--- a/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.golden.json
+++ b/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.golden.json
@@ -63,7 +63,7 @@
     },
     {
       "name": "subagent",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -77,7 +77,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -88,7 +88,7 @@
     },
     {
       "name": "subagent_fork",
-      "description": "Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -102,7 +102,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -141,7 +141,7 @@
     },
     {
       "name": "task_output",
-      "description": "Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.",
+      "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.golden.json
index c9537518de..4b07d8edef 100644
--- a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.golden.json
+++ b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.golden.json
@@ -63,7 +63,7 @@
     },
     {
       "name": "subagent",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -77,7 +77,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -88,7 +88,7 @@
     },
     {
       "name": "subagent_fork",
-      "description": "Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -102,7 +102,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -141,7 +141,7 @@
     },
     {
       "name": "task_output",
-      "description": "Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.",
+      "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.golden.json
index cbe762210e..da5e23216c 100644
--- a/examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.golden.json
+++ b/examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.golden.json
@@ -117,7 +117,7 @@
     },
     {
       "name": "subagent",
-      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -131,7 +131,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -142,7 +142,7 @@
     },
     {
       "name": "subagent_fork",
-      "description": "Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.",
+      "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -156,7 +156,7 @@
           },
           "run_in_background": {
             "type": "boolean",
-            "description": "Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill)."
+            "description": "Run as a background task and return its id; collect with task_output or stop with task_kill."
           }
         },
         "required": [
@@ -195,7 +195,7 @@
     },
     {
       "name": "task_output",
-      "description": "Read output/status from a background task (started by a tool with `run_in_background`). Stream tasks (bash) return only output produced since your previous task_output call; final-output tasks (subagent) return the final answer once the task finishes. Every response ends with a [status: ...] line. Non-blocking by default; set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.",
+      "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/packages/bash/bash-local/src/index.ts b/packages/bash/bash-local/src/index.ts
index f80ea45e98..9c2b0b4511 100644
--- a/packages/bash/bash-local/src/index.ts
+++ b/packages/bash/bash-local/src/index.ts
@@ -1,17 +1,7 @@
 /**
- * `LocalBashExecutor`: the local-subprocess implementation of the
- * `@deepseek-ai/dsh-bash` executor seam. Spawns `bash -c` per call in its
- * own process group (see `./run.ts` for the plumbing and the agent-tool
- * survey notes), tracks live background processes for disposal quiescence
- * ONLY (task semantics live in `ctx.tasks`), and kills everything on dispose.
- *
- * TODO(permissions/sandbox): execution policy does NOT belong here — use
- * the `tools/pre-execute` deny/ask gate (see docs/architecture.md
- * § Extending The Harness) or implement a sandboxing `BashExecutor`.
- * Reference points:
- * Claude Code wraps commands in sandbox-exec/bubblewrap; Codex applies
- * seatbelt/landlock plus an execpolicy prefix-rule engine.
- *
+ * Local-subprocess implementation of the bash executor seam. Each command runs
+ * as `bash -c` in its own process group; disposal kills and joins live groups.
+ * Execution policy belongs in `tools/pre-execute` or a sandboxing executor.
  * @module @deepseek-ai/dsh-bash-local
  */
 
@@ -47,10 +37,8 @@ function assertPositiveFinite(name: string, value: number): void {
 }
 
 /**
- * Local-subprocess bash executor. Defaults follow the agent-tool survey
- * consensus: 120s default / 600s max timeout (Claude Code, OpenCode), 64KB
- * in-memory output with full-stream spill files (pi, OpenCode),
- * process-group SIGTERM→SIGKILL kills with a 3s grace (OpenCode).
+ * Local bash executor with bounded output, spill files, and process-group
+ * `SIGTERM` to `SIGKILL` escalation.
  */
 export class LocalBashExecutor extends BashExecutor {
   static Config: z<Config> = z.object({
@@ -61,11 +49,7 @@ export class LocalBashExecutor extends BashExecutor {
     graceMs: z.number().default(DEFAULT_GRACE_MS),
   })
 
-  /**
-   * Live background processes, tracked for DISPOSAL only: an entry leaves
-   * the map the moment its process settles (callers keep reading through
-   * their own {@link BashProcess} handle — the buffers live on it).
-   */
+  /** Live processes retained only so disposal can kill and join them. */
   private live = new Map<BashProcess, RunningBash>()
   /** Test seam: spill knobs forwarded to runBash. */
   internals: RunInternals = {}
@@ -75,17 +59,14 @@ export class LocalBashExecutor extends BashExecutor {
 
   constructor(ctx: Context, config: Config) {
     super(ctx)
-    // schemastery (static Config) has already filled the defaulted fields;
-    // the cast records that runtime fact for exactOptionalPropertyTypes.
+    // Schemastery fills these fields before construction; the type does not encode that step.
     this.config = config as ResolvedConfig
     assertPositiveFinite('timeoutMs', this.config.timeoutMs)
     assertPositiveFinite('maxTimeoutMs', this.config.maxTimeoutMs)
     assertPositiveFinite('maxOutputBytes', this.config.maxOutputBytes)
     assertPositiveFinite('graceMs', this.config.graceMs)
     ctx.effect(() => async () => {
-      // Kill every live process group and WAIT for the processes to close so
-      // nothing outlives the fiber (HMR safety) — a TERM-trapping child is
-      // held until the SIGKILL escalation lands.
+      // Await closure so even a TERM-trapping child cannot outlive the fiber.
       const pending: Promise<void>[] = []
       for (const [proc, running] of this.live) {
         proc.status = 'killed'
@@ -116,20 +97,16 @@ export class LocalBashExecutor extends BashExecutor {
       workdir: request.workdir ?? this.config.cwd ?? process.cwd(),
       timeoutMs,
       ...request.signal ? { signal: request.signal } : {},
-      // Carry stdin/env through verbatim — optional, no config default (absent
-      // means none). env merges AFTER the scrub in run.ts.
+      // Explicit environment values are merged after credential scrubbing in run.ts.
       ...request.stdin !== undefined ? { stdin: request.stdin } : {},
       ...request.env !== undefined ? { env: request.env } : {},
-      // A local executor carries the override as an explicit inert fact; a
-      // sandboxing subclass resolves it to its configured fallback.
+      // Local execution carries this override for sandboxing subclasses.
       sandboxMode: request.sandboxMode,
     }
   }
 
   async run(spec: BashExecSpec): Promise<BashRunResult> {
-    // One fused deadline drives both the timeout and upstream cancellation;
-    // runBash listens on d.signal and runs the SIGTERM→grace→SIGKILL kill.
-    // `using` clears the timer across the awaited process lifetime.
+    // One deadline combines timeout and upstream cancellation; disposal clears its timer.
     using d = deadline(spec.signal, spec.timeoutMs, 'BASH_TIMEOUT')
     const outcome = await runBash({
       command: spec.command,
@@ -140,21 +117,14 @@ export class LocalBashExecutor extends BashExecutor {
       stdin: spec.stdin,
       env: spec.env,
     }, this.internals).done
-    // Classify the FIRST abort reason: a BASH_TIMEOUT TimeoutReason means our timeout cut the
-    // command short; any other abort — an upstream cancel, or a foreign (outer) deadline's
-    // timeout under nesting — is aborted.
+    // Only this executor's timeout reason counts as timedOut; outer deadlines count as aborts.
     const timedOut = timeoutOf(d.signal, 'BASH_TIMEOUT') !== undefined
     const aborted = d.signal.aborted && !timedOut
     return { ...outcome, timedOut, aborted, timeoutMs: spec.timeoutMs }
   }
 
   start(spec: BashExecSpec): BashProcess {
-    // No timeout for background processes (matches Claude Code, which
-    // detaches the timeout when backgrounding); callers stop them via the
-    // handle's kill() — or via spec.signal, which the seam contract honors
-    // for background runs too (runBash wires it to the group kill). No
-    // deadline is created here, so spec.timeoutMs is ignored by design —
-    // background processes stay timeout-free (see the timeout-library RFC).
+    // Background runs ignore timeoutMs; callers stop them through kill() or spec.signal.
     const running = runBash({
       command: spec.command,
       cwd: spec.workdir,
@@ -172,9 +142,7 @@ export class LocalBashExecutor extends BashExecutor {
       exitCode: null,
       signal: null,
       done: running.done.then((outcome) => {
-        // Caller-aborted and signal-terminated processes report as killed, not
-        // completed. The signal check also covers commands that terminate
-        // themselves without aborting the upstream signal.
+        // Any signal termination is killed, including a command signaling itself.
         if (proc.status === 'running') {
           proc.status = spec.signal?.aborted === true || outcome.signal !== null ? 'killed' : 'completed'
         }
@@ -183,9 +151,7 @@ export class LocalBashExecutor extends BashExecutor {
         this.onProcessDone(proc, running.stderr.readFrom(0).text)
         this.live.delete(proc)
       }, (error: unknown) => {
-        // Spawn-level failure (bad workdir, …): the process never ran. The
-        // error is surfaced through the read path, not a rejection. String()
-        // suffices — runBash only rejects with Error instances.
+        // Background spawn failures settle as killed and surface through the read path.
         proc.status = 'killed'
         running.stderr.push(Buffer.from(`spawn failed: ${String(error)}`))
         this.onProcessDone(proc, running.stderr.readFrom(0).text)
diff --git a/packages/bash/bash-sandbox/src/index.ts b/packages/bash/bash-sandbox/src/index.ts
index ab96db61c4..704cd4604b 100644
--- a/packages/bash/bash-sandbox/src/index.ts
+++ b/packages/bash/bash-sandbox/src/index.ts
@@ -20,7 +20,7 @@ import type { Config as LocalConfig } from '@deepseek-ai/dsh-bash-local'
  * Plugin config: the local executor's knobs plus the sandbox policy. All
  * optional — `static Config` supplies the defaults (`mode: 'read-only'` is the
  * fail-safe default; an example that wants a workspace-writable agent opts in
- * explicitly). The runner choice is NOT configured here: which platform
+ * explicitly). The runner choice is not configured here: which platform
  * backend confines the command is the `ctx.sandbox` provider's config.
  */
 export interface Config extends LocalConfig {
@@ -70,10 +70,8 @@ export function classifyRunnerFailure(result: BashRunResult, signatures: readonl
 }
 
 /**
- * The classifier core shared by foreground results and settled background
- * tasks: failed AND signature present. Lowercases BOTH sides — the seam
- * declares its signatures case-insensitive, and producers compose them from
- * runtime data of any case (an `argv0` path, `No such file or directory`).
+ * Shared classifier for failed runs. Signatures are case-insensitive and may
+ * include runtime values such as an executable path.
  */
 function matchesSignature(exitCode: number | null, stderr: string, signatures: readonly string[]): boolean {
   if (exitCode === null || exitCode === 0) return false
@@ -104,15 +102,10 @@ export class SandboxBashExecutor extends LocalBashExecutor {
   private readonly mode: SandboxMode
   private readonly workspaceRoot: string
   /**
-   * Per-process facts, keyed by handle from `start()` until the settle stamp
-   * consumes them: the mode the process runs under (per-call — an escalated process
-   * differs from its neighbors) plus its wrap facts. The seam returns facts
-   * PER WRAP — a provider may legally vary enforcement or dialect between
-   * calls — so overlapping background processes must each classify against their
-   * OWN wrap; a single latest-wrap field would let a later `start()` clobber
-   * an earlier process's facts before it settles. A `danger-full-access` process
-   * has NO entry (nothing confined it), which is what the settle stamp keys
-   * off.
+   * Per-process confinement facts retained until settlement. Providers may
+   * vary enforcement and diagnostic dialect between overlapping calls, so a
+   * shared latest-wrap value would classify a process against the wrong facts.
+   * Unconfined processes have no entry.
    */
   private readonly processFacts = new Map<BashProcess, {
     mode: ConfinedSandboxMode
@@ -123,10 +116,7 @@ export class SandboxBashExecutor extends LocalBashExecutor {
 
   constructor(ctx: Context, config: Config) {
     super(ctx, config)
-    // schemastery (static Config) already filled the defaulted fields — the
-    // cast records that runtime fact (mirrors LocalBashExecutor's config
-    // cast). `workspaceRoot` and `cwd` have NO schema default, so their
-    // fallback chain is real branching.
+    // Schemastery fills mode before construction; workspaceRoot and cwd retain runtime fallbacks.
     this.mode = config.mode as SandboxMode
     this.workspaceRoot = resolve(config.workspaceRoot ?? config.cwd ?? process.cwd())
   }
@@ -168,11 +158,7 @@ export class SandboxBashExecutor extends LocalBashExecutor {
     // Same stamped-by-resolve invariant as run().
     const mode = spec.sandboxMode as SandboxMode
     if (mode === 'danger-full-access') return super.start(spec)
-    // Sandbox facts are stamped at settle time by onProcessDone()
-    // (denial classification runs against the settled task's collected
-    // stderr). The map entry lands synchronously after spawn, strictly
-    // before the earliest possible settle (including a spawn rejection, whose
-    // promise reaction cannot run until this synchronous start call returns).
+    // Install facts synchronously; promise settlement cannot run before start() returns.
     const confined = this.confine(spec.command, mode)
     const proc = super.start({ ...spec, command: confined.command })
     const { enforcement, denialSignatures, runnerFailureSignatures } = confined
@@ -188,10 +174,7 @@ export class SandboxBashExecutor extends LocalBashExecutor {
     const facts = this.processFacts.get(proc)
     if (facts !== undefined) {
       this.processFacts.delete(proc)
-      // Runner failure outranks denial (the command never ran; the runner's
-      // own error text can contain denial words). A settled task has no
-      // error channel left, so the fact IS the surface here — the foreground
-      // path throws instead.
+      // Runner failure outranks denial because its diagnostics may contain denial terms.
       const runnerFailed = matchesSignature(proc.exitCode, stderr, facts.runnerFailureSignatures)
       proc.sandbox = {
         mode: facts.mode,
diff --git a/packages/bash/bash/src/index.ts b/packages/bash/bash/src/index.ts
index f5b37a3822..7563224000 100644
--- a/packages/bash/bash/src/index.ts
+++ b/packages/bash/bash/src/index.ts
@@ -1,23 +1,7 @@
 /**
- * The bash executor seam (`ctx.bash`): an abstract service defining WHAT a
- * bash backend does — run foreground commands, start background processes —
- * without saying HOW. Implementations subclass {@link BashExecutor} and
- * register themselves as the `bash` service; `@deepseek-ai/dsh-bash-local`
- * (local subprocesses) is the first. Future implementations swap in
- * sandboxes, containers, or remote exec servers without touching the tool
- * schemas that consume them (`@deepseek-ai/dsh-tool-bash`).
- *
- * The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the
- * surveyed agents: pi hides execution behind a `BashOperations` interface
- * (local shell / SSH / VM backends), Codex behind an exec-server protocol.
- *
- * The seam is deliberately TASK-FREE: `start()` hands back a
- * {@link BashProcess} handle (incremental reads, kill, a quiescence promise)
- * and nothing else. Task ids, owner isolation, polling tools, and completion
- * notices are the generic `ctx.tasks` runtime's job (`@deepseek-ai/dsh-tasks`)
- * — the tool layer adapts the handle into a task registration. This keeps a
- * remote/sandbox executor free of any session or registry dependency.
- *
+ * The `ctx.bash` executor seam for foreground commands and background process
+ * handles. Task ids, ownership, polling, and notices belong to
+ * `@deepseek-ai/dsh-tasks`, keeping executors independent of sessions.
  * @module @deepseek-ai/dsh-bash
  */
 
@@ -49,21 +33,15 @@ declare module 'cordis' {
  * implementation per context; loading a second throws, which is cordis'
  * standard duplicate-service behavior).
  *
- * Semantics every implementation must honor:
- * - {@link run} REJECTS only for infrastructure failures (unusable workdir,
- *   missing shell, pre-aborted signal). Nonzero exits, timeout kills, and
- *   abort kills RESOLVE with a descriptive {@link BashRunResult} — reporting
- *   a failed command is the tool layer's job, not an exception.
+ * Implementations must honor these semantics:
+ * - {@link run} rejects only for infrastructure failures. Nonzero exits,
+ *   timeout kills, and abort kills resolve with a {@link BashRunResult}.
  * - {@link start} returns immediately; no timeout applies to background
- *   processes (callers stop them via {@link BashProcess.kill} or the spec's
- *   AbortSignal). The handle's `done` settles at process close and never
- *   rejects (a spawn failure settles as `killed` with the error readable on
- *   stderr).
+ *   processes. `done` settles at process close and never rejects; spawn
+ *   failures settle as `killed` with the error on stderr.
  * - {@link BashProcess.readOutput} is incremental: consecutive reads never
- *   re-deliver output. Implementations bound their buffers; reads that lost
- *   data flag `lossy` and point at full-stream spill files when available.
- * - Disposal kills every running background process and awaits their exit
- *   (no orphan processes survive `fiber.dispose()`).
+ *   repeat output. Lossy reads report truncation and available spill files.
+ * - Disposal kills all running background processes and awaits their exit.
  */
 export abstract class BashExecutor extends Service {
   constructor(ctx: Context) {
diff --git a/packages/bash/bash/src/types.ts b/packages/bash/bash/src/types.ts
index 8cf579b767..d9ad6eda6d 100644
--- a/packages/bash/bash/src/types.ts
+++ b/packages/bash/bash/src/types.ts
@@ -1,14 +1,6 @@
 /**
- * Execution vocabulary for the bash executor seam. Types only — the abstract
- * service lives in `./index.ts`, implementations in sibling packages
- * (`@deepseek-ai/dsh-bash-local` first).
- *
- * Background TASK semantics (ids, ownership, polling protocol, completion
- * listeners) deliberately do NOT live here: the seam starts a background
- * PROCESS and returns a {@link BashProcess} handle; the caller (the tool
- * layer) registers that handle with the generic `ctx.tasks` runtime
- * (`@deepseek-ai/dsh-tasks`), which owns everything task-shaped.
- *
+ * Execution types for the bash executor seam. Background task semantics belong
+ * to `@deepseek-ai/dsh-tasks`; this seam exposes only process handles.
  * @module dsh-bash/types
  */
 
@@ -67,12 +59,9 @@ export interface BashExecRequest {
 }
 
 /**
- * A fully-resolved execution SPEC — exactly what {@link BashExecutor.run} /
- * {@link BashExecutor.start} act on. `workdir` and `timeoutMs` are REQUIRED:
- * defaulting and capping already happened in {@link BashExecutor.resolve}, so
- * the executor never hides a `?? config` fallback (explicit > implicit). For
- * background processes, `start()` ignores `timeoutMs` (background runs have no
- * timeout) — the field is still required because the type is shared.
+ * A resolved execution spec. {@link BashExecutor.resolve} fills and caps the
+ * required fields; {@link BashExecutor.start} ignores `timeoutMs` because
+ * background processes have no executor timeout.
  */
 export interface BashExecSpec {
   command: string
@@ -80,20 +69,11 @@ export interface BashExecSpec {
   timeoutMs: number
   /** Abort signal — implementations kill the command when it fires. */
   signal?: AbortSignal | undefined
-  /**
-   * Bytes to write to the command's stdin (then close it), carried through
-   * verbatim from {@link BashExecRequest.stdin}. OPTIONAL on the resolved spec:
-   * it has no config default, so a missing one means "no stdin" — the safe,
-   * ordinary case — not a silent footgun, so it stays a plain optional rather
-   * than required-but-nullable (see the request field).
-   */
+  /** Bytes to write to stdin before closing it; absent means no stdin. */
   stdin?: string | undefined
   /**
-   * Extra environment entries, carried through verbatim from
-   * {@link BashExecRequest.env} and merged by the implementation AFTER its
-   * credential scrub (an explicit entry wins even when its name matches the
-   * scrub pattern). OPTIONAL on the spec for the same reason as `stdin` — no
-   * config default, absent means "no extra env".
+   * Extra environment entries, merged after credential scrubbing so explicit
+   * values win; absent means no extra entries.
    */
   env?: Record<string, string> | undefined
   /** Resolved sandbox mode; ignored by executors that do not confine. */
@@ -144,12 +124,9 @@ export interface BashProcessRead {
 }
 
 /**
- * A live background process handle, returned by {@link BashExecutor.start}.
- * The HANDLE is the only access path (no executor-level id lookup): the
- * caller holds it, adapts it into a `ctx.tasks` registration, or drops it.
- * Reads stay valid after the process exits (the remaining buffered output is
- * still consumable); the executor's own disposal kills every running process
- * and awaits {@link done}.
+ * A background process handle returned by {@link BashExecutor.start}. It is the
+ * only access path; buffered output remains readable after exit. Executor
+ * disposal kills running processes and awaits {@link done}.
  */
 export interface BashProcess {
   /** Process lifecycle state (settled exactly once). */
diff --git a/packages/bash/tool-bash/src/index.ts b/packages/bash/tool-bash/src/index.ts
index 1784a2dd89..476cd1a176 100644
--- a/packages/bash/tool-bash/src/index.ts
+++ b/packages/bash/tool-bash/src/index.ts
@@ -1,28 +1,10 @@
 /**
- * The model-facing `bash` tool. Pure schema + text shaping — every process
- * concern lives behind the `ctx.bash` executor seam (`@deepseek-ai/dsh-bash`),
- * so sandbox/permission/remote executor implementations swap in without
- * touching what the model sees.
- *
- * Background runs are TASKS, not bash-private state: `run_in_background`
- * starts a process through the seam and registers its handle with the generic
- * `ctx.tasks` runtime (`@deepseek-ai/dsh-tasks`), which owns the id, the
- * owner fence, the completion notice, and the model-facing collect/stop
- * tools (`task_output`/`task_list`/`task_kill` from
- * `@deepseek-ai/dsh-tool-tasks`). Whether the parameter is exposed at all is
- * THIS plugin's `enableRunInBackground` config (default on) — the registry
- * never rewrites a producer's schema.
- *
- * The tool-call abort signal is deliberately NOT wired to a background
- * process: after the task id is returned the parent step may end while the
- * work continues; cancellation belongs to `task_kill` and the owner-disposal
- * cleanup. A signal already aborted before the call refuses to start.
- *
- * TODO(permissions): commands run with the executor's full authority. The
- * permission/sandbox seam is the `tools/pre-execute` waterfall (deny/ask) plus
- * sandboxing `BashExecutor` implementations — see docs/architecture.md
- * § Extending The Harness.
+ * Model-facing `bash` tool over the `ctx.bash` executor seam. Background calls
+ * register process handles with `ctx.tasks`; their work uses task cancellation
+ * rather than the tool-call signal after an id is returned.
  *
+ * TODO(permissions): deployment policy belongs in `tools/pre-execute` and
+ * sandboxing executors; see docs/architecture.md § Extending The Harness.
  * @module @deepseek-ai/dsh-tool-bash
  */
 
@@ -44,14 +26,9 @@ import { parseExitStatus, renderProcessRead, renderResult } from './render.ts'
 export const name = 'tool-bash'
 export const inject = ['tools', 'bash', 'systemPrompt']
 
-/** Config: whether the model may background commands (the producer-opt-in flag). */
+/** Configures whether the model may background commands. */
 export interface Config {
-  /**
-   * Expose `run_in_background` in the bash schema (default true). Disabled,
-   * the parameter is absent entirely — schema and capability never disagree.
-   * Backgrounding also needs the `ctx.tasks` runtime at call time; a missing
-   * one fails the call loud with the load-these-packages message.
-   */
+  /** Expose `run_in_background` (default true); disabled calls are also rejected. */
   enableRunInBackground?: boolean
 }
 
@@ -59,14 +36,7 @@ export const Config: z<Config> = z.object({
   enableRunInBackground: z.boolean().default(true),
 })
 
-/**
- * Validate the constraints the SchemaSpec can't express. `defineTool` now
- * validates parsed args against the SchemaSpec before `execute` runs (the
- * arg-validation RFC), so type/required/enum checks are already done and `args`
- * is the validated `InferArgs` shape here. What remains are value constraints
- * the DSL has no vocabulary for: non-empty strings and a positive, finite
- * timeout.
- */
+/** Parsed tool args; execute validates value constraints absent from SchemaSpec. */
 interface BashToolArgs {
   command: string
   description: string
@@ -129,39 +99,14 @@ function bashDescription(backgroundEnabled: boolean, escalationModes: readonly S
     + 'it — but it does not forbid attempting or escalating other commands later.'
 }
 
-// ---------------------------------------------------------------------------
-// UI presentation (tool-owned). These shape how a UI (e.g. the ACP bridge)
-// renders a bash call's pending and completed states. They are display-only and
-// pure — a UI may call them during live streaming AND a session-log replay.
-// ---------------------------------------------------------------------------
-
 /**
- * Pending-state presentation for a `bash` call. The TITLE is the exact `command`
- * — a `kind: 'execute'` card is rendered as a terminal whose header label IS the
- * title, and an execute-kind card HIDES `rawInput` (Zed: `should_show_raw_input
- * = !is_terminal_tool`), so the command must BE the title to be seen. This
- * mirrors the reference ACP adapters (claude-agent-acp, codex-acp), which both
- * use the bare command as an execute tool's title. The model-written
- * `description` (a readable summary) rides as a `content` text block shown ABOVE
- * the card. (Note: claude-agent-acp DROPS the description in terminal mode and
- * shows only the card; surfacing it as a content block is a deliberate
- * divergence here — we keep the human summary visible alongside the card.)
- * `rawInput` still carries the bare command for non-execute UIs that DO render it.
- *
- * `terminal` marks the call so a capable UI renders a TERMINAL card — but ONLY a
- * FOREGROUND run is a terminal: a `run_in_background` call returns a task id
- * immediately (it never streams a terminal; its output is polled via
- * `task_output`), so it is NOT marked terminal and renders as an ordinary
- * execute card. For a foreground run the `terminal.cwd` (header) is the model
- * `workdir` when given — ABSOLUTE as-is, RELATIVE for the UI bridge to resolve
- * against the session cwd; when omitted the bridge fills the session workspace
- * cwd (this PURE presenter, args only, can't see it).
+ * Present foreground calls as terminals and background starts as generic cards.
+ * The command remains the title on both paths; foreground cwd is passed through
+ * for the bridge to resolve, while background descriptions remain card content.
  */
 type BashCallArgs = { command: string; description: string; workdir?: string; run_in_background?: boolean }
 
 function presentBashCall(args: BashCallArgs): GenericCallView | TerminalCallView {
-  // A background start is not an interactive terminal — a generic execute card
-  // with the command as rawInput and the description as a content block.
   if (args.run_in_background === true) {
     return {
       card: 'generic',
@@ -171,7 +116,6 @@ function presentBashCall(args: BashCallArgs): GenericCallView | TerminalCallView
       content: [{ type: 'text', text: args.description }],
     }
   }
-  // A foreground run is a terminal; an explicit workdir supplies its cwd.
   return {
     card: 'terminal',
     title: args.command,
@@ -189,13 +133,10 @@ function presentBashResult(args: unknown, result: ToolResult): ToolResultView |
   if (block === undefined || block.type !== 'text') return undefined
   const raw = block.text
   const isBackground = typeof args === 'object' && args !== null && (args as { run_in_background?: unknown }).run_in_background === true
-  // A background ack or an errored run is not a real terminal exit: render the
-  // fenced ```console fallback as generic content (no exit pill).
+  // Background acknowledgements and errors have no terminal exit status.
   if (isBackground || result.isError) {
     return { card: 'generic', content: [{ type: 'text', text: `\`\`\`console\n${raw.replace(/\n+$/, '')}\n\`\`\`` }] }
   }
-  // A finished foreground run supplies raw output and parsed exit status.
-  // The bridge derives the no-capability fenced fallback from `output`.
   return { card: 'terminal', output: raw, ...parseExitStatus(raw) }
 }
 
@@ -251,9 +192,7 @@ export function apply(ctx: Context, config: Config): void {
     }
   }
 
-  // The bash tool's cross-call HABIT, which the per-tool description cannot
-  // carry (it describes one call): the exit-code marker is only useful
-  // if the model actually checks it every time.
+  // Cross-call guidance belongs in the prompt rather than one-call schema prose.
   ctx.systemPrompt.section({
     name: 'tool:bash',
     order: 105,
@@ -291,12 +230,7 @@ export function apply(ctx: Context, config: Config): void {
     },
     async execute(args: BashToolArgs, exec) {
       validateBashArgs(args)
-      // `description` is display/logging metadata only (surfaced to UIs via
-      // the tool/call session event); it is intentionally NOT forwarded to
-      // ctx.bash and has no effect on execution.
-      // Default the workdir to the calling agent's session cwd so each ACP
-      // session runs in its own workspace (see resolveWorkdir); an explicit
-      // model workdir still wins.
+      // Description is display metadata; workdir defaults to the caller's session.
       const sandboxMode = args.sandbox_permissions !== undefined && args.justification !== undefined
         ? await approveEscalation(args.sandbox_permissions, args.justification, exec)
         : sessionOverride(exec)
@@ -308,27 +242,17 @@ export function apply(ctx: Context, config: Config): void {
         ...sandboxMode !== undefined ? { sandboxMode } : {},
       }
       if (args.run_in_background === true) {
-        // The schema omission is advertising, not enforcement — the arg
-        // validator deliberately allows undeclared keys, so a caller (or a
-        // model that has seen the parameter elsewhere) can still send it.
-        // A disabled deployment must refuse at execution time, loud.
+        // Undeclared keys are allowed, so schema omission also needs enforcement.
         if (!backgroundEnabled) {
           throw new Error('run_in_background is disabled for this deployment (enableRunInBackground: false)')
         }
-        // The generic runtime owns everything task-shaped; without it a task
-        // id would be uncollectable — fail loud with the fix, not a dangle.
         const tasks = ctx.get('tasks')
         if (tasks === undefined) {
           throw new Error('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
         }
-        // A step already cancelled must not spawn; after the id is returned
-        // the tool-call signal is deliberately NOT wired to the process
-        // (cancellation belongs to task_kill / owner cleanup), so the check
-        // happens here, once, instead of passing the signal to start().
+        // Reject pre-start cancellation; returned tasks use their own lifecycle.
         if (exec.signal?.aborted) throw new Error('command aborted')
-        // tasks.start preflights (surface fence, owner cleanup) BEFORE run()
-        // spawns anything, and cannot fail after — the process can never
-        // start without a collectable id.
+        // Task preflight finishes before the starter can spawn a process.
         const id = tasks.start({
           kind: 'bash',
           label: args.command,
diff --git a/packages/bash/tool-bash/src/render.ts b/packages/bash/tool-bash/src/render.ts
index 12b407f364..2ce36af593 100644
--- a/packages/bash/tool-bash/src/render.ts
+++ b/packages/bash/tool-bash/src/render.ts
@@ -15,7 +15,7 @@ function streamText(output: CollectedOutput): string {
 
 /**
  * Shape one finished run into the text the model sees: stdout, then a marked
- * stderr section, then exit-status markers. Non-zero exits are REPORTED, not
+ * 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.
@@ -40,23 +40,15 @@ export function renderResult(
   if (body.length === 0) body = '(no output)'
 
   const markers: string[] = []
-  // The sandbox marker precedes the exit-status markers so `[exit code: N]`
-  // stays the LAST line (exitStatus() anchors its parse there). Denial is a
-  // reported fact like timeout: the model decides how to react.
+  // Keep the exit marker last because parseExitStatus anchors there.
   if (result.sandbox?.denied) {
     markers.push(`[sandbox: file access denied under ${result.sandbox.mode} mode]`)
-    // The same-turn nudge lives at the decision point: only when this
-    // composition advertises the fields (a lever is never hinted that the
-    // schema does not offer), and inside the sandbox marker family so the
-    // exit-code marker stays the last line.
+    // Hint only when the composition exposes escalation, before the final exit marker.
     if (escalationModes.length > 0) {
       markers.push('[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]')
     }
   }
-  // Timeout is reported independently of how the process actually ended: a
-  // command can trap SIGTERM and exit 0 after our timer fired (e.g.
-  // `trap "exit 0" TERM; sleep 60`), giving timedOut:true / exitCode:0 /
-  // signal:null — the model must still see that the command was cut short.
+  // A command may trap SIGTERM and exit 0 after timeout; still report interruption.
   if (result.timedOut) markers.push(`[timed out after ${result.timeoutMs}ms]`)
   if (result.signal !== null) {
     markers.push(`[killed by signal: ${result.signal}]`)
diff --git a/packages/bash/tool-bash/tests/tools.spec.ts b/packages/bash/tool-bash/tests/tools.spec.ts
index f694a6f494..c09c14c459 100644
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -419,8 +419,7 @@ describe('background execution through the task runtime', () => {
   })
 
   it('a background task started by an agent is registered with that agent as owner', async () => {
-    // The fence SEMANTICS are pinned in dsh-tasks; this only pins that
-    // tool-bash forwards exec.agent as the registration's owner.
+    // The producer must forward exec.agent as the task owner.
     const ctx = await setupWithTasks()
     const agent = registerFakeAgent(ctx, 'sess-owner')
     const started = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true }, agent)
@@ -466,9 +465,7 @@ describe('background execution through the task runtime', () => {
   })
 
   it('never spawns the process when tasks.start preflight throws (no orphan, by construction)', async () => {
-    // TaskService WITHOUT any control surface: tasks.start preflights that
-    // fence BEFORE invoking the producer's run(), so the executor is never
-    // asked to spawn — there is no orphan to roll back.
+    // With no control surface, task preflight fails before the executor can spawn.
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
@@ -500,9 +497,7 @@ describe('background execution through the task runtime', () => {
     const parameters = ctx.tools.get('bash')!.parameters as { properties: Record<string, unknown> }
     expect('run_in_background' in parameters.properties).toBe(false)
 
-    // Schema omission is advertising, not enforcement: the arg validator
-    // allows undeclared keys, so a forced run_in_background must be REFUSED
-    // at execution time (review finding) — while foreground still works.
+    // Schema omission is advertising; execution must also enforce the opt-out.
     const forced = await call(ctx, 'bash', { command: 'echo hi', description: 'test command', run_in_background: true })
     expect(forced.isError).toBe(true)
     expect(text(forced)).toContain('run_in_background is disabled for this deployment')
diff --git a/packages/subagent/tool-subagent/README.md b/packages/subagent/tool-subagent/README.md
index 4ec1f10648..b125839d75 100644
--- a/packages/subagent/tool-subagent/README.md
+++ b/packages/subagent/tool-subagent/README.md
@@ -1,63 +1,51 @@
 # @deepseek-ai/dsh-tool-subagent
 
-The `subagent` tool lets the model delegate one self-contained task and collect the child's final output. It is a thin consumer of `ctx.subagents`; changing the configured provider changes the transport without changing the model-facing execution contract.
+The model-facing delegation tool over one configured `ctx.subagents` provider. Changing the provider changes transport without changing the execution contract.
 
-## Provider selection
+## Provider selection and lifecycle
 
-This plugin binds to **exactly one** provider (`Config.provider`). The model sees only `{ description, prompt, run_in_background? }` — there is no provider/type parameter in the schema. To expose more than one transport, load the plugin more than once, each bound to a different provider **and a distinct `toolName`** (the tool registry rejects a duplicate name, so a second load that kept the default `subagent` name would throw). Keeping selection in config (not the schema) is the deliberate split: the *service* holds a multi-provider registry; the *tool* picks one.
+Each plugin instance binds one `provider` to one `toolName`; the model receives no provider selector. Load another distinctly named instance to expose another transport. The tool registers only while its provider exists, avoiding sibling load-order and provider-reload dependencies. Its description follows `provider.inheritsParentContext`: fresh children require standalone prompts, while forked children already see completed parent turns.
 
-The description is derived from `provider.inheritsParentContext`: spawn and ACP tell the model to provide a standalone prompt, while fork says the child already sees completed conversation turns. The plugin follows `subagent/provider-added` and `subagent/provider-removed`, so concurrent Cordis plugin loading does not create a registration-order dependency.
+A foreground call passes the execution signal through startup and execution, awaits `run.result`, and always awaits `run.dispose()` before returning. Only `completed` returns final text; abort, refusal, token limit, and other failures become errored tool results without partial output.
 
-## Lifecycle
+With `run_in_background: true`, the tool registers the parent-owned task before starting the provider. A task-owned signal covers pending startup and the child after the starting call returns. `task_kill` and owner disposal abort it. Settlement awaits startup rollback or child disposal, then maps completed final text, abort to `killed`, and other failures to `failed`. The task has no incremental read; generic task tools own later status, collection, cancellation, and notices. See the [background subagent RFC](../../../docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md).
 
-Foreground `execute` passes the tool execution's abort signal when present, otherwise supplies an inert signal to satisfy the required `SubagentStartRequest.signal`. It awaits `ctx.subagents.start(...)`, then awaits `run.result` inside a `try/finally` that always calls `run.dispose()`. The selected signal therefore covers startup and live execution, while disposal guarantees quiescence on success, failure, and abort.
-
-A non-`completed` stop reason becomes an `isError` tool result; partial child output is never reported as success. With `run_in_background`, an independent task-owned signal covers both asynchronous startup and the ready child, while collection moves to the generic task tools.
+`toolFilter` changes the child's global tool layer but is not a parent-derived authority ceiling. See the [agent-scope security non-goal](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals).
 
 ## Config
 
 | Key | Meaning |
 |---|---|
-| `provider` (required) | The `ctx.subagents` provider name to start runs on (`spawn`, `fork`, `acp`, …). |
-| `toolName` | The model-facing tool name to register (default `subagent`). Set a distinct value per load when exposing multiple providers, e.g. `subagent` + `subagent_acp`. |
-| `enableRunInBackground` | Expose `run_in_background` in this instance's schema (default `true`). Disabled, the parameter is absent entirely AND a caller that forces the key anyway is refused at execution time (the arg validator allows undeclared keys) — delegation through this instance stays strictly synchronous. |
-| `agentOptions` | Default child agent options, currently including `model`. |
+| `provider` (required) | Provider name (`spawn`, `fork`, `acp`, ...). |
+| `toolName` | Model-facing name, default `subagent`; distinct for every loaded instance. |
+| `enableRunInBackground` | Exposes background mode, default `true`; disabling also rejects forced background calls. |
+| `agentOptions` | Default child options, currently including `model`. |
 | `persona` | Per-child persona; requires provider `persona` capability. |
-| `toolFilter` | Per-child global-tool restriction; requires provider `toolFilter` capability. |
-| `maxDepth` | Absolute delegation-depth cap; requires provider `depthLimit` capability. |
-
-## Foreground lifecycle (synchronous collect)
-
-`execute` awaits a ready run from the configured provider and then **awaits `run.result` inside a `try/finally` that always `dispose()`s the run** — the owned child agent/session is torn down on every path (success, error, abort), never leaked. The required request signal is the canonical cancellation path across startup and live execution. A non-`completed` stop reason (aborted/error/max-tokens/refusal) maps to an `isError` tool result rather than returning partial output as success.
-
-## Background delegation (a generic task)
-
-`run_in_background: true` refuses an already-aborted `exec.signal`, synchronously registers `{ kind: 'subagent', label: description, owner: parent, cancel, done }` with `ctx.tasks`, and returns `started background subagent task <id>`. The starter immediately calls async `ctx.subagents.start()` with an independent `AbortController`; `task_kill` and owner-scope teardown abort that signal whether startup is still pending or the child is ready. The task is final-output-only, and `done` settles only after startup rollback or `run.dispose()` reaches quiescence. Mapping: `runOutcome` turns `completed` into final output, `aborted` into `killed`, and other terminal reasons into `failed`; `settleRun` contains infrastructure and disposal failures. A missing task runtime fails loud. See the [background subagent tasks RFC](../../../docs/rfc/implemented/feature/2026-07-08-background-subagent-tasks.md).
-
-`toolFilter` changes the child's visible global tool layer; it is not a parent-derived authority ceiling. See the [agent-scope security non-goal](../../../docs/rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals).
+| `toolFilter` | Per-child global-tool restriction; requires `toolFilter` capability. |
+| `maxDepth` | Absolute delegation-depth cap; requires `depthLimit` capability. |
 
 ## Model Experience
 
-### Tool schemas
+### Tool schema
 
-**What the model sees**: While the configured provider exists, the model sees the generated default [`subagent` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent) under this instance's configured `toolName`. Fresh-context and inherited-context providers change the tool and `prompt` descriptions; `enableRunInBackground: true` adds `run_in_background` and its generic-task guidance.
+**What the model sees**: The generated default [`subagent` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-subagent) under this instance's configured name while its provider exists. Provider context inheritance changes the tool and prompt descriptions; enabled background mode adds `run_in_background`.
 
-**Token effect**: Fixed schema cost per parent request while mounted; each additional provider instance contributes one independently named schema.
+**Token effect**: Fixed schema cost per parent request; each provider instance adds one schema.
 
 ### Foreground result
 
-**What the model sees**: The parent tool call retains the task description and prompt. Success contains only the child's data-dependent final text; non-completed stop reasons and infrastructure failures become `Error: <message>`. Intermediate child steps never enter the parent.
+**What the model sees**: The call retains the description and prompt. Success contains only the child's final text; other outcomes become `Error: <message>`. Intermediate child steps stay out of the parent.
 
-**Token effect**: The prompt and final result remain in parent history until compaction; child working context is paid only in the child.
+**Token effect**: The prompt and result remain in parent history until compaction; child working context remains in the child.
 
 ### Background task result
 
-**What the model sees**: Start returns exactly `started background subagent task <id>`. The generic task control surface owns later status, final output, cancellation responses, and completion notices; the child still contributes only its final text on successful collection.
+**What the model sees**: Start returns exactly `started background subagent task <id>`. The generic task surface provides later status, final output, cancellation responses, and notices.
 
-**Token effect**: The start acknowledgement is small and retained. Final output and generic task status enter parent history only when collected or injected by `dsh-tool-tasks`.
+**Token effect**: The acknowledgement is retained; final output enters parent history only when collected or injected.
 
 ## Known Limitations and Deferred Work
 
-- **Background runs expose final output only** — intermediate child steps remain in the child session and cannot be streamed through `task_output`.
-- **Duplicate `toolName` across waiting loads is detected late** (`TODO(subagent-dup-toolname)`) — two instances waiting on providers collide only when a provider arrives; config-time detection needs a cross-fiber registry of intended names.
-- **Child policy is fixed per tool registration** — model, persona, tool filter, and depth cap come from plugin config; another policy requires another distinctly named tool.
+- **Background runs expose final output only** — intermediate child steps stay in the child session.
+- **Duplicate names across waiting instances are detected late** (`TODO(subagent-dup-toolname)`) — preventing provider-registration rollback requires a registry of intended names.
+- **Child policy is fixed per instance** — another model, persona, tool filter, or depth cap requires another distinctly named tool.
diff --git a/packages/subagent/tool-subagent/src/index.ts b/packages/subagent/tool-subagent/src/index.ts
index ba5cf4a618..cee354bdfe 100644
--- a/packages/subagent/tool-subagent/src/index.ts
+++ b/packages/subagent/tool-subagent/src/index.ts
@@ -1,45 +1,9 @@
 /**
- * The model-facing `subagent` tool: delegate a task to a child agent and return
- * its final output. Pure schema + lifecycle shaping — every transport concern
- * lives behind the `ctx.subagents` provider registry
- * (`@deepseek-ai/dsh-subagent`), so an in-process, ACP, or future A2A backend
- * swaps in without touching what the model sees.
- *
- * Provider selection is config, not model-facing: this plugin is bound to
- * EXACTLY ONE provider name (`Config.provider`). To expose more than one
- * transport, load the plugin more than once, each bound to a different provider
- * — there is no provider/type parameter in the model-facing schema. The model
- * sees only `{ description, prompt }` (plus `run_in_background` when enabled).
- *
- * The tool DESCRIPTION is derived from the bound provider's conversation-history
- * descriptor ({@link providerWording}): a fresh-conversation provider (spawn,
- * ACP) gets the standalone-prompt wording, while a seeded-conversation provider
- * (fork) tells the model the child already sees the conversation's completed
- * turns. This descriptor says nothing about Cordis scope, services, tools, or
- * authority. The tool MIRRORS the
- * provider's lifecycle via `subagent/provider-added`/`-removed` — it registers
- * when the provider is (or becomes) available and unregisters when the
- * provider goes away — so no load-order requirement exists and an HMR reload
- * of the backend re-derives the wording from the fresh provider.
- *
- * FOREGROUND collection is synchronous: `execute` starts a run and awaits
- * `run.result` inside a `try/finally` that always disposes the run, so the
- * owned child agent/session is torn down on every path (success, error, abort)
- * and never leaks as a live idle child. A non-`completed` stop reason maps to an
- * `isError` tool result (by throwing) rather than returning partial output as
- * success.
- *
- * BACKGROUND delegation (`run_in_background: true`, exposed only when this
- * instance's `enableRunInBackground` config allows) is a generic background
- * TASK: the run is registered with `ctx.tasks` (kind `subagent`, final-output
- * only — the child session remains the detailed trace) and collected/stopped
- * through the generic `task_output`/`task_list`/`task_kill` tools. The
- * tool-call abort signal is deliberately NOT wired to a background child:
- * after the id is returned the parent step may end while the child works —
- * cancellation belongs to `task_kill` and the owner-disposal cleanup. The
- * task's `done` settles only after `run.dispose()` (child quiescence), which
- * is what makes owner-disposal cleanup an actual no-leak guarantee.
- *
+ * Model-facing delegation through one configured `ctx.subagents` provider.
+ * Provider lifecycle controls tool registration and context-sensitive schema
+ * wording. Foreground calls always dispose the run after collection; background
+ * calls use an independent cancellation signal and settle a final-output task
+ * only after child disposal.
  * @module @deepseek-ai/dsh-tool-subagent
  */
 
@@ -60,42 +24,29 @@ export interface Config {
   /** The `ctx.subagents` provider name to start runs on (e.g. `spawn`, `acp`). */
   provider: string
   /**
-   * The model-facing tool name to register (default `subagent`). To expose more
-   * than one transport, load this plugin once per provider — each load MUST set
-   * a distinct `toolName` (the tool registry rejects a duplicate name), e.g.
-   * `{ provider: 'spawn', toolName: 'subagent' }` and
-   * `{ provider: 'acp', toolName: 'subagent_acp' }`.
+   * Model-facing tool name (default `subagent`). Each loaded instance must use
+   * a distinct name.
    */
   toolName?: string
   /**
-   * Expose `run_in_background` in this instance's schema (default true).
-   * Disabled, the parameter is absent entirely — schema and capability never
-   * disagree; delegation through this instance stays strictly synchronous.
-   * Backgrounding also needs the `ctx.tasks` runtime at call time; a missing
-   * one fails the call loud with the load-these-packages message.
+   * Expose `run_in_background` (default true). Disabled instances omit the
+   * parameter and reject forced background calls.
    */
   enableRunInBackground?: boolean
   /**
-   * Default per-child agent options (model) applied to every spawned child.
-   * Omitted fields fall back to the child loop's own defaults.
+   * Agent options applied to every child; omitted fields use child-loop defaults.
    */
   agentOptions?: AgentOptions
   /**
-   * Per-child persona applied to every child this tool spawns: a scoped
-   * `deployment:persona` section shadowing the deployment's persona for the
-   * child alone. Requires the bound provider's `persona` capability
-   * (in-process backends support it; a request against one that doesn't is
-   * rejected at start). Omitted ⇒ the child renders the deployment persona.
+   * Per-child persona that shadows `deployment:persona`. Requires the
+   * provider's `persona` capability; omission preserves the deployment persona.
    */
   persona?: string
   /**
-   * Tool scoping applied to every child this tool spawns (see
-   * `SubagentStartRequest.toolFilter`): the named global tools vanish from
-   * the child's prompt AND refuse to execute. Requires the provider's
-   * `toolFilter` capability. Unknown names fail the spawn loudly. Note the
-   * child otherwise sees every global tool — including this delegation tool
-   * itself; `deny`-listing it (or setting `maxDepth`) is how a deployment
-   * bounds recursion.
+   * Tool filter applied to every child. Filtered tools disappear from its
+   * prompt and reject execution. Requires the provider's `toolFilter`
+   * capability; unknown names fail startup. Children otherwise see this tool,
+   * so deny it or set `maxDepth` to bound recursion.
    */
   toolFilter?: {
     /** Global tool names the child keeps; everything else is removed. */
@@ -104,12 +55,8 @@ export interface Config {
     deny?: string[]
   }
   /**
-   * Recursion cap applied to every child this tool spawns (see
-   * `SubagentStartRequest.maxDepth`): a spawn whose child would sit deeper
-   * than this in the delegation tree is rejected. Requires the provider's
-   * `depthLimit` capability. Must be a non-negative safe integer and is
-   * validated when the plugin loads. Omitted ⇒ unbounded (bound it in
-   * deployments that expose this tool to children).
+   * Maximum child depth. Requires the provider's `depthLimit` capability and a
+   * non-negative safe integer. Omission is unbounded.
    */
   maxDepth?: number
 }
@@ -118,16 +65,12 @@ export const Config: z<Config> = z.object({
   provider: z.string().required(),
   toolName: z.string().default('subagent'),
   enableRunInBackground: z.boolean().default(true),
-  // Omitted-object discipline (see the toolFilter note below): without the
-  // forced default an omitted `agentOptions` materializes `{}`, which reads as
-  // present — the request would carry `agentOptions: {}` and the presence
-  // check in execute() could never be false through config.
+  // Prevent Schemastery from materializing omitted agentOptions as `{}`.
   agentOptions: z.object({
     model: z.string(),
   }).default(undefined as unknown as { model: string }),
   persona: z.string(),
-  // Schemastery otherwise materializes omitted objects and nested arrays as `{ allow: [] }`, which
-  // silently means deny all. Preserve omission while retaining an explicit empty allow-list.
+  // Preserve omission; Schemastery's `{ allow: [] }` default would deny every tool.
   toolFilter: z.object({
     allow: z.array(z.string()).default(undefined as unknown as string[]),
     deny: z.array(z.string()).default(undefined as unknown as string[]),
@@ -137,9 +80,8 @@ export const Config: z<Config> = z.object({
 
 /**
  * Flatten a child's final output blocks to text for the tool result. The child
- * may return non-text blocks; this cut surfaces the text content (the common
- * case) and drops the rest, which is acceptable for a synchronous summary —
- * the structured path (`outputSchema`) is the channel for non-text results.
+ * may return non-text blocks; this path returns only text. Structured results
+ * use `outputSchema`.
  */
 function outputText(blocks: ContentBlock[]): string {
   return blocks
@@ -169,15 +111,10 @@ function stopReasonError(result: SubagentResult): string | undefined {
 }
 
 /**
- * Map a settled subagent result onto the generic task-outcome vocabulary:
- * `completed` carries the final text as the task's idempotent output;
- * `aborted` is the task-level `killed`; everything else — `error`,
- * `max-tokens`, `refusal`, and unknown merge-extensible reasons — is `failed`
- * with the reason as the status-line detail (partial output is NOT reported
- * as output, mirroring the synchronous path's report-the-reason rule).
- * Exported for tests.
- * @param result - the child's terminal result.
- * @returns the outcome for the `ctx.tasks` registration.
+ * Map a child result to the task outcome: completed carries final text,
+ * aborted is killed, and every other reason is failed without partial output.
+ * @param result - child terminal result.
+ * @returns outcome for the `ctx.tasks` registration.
  */
 export function runOutcome(result: SubagentResult): TaskOutcome {
   switch (result.stopReason) {
@@ -189,23 +126,17 @@ export function runOutcome(result: SubagentResult): TaskOutcome {
     case 'max-tokens':
     case 'refusal':
       return { status: 'failed', detail: result.stopReason }
-    // Merge-extensible union: an unknown terminal reason is a failure with
-    // the raw reason as detail, never partial output as success.
+    // Merge-extensible reasons remain failures with their raw detail.
     default:
       return { status: 'failed', detail: String(result.stopReason) }
   }
 }
 
 /**
- * Settle a background run at QUIESCENCE: await the child's result, ALWAYS
- * dispose the run (the owned child agent/session is released on every path),
- * and only then report the mapped outcome — so the task registry's `done`,
- * and therefore owner-disposal cleanup, cannot resolve before the child is
- * actually gone. A rejected `run.result` or `run.dispose()` reports `failed`
- * with the error as detail rather than rejecting the producer contract; when
- * both fail, both independent failures are preserved. Exported for tests.
- * @param run - the live background run to settle and release.
- * @returns the task outcome, after the run's resources are released.
+ * Await the child result, dispose the run, then return its task outcome. Result
+ * and disposal failures become `failed`; when both fail, both details survive.
+ * @param run - live run to settle and release.
+ * @returns outcome after child resources are released.
  */
 export async function settleRun(run: SubagentRun): Promise<TaskOutcome> {
   let outcome: TaskOutcome
@@ -239,7 +170,7 @@ export function providerWording(inheritsConversation: boolean): { description: s
   if (inheritsConversation) {
     return {
       description:
-        'Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all '
+        'Delegate a task to a subagent that inherits this conversation: a child agent seeded with all '
         + 'completed turns so far (it does not see the current in-flight turn), returning only its final '
         + 'result. Use this when the subtask builds on this conversation\'s context — a follow-up analysis, '
         + 'a review, a continuation — without consuming this conversation\'s context for the work itself. '
@@ -262,7 +193,6 @@ export function providerWording(inheritsConversation: boolean): { description: s
   }
 }
 
-/** Build the provider request shared by foreground and background execution. */
 function startRequest(config: Config, prompt: string, parent: Agent, signal: AbortSignal): SubagentStartRequest {
   return {
     prompt: [{ type: 'text', text: prompt }],
@@ -275,7 +205,7 @@ function startRequest(config: Config, prompt: string, parent: Agent, signal: Abo
   }
 }
 
-/** Settle a possibly-pending provider start through the task outcome contract. */
+/** Settle pending startup without rejecting the task producer contract. */
 async function settleStart(start: Promise<SubagentRun>, signal: AbortSignal): Promise<TaskOutcome> {
   try {
     return await settleRun(await start)
@@ -287,23 +217,14 @@ async function settleStart(start: Promise<SubagentRun>, signal: AbortSignal): Pr
 }
 
 export function apply(ctx: Context, config: Config): void {
-  // Keep misconfiguration at plugin load even when a caller invokes apply()
-  // directly and bypasses Schemastery's natural/max metadata.
+  // Direct apply() bypasses Schemastery's numeric constraints.
   assertSubagentMaxDepth(config.maxDepth)
-  // Misconfiguration fails loud AT LOAD (the check is self-contained): an
-  // explicit `toolFilter: {}` would otherwise pass the capability gate and
-  // kill every delegation later, in the child-setup `restrict({})` throw.
+  // Reject an empty explicit filter at load instead of failing every delegation.
   if (config.toolFilter !== undefined && config.toolFilter.allow === undefined && config.toolFilter.deny === undefined) {
     throw new Error('tool-subagent: `toolFilter` is configured but names neither `allow` nor `deny` — remove the key or fill the filter')
   }
-  // The tool MIRRORS its provider's lifecycle instead of assuming load order:
-  // the cordis Loader starts sibling entries concurrently, so "backend listed
-  // first in cordis.yml" does not guarantee "provider registered first", and
-  // an HMR reload of the backend replaces the provider while this fiber stays
-  // loaded. Register the tool when the bound provider is (or becomes)
-  // available — deriving the wording from THAT provider — and unregister it
-  // when the provider goes away, so the description can never outlive or
-  // predate the provider it describes.
+  // Mirror provider lifecycle because sibling load order and HMR replacement
+  // can change provider availability while this fiber remains active.
   let disposeTool: (() => void) | undefined
   const mount = (provider: SubagentProvider): void => {
     const wording = providerWording(provider.inheritsParentContext)
@@ -311,7 +232,7 @@ export function apply(ctx: Context, config: Config): void {
     disposeTool = ctx.tools.register(defineTool({
       name: config.toolName ?? 'subagent',
       description: wording.description + (backgroundEnabled
-        ? ' Set `run_in_background: true` to get a task id immediately and keep working; collect the final answer with `task_output` (wait: true when you are blocked on it) and stop it with `task_kill`.'
+        ? ' Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.'
         : ''),
       parameters: {
         description: {
@@ -327,42 +248,31 @@ export function apply(ctx: Context, config: Config): void {
         ...backgroundEnabled ? {
           run_in_background: {
             type: 'boolean' as const,
-            description: 'Run the subagent as a background task and return a task id immediately (collect with task_output, stop with task_kill).',
+            description: 'Run as a background task and return its id; collect with task_output or stop with task_kill.',
           },
         } : {},
       },
       async execute(args, exec): Promise<ContentBlock[]> {
         const parent = exec.agent
         if (!parent) {
-          // The loop sets `exec.agent` for every model-driven call; its absence
-          // means a non-agent caller invoked the tool directly, which has no
-          // parent to attribute the child to. Fail loud rather than guess.
+          // Non-agent callers provide no parent for delegation ownership.
           throw new Error('subagent tool requires a calling agent (exec.agent was undefined)')
         }
 
         if (args.run_in_background === true) {
-          // The schema omission is advertising, not enforcement — the arg
-          // validator deliberately allows undeclared keys, so a caller (or a
-          // model that has seen the parameter elsewhere) can still send it.
-          // A disabled instance must refuse at execution time, loud.
+          // The validator permits undeclared keys, so schema omission also needs
+          // execution-time enforcement.
           if (!backgroundEnabled) {
             throw new Error('run_in_background is disabled for this tool instance (enableRunInBackground: false)')
           }
-          // The generic runtime owns everything task-shaped; without it a task
-          // id would be uncollectable — fail loud with the fix, not a dangle.
           const tasks = ctx.get('tasks')
           if (tasks === undefined) {
             throw new Error('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
           }
-          // A step already cancelled must not spawn a child. After the id is
-          // returned the tool-call signal is deliberately NOT wired to the run;
-          // an independent controller lets task_kill/owner disposal cancel both
-          // a pending async start and a ready child through the seam's one
-          // canonical cancellation channel.
+          // Reject cancellation before spawning; after return, the task-owned
+          // signal covers both pending startup and the ready child.
           if (exec.signal?.aborted) throw new Error('subagent delegation aborted')
-          // tasks.start preflights (surface fence, owner cleanup) BEFORE run()
-          // spawns the child, and cannot fail after — a child can never start
-          // without a collectable id.
+          // Task preflight finishes before the starter can spawn a child.
           const id = tasks.start({
             kind: 'subagent',
             label: args.description,
@@ -378,8 +288,7 @@ export function apply(ctx: Context, config: Config): void {
                   controller.abort(reason ?? 'background subagent task killed')
                 },
                 done: settleStart(start, controller.signal),
-                // No readOutput: a subagent task is final-output-only — the
-                // child session remains the detailed trace.
+                // No readOutput: the child session owns intermediate detail.
               }
             },
           })
@@ -399,29 +308,22 @@ export function apply(ctx: Context, config: Config): void {
           const result = await run.result
           const error = stopReasonError(result)
           if (error !== undefined) {
-            // Map a non-clean finish to an isError result (the registry turns a
-            // throw into an isError). Report the reason, not partial output.
+            // The registry converts this throw to isError; partial output is not success.
             throw new Error(error)
           }
           return [{ type: 'text', text: outputText(result.output) }]
         } finally {
-          // Always reach child quiescence — never leak a live idle child/session.
+          // Dispose before returning so no child session outlives the call.
           await run.dispose()
         }
       },
     }))
   }
 
-  // Listeners first, then the presence check: both run synchronously, so no
-  // registration can slip between them; the `disposeTool === undefined` guard
-  // makes a same-tick added-event after a successful mount a no-op.
+  // Register listeners before checking presence so no synchronous change is missed.
   // TODO(subagent-dup-toolname): two WAITING fibers configured with the same
-  // toolName collide only when their provider finally arrives — the duplicate
-  // tool-name throw then propagates through `subagent/provider-added` and
-  // rolls back the PROVIDER registration, so an invalid config blasts the
-  // backend's fiber instead of the misconfigured tool's. Config-time detection
-  // would need a cross-fiber registry of intended tool names; revisit if a
-  // real deployment ever hits it.
+  // toolName collide when their provider appears, and the duplicate-name throw
+  // rolls back the provider registration. Add an intent registry if this occurs.
   ctx.on('subagent/provider-added', (provider) => {
     if (provider.name === config.provider && disposeTool === undefined) mount(provider)
   })
@@ -434,9 +336,7 @@ export function apply(ctx: Context, config: Config): void {
   if (present !== undefined) {
     mount(present)
   } else {
-    // Not an error: the backend's fiber may activate after this one.
-    // The tool appears the moment the provider registers; a typo'd provider
-    // name shows up as this note plus a tool that never materializes.
+    // A backend fiber may activate later; a misspelled provider remains visible in this log.
     ctx.logger.info(`subagent provider "${config.provider}" not registered yet; the "${config.toolName ?? 'subagent'}" tool will register when it appears`)
   }
 }
diff --git a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
index 6a86d808e0..9a5f369f8b 100644
--- a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
+++ b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
@@ -81,7 +81,7 @@ describe('dsh-tool-subagent', () => {
     expect(schema!.description).not.toContain('task_output')
   })
 
-  it('refuses a forced run_in_background at execution time when the instance disables it (review finding)', async () => {
+  it('refuses a forced run_in_background at execution time when the instance disables it', async () => {
     // Schema omission is advertising, not enforcement: the arg validator
     // allows undeclared keys, so the opt-out must also hold in execute().
     const ctx = await setup({ provider: 'mock', enableRunInBackground: false })
@@ -253,7 +253,7 @@ describe('dsh-tool-subagent', () => {
     // Backend reloads with a DIFFERENT conversation-history descriptor: the wording is re-derived
     // from the fresh provider, not served stale from the first mount.
     await ctx.plugin(mock, { name: 'mock', inheritsParentContext: true })
-    expect(ctx.tools.schemas().find(s => s.name === 'subagent')!.description).toContain('INHERITS this conversation')
+    expect(ctx.tools.schemas().find(s => s.name === 'subagent')!.description).toContain('inherits this conversation')
   })
 
   it('the tool PLUGIN fiber owns its lifecycle listeners: disposal unmounts, and a disposed fiber never zombie-mounts', async () => {
@@ -303,10 +303,10 @@ describe('dsh-tool-subagent', () => {
     expect(props['prompt']!.description).toContain('include everything it needs')
   })
 
-  it('derives fork-shaped wording from a seeded-conversation provider (the description stops lying)', async () => {
+  it('derives inherited-context wording from a seeded-conversation provider', async () => {
     const ctx = await setup({ provider: 'mock', toolName: 'subagent' }, { inheritsParentContext: true })
     const schema = ctx.tools.schemas().find(s => s.name === 'subagent')!
-    expect(schema.description).toContain('INHERITS this conversation')
+    expect(schema.description).toContain('inherits this conversation')
     expect(schema.description).not.toContain('does not see this conversation')
     const props = (schema.parameters as { properties: Record<string, { description: string }> }).properties
     expect(props['prompt']!.description).toContain('completed turns')
@@ -711,8 +711,7 @@ describe('dsh-tool-subagent background mode', () => {
   })
 
   it('forwards task_kill reasons through the run signal (and defaults one when absent)', async () => {
-    // A provider whose runs settle only on signal abort — the mock settles on a
-    // microtask, too fast to observe a LIVE kill through the real tools.
+    // Use a provider that remains live until its signal is aborted.
     const ctx = await backgroundSetup({ provider: 'mock', agentOptions: { model: 'child-model' } })
     const parent = ownerAgent(ctx, 'sess-parent')
     const cancels: (string | undefined)[] = []
@@ -736,9 +735,7 @@ describe('dsh-tool-subagent background mode', () => {
         }
       },
     })
-    // Direct apply (schema bypass): schemastery would default agentOptions to
-    // an (truthy) empty object — the raw config exercises the omitted branch
-    // on the background start request.
+    // Direct apply preserves omitted agentOptions instead of applying schema defaults.
     tool.apply(ctx, { provider: 'hanging', toolName: 'subagent_hang' })
 
     const startOne = await ctx.tools.execute({ callId: CallId('h1'), name: 'subagent_hang', arguments: { description: 'one', prompt: 'p', run_in_background: true }, agent: parent })
@@ -810,9 +807,7 @@ describe('dsh-tool-subagent background mode', () => {
 
 describe('background preflight failure (no orphaned child, by construction)', () => {
   it('never starts the child when tasks.start preflight throws', async () => {
-    // TaskService is loaded but NO control surface is attached: tasks.start
-    // preflights that fence BEFORE invoking the producer's run(), so the
-    // provider is never asked to spawn — there is no orphan to roll back.
+    // With no control surface, task preflight fails before the provider can spawn.
     const ctx = await setup({ provider: 'mock' })
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(TaskService)
diff --git a/packages/tasks/README.md b/packages/tasks/README.md
index e2221dce64..12e8f41a59 100644
--- a/packages/tasks/README.md
+++ b/packages/tasks/README.md
@@ -1,10 +1,10 @@
 # tasks/ — background task capability family
 
-The shared background-task runtime: ONE home for task ids, owner isolation, polling, cancellation, wait, and completion notification, so bash, subagents, and every future long-running tool expose the same model-facing habit instead of cloning a private task protocol each. Rationale and the full design: [the background-task-runtime RFC](../../docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md).
+The shared home for background-task ids, owner isolation, reads, cancellation, waiting, and completion notices. Bash, subagents, and future long-running tools use one model-facing protocol. See the [background-task runtime RFC](../../docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md).
 
 | Package | ctx key | Role |
 |---|---|---|
 | [`tasks`](tasks/README.md) (`@deepseek-ai/dsh-tasks`) | `ctx.tasks` | The registry service: branded `<kind>-N` ids, owner-fenced read/kill/wait/list, settlement bookkeeping, the awaited owner-cleanup path, and the `attachSurface` misconfiguration fence |
 | [`tool-tasks`](tool-tasks/README.md) (`@deepseek-ai/dsh-tool-tasks`) | — | The model-facing control surface: `task_output`, `task_list`, `task_kill`, the completion-notice injection, and the background-habit prompt section |
 
-The split is the state/surface boundary: the registry holds task state (an HMR reload of any tool plugin never orphans or kills a running task), while the tool surface is stateless presentation. Producers (`dsh-tool-bash`, `dsh-tool-subagent`) hand their work to `ctx.tasks.start` (preflight, then the producer's starter, then an atomic commit) and keep their own execution concerns; whether a producer exposes `run_in_background` is that producer's own `enableRunInBackground` config, never rewritten by this family.
+The registry owns state across producer or surface reloads; the tool package owns presentation. Producers register execution hooks through `ctx.tasks.start` and own whether their config exposes `run_in_background`.
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index f146910516..e9ddf43256 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -1,35 +1,34 @@
 # @deepseek-ai/dsh-tasks
 
-The background task registry (`ctx.tasks`): a runtime-global, CONCRETE service (no interface/implementation split — one sensible in-process implementation exists; a durable job backend would own that extraction) that gives every long-running tool the same ids, isolation, and lifecycle.
+The process-local background task registry (`ctx.tasks`). It gives long-running producers shared ids, owner isolation, reads, cancellation, waiting, notices, and cleanup. The service is concrete; a durable backend can introduce an interface when its different lifecycle is specified.
 
 ## Service API
 
-- `start(spec): TaskId` — declare-then-execute: the producer hands identity (`kind` — also the id prefix — `label`, optional `owner: Agent`) plus `run()`, the starter that returns the work's `TaskHooks` (`cancel(reason?)`, `done: Promise<TaskOutcome>` settling at QUIESCENCE and never rejecting, optional `readOutput()` for stream kinds; absence = final-output-only). Every check that can fail — the control-surface fence (the loud guard against a deployment exposing `run_in_background` with no way to collect or stop the work), validation, the owner-cleanup attach — runs BEFORE `run()` starts the actual work, and nothing can fail after it returns: work started without a collectable id is structurally impossible, not a producer rollback obligation.
-- `get(id, caller?)` / `list(caller?)` — non-consuming snapshots; `list` returns only caller-owned plus unowned tasks (a global listing would leak foreign labels).
-- `read(id, caller?): TaskRead` — stream kinds consume the per-task cursor (v1's single intended reader is the owning model — a non-consuming multi-reader surface would be a cursor/snapshot API extension, not a `read` change); final kinds read the terminal output idempotently.
-- `kill(id, caller?, reason?)` — `'requested'` (live task: producer `cancel` runs first — a throw fails the kill loud and leaves the task untouched — then `stopping`) or `'already-terminal'`. Every successful kill marks the task `reported` (the killer saw the end → completion notice suppressed).
-- `wait(id, timeoutMs, caller?, signal?)` — resolves with the terminal snapshot (marked `reported`), or the live snapshot at timeout; an aborted signal rejects the WAIT only — unless the task already settled, in which case the wait still resolves and delivers the terminal snapshot (settlement suppressed the completion notice on this waiter's behalf, so rejecting would leave the finish both unreported and un-noticed). Timing is a [`dsh-timeout`](../../util/timeout/README.md) `deadline()` scoped to the `TASK_WAIT_TIMEOUT` code, so a nested foreign deadline never misreads as a wait timeout; timeout and abort detach their settlement resolver immediately, keeping retention bounded while the task remains live.
-- `onTaskDone(listener)` — exactly once per terminal task record, with the snapshot plus its exact lifecycle owner (or `undefined`); effect-scoped, contains synchronous throws and returned promise rejections without awaiting listener work, silent after service disposal.
-- `attachSurface(name)` — declares a control surface exists (the model tools, or a deployment's custom surface); effect-scoped.
+- `start(spec): TaskId` validates the control surface, spec, and exact live owner before calling the producer's `run()` once. A starter throw leaves nothing registered; successful return commits without another failable step.
+- `get(id, caller?)` and `list(caller?)` return non-consuming snapshots. Listing includes only caller-owned and unowned tasks.
+- `read(id, caller?)` consumes the single cursor for stream tasks and reads terminal output idempotently for final-output tasks.
+- `kill(id, caller?, reason?)` invokes producer cancellation before changing status. A cancellation throw leaves the task running; success changes it to `stopping` and marks terminal delivery reported.
+- `wait(id, timeoutMs, caller?, signal?)` returns a terminal snapshot or the live snapshot at timeout. Aborting stops only the wait; settlement wins once it has committed terminal delivery to that waiter.
+- `onTaskDone(listener)` observes each terminal record with the exact owner. Listener throws and rejections are contained; listener work is not awaited.
+- `attachSurface(name)` declares a control surface for its effect lifetime. `start()` fails before producer execution when none is attached.
 
-Every read/kill/wait/get compares the task's owner session (`owner.session.header.id`) with the caller's and rejects a foreign one — ids are predictable (`bash-1`), so the fence, not id secrecy, is the isolation boundary.
+Owned access compares the task's `SessionId` with the caller's. Ids such as `bash-1` are predictable, so this fence is the boundary. Unowned tasks are open to callers and last until service disposal.
 
 ## Lifecycle
 
-- Registrations are NOT effect-scoped to the registering fiber: tasks belong to their owning agent + producing backend, so producer/surface HMR reloads never touch them.
-- An owned task retains the exact live `Agent` instance validated at start and attaches one awaited cleanup through `owner.ctx`: agent-scope disposal selects only that instance's tasks, cancels them, awaits contract-compliant producers to quiescence, and drops their snapshots. Reused agent/session ids cannot make an old cleanup sweep replacement work. If a teardown cancel throws, it force-fails the record and logs that the underlying work may be orphaned rather than deadlocking `AgentHandle.dispose()`.
-- Service disposal closes the listener registry first, applies the same cancellation rule to every live task, awaits terminal records, then detaches its effects from still-live agent scopes so a reloaded tasks service is not retained until those agents exit.
-- A producer whose `cancel` returns but never causes `done` to settle remains indistinguishable from a slow stop and can stall teardown; solving that residual requires an explicit bounded-lifetime or forced-disposal design.
+Tasks belong to their owner and backend, not the producer tool fiber, so producer and surface reloads do not stop them. The first task for an owner attaches one awaited effect to the exact `Agent` scope. Owner disposal cancels that object's tasks, awaits producer quiescence, and removes their snapshots; reused agent or session ids cannot redirect an old cleanup.
+
+Service disposal closes listeners, cancels all live tasks, awaits their records, and detaches effects from surviving owner scopes. If teardown cancellation throws, the service force-fails the record and warns that work may be orphaned instead of deadlocking. A cancellation that returns but never settles `done` remains indistinguishable from a slow stop and can stall teardown.
+
+See the [task type catalog](../../../docs/core-data-structures/tasks.md) and [runtime RFC](../../../docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md).
 
 ## Model Experience
 
-Indirectly, through `dsh-tool-tasks` and producer plugins, which render task ids, output, status, and completion notices.
+Indirectly, through producer plugins and [`dsh-tool-tasks`](../tool-tasks/README.md), which render task ids, output, status, cancellation, and completion notices.
 
 ## Known Limitations and Deferred Work
 
-- **Tasks are process-local** — durable or cross-restart execution is deferred.
-- **Stream output has one consuming cursor** — non-consuming observation and multiple independent readers require a separate cursor/snapshot API.
-- **Foreground work cannot be promoted** — producers must choose foreground or background before execution starts.
-- **A silently ineffective producer cancel can stall teardown** — the runtime can force-settle an explicit cancel throw, but cannot distinguish a slow stop from a cancel that returned without stopping work.
-
-See the [runtime RFC](../../../docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) § Alternatives for the deferred designs.
+- **Tasks are process-local** — durable or cross-restart execution needs a separate lifecycle.
+- **Stream output has one consuming cursor** — independent observers need a cursor or snapshot API.
+- **Foreground work cannot be promoted** — producers choose foreground or background before starting.
+- **A silently ineffective cancel can stall teardown** — only an explicit throw can be force-failed safely.
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index 68a36d8c0c..68300a7079 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -1,32 +1,11 @@
 /**
- * The background task registry (`ctx.tasks`): ONE home for the semantics every
- * long-running tool needs — branded task ids, owner-scoped isolation, status
- * snapshots, incremental/final output reads, cancellation, wait-for-terminal,
- * completion listeners, and the awaited owner-cleanup path. Producers
- * (`dsh-tool-bash` background commands, `dsh-tool-subagent` background
- * delegations, future long-running tools) hand their work to
- * {@link TaskService.start} — preflight, then the producer's starter, then an
- * atomic commit — and keep their own execution concerns; the
- * model-facing control surface (`@deepseek-ai/dsh-tool-tasks`) drives the
- * generic read/list/kill/wait operations.
- *
- * A CONCRETE service, not an interface/implementation seam pair: there is one
- * sensible in-process implementation today, and the capability-seam convention
- * says not to split preemptively (see the background-task-runtime RFC).
- *
- * Cross-session isolation lives IN the registry: task ids are runtime-global
- * and predictable (`bash-1`, `subagent-1`), so every read/kill/wait compares
- * the task's owner session against the caller and rejects a foreign one —
- * every surface gets the fence for free instead of re-implementing it.
- *
- * Task registrations are NOT effect-scoped to the registering fiber: a task
- * belongs to its owning agent and producing backend, not to the tool plugin
- * whose call started it, so an HMR reload of a producer or of the control
- * surface never orphans or kills a running task. The registry's own disposal
- * cancels every live task and awaits contract-compliant producers to
- * quiescence. If a teardown cancel throws, the registry force-fails its record
- * to avoid deadlock and logs that the underlying work may be orphaned.
+ * The in-process background task registry (`ctx.tasks`). It owns task ids,
+ * session-scoped access, lifecycle state, completion listeners, and owner
+ * cleanup while producers retain their execution resources.
  *
+ * Registrations outlive producer and control-surface fibers. Agent or service
+ * disposal cancels live work and awaits compliant producers; a throwing
+ * teardown cancel force-fails only the record and reports a possible orphan.
  * @module @deepseek-ai/dsh-tasks
  */
 
@@ -53,12 +32,7 @@ declare module 'cordis' {
   }
 }
 
-/**
- * The `dsh-timeout` code stamped on a {@link TaskService.wait} deadline's
- * `TimeoutReason`. A wait timeout only ends the WAIT (the task keeps running
- * and the live snapshot is returned) — scoping `timeoutOf` to this code keeps
- * a foreign (outer, nested) deadline's timeout from being misread as ours.
- */
+/** Timeout code that distinguishes a bounded wait from caller cancellation. */
 export const TASK_WAIT_TIMEOUT = 'TASK_WAIT_TIMEOUT'
 
 /** The registry's mutable per-task record (never handed out — see {@link TaskService.snapshot}). */
@@ -78,9 +52,9 @@ interface TrackedTask {
   reported: boolean
   /** Resolves once the terminal snapshot is recorded and listeners notified. */
   settled: Promise<void>
-  /** Resolver for {@link settled} (called by the first effective {@link TaskService.settle}). */
+  /** Resolver for {@link settled}, called by the first effective settlement. */
   markSettled: () => void
-  /** Live {@link TaskService.wait} calls — a settlement with waiters marks the task reported. */
+  /** Live waits; settlement with a waiter marks the task reported. */
   waiters: number
   /** Removable resolvers for live waits; timeout/abort unregister before the task settles. */
   waitResolvers: Set<() => void>
@@ -101,15 +75,9 @@ export class TaskService extends Service {
   private surfaces = new Set<symbol>()
   private listeners = new Set<TaskDoneListener>()
   private listenersClosed = false
-  /** Owner agents whose scope cleanup is attached, mapped to its exact disposer. */
+  /** Owner agents with attached scope cleanup, mapped to the exact disposer. */
   private ownerCleanups = new Map<Agent, () => Promise<void> | void>()
-  /**
-   * The service's OWN construction-time context, for work that outlives the
-   * calling fiber: detached settlement continuations (logging), and the
-   * service teardown. Owner cleanup itself is registered through the owning
-   * agent's scope so it survives producer-plugin reloads and participates in
-   * the agent's structural quiescence boundary.
-   */
+  /** Service context used by detached settlement continuations and teardown. */
   private readonly selfCtx: Context
 
   constructor(ctx: Context) {
@@ -119,24 +87,14 @@ export class TaskService extends Service {
   }
 
   /**
-   * PREFLIGHT, start, then atomically register background work; returns its
-   * task id (`<kind>-N`, per-kind counter). Every check that can fail — the
-   * control-surface fence ({@link attachSurface}; a task the model could
-   * never read or stop must fail loud before it exists), kind/label
-   * validation, exact live owner-instance identity, and the owner's awaited
-   * disposal-cleanup attach (once per owner agent, through `owner.ctx`) — runs BEFORE
-   * `spec.run()` starts the actual work, and nothing in the runtime can fail
-   * after it returns: "work started but never got a collectable id" is
-   * structurally impossible, not a producer rollback obligation. The runtime
-   * attaches ONE continuation to the returned `done` that records the
-   * terminal snapshot, notifies {@link onTaskDone} listeners, and releases
-   * waiters. A throwing `run()` propagates with nothing registered (the
-   * producer owns any partial cleanup of its own failed start).
-   * @param spec - the task's identity/owner plus the `run()` starter (see {@link TaskStart}).
-   * @returns the registry-issued task id.
+   * Preflight access, validation, and owner cleanup before starting and
+   * atomically registering work. A throwing starter leaves nothing registered;
+   * after it returns, registration cannot fail. Settlement records the outcome,
+   * notifies listeners, and releases waiters.
+   * @param spec - task identity, owner, and synchronous starter.
+   * @returns the registry-issued `<kind>-N` id.
    */
   start(spec: TaskStart): TaskId {
-    // -- Preflight: everything that can throw, before any work or mutation. --
     if (this.surfaces.size === 0) {
       throw new Error('background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)')
     }
@@ -144,10 +102,7 @@ export class TaskService extends Service {
     if (spec.label.length === 0) throw new Error('invalid task label: expected a non-empty string')
     if (spec.owner !== undefined) this.ensureOwnerCleanup(spec.owner)
 
-    // -- Start: the producer's work begins only now, preflight-clean. --
     const hooks = spec.run()
-
-    // -- Commit: pure mutations; nothing below can throw. --
     const count = (this.counters.get(spec.kind) ?? 0) + 1
     this.counters.set(spec.kind, count)
     const id = TaskId(`${spec.kind}-${count}`)
@@ -177,8 +132,7 @@ export class TaskService extends Service {
     void hooks.done.then(
       (outcome) => { this.settle(task, outcome) },
       (error: unknown) => {
-        // Producer contract violation (`done` must never reject) — contained
-        // as a failed outcome so waiters, cleanup, and disposal never hang.
+        // Contain a producer contract violation so cleanup and waiters cannot hang.
         this.selfCtx.logger.warn(`tasks: task ${task.id} 'done' rejected (producer contract violation): ${String(error)}`)
         this.settle(task, { status: 'failed', detail: String(error) })
       },
@@ -187,11 +141,10 @@ export class TaskService extends Service {
   }
 
   /**
-   * The caller-VISIBLE tasks (owned by the caller's session, or unowned), in
-   * registration order. Never lists another session's tasks — a global
-   * listing would leak their labels across the isolation fence.
-   * @param caller - the reading agent; undefined (a non-agent caller) sees only unowned tasks.
-   * @returns fresh snapshots; mutating them does not affect the registry.
+   * List caller-owned and unowned tasks in registration order without exposing
+   * another session's labels.
+   * @param caller - reading agent; a non-agent caller sees only unowned tasks.
+   * @returns fresh snapshots.
    */
   list(caller?: Agent): TaskSnapshot[] {
     const session = caller?.session.header.id
@@ -201,12 +154,10 @@ export class TaskService extends Service {
   }
 
   /**
-   * A non-consuming snapshot of one task — unlike {@link read}, never touches
-   * the stream cursor or the reported flag (the kill surface uses it to
-   * describe an already-terminal task WITHOUT eating a pending delta).
-   * Throws for an unknown id or a task owned by another session.
-   * @param id - the task to look up.
-   * @param caller - the reading agent, checked against the task's owner.
+   * Return a non-consuming snapshot without changing its read cursor or notice
+   * state. Throws for an unknown or foreign task.
+   * @param id - task to look up.
+   * @param caller - reading agent checked against the owner.
    * @returns a fresh snapshot.
    */
   get(id: TaskId, caller?: Agent): TaskSnapshot {
@@ -216,15 +167,12 @@ export class TaskService extends Service {
   }
 
   /**
-   * Read a task's output. Stream kinds (registered with `readOutput`) yield
-   * the CONSUMING delta since the previous read — one cursor per task, the
-   * owning model is v1's single intended reader; final-output kinds yield
-   * empty text while live and the terminal output idempotently once settled.
-   * A read that returns the terminal state marks the task {@link TaskSnapshot.reported}.
-   * Throws for an unknown id or a task owned by another session.
-   * @param id - the task to read.
-   * @param caller - the reading agent, checked against the task's owner.
-   * @returns the read text plus the post-read snapshot.
+   * Read the next stream delta, or the idempotent final output after settlement.
+   * A terminal read marks the task reported. Throws for an unknown or foreign
+   * task.
+   * @param id - task to read.
+   * @param caller - reading agent checked against the owner.
+   * @returns output text and the post-read snapshot.
    */
   read(id: TaskId, caller?: Agent): TaskRead {
     const task = this.expect(id)
@@ -237,18 +185,13 @@ export class TaskService extends Service {
   }
 
   /**
-   * Request cancellation of a task. A live task has its producer
-   * `cancel(reason)` invoked FIRST — a throw propagates (fail loud) and
-   * leaves the task untouched (still `running`, notice not suppressed) —
-   * then moves to `stopping` and settles through the normal `done` path; an
-   * already-terminal task is reported, not failed. Every SUCCESSFUL kill
-   * marks the task {@link TaskSnapshot.reported}: the killer has seen (or
-   * asked for) the end, so the completion notice is suppressed. Throws for
-   * an unknown id or a task owned by another session.
-   * @param id - the task to cancel.
-   * @param caller - the killing agent, checked against the task's owner.
-   * @param reason - the surface's logged reason, forwarded to the producer.
-   * @returns 'requested' when cancellation was asked of a live task, 'already-terminal' otherwise.
+   * Request cancellation, then mark the task stopping and reported. A producer
+   * throw propagates without changing task state. Throws for an unknown or
+   * foreign task.
+   * @param id - task to cancel.
+   * @param caller - killing agent checked against the owner.
+   * @param reason - logged reason forwarded to the producer.
+   * @returns `requested` for live work, otherwise `already-terminal`.
    */
   kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-terminal' {
     const task = this.expect(id)
@@ -257,12 +200,7 @@ export class TaskService extends Service {
       task.reported = true
       return 'already-terminal'
     }
-    // Producer cancel FIRST: a throw must leave the task untouched (still
-    // `running`, notice not suppressed) — the killer's tool call fails loud,
-    // but task_list and the eventual completion notice keep telling the
-    // truth about a cancellation that never happened. Cancel is synchronous
-    // and settlement lands on a later microtask, so the mutations below
-    // cannot race the settle path.
+    // Cancel first so a throw leaves both lifecycle and notice state unchanged.
     task.cancel(reason)
     task.status = 'stopping'
     task.reported = true
@@ -270,23 +208,16 @@ export class TaskService extends Service {
   }
 
   /**
-   * Wait for a task to settle, bounded by a timeout. Resolves with the
-   * terminal snapshot (marked {@link TaskSnapshot.reported} — the wait
-   * response reports the end, so the completion notice is suppressed), or
-   * with the still-live snapshot when the timeout expires first. An abort of
-   * `signal` rejects the WAIT only (the task keeps running) — UNLESS the task
-   * has already settled: settlement saw this live waiter and suppressed the
-   * completion notice on its behalf, so the wait still resolves and delivers
-   * the terminal snapshot it owes (an abort must never leave a finished task
-   * both unreported and notice-suppressed). Each live wait uses a removable
-   * resolver that timeout/abort detaches, so a long-running task does not
-   * retain expired waits. Throws for an unknown id, a task owned by another
-   * session, or a non-positive timeout.
-   * @param id - the task to wait for.
-   * @param timeoutMs - max wait in milliseconds (positive, finite; the surface caps it).
-   * @param caller - the waiting agent, checked against the task's owner.
-   * @param signal - optional abort for the wait itself.
-   * @returns the snapshot at settlement, or at timeout when the task outlives the wait.
+   * Wait for settlement or timeout without cancelling the task. Caller abort
+   * rejects only while the task is live; after settlement it returns the
+   * terminal snapshot so a notice suppressed for this waiter is still delivered.
+   * Timed-out and aborted waits detach their resolvers. Throws for invalid,
+   * unknown, or foreign input.
+   * @param id - task to wait for.
+   * @param timeoutMs - positive finite wait bound in milliseconds.
+   * @param caller - waiting agent checked against the owner.
+   * @param signal - optional cancellation of the wait itself.
+   * @returns snapshot at settlement or timeout.
    */
   async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot> {
     const task = this.expect(id)
@@ -296,12 +227,8 @@ export class TaskService extends Service {
     }
     if (!isTerminal(task.status)) {
       if (signal?.aborted) throw new Error('wait aborted')
-      // `waiters` is the settle-path heuristic "someone WILL deliver the
-      // terminal snapshot, suppress the notice". An abort breaks that promise,
-      // so the un-count must happen SYNCHRONOUSLY inside onAbort — the
-      // `finally` decrement alone runs a microtask later, after a same-tick
-      // settlement could already have read the stale count and suppressed the
-      // notice for a waiter that then rejects and delivers nothing.
+      // Abort removes the waiter synchronously so same-tick settlement cannot
+      // suppress a notice for a wait that will reject.
       task.waiters += 1
       let counted = true
       const uncount = (): void => {
@@ -310,11 +237,8 @@ export class TaskService extends Service {
         task.waiters -= 1
       }
       try {
-        // The dsh-timeout deadline fits wait() exactly because both only
-        // NOTIFY: a wait timeout returns the live snapshot (the task keeps
-        // running — nothing is terminated), and timeoutOf scoped to our own
-        // code tells that timeout apart from a caller abort, which rejects
-        // the wait. `using` clears the timer on every exit path.
+        // The scoped deadline distinguishes a successful wait timeout from
+        // caller cancellation and clears its timer on every exit.
         using d = deadline(signal, timeoutMs, TASK_WAIT_TIMEOUT)
         await new Promise<void>((resolve, reject) => {
           const onSettled = (): void => {
@@ -327,8 +251,7 @@ export class TaskService extends Service {
             if (timeoutOf(d.signal, TASK_WAIT_TIMEOUT) !== undefined) {
               resolve()
             } else if (isTerminal(task.status)) {
-              // Settlement already ran and suppressed the notice for this
-              // waiter — deliver the terminal snapshot instead of rejecting.
+              // Settlement suppressed the notice for this waiter; deliver it.
               resolve()
             } else {
               uncount()
@@ -347,14 +270,11 @@ export class TaskService extends Service {
   }
 
   /**
-   * Register a completion listener, called exactly once per terminal task
-   * record with its snapshot and exact lifecycle owner (or `undefined` for an
-   * unowned task). Effect-scoped (disposed with the calling fiber); per-listener
-   * containment (one throwing or rejecting listener is logged, never starves
-   * the rest); returned promises are observed but not awaited; never fires
-   * after this service is disposed.
-   * @param listener - called with each terminal snapshot and its exact owner.
-   * @returns the disposer that unregisters the listener.
+   * Register an effect-scoped completion listener. Each listener is contained;
+   * returned promises are observed but not awaited. No listener runs after
+   * service disposal.
+   * @param listener - receives each terminal snapshot and its exact owner.
+   * @returns disposer that unregisters the listener.
    */
   onTaskDone(listener: TaskDoneListener): () => void {
     const dispose = this.ctx.effect(() => {
@@ -365,19 +285,13 @@ export class TaskService extends Service {
   }
 
   /**
-   * Declare that a control surface capable of reading/stopping tasks is
-   * loaded. {@link start} refuses to start a background task while NO
-   * surface is attached — the loud fence against a deployment exposing
-   * `run_in_background` without any way to collect or stop the work. The
-   * model-facing `@deepseek-ai/dsh-tool-tasks` attaches on load; a deployment
-   * with a custom (non-model) surface attaches its own. Effect-scoped:
-   * detached with the calling fiber.
-   * @param name - a diagnostic label for the surface (duplicate names count independently).
-   * @returns the disposer that detaches the surface.
+   * Attach an effect-scoped surface that can read and stop tasks. {@link start}
+   * refuses work while none is attached.
+   * @param name - diagnostic label; duplicate names remain independent.
+   * @returns disposer that detaches this surface.
    */
   attachSurface(name: string): () => void {
-    // One token per attach call: duplicate names stay independent, and the
-    // single-shot effect disposer removes exactly its own attachment.
+    // One token per call keeps duplicate labels independently disposable.
     const token = Symbol(name)
     const dispose = this.ctx.effect(() => {
       this.surfaces.add(token)
@@ -421,14 +335,9 @@ export class TaskService extends Service {
   }
 
   /**
-   * Record the first terminal outcome, notify listeners with containment, then
-   * release waiters. Normally the producer's single `done` continuation calls
-   * this; teardown also force-fails the record when `cancel` throws and `done`
-   * may never settle. First-wins makes a producer outcome arriving after that
-   * fallback a no-op, so listeners fire once and the diagnosed terminal state
-   * is never overwritten. A settlement observed by a pending {@link wait}
-   * marks the task reported BEFORE listeners run, so the notice surface can
-   * suppress its redundant "finished".
+   * Record the first terminal outcome, notify contained listeners, and release
+   * waiters. First-wins preserves a teardown force-failure against late producer
+   * settlement. Pending waits mark the task reported before listeners run.
    */
   private settle(task: TrackedTask, outcome: TaskOutcome): void {
     if (isTerminal(task.status)) return
@@ -457,17 +366,10 @@ export class TaskService extends Service {
   }
 
   /**
-   * Attach the awaited owner-disposal cleanup for an owner agent, once. The
-   * effect is registered through `owner.ctx`, so it belongs to the agent scope
-   * rather than the producer or long-lived tasks fiber: it survives producer
-   * reloads, runs at the structural agent quiescence boundary, and removes its
-   * wrapper automatically when that scope unwinds. The tasks service retains
-   * the exact disposer only so service teardown can detach cross-fiber effects
-   * instead of leaving a dead service captured by still-live agents.
-   * Fails loud when no agent registry is mounted or when `owner` is not the
-   * exact live instance currently registered under its id — accepting a stale
-   * object after id reuse would attach its session's task to another agent's
-   * lifecycle.
+   * Attach one awaited cleanup through the exact owner's scope. This survives
+   * producer reloads and joins agent quiescence; the retained disposer lets
+   * service teardown detach the cross-fiber effect. Fails when the registry is
+   * absent or the owner is not its currently registered instance.
    */
   private ensureOwnerCleanup(owner: Agent): void {
     const ownerId = owner.id
@@ -479,8 +381,7 @@ export class TaskService extends Service {
       throw new Error(`agent "${ownerId}" is not the registered agent instance (background task owner must be live)`)
     }
     if (this.ownerCleanups.has(owner)) return
-    // Attach FIRST, record after: an already-disposing scope rejects effects,
-    // and marking the owner as covered before that would poison later starts.
+    // Record only after attach succeeds; a disposing scope rejects new effects.
     const detach = owner.ctx.effect(() => async () => {
       this.ownerCleanups.delete(owner)
       await this.disposeOwned(owner)
@@ -497,11 +398,8 @@ export class TaskService extends Service {
   }
 
   /**
-   * Service teardown: close the listener registry FIRST (late completions
-   * from teardown kills stay silent), cancel every live task, and await each
-   * terminal record. Contract-compliant producers settle at quiescence; a
-   * producer whose cancel throws is force-failed so disposal cannot deadlock,
-   * with the possible underlying orphan logged explicitly.
+   * Close listeners, cancel live tasks, await settlement, and detach owner
+   * effects. Throwing cancels are force-failed to avoid teardown deadlock.
    */
   private async disposeAll(): Promise<void> {
     this.listenersClosed = true
@@ -510,24 +408,16 @@ export class TaskService extends Service {
     this.cancelForTeardown(all, 'tasks service disposed')
     await Promise.all(all.map(task => task.settled))
     this.store.clear()
-    // These effects belong to agent scopes, not this service's fiber. Detach
-    // them after the shared store is quiescent so a tasks-service reload cannot
-    // leave old callbacks retaining the dead service until each agent exits.
+    // Detach cross-fiber owner effects after the shared store is quiescent.
     const ownerCleanups = [...this.ownerCleanups.values()]
     this.ownerCleanups.clear()
     await Promise.all(ownerCleanups.map(cleanup => Promise.resolve(cleanup())))
   }
 
   /**
-   * Teardown-path cancellation with per-task containment: unlike the
-   * model-facing {@link kill} (where a throwing producer `cancel` fails the tool
-   * call and leaves the record live), teardown force-fails a record whose cancel
-   * throws because its `done` may depend on a request that never arrived. This
-   * prevents disposal deadlock but cannot prove the underlying work stopped, so
-   * the potential orphan is carried in the detail and warning. A cancel that
-   * returns but never leads to `done` remains indistinguishable from a slow stop
-   * and can still stall teardown; fixing that requires a separate bounded-lifetime
-   * or forced-disposal design.
+   * Cancel tasks during teardown with per-task containment. A throwing cancel
+   * force-fails the record and reports a possible orphan; a cancel that returns
+   * without settling remains indistinguishable from a slow stop and may stall.
    */
   private cancelForTeardown(tasks: TrackedTask[], reason: string): void {
     for (const task of tasks) {
diff --git a/packages/tasks/tasks/src/types.ts b/packages/tasks/tasks/src/types.ts
index bd3b3b1c24..34d0189913 100644
--- a/packages/tasks/tasks/src/types.ts
+++ b/packages/tasks/tasks/src/types.ts
@@ -1,9 +1,6 @@
 /**
- * Task-runtime vocabulary: the {@link TaskStart} a producer hands to
- * {@link TaskService.start} (identity + the `run()` starter), the
- * {@link TaskHooks} its work is driven through, and the snapshots/reads
- * consumers get back. Types only — the service lives in `./index.ts`.
- *
+ * Types shared by task producers, the registry, and control surfaces. The
+ * service implementation lives in `./index.ts`.
  * @module @deepseek-ai/dsh-tasks/types
  */
 
@@ -12,10 +9,8 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 
 /**
- * Identifies one background task in the runtime-global registry. Generated by
- * {@link TaskService.start} as `<kind>-N` (per-kind counter) — kind-prefixed
- * so transcripts stay self-describing, sequential because the owner fence (not
- * id secrecy) is the isolation boundary.
+ * Identifies a background task. The registry generates `<kind>-N`; predictable
+ * ids rely on owner authorization rather than secrecy.
  */
 export type TaskId = Branded<'TaskId'>
 
@@ -29,40 +24,25 @@ export function TaskId(id: string): TaskId {
 }
 
 /**
- * Task lifecycle. `running` → (`stopping` when cancellation was requested) →
- * exactly one terminal {@link TaskOutcome.status} (`completed`, `killed`,
- * `failed`). The vocabulary is generic and CLOSED — kind-specific meaning
- * (exit codes, stop reasons) rides in {@link TaskSnapshot.detail}, so the
- * registry never learns process or agent semantics.
+ * Task lifecycle: `running`, optionally `stopping`, then exactly one terminal
+ * status. Producer-specific facts belong in {@link TaskSnapshot.detail}.
  */
 export type TaskStatus = 'running' | 'stopping' | 'completed' | 'killed' | 'failed'
 
-/**
- * The terminal result a producer's {@link TaskHooks.done} resolves
- * with, mapped from the producer's own vocabulary (a process exit, a subagent
- * stop reason) into the registry's closed status set.
- */
+/** Terminal result supplied by a producer through {@link TaskHooks.done}. */
 export interface TaskOutcome {
   /** How the task ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
   status: 'completed' | 'killed' | 'failed'
   /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */
   detail?: string
-  /**
-   * Final output for FINAL-OUTPUT-ONLY kinds (no {@link TaskHooks.readOutput}),
-   * read idempotently after the task settles. Stream kinds leave it unset —
-   * their output is consumed incrementally through `readOutput`.
-   */
+  /** Final output for tasks without `readOutput`; stream tasks leave it unset. */
   output?: string
 }
 
 /**
- * What a producer hands to {@link TaskService.start}: the task's identity and
- * owner (preflighted BEFORE any work starts), plus {@link run} — the starter
- * the runtime invokes only once preflight cannot fail anymore. The producer
- * stays the owner of its execution concerns (process streams, child agents);
- * the runtime owns ids, isolation, status, and completion fan-out. This
- * declare-then-execute split is what makes "work started but never got a
- * collectable id" structurally impossible.
+ * Producer declaration passed to {@link TaskService.start}. The runtime
+ * preflights access and cleanup before invoking {@link run}; the producer owns
+ * execution resources while the runtime owns identity and lifecycle state.
  */
 export interface TaskStart {
   /** Producer kind — also the id prefix (`bash`, `subagent`, …). Non-empty. */
@@ -70,56 +50,38 @@ export interface TaskStart {
   /** One-line model-facing label (the command; the delegation description). */
   label: string
   /**
-   * The spawning agent. Its `session.header.id` becomes the task's owner
-   * identity (read/kill/wait/list are fenced to that session), and its `ctx` scope
-   * owns an async cleanup that cancels and awaits the task during disposal. It
-   * must be the exact live instance currently registered under its agent id;
-   * a stale object whose id has been reused is rejected before work starts.
-   * `undefined` starts an UNOWNED task: open to any caller, alive until the
-   * tasks service disposes.
+   * Owning live agent. Access is fenced by its session id, and agent disposal
+   * cancels and awaits the task. The instance must be the one currently
+   * registered under its agent id. `undefined` creates an unowned task, open to
+   * any caller until service disposal.
    */
   owner?: Agent | undefined
   /**
-   * Start the actual work and return its {@link TaskHooks}. Called EXACTLY
-   * once, synchronously, after every preflight check (control-surface fence,
-   * validation, owner-cleanup attach) has passed — nothing in the runtime can
-   * fail after it returns, so the started work is always registered. A throw
-   * here propagates with nothing registered; the producer owns any partial
-   * cleanup of its own failed start.
+   * Start the work after preflight and synchronously return its hooks. Called
+   * once; a throw leaves nothing registered, and the producer must clean up any
+   * partially started resources.
    */
   run(): TaskHooks
 }
 
-/**
- * The live-work hooks a {@link TaskStart.run} returns: how the runtime
- * cancels the work, observes its settlement, and (for stream kinds) reads
- * its incremental output.
- */
+/** Hooks through which the runtime controls and observes producer work. */
 export interface TaskHooks {
   /**
-   * Request termination. Idempotent, synchronous, and must lead to
-   * {@link done} settling; a throw propagates to the killer (fail loud — a
-   * cancel that cannot even be requested is a producer bug). The optional
-   * reason is `task_kill`'s logged reason, forwarded verbatim.
+   * Request termination. Must be synchronous, idempotent, and eventually settle
+   * {@link done}; throws propagate. The optional reason is forwarded verbatim.
    */
   cancel(reason?: string): void
   /**
-   * Settles with the terminal outcome at QUIESCENCE — after the producer has
-   * released the task's resources (process exited, child agent disposed) —
-   * not merely when the work finished. Must never reject; a rejection is
-   * contained as a `failed` outcome and logged as a producer contract
-   * violation. If `cancel` throws during teardown, the runtime may force-fail
-   * only its registry record to avoid deadlock because this promise may never
-   * settle; that fallback explicitly does not claim work quiescence.
+   * Resolves after the producer releases its resources, not merely when work
+   * finishes. Must not reject; the runtime converts a rejection to `failed`.
+   * If teardown cancellation throws, the runtime may force-fail only the
+   * registry record without claiming that the work stopped.
    */
   done: Promise<TaskOutcome>
   /**
-   * OPTIONAL incremental read (stream kinds): everything produced since the
-   * previous call, formatted by the producer (truncation/spill notices
-   * included). Consecutive calls never re-deliver output; the registry keeps
-   * ONE consuming cursor per task, so v1's single intended reader is the
-   * owning model. Absence marks a final-output-only kind (the method presence
-   * IS the capability).
+   * Consume output produced since the previous call. The producer formats
+   * truncation and spill notices. Absence marks a final-output-only task; each
+   * task has one consuming cursor.
    */
   readOutput?(): string
 }
@@ -136,12 +98,9 @@ export interface TaskSnapshot {
   /** The producer-supplied one-line label. */
   label: string
   /**
-   * The owner's session id (`session.header.id`), for authorization and
-   * correlation; absent for unowned tasks. A listener that must reach the
-   * lifecycle owner receives the exact Agent separately through
-   * {@link TaskDoneListener}. Session ids are runtime-shared identifiers, not
-   * secrets — the read/kill/wait/list FENCE is what isolation rests on. The
-   * shared {@link SessionId} brand is preserved across this package boundary.
+   * Owner session id used for authorization and correlation; absent for
+   * unowned tasks. Completion listeners receive the exact {@link Agent}
+   * separately through {@link TaskDoneListener}.
    */
   ownerSession?: SessionId
   /** Current lifecycle state. */
@@ -153,20 +112,13 @@ export interface TaskSnapshot {
   /** Epoch ms when the task settled; absent while `running`/`stopping`. */
   finishedAt?: number
   /**
-   * True once the terminal state has been (or is being) reported to the owner
-   * through an explicit surface response — a `kill` call, or a `read`/`wait`
-   * that returned the terminal state (including a wait pending at settlement).
-   * Completion-notice surfaces suppress their notice when set, so the model
-   * never gets a redundant "finished" for a task it just collected or killed.
+   * True when a kill, read, or wait has reported or committed to report the
+   * terminal state. Completion surfaces suppress redundant notices when set.
    */
   reported: boolean
 }
 
-/**
- * One {@link TaskService.read}: the output text this read yields (may be
- * empty — the surface decides how to render "nothing new") plus the snapshot
- * taken after the read.
- */
+/** Output and post-read state returned by {@link TaskService.read}. */
 export interface TaskRead {
   /**
    * Stream kinds: the consuming delta since the previous read. Final-output
@@ -179,10 +131,8 @@ export interface TaskRead {
 }
 
 /**
- * Completion callback registered via {@link TaskService.onTaskDone}.
- * `owner` is the exact lifecycle instance supplied at start, not a registry
- * lookup by reusable agent or session id; it is absent for unowned tasks. A
- * returned promise is observed for rejection but does not delay settlement.
+ * Completion callback with the exact owner supplied at start, or `undefined`
+ * for an unowned task. Returned promises are observed but not awaited.
  */
 export type TaskDoneListener = (
   snapshot: TaskSnapshot,
diff --git a/packages/tasks/tasks/tests/tasks.spec.ts b/packages/tasks/tasks/tests/tasks.spec.ts
index 42c2f23860..b9b6cfdf01 100644
--- a/packages/tasks/tasks/tests/tasks.spec.ts
+++ b/packages/tasks/tasks/tests/tasks.spec.ts
@@ -269,7 +269,7 @@ describe('TaskService.wait', () => {
     const wait = ctx.tasks.wait(id, 5_000)
     p.settle({ status: 'completed', detail: 'exit code: 0' })
     expect(await wait).toMatchObject({ status: 'completed', reported: true })
-    // The pending wait marked the task reported BEFORE listeners ran.
+    // A waiting reader claims delivery before completion listeners inspect the snapshot.
     expect(seen[0]).toMatchObject({ id, reported: true })
   })
 
@@ -330,7 +330,7 @@ describe('TaskService.wait', () => {
     await expect(ctx.tasks.wait(id, 5_000, undefined, preAborted.signal)).rejects.toThrow('wait aborted')
   })
 
-  it('an abort racing settlement in the same tick does not swallow the notice (review finding)', async () => {
+  it('an abort racing settlement in the same tick does not swallow the notice', async () => {
     const ctx = await harness()
     const seen: TaskSnapshot[] = []
     ctx.tasks.onTaskDone(snapshot => void seen.push(snapshot))
@@ -339,11 +339,8 @@ describe('TaskService.wait', () => {
 
     const controller = new AbortController()
     const wait = ctx.tasks.wait(id, 5_000, undefined, controller.signal)
-    // Same synchronous tick, settlement QUEUED first: the settle continuation
-    // will run before the rejected wait's `finally`, so only the SYNCHRONOUS
-    // un-count inside onAbort keeps it from reading a stale waiter count,
-    // marking the task reported, and suppressing the completion notice for a
-    // wait that then delivers nothing.
+    // Settlement is queued first, so abort must remove the waiter synchronously;
+    // otherwise settlement suppresses the notice for a reader that receives nothing.
     p.settle({ status: 'completed', detail: 'exit code: 0' })
     controller.abort()
     await expect(wait).rejects.toThrow('wait aborted')
@@ -351,15 +348,12 @@ describe('TaskService.wait', () => {
     expect(seen[0]).toMatchObject({ id, status: 'completed', reported: false })
   })
 
-  it('an abort landing AFTER settlement still delivers the terminal snapshot it owes', async () => {
+  it('an abort landing after settlement still delivers the terminal snapshot it owes', async () => {
     const ctx = await harness()
     const controller = new AbortController()
     const seen: TaskSnapshot[] = []
-    // The listener runs synchronously inside settle — aborting HERE lands the
-    // abort after settlement marked this waiter reported (notice suppressed)
-    // but before the wait's own resolve microtask. Rejecting now would leave
-    // the finished task both unreported and notice-suppressed, so the wait
-    // must resolve and deliver instead.
+    // The listener aborts after settlement has assigned delivery to this waiter
+    // but before its resolve microtask; the waiter must still receive the result.
     ctx.tasks.onTaskDone((snapshot) => {
       seen.push(snapshot)
       controller.abort()
@@ -426,14 +420,12 @@ describe('TaskService owner isolation', () => {
     const ctx = await harness()
     const ghost = stubAgent(ctx, 'ghost') // never registered in ctx.agents
 
-    // Exact-instance preflight rejects the unregistered agent BEFORE any
-    // registry mutation or owner-cleanup attachment.
+    // Exact-instance validation precedes registry mutation and cleanup attachment.
     expect(() => ctx.tasks.start(producer({ owner: ghost }).spec))
       .toThrow('is not the registered agent instance')
     expect(ctx.tasks.list(ghost)).toEqual([])
 
-    // Once the agent actually exists, the same owner gets a WORKING cleanup —
-    // the failed attempt must not have marked it as already covered.
+    // A later valid registration must still attach cleanup for the same object.
     ctx.agents.register(ghost)
     const cancels: (string | undefined)[] = []
     let settle!: (outcome: TaskOutcome) => void
@@ -607,13 +599,11 @@ describe('TaskService owner cleanup', () => {
     await tick()
     const drainedWithoutProducerDone = drained
     if (!drainedWithoutProducerDone) {
-      // Failure-path cleanup for the pre-fix implementation: let its pending
-      // drain finish without weakening the assertion captured above.
+      // Release the producer if the assertion fails so the test can finish.
       settle({ status: 'completed' })
       await drain
     } else {
-      // A late producer completion must not replace the forced failed record or
-      // notify listeners a second time.
+      // A late producer completion must not replace the failure or notify twice.
       settle({ status: 'completed' })
       await tick()
     }
@@ -681,7 +671,7 @@ describe('TaskService disposal', () => {
     await tick()
     const disposedWithoutProducerDone = disposed
     if (!disposedWithoutProducerDone) {
-      // Failure-path cleanup for the pre-fix implementation.
+      // Release the producer if the assertion fails so the test can finish.
       settle({ status: 'completed' })
       await disposal
     } else {
diff --git a/packages/tasks/tool-tasks/README.md b/packages/tasks/tool-tasks/README.md
index 54d859734f..520a874df1 100644
--- a/packages/tasks/tool-tasks/README.md
+++ b/packages/tasks/tool-tasks/README.md
@@ -1,35 +1,35 @@
 # @deepseek-ai/dsh-tool-tasks
 
-The model-facing background task control surface over `ctx.tasks`: three kind-agnostic tools, the completion-notice injection, and the prompt section that teaches the background habit. Loading this plugin calls `ctx.tasks.attachSurface('tool-tasks')`, which is what arms producers' `ctx.tasks.start()`.
+The model-facing control surface for `ctx.tasks`: three kind-independent tools, completion notices, and one background-work prompt section. Loading the plugin attaches the surface required by `ctx.tasks.start()`.
 
 ## Tools
 
-- `task_output(task_id, wait?, timeout_ms?)` — non-blocking read by default (stream kinds: the consuming delta since the previous read; final kinds: the final answer once terminal); every response ends with a `[status: …]` line (generic status + producer detail, e.g. `[status: completed, exit code: 0]`). `wait: true` blocks until settlement, bounded by `waitTimeoutMs`/`maxWaitTimeoutMs` config; a timed-out wait returns `[status: running]` and leaves the task alive.
-- `task_list()` — the caller's tasks, `<id> [<kind>] <status> — <label>` per line.
-- `task_kill(task_id, reason?)` — requests cancellation and returns immediately; the logged `reason` is forwarded to the producer. An already-terminal task is described via a non-consuming snapshot (never eats a pending delta).
+- `task_output(task_id, wait?, timeout_ms?)` reads without blocking by default. Stream tasks return only the next delta; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. `wait: true` waits up to the configured cap and leaves a still-running task alive on timeout.
+- `task_list()` returns caller-visible tasks as `<id> [<kind>] <status> — <label>`.
+- `task_kill(task_id, reason?)` requests cancellation immediately and forwards the logged reason. Terminal tasks return a non-consuming snapshot.
 
-ACP render intent: all three are `generic` cards (`read`/`read`/`execute`) — a task read is not a terminal.
+All three use generic ACP cards: `read` for output and list, `execute` for kill.
 
 ## Completion notices
 
-On `onTaskDone`, injects `background task <id> (<kind>: <label>) finished [status: …]. Read its output with task_output.` through the exact owner `Agent` captured at task start (`agent.inject()` — durable context for the next request, not a wake-up). It never re-resolves a reusable agent/session id to a replacement. Suppressed when the snapshot is `reported` (the model already killed it, or a read/wait returned the end) — never a redundant "finished"; the disposed-owner race is contained.
+An unreported completion injects `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` into the exact owner's session. Injection is durable context for the next request, not a wake-up. A kill or terminal read/wait marks delivery reported and suppresses the redundant notice; owner-disposal races are contained.
 
 ## Config
 
 | key | default | meaning |
 |---|---|---|
-| `waitTimeoutMs` | `30000` | wait duration when `task_output` sets `wait` without `timeout_ms` |
-| `maxWaitTimeoutMs` | `600000` | hard cap; larger model-supplied `timeout_ms` values are clamped |
+| `waitTimeoutMs` | `30000` | wait used when `wait: true` omits `timeout_ms` |
+| `maxWaitTimeoutMs` | `600000` | cap for model-supplied waits |
 
-A config whose default exceeds the cap fails loud at load.
+A default above the cap fails at load.
 
 ## Model Experience
 
 ### System prompt
 
-**What the model sees**: Every request in this plugin's registration scope contains the background-task guidance below. Agent-scoped tool filtering can hide the control schemas without removing this independently registered section.
+**What the model sees**: Every request in this plugin's registration scope contains this guidance. Agent-scoped tool filtering may hide the tools without removing the independently registered prompt section.
 
-**Token effect**: Small fixed input cost per request while the plugin is active.
+**Token effect**: Small fixed input cost per request while active.
 
 #### Background-task guidance
 
@@ -39,18 +39,18 @@ Track every background task id you start. You are notified in-session when a tas
 
 ### Tool schemas
 
-**What the model sees**: The model sees the generated [`task_output`, `task_list`, and `task_kill` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-tasks) while this control surface is visible.
+**What the model sees**: The generated [`task_output`, `task_list`, and `task_kill` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-tasks) while this surface is visible.
 
 **Token effect**: Fixed schema cost on each request where the tools are visible.
 
-### Task results and notices
+### Results and notices
 
-**What the model sees**: Reads return a producer-owned output delta or `(no new output)`, followed by `[status: <status>]` with optional producer detail. Listing returns `(no background tasks)` or one `<id> [<kind>] <status> — <label>` line per visible task. Kill returns `requested cancellation of task <id>` or `task <id> had already finished [status: ...]`. An unreported owned completion injects exactly `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.`
+**What the model sees**: Reads return output or `(no new output)` followed by `[status: <status>]` and optional detail. An empty list returns `(no background tasks)`. Kill returns `requested cancellation of task <id>` or the existing terminal status. Unreported owned completion uses the notice above.
 
-**Token effect**: Results and completion notices are retained in the parent session until compaction; stream reads consume their cursor and do not repeat prior output.
+**Token effect**: Results and notices remain in parent history until compaction. Stream reads do not repeat consumed output.
 
 ## Known Limitations and Deferred Work
 
-- **Completion notices do not wake idle agents** — they become durable context for the next request; callers needing an immediate result must use `task_output`.
-- **Stream reads are single-consumer** — this control surface exposes the task runtime's one consuming cursor rather than independent observers.
-- **Unowned tasks have no session fence** — deployments exposing background starts outside an agent must provide their own caller policy or avoid ownerless tasks.
+- **Completion notices do not wake idle agents** — callers needing an immediate result must use `task_output`.
+- **Stream reads are single-consumer** — independent observers need another runtime API.
+- **Unowned tasks have no session fence** — external surfaces must supply caller policy or avoid them.
diff --git a/packages/tasks/tool-tasks/src/index.ts b/packages/tasks/tool-tasks/src/index.ts
index f7a91f0abd..f0de782eea 100644
--- a/packages/tasks/tool-tasks/src/index.ts
+++ b/packages/tasks/tool-tasks/src/index.ts
@@ -1,21 +1,8 @@
 /**
- * The model-facing background task control tools: `task_output`, `task_list`,
- * `task_kill`. Kind-agnostic — a background bash command and a background
- * subagent read, list, and die through the same three schemas — with every
- * task concern (ids, isolation, cursors, settlement) behind the `ctx.tasks`
- * registry (`@deepseek-ai/dsh-tasks`).
- *
- * This plugin IS the control surface: it calls `ctx.tasks.attachSurface()` on
- * load, which is what arms producers' `ctx.tasks.start()` (the runtime's
- * preflight refuses background work while no surface could collect or stop it).
- *
- * Completion notices: when a task settles, a short notice is injected into
- * the owning agent's session (`agent.inject()` — durable context for the NEXT
- * model request, not a wake-up). A task whose terminal state the model
- * already saw (`snapshot.reported` — an explicit kill, or a read/wait that
- * returned the end) is suppressed, so the model never gets a redundant
- * "finished" for work it just collected.
- *
+ * Model-facing `task_output`, `task_list`, and `task_kill` tools over
+ * `ctx.tasks`. Loading the plugin attaches the control surface required by
+ * producers. It also injects unreported completions as durable context for the
+ * owner's next request; notices do not wake idle agents.
  * @module @deepseek-ai/dsh-tool-tasks
  */
 
@@ -30,7 +17,7 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 export const name = 'tool-tasks'
 export const inject = ['tools', 'tasks', 'systemPrompt']
 
-/** Config: the `task_output` wait bounds (defaulted, capped — never hardcoded). */
+/** Configures bounded `task_output` waits. */
 export interface Config {
   /** Wait duration applied when `task_output` sets `wait` without `timeout_ms` (default 30s). */
   waitTimeoutMs?: number
@@ -44,12 +31,9 @@ export const Config: z<Config> = z.object({
 })
 
 /**
- * Render a snapshot's status line — generic status plus the producer's
- * kind-specific detail: `[status: completed, exit code: 0]`,
- * `[status: failed, max-tokens]`, `[status: running]`. Exported for tests
- * and for producers that want a consistent line in their own results.
- * @param snapshot - the task state to render.
- * @returns the bracketed status line.
+ * Render generic status with optional producer detail.
+ * @param snapshot - task state to render.
+ * @returns a bracketed status line.
  */
 export function statusLine(snapshot: TaskSnapshot): string {
   return snapshot.detail !== undefined
@@ -57,11 +41,7 @@ export function statusLine(snapshot: TaskSnapshot): string {
     : `[status: ${snapshot.status}]`
 }
 
-/**
- * Reject an empty `task_id`. Type/presence come from the SchemaSpec
- * validation; only the non-empty constraint, which the DSL cannot express,
- * is checked here.
- */
+/** Validate the non-empty constraint that SchemaSpec cannot express. */
 function validateTaskId(value: string): TaskId {
   if (value.length === 0) {
     throw new Error(`invalid task_id: expected a non-empty string, got ${JSON.stringify(value)}`)
@@ -69,7 +49,7 @@ function validateTaskId(value: string): TaskId {
   return TaskId(value)
 }
 
-/** Pending-state presentation shared by the three control tools (generic cards by design — a task read/kill is not a terminal). */
+/** Pending presentation shared by the three generic task controls. */
 function presentTaskCall(title: string, kind: 'read' | 'execute', rawInput?: string): GenericCallView {
   return { card: 'generic', title, kind, ...rawInput !== undefined ? { rawInput } : {} }
 }
@@ -81,24 +61,18 @@ export function apply(ctx: Context, config: Config): void {
     throw new Error(`tool-tasks: waitTimeoutMs (${waitDefault}) exceeds maxWaitTimeoutMs (${waitCap})`)
   }
 
-  // The registry's misconfiguration fence: producers can register background
-  // work only while a surface capable of collecting/stopping it is attached.
+  // Producers may start work only while a control surface is attached.
   ctx.tasks.attachSurface('tool-tasks')
 
-  // The cross-call HABIT the per-tool descriptions cannot carry. Order 106:
-  // right after tool:bash (105), before deployment product sections.
+  // Cross-call guidance follows the bash section and precedes product sections.
   ctx.systemPrompt.section({
     name: 'tool:tasks',
     order: 106,
     text: 'Track every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task\'s work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.',
   })
 
-  // Background completion → inject a notice through the exact lifecycle owner.
-  // Re-resolving by a reusable agent/session id could target a replacement
-  // while the old owner's scope is still unwinding.
+  // Use the exact lifecycle owner; reusable ids could resolve to a replacement.
   ctx.tasks.onTaskDone((snapshot, owner) => {
-    // A reported terminal state was already surfaced by an explicit
-    // read/wait/kill response — a notice would be a redundant "finished".
     if (snapshot.reported || owner === undefined) return
     try {
       owner.inject(
@@ -106,9 +80,7 @@ export function apply(ctx: Context, config: Config): void {
         { source: { kind: 'plugin', plugin: 'tool-tasks' } },
       )
     } catch (error: unknown) {
-      // The ONE expected failure: the agent was disposed between settlement
-      // and this injection (inject throws `agent "<id>" is disposed`). That
-      // race is benign — drop the notice. Anything else must surface.
+      // Disposal may win the race after settlement; other injection failures surface.
       if (error instanceof Error && error.message.includes('is disposed')) return
       throw error
     }
@@ -116,16 +88,11 @@ export function apply(ctx: Context, config: Config): void {
 
   ctx.tools.register(defineTool({
     name: 'task_output',
-    description: 'Read output/status from a background task (started by a tool with `run_in_background`). '
-      + 'Stream tasks (bash) return only output produced since your previous task_output call; '
-      + 'final-output tasks (subagent) return the final answer once the task finishes. '
-      + 'Every response ends with a [status: ...] line. Non-blocking by default; '
-      + 'set `wait: true` to block until the task finishes (bounded by a capped timeout) when you are genuinely blocked on its result.',
-    // Deliberately NO ToolDefinition.timeoutMs: the timeout-policy plugin
-    // replaces a timed-out call with a structured TOOL_TIMEOUT failure, but a
-    // timed-out wait here is a SUCCESS that reports [status: running] — the
-    // task's state must reach the model either way, so the wait bounds its
-    // own deadline (waitTimeoutMs/maxWaitTimeoutMs) via ctx.tasks.wait.
+    description: 'Read a background task. Stream tasks return only output since the previous read; '
+      + 'final-output tasks return their result after settlement. Every response ends with '
+      + '`[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.',
+    // A timed-out wait returns task state rather than a TOOL_TIMEOUT error, so
+    // this tool owns its deadline instead of using ToolDefinition.timeoutMs.
     parameters: {
       task_id: { type: 'string', required: true, description: 'Task id returned by the tool that started the background work.' },
       wait: { type: 'boolean', description: 'Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive.' },
@@ -149,8 +116,6 @@ export function apply(ctx: Context, config: Config): void {
     name: 'task_list',
     description: 'List your background tasks (running and finished) with their ids, kinds, and statuses.',
     parameters: {},
-    // execute is synchronous (registry reads + string shaping) but the
-    // ToolDefinition contract wants a Promise — hence resolve(), not async.
     execute(_args, exec) {
       const tasks = ctx.tasks.list(exec.agent)
       const text = tasks.length === 0
@@ -172,8 +137,7 @@ export function apply(ctx: Context, config: Config): void {
       const id = validateTaskId(args.task_id)
       const result = ctx.tasks.kill(id, exec.agent, args.reason)
       if (result === 'already-terminal') {
-        // ctx.tasks.get, NOT .read: a read would consume a stream task's
-        // pending delta just to describe the terminal state.
+        // A snapshot describes terminal state without consuming pending output.
         const snapshot = ctx.tasks.get(id, exec.agent)
         return Promise.resolve([{ type: 'text', text: `task ${id} had already finished ${statusLine(snapshot)}` }])
       }
diff --git a/packages/ui/acp/README.md b/packages/ui/acp/README.md
index 748c502585..3650cf27d4 100644
--- a/packages/ui/acp/README.md
+++ b/packages/ui/acp/README.md
@@ -42,7 +42,7 @@ Forward and reverse indexes route every event, prompt, cancel, and approval to o
 
 When `ctx.permission` is composed, the bridge advertises one `permission` select in `session/new` and `session/load`. Options come from the deployment's preset table; the current value comes from the session fold, with switch-away-only `custom` for unmatched knobs. `session/set_config_option` accepts advertised presets and writes both sandbox-mode and approval-policy events through `PermissionService.set()`. Open-turn switches append immediately; idle switches overlay responses and anchor at the next `agent/prompt-submit`, before request assembly. A crash before anchoring restores the durable fold. See the [sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md), [`dsh-permission`](../permission/README.md), and [protocol matrix](acp-feature-support.md#6-session-config-options).
 
-Background-task isolation rides on the `ctx.tasks` runtime (`dsh-tasks`): task ids are global and predictable, so every read/kill/wait/list is fenced to the owning agent's session (`session.header.id`), and one session's agent can't read or kill another's task through `task_output`/`task_kill`. Ownership is by session token, not `Agent` object identity — a different `Agent` object on the same session may access the task — and because the registration lives in the tasks service it survives a producer-plugin HMR reload.
+The shared [`ctx.tasks` runtime](../../tasks/tasks/) fences access to predictable task ids by the owning session; ACP sessions therefore cannot read or stop one another's background work.
 
 ## Per-session cwd
 
diff --git a/packages/util/brand/README.md b/packages/util/brand/README.md
index 41cdb8f774..46e6c1ff98 100644
--- a/packages/util/brand/README.md
+++ b/packages/util/brand/README.md
@@ -17,10 +17,10 @@ export function SessionId(id: string): SessionId {
 }
 ```
 
-Construction goes through the per-id factory in the OWNING package (a plain cast inside — zero runtime cost). Comparison, logging, JSON serialization, and the wire format all behave exactly as for an ordinary string; the brand is erased at compile time.
+Construction goes through the per-id factory in the owning package. Comparison, logging, JSON serialization, and the wire format behave as for an ordinary string; the brand is erased at compile time.
 
 ## Policy: brand ids that cross package boundaries
 
-A package brands the ids it OWNS — `CallId` in `dsh-llm` (tool-call correlation), `SessionId` in `dsh-session`, `AgentId` in `dsh-agent`, `TaskId` in `dsh-tasks`. Branding is for ids that cross package boundaries and could plausibly be confused; **not every string needs a brand.**
+A package brands the ids it owns — `CallId` in `dsh-llm`, `SessionId` in `dsh-session`, `AgentId` in `dsh-agent`, and `TaskId` in `dsh-tasks`. Brand cross-package ids that could plausibly be confused; not every string needs one.
 
-This package owns ONLY the primitive — no concrete id, no runtime code beyond the (erased) type. Keeping the primitive dependency-free is the point: a capability package can brand its ids without depending on an unrelated package. `dsh-tasks`, for example, brands `TaskId` by depending on `dsh-brand` alone — it never pulls in `dsh-llm` (or `dsh-session`) just to reach `Branded`.
+This package owns only the primitive. Keeping it dependency-free lets `dsh-tasks`, for example, brand `TaskId` without importing an unrelated capability package merely to reach `Branded`.

From dffeac037d6b98649ce38dbdc8a42e7289d316af Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 15 Jul 2026 21:39:20 +0800
Subject: [PATCH 39/48] docs(review): fail closed across skill maintenance

A saved complete-file candidate could overwrite newer skill guidance, while a provider-wide outage was indistinguishable from a healthy no-op run. Record the source blob and provenance, reject drift during promotion, and make total adapter failure visible.

Align cadence and feedback acquisition with the evidence contract, and narrow the borrowed-state and negative-control checks so they do not contradict the package and testing standards.
---
 .agents/skills/dsh-code-review/SKILL.md       |  6 ++---
 docs/cookbook/maintaining-dsh-code-review.md  | 23 ++++++++++---------
 ...26-07-13-human-review-skill-maintenance.md | 23 +++++++++++--------
 3 files changed, 29 insertions(+), 23 deletions(-)

diff --git a/.agents/skills/dsh-code-review/SKILL.md b/.agents/skills/dsh-code-review/SKILL.md
index 03a0189227..8059950d8f 100644
--- a/.agents/skills/dsh-code-review/SKILL.md
+++ b/.agents/skills/dsh-code-review/SKILL.md
@@ -32,11 +32,11 @@ description: Use when reviewing a pull request in the deepseek-harness repo —
 - **Scope, ownership, and necessity:** tie each abstraction, state machine, option, defensive copy, and compatibility path to a current contract or production consumer. Challenge unrelated features, speculative generality, and behavior placed outside its owning plugin or service.
 - **Configuration:** deployment-varying timeouts, caps, models, URLs, paths, and retry counts are validated `Config` fields, not literals or `DEFAULT_*` constants.
 - **Enforcement boundaries:** hidden schema fields, filtered prompts, facades, wrappers, and listener ordering are not authoritative enforcement when direct or alternate callers can bypass them. Exercise denial paths at the boundary that actually executes the operation.
-- **Borrowed and derived state:** snapshot caller-owned values retained after return or crossing queues, logs, processes, workers, and wire boundaries. Commit notifications and derived state only at the documented success boundary, and trace caches, prompts, UI echoes, replay, and query views to one authoritative source.
-- **Final artifact bounds:** verify byte, token, item, and time limits against the complete emitted or retained artifact, including wrappers and metadata. Probe tiny limits, threshold edges, oversized single chunks, and multibyte text.
+- **Borrowed and derived state:** determine whether retained caller-owned values are borrowed or snapshotted by contract; do not demand copies at typed same-process seams. Materialize mutable values that cross queues, model/tool JSON, durable logs or files, workers, processes, or wire boundaries. Commit notifications and derived state only at the documented success boundary, and trace caches, prompts, UI echoes, replay, and query views to one authoritative source.
+- **Bounds cover the final operation:** verify byte, token, item, and time limits at the boundary that owns the complete emitted or retained result, including wrappers and metadata. Probe tiny limits, exact thresholds, oversized single chunks, and multibyte text for byte limits.
 - **Real entry path:** tests exercise the shipped Loader, bin, worker, ACP bridge, or subprocess where relevant. A hand-mounted plugin does not catch Loader export-shape failures; a function plugin must named-export its namespace and have no default export.
 - **Test strength:** assertions fail on the intended regression and verify external state, logs, events, or disposal rather than restating the implementation or trusting an agent's report. Coverage is necessary but not evidence that the scenario is correct.
-- **Changed checks have a negative control:** a new or changed automated check includes a deliberately invalid fixture that fails through the real top-level runner; a green happy path does not prove the check is wired.
+- **Changed checks have a negative control:** a new automated check, or a changed acceptance path in one, has a deliberately invalid case that reaches the real top-level runner and fails for the intended rule; a green happy path does not prove the check is wired.
 - **Implemented RFCs match shipped reality:** when a PR implements a proposed RFC, move and rewrite it as present-tense shipped state in the same diff, then verify paths, names, and mechanisms against the implementation.
 - **Transcript changes:** editor-visible or model-visible changes update snapshots or explain why no snapshot applies. Review golden diffs as behavior changes, not formatting noise.
 - **Bilingual changes:** compare meaning and terminology on both sides; a green pairing hash does not prove translation quality.
diff --git a/docs/cookbook/maintaining-dsh-code-review.md b/docs/cookbook/maintaining-dsh-code-review.md
index 6158af5850..3d83d20bd9 100644
--- a/docs/cookbook/maintaining-dsh-code-review.md
+++ b/docs/cookbook/maintaining-dsh-code-review.md
@@ -1,18 +1,18 @@
 # Maintaining the dsh-code-review skill
 
-The [`dsh-code-review`](../../.agents/skills/dsh-code-review/SKILL.md) skill is kept current by a single designated operator running a private weekly maintenance tool. This cookbook is the entry point for that operator — and for anyone taking over the role — and for repo contributors who want to understand why skill updates arrive as small periodic PRs rather than one-off audits. The workflow itself is specified in the [human-review skill-maintenance RFC](../rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md).
+The [`dsh-code-review`](../../.agents/skills/dsh-code-review/SKILL.md) skill is kept current by a single designated operator running a private periodic maintenance tool. This cookbook is the entry point for that operator — and for anyone taking over the role — and for repo contributors who want to understand why skill updates arrive as small periodic PRs rather than one-off audits. The workflow itself is specified in the [human-review skill-maintenance RFC](../rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md).
 
 ## What the maintainer receives
 
-On the operator's chosen cadence (currently daily at 10:00 local time, with a two-day overlap window) a private tool runs the workflow the RFC describes:
+Run the private tool daily with a two-UTC-day overlap; until the proposed scheduler has completed its acceptance run, the operator invokes the wrapper manually at the same cadence. A manual weekly recovery run uses a seven-day window. The workflow:
 
 1. It selects PRs merged in the chosen window (default two UTC days for the daily cadence, seven for weekly) whose merge commit is reachable from `origin/master`. PRs whose merge commit is not reachable (stacked branches whose parent was squashed) or that exceed a 250-commit acquisition cap are logged to `skipped-pulls.json` and skipped rather than aborting the run.
-2. It collects pre-merge human review feedback (inline comments, review submissions, PR conversation comments) and post-feedback diff evidence.
+2. It collects pre-merge human review feedback with commit anchors (inline comments and review submissions) plus post-feedback diff evidence. It does not acquire PR conversation comments because current GitHub state cannot give them a force-push-safe feedback-time baseline.
 3. Two independently configured reviewer adapters classify provenance and adoption, then classify agreed-adopted items against the current skill.
 4. The primary adapter drafts a complete revised `SKILL.md`; both adapters review the same diff; blocking findings loop until both approve.
 5. `pnpm run doc-sync` and `pnpm run lint` run against the candidate before the tool declares success.
 
-Each run stores its artifacts on the operator's machine. The saved diff and candidate `SKILL.md` land under `~/dsh-code-review-outputs/` named by timestamp; the raw per-adapter I/O, adopted evidence, and consensus/dispute JSON stay in a private temp directory whose path is written to the notification and to the daily log under `~/Library/Logs/dsh-code-review-maintainer/`. The maintenance worktree itself is restored clean after every run so the operator is never tempted to edit the maintenance copy in place.
+Each run stores its artifacts on the operator's machine. The saved diff, candidate `SKILL.md`, and promotion manifest land under `~/dsh-code-review-outputs/` named by timestamp. The manifest records the source master commit and skill blob, source feedback IDs and URLs, landed evidence ranges, adapter verdicts, and gate results; raw per-adapter I/O stays in a private temp directory whose path is written to the notification and to the daily log under `~/Library/Logs/dsh-code-review-maintainer/`. The maintenance worktree itself is restored clean after every run so the operator is never tempted to edit the maintenance copy in place.
 
 ## What the operator does with a candidate diff
 
@@ -24,36 +24,37 @@ When a run produces a candidate, a macOS notification arrives with a `dsh-code-r
    ls ~/dsh-code-review-outputs/                         # every candidate ever produced
    less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.diff
    less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.SKILL.md
+   less ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.manifest.json
    ```
 
-2. **Cross-check against the run artifacts.** Each candidate's per-adapter I/O, consensus, and adopted evidence live under the run's private temp directory (path shown in the log). Spot-check at least one candidate: does the linked human comment actually support the added rule? Does the linked PR actually adopt it?
+2. **Cross-check against the run artifacts.** The promotion manifest maps each proposed rule to source feedback and landed evidence; detailed per-adapter I/O, consensus, and adopted evidence live under the run's private temp directory (path shown in the log). Spot-check at least one candidate: does the linked human comment actually support the added rule? Does the linked PR actually adopt it?
 
 3. **Decide one of three:**
    - **Discard.** Delete the saved candidate. The tool re-considers the same feedback on the next run under whatever the current skill then says.
 
      ```sh
-     rm ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.{diff,SKILL.md}
+     rm ~/dsh-code-review-outputs/2026-07-16T02-00-00Z.{diff,SKILL.md,manifest.json}
      ```
-   - **Batch.** Keep the candidate aside if the update is small and could combine with a future one.
-   - **Promote.** From a clean `master` checkout of the repo, run the promote helper. It creates a branch, copies the saved candidate over the current skill, commits, pushes, and opens a draft PR — the operator still reviews the PR on GitHub and either merges it or closes it.
+   - **Batch.** Keep the candidate aside if the update is small and could combine with a future one. The source-skill check still applies; rerun the analysis or manually rebase and re-review the diff if `master` changes first.
+   - **Promote.** From a clean `master` checkout of the repo, run the promote helper. It refreshes `master`, verifies that the current skill matches the recorded source blob, applies the saved diff, and opens a draft PR whose body carries the manifest's provenance summary. It stops on skill drift rather than overwriting newer guidance; the operator still reviews the PR on GitHub and either merges it or closes it.
 
      ```sh
      cd ~/path/to/deepseek-harness   # clean master
-     dsh-code-review-promote 2026-07-16
+     dsh-code-review-promote 2026-07-16T02-00-00Z
      ```
 
 4. **Do not commit adapter output verbatim.** Small edits during promotion — tightening wording, removing an example that only makes sense with the source PR's context, folding a rule into an existing one — are expected and preserve the "reviewer judgment" the workflow depends on. Amend the branch before merging.
 
 ## When a run produces no candidate
 
-That is the common case. The tool records "no candidate" in its daily log, sends no notification (to avoid alert fatigue), and moves on. Days without a skill update are the workflow behaving correctly, not a stall.
+That is the common case after every nonempty classification stage has produced at least one valid adapter result. The tool records "no candidate" in its daily log, sends no notification (to avoid alert fatigue), and moves on. Days without a skill update are the workflow behaving correctly, not a stall.
 
 ## Interruptions and handoff
 
 The mechanism lives on one machine. Interruptions the operator handles as they arise:
 
 - **Daily run missed.** The two-day overlap window catches one skipped day automatically; longer gaps recover by running the wrapper manually with `DSH_CODE_REVIEW_SINCE=<Nd>`. Overlapping windows are idempotent: guidance already in the current skill is classified `covered` and does not re-enter as a candidate.
-- **Adapter provider outage.** The tool refuses to run when the two reviewer commands resolve to byte-identical executables. A single batch whose adapter response fails schema or id validation is failed closed at the batch level (every item in the batch marked unclear) and the run continues; the raw output is preserved for debugging. A total-provider outage that fails every batch produces a "no candidate" result — retry after the provider is restored.
+- **Adapter provider outage.** The tool refuses to run when the two reviewer commands resolve to byte-identical executables. A single batch whose adapter response fails schema or id validation is failed closed at the batch level (every item in the batch marked unclear) and the run continues; the raw output is preserved for debugging. If either adapter produces no valid result for any nonempty batch in an operation, the run fails, writes a failure record, and notifies the operator; it never collapses a total-provider outage into "no candidate."
 - **Handoff to another maintainer.** Open a follow-up RFC that supersedes the current one: either move the mechanism into the repository or record the new operator's private setup. Do not silently transfer the tool — the "single-maintainer bus factor" in the RFC's Risks section is the reason the handoff needs a documented decision.
 
 ## Where the operator's private setup lives
diff --git a/docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md b/docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md
index 6a760286ff..9629a832e8 100644
--- a/docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md
+++ b/docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md
@@ -8,11 +8,11 @@ The `dsh-code-review` skill records failure modes that require reviewer judgment
 
 ## Proposal
 
-Periodic out-of-repo maintenance. A private tool, kept on the skill maintainer's machine rather than committed to this repository, runs against a clean full-history checkout at refreshed `origin/master` on an operator-chosen cadence — daily and weekly are both safe because the scan is idempotent against the current skill, and the `--since` window is a `--since 2d` overlap for daily or `--since 7d` for weekly. Repeated `--pr` arguments inspect an explicit set. The tool stores no repository cursor. The only artifact that reaches this repository is a working-tree diff to [.agents/skills/dsh-code-review/SKILL.md](../../../../.agents/skills/dsh-code-review/SKILL.md) that the maintainer inspects and, if useful, promotes through the repository's normal PR review.
+Periodic out-of-repo maintenance. A private tool, kept on the skill maintainer's machine rather than committed to this repository, runs against a clean full-history checkout at refreshed `origin/master`. The intended scheduler runs daily with a two-UTC-day overlap; manual runs accept another `--since` duration or repeated `--pr` arguments for an explicit set. The scan is idempotent against the current skill and stores no repository cursor. The only repository file changed by promotion is [.agents/skills/dsh-code-review/SKILL.md](../../../../.agents/skills/dsh-code-review/SKILL.md); the draft PR carries a provenance summary so reviewers can audit the source feedback and adoption evidence without the private adapter logs.
 
 ```mermaid
 flowchart TD
-  A["Maintainer runs the weekly tool on origin/master"] --> B["List PRs merged in the seven-day window"]
+  A["Maintainer or scheduler runs the tool on origin/master"] --> B["List PRs merged in the overlap window"]
   B --> C["Collect pre-merge User feedback and final PR evidence"]
   C --> D["Two reviewers verify provenance and adoption"]
   D --> E{"Both confirm human-authored and adopted?"}
@@ -28,31 +28,35 @@ flowchart TD
 
 ### Acquisition contract
 
-Each selected PR is filtered before any feedback is retrieved: its merge commit must be an ancestor of `origin/master`. Merge-commit reachability is the sole eligibility check — a stacked PR whose direct base is a feature branch is admitted whenever the base has since reached master, because the code the reviewer commented on is now on master regardless of the intermediate stack. A single PR that fails preflight, acquisition, or evidence collection is logged to `skipped-pulls.json` and skipped rather than aborting the whole weekly run. The search stage also fails loud when the window would exceed GitHub's 1,000-result search cap so no merged PR is silently omitted. The acquisition stage then reads complete paginated connections for inline review comments, review submissions, PR conversation comments, and PR commits. It admits feedback only when GitHub reports the actor `type` as `User`, and only when both creation and last-edit timestamps strictly predate the PR merge (an equal-timestamp edit is treated as post-merge); review submissions use GraphQL `lastEditedAt` because the REST representation omits edit time.
+Each selected PR is filtered before any feedback is retrieved: its merge commit must be an ancestor of `origin/master`. Merge-commit reachability is the sole eligibility check — a stacked PR whose direct base is a feature branch is admitted whenever the base has since reached master, because the code the reviewer commented on is now on master regardless of the intermediate stack. A single PR that fails preflight, acquisition, or evidence collection is logged to `skipped-pulls.json` and skipped rather than aborting the whole run. The search stage also fails loud when the window would exceed GitHub's 1,000-result search cap so no merged PR is silently omitted. The acquisition stage reads complete paginated connections for inline review comments, review submissions, and PR commits. PR conversation comments are not acquired because current GitHub state cannot prove which surviving commit preceded them after a force-push, so the adoption contract would exclude them unconditionally. The workflow admits acquired feedback only when GitHub reports the actor `type` as `User`, and only when both creation and last-edit timestamps strictly predate the PR merge (an equal-timestamp edit is treated as post-merge); review submissions use GraphQL `lastEditedAt` because the REST representation omits edit time.
 
 ### Adoption evidence
 
-Each feedback item carries a stable source ID and bounded change evidence. When the reviewer's `commit_id` still belongs to the PR (force-push fail-closed), the tool selects the latest PR commit whose committer timestamp strictly predates the feedback as the baseline — not the reviewer's clicked commit, which may be an older commit — and compares that baseline with the merge commit that actually landed on master. Conversation feedback, force-pushed reviews, and any feedback that predates every PR commit fall to the whole-PR baseline and are deterministically classified `unclear` before any reviewer sees them, because the base-to-head diff cannot prove that a change is causally after the feedback; only feedback-commit baselines reach the adapter for adoption. Merge status, a resolved thread, an author's “fixed” reply, or a same-file edit is context rather than adoption proof; the PR author's own comments never reach the adapter as they cannot be adoption of themselves.
+Each feedback item carries a stable source ID and bounded change evidence. When the reviewer's `commit_id` still belongs to the PR (force-push fail-closed), the tool selects the latest PR commit whose committer timestamp strictly predates the feedback as the baseline — not the reviewer's clicked commit, which may be an older commit — and compares that baseline with the merge commit that actually landed on master. Force-pushed reviews and feedback that predates every surviving PR commit fall to the whole-PR baseline and are deterministically classified `unclear` before any reviewer sees them, because the base-to-head diff cannot prove that a change is causally after the feedback; only feedback-commit baselines reach the adapter for adoption. Merge status, a resolved thread, an author's “fixed” reply, or a same-file edit is context rather than adoption proof; the PR author's own comments never reach the adapter as they cannot be adoption of themselves.
 
 ### Dual-reviewer classification and drafting
 
-Two independently configured reviewer adapters classify every item by provenance (`human-authored`, `forwarded-automation`, or `unclear`) and adoption (`adopted`, `rejected`, or `unclear`). Only matching `human-authored` plus `adopted` verdicts proceed. The adopted set then receives a second independent classification against the current skill: candidate, already covered, implementation-specific, or not feedback. A singleton may qualify; recurrence is not required. Disagreement receives one bounded re-evaluation and remains visible in run artifacts if unresolved. A single batch whose adapter output fails schema or id validation is failed closed at the batch level — every feedback item in it is marked unclear and routed to `excluded` — rather than aborting the whole run; the offending raw output is preserved under the run's private artifacts for debugging.
+Two independently configured reviewer adapters classify every eligible item by provenance (`human-authored`, `forwarded-automation`, or `unclear`) and adoption (`adopted`, `rejected`, or `unclear`). Only matching `human-authored` plus `adopted` verdicts proceed. The adopted set then receives a second independent classification against the current skill: candidate, already covered, implementation-specific, or not feedback. A singleton may qualify; recurrence is not required. Disagreement receives one bounded re-evaluation and remains visible in run artifacts if unresolved. A single batch whose adapter output fails schema or id validation is failed closed at the batch level — every feedback item in it is marked unclear and routed to `excluded` — rather than aborting the whole run; the offending raw output is preserved under the run's private artifacts for debugging. If either adapter returns no valid result for any nonempty batch in an operation, the run exits non-zero and emits a failure record instead of reporting “no candidate.”
 
-The primary adapter drafts from structured agreed guidance, never raw review text. It remains tool-free and read-only by adapter-author contract: it returns complete candidate file content, which the tool validates before writing the sole target. Both adapters then review the same complete skill diff; blocking findings return to a bounded revision loop, and both must approve the same revision. The tool rejects staged changes and edits outside the target skill both before running the documentation and lint gates and again before reporting success, so a gate or concurrent process that adds another path cannot slip through. It restores its own write on failure using best-effort compare-and-swap so a concurrent maintainer edit is not overwritten, produces a reviewed local diff and private run artifacts on success, and never commits, pushes, opens, or merges a PR.
+The primary adapter drafts from structured agreed guidance, never raw review text. It remains tool-free and read-only by adapter-author contract: it returns complete candidate file content, which the tool validates before writing the sole target. Both adapters then review the same complete skill diff; blocking findings return to a bounded revision loop, and both must approve the same revision. The tool rejects staged changes and edits outside the target skill both before running the documentation and lint gates and again before reporting success, so a gate or concurrent process that adds another path cannot slip through. It restores its own write on failure using best-effort compare-and-swap so a concurrent maintainer edit is not overwritten. On success it saves a candidate bundle containing the source `origin/master` commit, source skill blob ID, reviewed diff, complete candidate, source feedback IDs and URLs, landed evidence ranges, adapter verdicts, and gate results; it never commits, pushes, opens, or merges a PR.
 
 ### Reviewer adapter protocol
 
 Each private executable receives a byte-bounded, versioned JSON request on stdin and returns byte-bounded, schema-conforming JSON on stdout. The tool refuses to run when the two reviewer commands resolve to byte-identical executables — a minimum-bar mechanical check; guaranteeing that primary and secondary are backed by independent providers or models is the deployment operator's responsibility. The `access` and `tools` fields are contract markers on the adapter author, not an OS sandbox: reviewer subprocesses spawn with a scrubbed environment, `cwd` set to a private run directory rather than the repository root, and feedback wrapped in a nonce-tagged `<untrusted-feedback nonce="…">` block that every prompt instructs the model to treat as data; the 128-bit nonce prevents an untrusted body from forging the closing tag. Every subprocess uses bounded, abort-aware process-tree cleanup. Adapter authors implement each operation as pure read-only inference — even the `edit` operation returns complete candidate content in JSON, which the tool validates and writes to the sole target. Every production `git`/`gh`/gate spawn also uses the scrubbed environment so a pre-push hook's routing variables cannot silently redirect the maintainer. Candidate writes and the failure rollback use best-effort compare-and-swap against the last written content; the rollback also unstages the target so an adapter- or gate-staged candidate cannot survive a failed run into a later commit.
 
+### Promotion contract
+
+The promote helper starts from a clean checkout at refreshed `origin/master` and refuses to apply a candidate when the current skill blob differs from the bundle's recorded source blob. The operator then reruns the maintenance analysis or manually rebases the diff and repeats the candidate review; the helper never replaces a newer `SKILL.md` with stale complete-file output. After applying a current candidate, it opens a draft PR whose body lists the source feedback URLs or IDs, the landed commit range used as adoption evidence, the originating run, gate results, and any operator edits. Raw adapter prompts and responses remain private, but repository reviewers receive enough provenance to judge whether each proposed rule follows from adopted human feedback.
+
 ### Where the mechanism lives
 
-The tool source, adapter binaries, provider credentials, and the seven-day scheduler are kept private to the maintainer's machine rather than committed to this repository. This document specifies the protocol; the reference implementation is private infrastructure. The mechanism serves a single skill maintained by a single operator, so the ongoing cost of vetting mechanism edits through repository review outweighs any provenance benefit. If the mechanism is ever handed off to a second maintainer, that handoff is a follow-up RFC that revises this decision — the operator doc at [docs/cookbook/maintaining-dsh-code-review.md](../../../cookbook/maintaining-dsh-code-review.md) is the entry point for anyone taking over.
+The tool source, adapter binaries, provider credentials, and intended daily scheduler are kept private to the maintainer's machine rather than committed to this repository. This document specifies the protocol; the reference implementation is private infrastructure. The mechanism serves a single skill maintained by a single operator, so the ongoing cost of vetting mechanism edits through repository review outweighs any provenance benefit. If the mechanism is ever handed off to a second maintainer, that handoff is a follow-up RFC that revises this decision — the operator doc at [docs/cookbook/maintaining-dsh-code-review.md](../../../cookbook/maintaining-dsh-code-review.md) is the entry point for anyone taking over.
 
 ## Alternatives considered
 
 - **Ship the tool inside this repository.** Rejected for a single-maintainer scope: repository maintenance overhead (typecheck, lint, coverage, cross-cutting refactors) would exceed the value of committed provenance. Retained option for a later handoff.
 - **Record every feedback-time PR head** — rejected: it improves causal isolation but requires a continuously running observer, durable event state, retries, and force-push reconciliation. Periodic maintenance uses reviewed-commit evidence where available and fails closed on broader whole-PR evidence.
-- **Persist a processed-PR cursor** — rejected: an overlapping seven-day scan is cheap and naturally idempotent against the current skill, while cursor state creates recovery and missed-event problems.
+- **Persist a processed-PR cursor** — rejected: an overlapping time-window scan is cheap and naturally idempotent against the current skill, while cursor state creates recovery and missed-event problems.
 - **Run on every new comment** — rejected: review waves produce many related comments and lack the final artifact needed to judge adoption.
 - **Treat merge or thread resolution as adoption** — rejected: a PR can merge with rejected, superseded, or intentionally unresolved feedback.
 - **Create or merge repository changes automatically** — rejected: the tool first needs a track record of useful periodic output. The maintainer inspects and promotes the local diff through normal repository review.
@@ -66,6 +70,7 @@ Promotion from `proposed/` to `implemented/` requires all of the following to be
 - The private tool runs from a clean detached checkout at refreshed `origin/master` and either reports "no candidate" or produces a working-tree diff limited to `.agents/skills/dsh-code-review/SKILL.md`. **Observed on 2026-07-15:** 62 merged PRs scanned, 5 skipped (unreachable merge commit or >250-commit acquisition cap), 426 human feedback items considered, 0 candidates surfaced.
 - Both reviewer adapters are independently configured (distinct providers or models) and complete an analyze / adopt / review pass without user intervention. **Observed on 2026-07-15:** distinct primary/secondary adapters completed adoption + analysis in ~8 minutes; batch fail-closed handled one adapter id-hallucination without aborting the run.
 - A scheduler triggers the tool without an interactive terminal, and a candidate diff (or a "no candidate" record) reaches the operator through a durable notification channel.
+- The promote helper rejects a candidate after the source skill changes, and a current candidate opens a draft PR with the provenance summary defined above.
 - At least one candidate diff produced by this workflow is inspected by the operator and promoted to `master` through a normal repository PR review. That PR is the evidence that the workflow can turn adopted feedback into shipped skill guidance.
 
 ## Risks
@@ -73,5 +78,5 @@ Promotion from `proposed/` to `implemented/` requires all of the following to be
 - **Causality inferred from committer timestamps.** The feedback-commit baseline is selected by comparing GitHub commit timestamps with feedback creation timestamps; committer clock skew and rewrites still leave a residual false-adoption window. Cross-referencing GitHub's PR event stream would tighten this but requires event acquisition beyond the scope of the periodic tool.
 - **Two-non-candidate classifications routed to `excluded` without a dispute round.** When both classifiers say "not a candidate" but disagree on which non-candidate reason applies (for example `covered` vs `specific`), the item is excluded rather than re-evaluated. Both classifiers agree the item does not become new reviewer behavior, so a dispute round would not change the outcome.
 - **Dual-reviewer independence beyond byte-hash distinctness is a deployment contract.** The tool refuses to run when the two commands resolve to byte-identical executables, but cannot verify that two distinct wrappers back different providers or models. Operators must configure independent primary and secondary adapters.
-- **Best-effort compare-and-swap for candidate writes and rollback.** File-based CAS on POSIX is not truly atomic; the window is one event-loop tick. The tool targets single-user weekly maintenance and a truly concurrent editor is out of scope.
+- **Best-effort compare-and-swap for candidate writes and rollback.** File-based CAS on POSIX is not truly atomic; the window is one event-loop tick. The tool targets single-user periodic maintenance and a truly concurrent editor is out of scope.
 - **Single-maintainer bus factor.** Because the mechanism lives on one machine, its interruption stops skill maintenance entirely until the operator restores service or hands off to a new maintainer through a follow-up RFC.

From d340fb2999690d881093a033e56b2cbbe3d26229 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 15 Jul 2026 21:43:32 +0800
Subject: [PATCH 40/48] docs(rfc): isolate PR-owned adoption evidence

Comparing a feedback-time PR commit directly with the landing merge lets unrelated target-branch changes satisfy a review comment and creates false adoption evidence.

Define feedback-time and final PR-specific patch snapshots, fail closed when the landing shape cannot be reconstructed, and require a target-only negative control before implementation.
---
 docs/cookbook/maintaining-dsh-code-review.md                 | 2 +-
 .../process/2026-07-13-human-review-skill-maintenance.md     | 5 +++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/cookbook/maintaining-dsh-code-review.md b/docs/cookbook/maintaining-dsh-code-review.md
index 3d83d20bd9..5a6c2df120 100644
--- a/docs/cookbook/maintaining-dsh-code-review.md
+++ b/docs/cookbook/maintaining-dsh-code-review.md
@@ -7,7 +7,7 @@ The [`dsh-code-review`](../../.agents/skills/dsh-code-review/SKILL.md) skill is
 Run the private tool daily with a two-UTC-day overlap; until the proposed scheduler has completed its acceptance run, the operator invokes the wrapper manually at the same cadence. A manual weekly recovery run uses a seven-day window. The workflow:
 
 1. It selects PRs merged in the chosen window (default two UTC days for the daily cadence, seven for weekly) whose merge commit is reachable from `origin/master`. PRs whose merge commit is not reachable (stacked branches whose parent was squashed) or that exceed a 250-commit acquisition cap are logged to `skipped-pulls.json` and skipped rather than aborting the run.
-2. It collects pre-merge human review feedback with commit anchors (inline comments and review submissions) plus post-feedback diff evidence. It does not acquire PR conversation comments because current GitHub state cannot give them a force-push-safe feedback-time baseline.
+2. It collects pre-merge human review feedback with commit anchors (inline comments and review submissions), then compares feedback-time and final landed PR patches. It does not acquire PR conversation comments because current GitHub state cannot give them a force-push-safe feedback-time baseline, and it excludes target-branch-only changes from adoption evidence.
 3. Two independently configured reviewer adapters classify provenance and adoption, then classify agreed-adopted items against the current skill.
 4. The primary adapter drafts a complete revised `SKILL.md`; both adapters review the same diff; blocking findings loop until both approve.
 5. `pnpm run doc-sync` and `pnpm run lint` run against the candidate before the tool declares success.
diff --git a/docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md b/docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md
index 9629a832e8..8098247fdf 100644
--- a/docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md
+++ b/docs/rfc/proposed/process/2026-07-13-human-review-skill-maintenance.md
@@ -28,11 +28,11 @@ flowchart TD
 
 ### Acquisition contract
 
-Each selected PR is filtered before any feedback is retrieved: its merge commit must be an ancestor of `origin/master`. Merge-commit reachability is the sole eligibility check — a stacked PR whose direct base is a feature branch is admitted whenever the base has since reached master, because the code the reviewer commented on is now on master regardless of the intermediate stack. A single PR that fails preflight, acquisition, or evidence collection is logged to `skipped-pulls.json` and skipped rather than aborting the whole run. The search stage also fails loud when the window would exceed GitHub's 1,000-result search cap so no merged PR is silently omitted. The acquisition stage reads complete paginated connections for inline review comments, review submissions, and PR commits. PR conversation comments are not acquired because current GitHub state cannot prove which surviving commit preceded them after a force-push, so the adoption contract would exclude them unconditionally. The workflow admits acquired feedback only when GitHub reports the actor `type` as `User`, and only when both creation and last-edit timestamps strictly predate the PR merge (an equal-timestamp edit is treated as post-merge); review submissions use GraphQL `lastEditedAt` because the REST representation omits edit time.
+Each selected PR is filtered before any feedback is retrieved: its merge commit must be an ancestor of `origin/master`. Merge-commit reachability is the sole eligibility check — a stacked PR whose direct base is a feature branch is admitted whenever the base has since reached master, because the code the reviewer commented on is now on master regardless of the intermediate stack. The tool also resolves the landing merge's target parent; a landing shape it cannot reconstruct is logged to `skipped-pulls.json` and skipped. A single PR that fails preflight, acquisition, or evidence collection is skipped rather than aborting the whole run. The search stage fails loud when the window would exceed GitHub's 1,000-result search cap so no merged PR is silently omitted. The acquisition stage reads complete paginated connections for inline review comments, review submissions, and PR commits. PR conversation comments are not acquired because current GitHub state cannot prove which surviving commit preceded them after a force-push, so the adoption contract would exclude them unconditionally. The workflow admits acquired feedback only when GitHub reports the actor `type` as `User`, and only when both creation and last-edit timestamps strictly predate the PR merge (an equal-timestamp edit is treated as post-merge); review submissions use GraphQL `lastEditedAt` because the REST representation omits edit time.
 
 ### Adoption evidence
 
-Each feedback item carries a stable source ID and bounded change evidence. When the reviewer's `commit_id` still belongs to the PR (force-push fail-closed), the tool selects the latest PR commit whose committer timestamp strictly predates the feedback as the baseline — not the reviewer's clicked commit, which may be an older commit — and compares that baseline with the merge commit that actually landed on master. Force-pushed reviews and feedback that predates every surviving PR commit fall to the whole-PR baseline and are deterministically classified `unclear` before any reviewer sees them, because the base-to-head diff cannot prove that a change is causally after the feedback; only feedback-commit baselines reach the adapter for adoption. Merge status, a resolved thread, an author's “fixed” reply, or a same-file edit is context rather than adoption proof; the PR author's own comments never reach the adapter as they cannot be adoption of themselves.
+Each feedback item carries a stable source ID and bounded change evidence. When the reviewer's `commit_id` still belongs to the PR (force-push fail-closed), the tool selects the latest PR commit whose committer timestamp strictly predates the feedback as the baseline — not the reviewer's clicked commit, which may be an older commit. It never compares that baseline directly with the landing merge: such a diff includes unrelated changes from an advancing target branch. Instead, it gives the adoption reviewers two PR-specific patch snapshots. Let `B` be the feedback baseline, `T` the landing merge's target parent, and `M` the landing merge. The feedback-time snapshot is the tree diff from `merge-base(B, T)` to `B`; the final snapshot is the tree diff from `T` to `M`. A target-only change therefore appears in neither PR patch, while a change added to the PR after feedback appears only in the final snapshot. Force-pushed reviews, feedback that predates every surviving PR commit, and landing shapes whose target parent cannot be reconstructed are deterministically classified `unclear` before any reviewer sees them. Merge status, a resolved thread, an author's “fixed” reply, or a same-file edit is context rather than adoption proof; the PR author's own comments never reach the adapter as they cannot be adoption of themselves.
 
 ### Dual-reviewer classification and drafting
 
@@ -70,6 +70,7 @@ Promotion from `proposed/` to `implemented/` requires all of the following to be
 - The private tool runs from a clean detached checkout at refreshed `origin/master` and either reports "no candidate" or produces a working-tree diff limited to `.agents/skills/dsh-code-review/SKILL.md`. **Observed on 2026-07-15:** 62 merged PRs scanned, 5 skipped (unreachable merge commit or >250-commit acquisition cap), 426 human feedback items considered, 0 candidates surfaced.
 - Both reviewer adapters are independently configured (distinct providers or models) and complete an analyze / adopt / review pass without user intervention. **Observed on 2026-07-15:** distinct primary/secondary adapters completed adoption + analysis in ~8 minutes; batch fail-closed handled one adapter id-hallucination without aborting the run.
 - A scheduler triggers the tool without an interactive terminal, and a candidate diff (or a "no candidate" record) reaches the operator through a durable notification channel.
+- A controlled acquisition case advances the target branch with a feedback-matching change after the feedback baseline; the reviewer evidence excludes that target-only change while retaining a later PR-owned change.
 - The promote helper rejects a candidate after the source skill changes, and a current candidate opens a draft PR with the provenance summary defined above.
 - At least one candidate diff produced by this workflow is inspected by the operator and promoted to `master` through a normal repository PR review. That PR is the evidence that the workflow can turn adopted feedback into shipped skill guidance.
 

From b06ae91fa8acb38cd62c1b5e23992d95dc032201 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 15 Jul 2026 21:45:30 +0800
Subject: [PATCH 41/48] fix(tasks): address task API review feedback

The public kill result used the awkward phrase already-terminal. Rename it to already-finished and keep the model-facing response aligned; not-alive would be inaccurate because a force-failed registry record can still correspond to orphaned producer work.

Task kinds were open strings even though producer namespaces are an extension point. Add the merge-extensible TaskKindMap and derived TaskKind, cover consumer declarations in task and bundle tests, and retain the runtime non-empty check for untyped callers.

With exactOptionalPropertyTypes, owner?: Agent | undefined allowed an explicit undefined value that no caller needs. Tighten the property to owner?: Agent so unowned work is expressed by omitting it.

Record the requested task-service/backend split as a follow-up, using a systemd-backed runtime as a concrete candidate without guessing its durability and ownership contract in this PR. Regenerate the type and Cordis catalogs so public docs match the declarations.
---
 docs/cordis-catalog/services.md               |  4 ++--
 docs/core-data-structures/tasks.md            | 23 ++++++++++++------
 ...06-20-generic-long-running-tool-runtime.md |  8 +++----
 .../cordis/tool-cordis/src/api-catalog.ts     | 14 ++++++++---
 .../agent-spine-demo/tests/agent-core.spec.ts |  6 +++++
 packages/tasks/tasks/README.md                |  3 ++-
 packages/tasks/tasks/src/index.ts             | 14 +++++++----
 packages/tasks/tasks/src/types.ts             | 24 ++++++++++++++-----
 packages/tasks/tasks/tests/tasks.spec.ts      | 19 ++++++++++-----
 packages/tasks/tool-tasks/src/index.ts        |  2 +-
 .../tasks/tool-tasks/tests/tool-tasks.spec.ts |  2 +-
 scripts/type-equiv.manifest.json              |  1 +
 12 files changed, 84 insertions(+), 36 deletions(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 19c09d944b..18e00b7904 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -251,7 +251,7 @@ start(spec: TaskStart): TaskId
 list(caller?: Agent): TaskSnapshot[]
 get(id: TaskId, caller?: Agent): TaskSnapshot
 read(id: TaskId, caller?: Agent): TaskRead
-kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-terminal'
+kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
 async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
 onTaskDone(listener: TaskDoneListener): () => void
 attachSurface(name: string): () => void
@@ -259,7 +259,7 @@ attachSurface(name: string): () => void
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/tasks/tasks/src/index.ts:72`](../../packages/tasks/tasks/src/index.ts)
+Source: [`packages/tasks/tasks/src/index.ts:76`](../../packages/tasks/tasks/src/index.ts)
 
 ## `ctx.tools` — `ToolRegistry`
 
diff --git a/docs/core-data-structures/tasks.md b/docs/core-data-structures/tasks.md
index 0f84ac33b4..0482912af7 100644
--- a/docs/core-data-structures/tasks.md
+++ b/docs/core-data-structures/tasks.md
@@ -4,7 +4,16 @@ Types shared by long-running producers, `ctx.tasks`, and task control surfaces.
 
 ## Ids and status
 
-`TaskId` is a [branded id](core.md#branded-ids) generated as `<kind>-N`. Access control relies on owner authorization, not id secrecy. `TaskStatus` is `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`; producer-specific facts belong in `TaskSnapshot.detail`.
+`TaskId` is a [branded id](core.md#branded-ids) generated as `<kind>-N`. Access control relies on owner authorization, not id secrecy. `TaskKind` derives from a merge-extensible map; the registry treats kinds as opaque id namespaces.
+
+```ts type-equiv
+interface TaskKindMap {
+  bash: 'bash'
+  subagent: 'subagent'
+}
+```
+
+`TaskStatus` is `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`; producer-specific facts belong in `TaskSnapshot.detail`.
 
 ## Producer contract
 
@@ -12,17 +21,17 @@ Types shared by long-running producers, `ctx.tasks`, and task control surfaces.
 
 ```ts type-equiv
 interface TaskStart {
-  /** Producer kind — also the id prefix (`bash`, `subagent`, …). Non-empty. */
-  kind: string
+  /** Producer kind — also the id prefix (`bash`, `subagent`, …). */
+  kind: TaskKind
   /** One-line model-facing label (the command; the delegation description). */
   label: string
   /**
    * Owning live agent. Access is fenced by its session id, and agent disposal
    * cancels and awaits the task. The instance must be the one currently
-   * registered under its agent id. `undefined` creates an unowned task, open to
-   * any caller until service disposal.
+   * registered under its agent id. Omitting the owner creates an unowned task,
+   * open to any caller until service disposal.
    */
-  owner?: Agent | undefined
+  owner?: Agent
   /**
    * Start the work after preflight and synchronously return its hooks. Called
    * once; a throw leaves nothing registered, and the producer must clean up any
@@ -77,7 +86,7 @@ interface TaskSnapshot {
   /** The registry-issued id (`<kind>-N`). */
   id: TaskId
   /** The producer kind the task was registered with. */
-  kind: string
+  kind: TaskKind
   /** The producer-supplied one-line label. */
   label: string
   /**
diff --git a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
index 64c5dff5a4..c99eb9f0fe 100644
--- a/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
+++ b/docs/rfc/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md
@@ -17,7 +17,7 @@ The `tasks/` package group owns background-task semantics:
 
 Long-running tools are producers. `dsh-tool-bash` adapts a `BashProcess` into incremental output and process cancellation; `dsh-tool-subagent` adapts a child run into final output and child disposal. The execution seams remain independent of sessions and the task registry.
 
-`TaskService` is a concrete service. There is one in-process implementation, so an interface/backend package split would be speculative. A durable or remote implementation can introduce that seam when its lifecycle requirements are known.
+`TaskService` is a concrete, process-local service. TODO(task-service-backend): separate its public contract from the implementation when a second backend defines the required lifecycle; a systemd-backed runtime is one plausible driver, but this PR does not speculate about its durability, reconnect, ownership, or observation semantics.
 
 ## Runtime contract
 
@@ -29,7 +29,7 @@ The producer hooks define three responsibilities:
 - `done` never rejects and settles only after the producer has released the task's resources.
 - Optional `readOutput()` returns the next consuming output delta. Omitting it declares a final-output task whose terminal result comes from `TaskOutcome.output`.
 
-Statuses are `running`, `stopping`, `completed`, `killed`, and `failed`. Producer-specific information such as an exit code or stop reason belongs in `detail`; the registry does not interpret it. Task ids are branded and generated as `<kind>-N`, with a counter per kind.
+Statuses are `running`, `stopping`, `completed`, `killed`, and `failed`. Producer-specific information such as an exit code or stop reason belongs in `detail`; the registry does not interpret it. Task kinds form a merge-extensible string union, and task ids are branded and generated as `<kind>-N`, with a counter per kind.
 
 The runtime attaches one continuation to `done`, records the first terminal outcome, resolves waiters, and invokes completion listeners with per-listener error containment. First-wins settlement matters during teardown: if `cancel` throws, the runtime force-fails the record and warns that work may be orphaned rather than waiting forever for a promise that may never settle. A later producer outcome cannot overwrite that diagnosis or notify twice. A `cancel` that returns without eventually settling `done` still blocks teardown because the runtime cannot distinguish it from a slow, valid stop.
 
@@ -95,9 +95,9 @@ For background subagents, `dsh-tool-subagent` creates a task-owned `AbortControl
 
 Separate bash and subagent output/stop tools duplicate ids, isolation, cleanup, notification, and guidance while increasing the model's schema and protocol burden. One runtime keeps execution-specific behavior in producers without cloning the task lifecycle.
 
-### An abstract task-runtime backend
+### An immediate abstract task-runtime backend
 
-No second backend exists. Durable work also changes owner and restart semantics, so its design should extract an interface from concrete requirements rather than preserve this implementation speculatively.
+The current `TaskStart.run()` contract passes in-process callbacks and exact `Agent` objects. A durable backend changes identity, restart, ownership, and observation semantics, so extracting an interface before a second implementation exists would freeze the wrong boundary.
 
 ### Consumer-owned authorization or cleanup events
 
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 9401425dd3..51b4a5155f 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -216,7 +216,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       'list(caller?: Agent): TaskSnapshot[]',
       'get(id: TaskId, caller?: Agent): TaskSnapshot',
       'read(id: TaskId, caller?: Agent): TaskRead',
-      'kill(id: TaskId, caller?: Agent, reason?: string): \'requested\' | \'already-terminal\'',
+      'kill(id: TaskId, caller?: Agent, reason?: string): \'requested\' | \'already-finished\'',
       'async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>',
       'onTaskDone(listener: TaskDoneListener): () => void',
       'attachSurface(name: string): () => void',
@@ -933,6 +933,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'TaskId',
     declaration: 'export type TaskId = Branded<\'TaskId\'>;',
   },
+  {
+    name: 'TaskKind',
+    declaration: 'export type TaskKind = TaskKindMap[keyof TaskKindMap];',
+  },
+  {
+    name: 'TaskKindMap',
+    declaration: 'export interface TaskKindMap {\n    bash: \'bash\';\n    subagent: \'subagent\';\n}',
+  },
   {
     name: 'TaskOutcome',
     declaration: 'export interface TaskOutcome {\n    status: \'completed\' | \'killed\' | \'failed\';\n    detail?: string;\n    output?: string;\n}',
@@ -943,11 +951,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'TaskSnapshot',
-    declaration: 'export interface TaskSnapshot {\n    id: TaskId;\n    kind: string;\n    label: string;\n    ownerSession?: SessionId;\n    status: TaskStatus;\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n    reported: boolean;\n}',
+    declaration: 'export interface TaskSnapshot {\n    id: TaskId;\n    kind: TaskKind;\n    label: string;\n    ownerSession?: SessionId;\n    status: TaskStatus;\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n    reported: boolean;\n}',
   },
   {
     name: 'TaskStart',
-    declaration: 'export interface TaskStart {\n    kind: string;\n    label: string;\n    owner?: Agent | undefined;\n    run(): TaskHooks;\n}',
+    declaration: 'export interface TaskStart {\n    kind: TaskKind;\n    label: string;\n    owner?: Agent;\n    run(): TaskHooks;\n}',
   },
   {
     name: 'TaskStatus',
diff --git a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
index a09479bdb9..74dbfe5484 100644
--- a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
+++ b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
@@ -9,6 +9,12 @@ import * as agentCore from '../src/index.ts'
 import { AgentId, agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
 import { CallId, type Message } from '@deepseek-ai/dsh-llm'
 
+declare module '@deepseek-ai/dsh-tasks' {
+  interface TaskKindMap {
+    probe: 'probe'
+  }
+}
+
 async function composePrefix(ctx: Context, cwd: string): Promise<Message[]> {
   const agent = { session: { header: { cwd } } } as unknown as Agent
   const empty: Message[] = []
diff --git a/packages/tasks/tasks/README.md b/packages/tasks/tasks/README.md
index e9ddf43256..b061038714 100644
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-tasks
 
-The process-local background task registry (`ctx.tasks`). It gives long-running producers shared ids, owner isolation, reads, cancellation, waiting, notices, and cleanup. The service is concrete; a durable backend can introduce an interface when its different lifecycle is specified.
+The process-local background task registry (`ctx.tasks`). It gives long-running producers shared ids, owner isolation, reads, cancellation, waiting, notices, and cleanup. Producer plugins extend `TaskKindMap` with their opaque id namespace.
 
 ## Service API
 
@@ -29,6 +29,7 @@ Indirectly, through producer plugins and [`dsh-tool-tasks`](../tool-tasks/README
 ## Known Limitations and Deferred Work
 
 - **Tasks are process-local** — durable or cross-restart execution needs a separate lifecycle.
+- **The service and implementation are not split** — a second backend must define the lifecycle that shapes that boundary.
 - **Stream output has one consuming cursor** — independent observers need a cursor or snapshot API.
 - **Foreground work cannot be promoted** — producers choose foreground or background before starting.
 - **A silently ineffective cancel can stall teardown** — only an explicit throw can be force-failed safely.
diff --git a/packages/tasks/tasks/src/index.ts b/packages/tasks/tasks/src/index.ts
index 68300a7079..e9c896c3a1 100644
--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -13,12 +13,14 @@ import { Context, Service } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
 import { TaskId } from './types.ts'
-import type { TaskDoneListener, TaskOutcome, TaskRead, TaskSnapshot, TaskStart, TaskStatus } from './types.ts'
+import type { TaskDoneListener, TaskKind, TaskOutcome, TaskRead, TaskSnapshot, TaskStart, TaskStatus } from './types.ts'
 
 export { TaskId } from './types.ts'
 export type {
   TaskDoneListener,
   TaskHooks,
+  TaskKind,
+  TaskKindMap,
   TaskOutcome,
   TaskRead,
   TaskSnapshot,
@@ -38,7 +40,7 @@ export const TASK_WAIT_TIMEOUT = 'TASK_WAIT_TIMEOUT'
 /** The registry's mutable per-task record (never handed out — see {@link TaskService.snapshot}). */
 interface TrackedTask {
   id: TaskId
-  kind: string
+  kind: TaskKind
   label: string
   /** Exact lifecycle owner; session-id authorization is derived from it. */
   owner: Agent | undefined
@@ -69,6 +71,8 @@ function isTerminal(status: TaskStatus): boolean {
  * The `tasks` service: the runtime-global background task registry. See the
  * module doc for the ownership, isolation, and lifecycle contracts.
  */
+// TODO(task-service-backend): Separate the service contract from this
+// process-local implementation when a second backend defines its lifecycle.
 export class TaskService extends Service {
   private store = new Map<TaskId, TrackedTask>()
   private counters = new Map<string, number>()
@@ -191,14 +195,14 @@ export class TaskService extends Service {
    * @param id - task to cancel.
    * @param caller - killing agent checked against the owner.
    * @param reason - logged reason forwarded to the producer.
-   * @returns `requested` for live work, otherwise `already-terminal`.
+   * @returns `requested` for live work, otherwise `already-finished`.
    */
-  kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-terminal' {
+  kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished' {
     const task = this.expect(id)
     this.assertAccess(task, caller)
     if (isTerminal(task.status)) {
       task.reported = true
-      return 'already-terminal'
+      return 'already-finished'
     }
     // Cancel first so a throw leaves both lifecycle and notice state unchanged.
     task.cancel(reason)
diff --git a/packages/tasks/tasks/src/types.ts b/packages/tasks/tasks/src/types.ts
index 34d0189913..96316260ec 100644
--- a/packages/tasks/tasks/src/types.ts
+++ b/packages/tasks/tasks/src/types.ts
@@ -29,6 +29,18 @@ export function TaskId(id: string): TaskId {
  */
 export type TaskStatus = 'running' | 'stopping' | 'completed' | 'killed' | 'failed'
 
+/**
+ * Producer-defined task kinds. Plugins extend this map by declaration merging;
+ * the registry treats every value as an opaque id namespace.
+ */
+export interface TaskKindMap {
+  bash: 'bash'
+  subagent: 'subagent'
+}
+
+/** The merge-extensible union of registered producer kind names. */
+export type TaskKind = TaskKindMap[keyof TaskKindMap]
+
 /** Terminal result supplied by a producer through {@link TaskHooks.done}. */
 export interface TaskOutcome {
   /** How the task ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */
@@ -45,17 +57,17 @@ export interface TaskOutcome {
  * execution resources while the runtime owns identity and lifecycle state.
  */
 export interface TaskStart {
-  /** Producer kind — also the id prefix (`bash`, `subagent`, …). Non-empty. */
-  kind: string
+  /** Producer kind — also the id prefix (`bash`, `subagent`, …). */
+  kind: TaskKind
   /** One-line model-facing label (the command; the delegation description). */
   label: string
   /**
    * Owning live agent. Access is fenced by its session id, and agent disposal
    * cancels and awaits the task. The instance must be the one currently
-   * registered under its agent id. `undefined` creates an unowned task, open to
-   * any caller until service disposal.
+   * registered under its agent id. Omitting the owner creates an unowned task,
+   * open to any caller until service disposal.
    */
-  owner?: Agent | undefined
+  owner?: Agent
   /**
    * Start the work after preflight and synchronously return its hooks. Called
    * once; a throw leaves nothing registered, and the producer must clean up any
@@ -94,7 +106,7 @@ export interface TaskSnapshot {
   /** The registry-issued id (`<kind>-N`). */
   id: TaskId
   /** The producer kind the task was registered with. */
-  kind: string
+  kind: TaskKind
   /** The producer-supplied one-line label. */
   label: string
   /**
diff --git a/packages/tasks/tasks/tests/tasks.spec.ts b/packages/tasks/tasks/tests/tasks.spec.ts
index b9b6cfdf01..f21eb9c433 100644
--- a/packages/tasks/tasks/tests/tasks.spec.ts
+++ b/packages/tasks/tasks/tests/tasks.spec.ts
@@ -4,7 +4,13 @@ import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import TaskService, { TaskId } from '@deepseek-ai/dsh-tasks'
-import type { TaskHooks, TaskOutcome, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks'
+import type { TaskHooks, TaskKind, TaskOutcome, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks'
+
+declare module '@deepseek-ai/dsh-tasks' {
+  interface TaskKindMap {
+    workflow: 'workflow'
+  }
+}
 
 const agentScopeDisposers = new WeakMap<Agent, () => Promise<void>>()
 
@@ -81,7 +87,7 @@ describe('TaskService.start', () => {
 
   it('rejects an empty kind and an empty label', async () => {
     const ctx = await harness()
-    expect(() => ctx.tasks.start(producer({ kind: '' }).spec)).toThrow('invalid task kind')
+    expect(() => ctx.tasks.start(producer({ kind: '' as TaskKind }).spec)).toThrow('invalid task kind')
     expect(() => ctx.tasks.start(producer({ label: '' }).spec)).toThrow('invalid task label')
   })
 
@@ -90,6 +96,7 @@ describe('TaskService.start', () => {
     expect(ctx.tasks.start(producer().spec)).toBe('bash-1')
     expect(ctx.tasks.start(producer().spec)).toBe('bash-2')
     expect(ctx.tasks.start(producer({ kind: 'subagent' }).spec)).toBe('subagent-1')
+    expect(ctx.tasks.start(producer({ kind: 'workflow' }).spec)).toBe('workflow-1')
   })
 })
 
@@ -222,13 +229,13 @@ describe('TaskService.kill', () => {
     expect(seen[0]).toMatchObject({ id, status: 'killed', reported: true })
   })
 
-  it('reports an already-terminal task instead of failing', async () => {
+  it('reports an already-finished task instead of failing', async () => {
     const ctx = await harness()
     const p = producer()
     const id = ctx.tasks.start(p.spec)
     p.settle({ status: 'completed' })
     await tick()
-    expect(ctx.tasks.kill(id)).toBe('already-terminal')
+    expect(ctx.tasks.kill(id)).toBe('already-finished')
   })
 
   it('propagates a throwing producer cancel and leaves the task untouched', async () => {
@@ -254,7 +261,7 @@ describe('TaskService.kill', () => {
     expect(seen[0]).toMatchObject({ id, reported: false }) // notice would still fire
 
     broken = false
-    expect(ctx.tasks.kill(id)).toBe('already-terminal')
+    expect(ctx.tasks.kill(id)).toBe('already-finished')
   })
 })
 
@@ -299,7 +306,7 @@ describe('TaskService.wait', () => {
     expect(ctx.tasks.get(id).status).toBe('running')
   })
 
-  it('returns immediately for an already-terminal task', async () => {
+  it('returns immediately for an already-finished task', async () => {
     const ctx = await harness()
     const p = producer()
     const id = ctx.tasks.start(p.spec)
diff --git a/packages/tasks/tool-tasks/src/index.ts b/packages/tasks/tool-tasks/src/index.ts
index f0de782eea..2d556cada9 100644
--- a/packages/tasks/tool-tasks/src/index.ts
+++ b/packages/tasks/tool-tasks/src/index.ts
@@ -136,7 +136,7 @@ export function apply(ctx: Context, config: Config): void {
     execute(args, exec) {
       const id = validateTaskId(args.task_id)
       const result = ctx.tasks.kill(id, exec.agent, args.reason)
-      if (result === 'already-terminal') {
+      if (result === 'already-finished') {
         // A snapshot describes terminal state without consuming pending output.
         const snapshot = ctx.tasks.get(id, exec.agent)
         return Promise.resolve([{ type: 'text', text: `task ${id} had already finished ${statusLine(snapshot)}` }])
diff --git a/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
index d78bd1668a..1b5e221a3c 100644
--- a/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
+++ b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
@@ -192,7 +192,7 @@ describe('task_kill', () => {
     expect(p.cancels).toEqual(['superseded'])
   })
 
-  it('reports an already-terminal task without consuming its pending delta', async () => {
+  it('reports an already-finished task without consuming its pending delta', async () => {
     const { ctx } = await setup()
     let delta = 'unread tail'
     const p = producer({ readOutput: () => { const d = delta; delta = ''; return d } })
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index b270dd50bf..c3e4533ba5 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -91,6 +91,7 @@
     { "doc": "docs/core-data-structures/bash.md", "symbol": "BashProcess", "source": "packages/bash/bash/src/types.ts" },
     { "doc": "docs/core-data-structures/bash.md", "symbol": "BashProcessRead", "source": "packages/bash/bash/src/types.ts" },
 
+    { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskKindMap", "source": "packages/tasks/tasks/src/types.ts" },
     { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskStart", "source": "packages/tasks/tasks/src/types.ts" },
     { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskHooks", "source": "packages/tasks/tasks/src/types.ts" },
     { "doc": "docs/core-data-structures/tasks.md", "symbol": "TaskOutcome", "source": "packages/tasks/tasks/src/types.ts" },

From cd092e70ad096cdf1ab5d183f45d70b8712eb421 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 15 Jul 2026 21:56:46 +0800
Subject: [PATCH 42/48] docs(skill): require critical prose review

A source-of-truth link did not make the review obligation explicit, so reviewers could treat green documentation checks as sufficient. Make dsh-prose-standard a blocking requirement for every added or changed prose form and require semantic comparison with the owning code or behavior.
---
 .agents/skills/dsh-code-review/SKILL.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/.agents/skills/dsh-code-review/SKILL.md b/.agents/skills/dsh-code-review/SKILL.md
index 8059950d8f..2b562cc321 100644
--- a/.agents/skills/dsh-code-review/SKILL.md
+++ b/.agents/skills/dsh-code-review/SKILL.md
@@ -19,10 +19,11 @@ description: Use when reviewing a pull request in the deepseek-harness repo —
 
 ## Blocking requirements
 
-1. **Docs match the code.** Config, defaults, errors, wire fields, events, and public behavior update the package README and JSDoc in the same diff. Comments state non-obvious contracts; flag implementation narration, test walkthroughs, review history, and duplicated rationale for deletion or a link to their one home.
-2. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [core-data-structures](../../../docs/core-data-structures/core.md) page and any `type-equiv` entry. Internal types need no catalog entry.
-3. **Registrations clean up.** A new registry contribution has a test that disposes its owner and observes removal.
-4. **Required gates pass.** Trust the [current readiness sequence](../../../AGENTS.md#run-the-ci-gates-locally-before-marking-a-pr-ready) and `pnpm run check:pre-push` for their enforced inventory; review the semantic gaps they cannot detect.
+1. **New prose receives semantic review.** Use [dsh-prose-standard](../dsh-prose-standard/SKILL.md) to critically review every added or changed Markdown passage, JSDoc, comment, prompt, description, diagnostic, and visible string. Verify required coverage, accuracy, placement, and editorial quality against the owning code or behavior; automated checks do not establish those properties.
+2. **Docs match the code.** Config, defaults, errors, wire fields, events, and public behavior update the package README and JSDoc in the same diff. Comments state non-obvious contracts; flag implementation narration, test walkthroughs, review history, and duplicated rationale for deletion or a link to their one home.
+3. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [core-data-structures](../../../docs/core-data-structures/core.md) page and any `type-equiv` entry. Internal types need no catalog entry.
+4. **Registrations clean up.** A new registry contribution has a test that disposes its owner and observes removal.
+5. **Required gates pass.** Trust the [current readiness sequence](../../../AGENTS.md#run-the-ci-gates-locally-before-marking-a-pr-ready) and `pnpm run check:pre-push` for their enforced inventory; review the semantic gaps they cannot detect.
 
 ## Manual checks
 

From 42b07a7022c54de68aff0cf018b8cdb45adc79b3 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 15 Jul 2026 18:17:38 +0800
Subject: [PATCH 43/48] feat(sdk): add developer project tooling

docs(rfc): propose SDK developer project tooling

feat: rename / docs

ci: fix windows gates

docs: revert
---
 docs/config-catalog.md                        |   3 +
 docs/i18n/terminology.md                      |  10 +-
 docs/module-graph.md                          |   8 +
 docs/rfc/INDEX.md                             |   2 +
 ...sdk-project-editing-architecture.i18n.yaml |   6 +
 ...-07-15-sdk-project-editing-architecture.md | 129 +++
 ...-15-sdk-project-editing-architecture.zh.md | 129 +++
 ...026-07-14-sdk-developer-projects.i18n.yaml |   6 +
 .../2026-07-14-sdk-developer-projects.md      | 167 ++++
 .../2026-07-14-sdk-developer-projects.zh.md   | 167 ++++
 knip.json                                     |   9 +
 packages/README.md                            |   1 +
 .../agent/tests/verify-export-jsdoc.spec.ts   |  16 +
 packages/sdk/README.md                        |  15 +
 packages/sdk/create-sdk/README.md             |  19 +
 packages/sdk/create-sdk/package.json          |  37 +
 packages/sdk/create-sdk/src/args.ts           |  84 ++
 packages/sdk/create-sdk/src/bin.ts            |  10 +
 packages/sdk/create-sdk/src/command.ts        | 110 +++
 .../sdk/create-sdk/src/create-questions.ts    | 205 +++++
 packages/sdk/create-sdk/src/create-wizard.ts  | 222 +++++
 packages/sdk/create-sdk/src/index.ts          |   7 +
 .../sdk/create-sdk/src/project-scaffolder.ts  |  41 +
 .../src/templates/assets/created.txt.tpl      |   1 +
 .../templates/assets/install-question.txt.tpl |   1 +
 .../src/templates/assets/next-steps.txt.tpl   |   1 +
 .../templates/assets/setup-failure.txt.tpl    |   2 +
 .../src/templates/assets/usage.txt.tpl        |  11 +
 .../src/templates/create-templates.ts         |  59 ++
 .../create-sdk/tests/built-artifacts.e2e.ts   |  28 +
 .../sdk/create-sdk/tests/create.snapshot.ts   | 397 ++++++++
 packages/sdk/create-sdk/tests/create.spec.ts  | 501 ++++++++++
 .../create-sdk/tests/link-workspace.e2e.ts    | 112 +++
 packages/sdk/create-sdk/tsconfig.json         |  12 +
 packages/sdk/create-sdk/tsdown.config.ts      |  14 +
 packages/sdk/helper/README.md                 |  23 +
 packages/sdk/helper/package.json              |  45 +
 .../helper/src/documents/cordis-yaml-file.ts  | 188 ++++
 packages/sdk/helper/src/documents/env-file.ts | 111 +++
 .../helper/src/documents/package-json-file.ts | 159 ++++
 .../src/documents/pnpm-workspace-file.ts      |  76 ++
 .../sdk/helper/src/documents/project-file.ts  |  60 ++
 .../sdk/helper/src/documents/tsconfig-file.ts |  89 ++
 .../sdk/helper/src/features/builtin/app.ts    |  98 ++
 .../helper/src/features/builtin/helpers.ts    |  99 ++
 .../sdk/helper/src/features/builtin/index.ts  | 359 ++++++++
 .../helper/src/features/builtin/provider.ts   | 111 +++
 .../sdk/helper/src/features/builtin/spine.ts  |  55 ++
 .../sdk/helper/src/features/define-feature.ts | 283 ++++++
 .../src/features/feature-configurator.ts      | 104 +++
 packages/sdk/helper/src/features/feature.ts   | 340 +++++++
 packages/sdk/helper/src/features/registry.ts  |  87 ++
 packages/sdk/helper/src/features/resources.ts |  86 ++
 packages/sdk/helper/src/ids.ts                |  31 +
 packages/sdk/helper/src/index.ts              |  45 +
 .../src/package-managers/link-workspace.ts    | 137 +++
 .../src/package-managers/package-manager.ts   | 280 ++++++
 .../src/plugins/local-plugin-blueprint.ts     | 123 +++
 packages/sdk/helper/src/project/change-set.ts |  26 +
 .../src/project/npm-dependency-policy.ts      |  62 ++
 .../src/project/project-edit-session.ts       | 542 +++++++++++
 .../sdk/helper/src/project/sdk-project.ts     | 319 +++++++
 packages/sdk/helper/src/project/types.ts      |  48 +
 .../src/questions/clack-nested-multiselect.ts | 304 +++++++
 .../helper/src/questions/clack-prompt-port.ts | 127 +++
 .../sdk/helper/src/questions/prompt-port.ts   | 124 +++
 packages/sdk/helper/src/questions/question.ts | 206 +++++
 .../helper/src/templates/assets/README.md.tpl |  33 +
 .../helper/src/templates/assets/gitignore.tpl |   5 +
 .../helper/src/templates/assets/index.ts.tpl  |  45 +
 .../assets/local-plugin-tsdown.config.ts.tpl  |  13 +
 .../src/templates/assets/local-plugin.ts.tpl  |   9 +
 .../src/templates/assets/local-tool.ts.tpl    |  17 +
 .../src/templates/assets/package.json.tpl     |  16 +
 .../src/templates/assets/persona.txt.tpl      |   3 +
 .../templates/assets/tsconfig.base.json.tpl   |  14 +
 .../src/templates/assets/tsdown.config.ts.tpl |  13 +
 .../src/templates/assets/yarnrc.yml.tpl       |   1 +
 .../helper/src/templates/project-template.ts  |  78 ++
 .../helper/src/templates/template-assets.ts   |  19 +
 .../sdk/helper/src/templates/text-template.ts |  44 +
 packages/sdk/helper/tests/documents.spec.ts   | 363 ++++++++
 packages/sdk/helper/tests/project.spec.ts     | 855 ++++++++++++++++++
 packages/sdk/helper/tests/questions.spec.ts   | 453 ++++++++++
 packages/sdk/helper/tsconfig.json             |  19 +
 packages/sdk/helper/tsdown.config.ts          |  14 +
 packages/sdk/scripts/README.md                |  30 +
 packages/sdk/scripts/package.json             |  54 ++
 packages/sdk/scripts/src/args.ts              |  70 ++
 packages/sdk/scripts/src/bin.ts               |  10 +
 packages/sdk/scripts/src/build.ts             |  79 ++
 packages/sdk/scripts/src/command.ts           |  58 ++
 packages/sdk/scripts/src/config.ts            |  37 +
 .../sdk/scripts/src/config/config-workflow.ts | 200 ++++
 packages/sdk/scripts/src/dev/tsdown-config.ts |   7 +
 packages/sdk/scripts/src/index.ts             |   7 +
 .../scripts/src/local-plugin-loader-hooks.ts  |  27 +
 packages/sdk/scripts/src/runtime.ts           | 137 +++
 .../assets/config-install-failure.txt.tpl     |   2 +
 .../src/templates/assets/usage.txt.tpl        |   7 +
 .../scripts/src/templates/dsh-templates.ts    |  21 +
 .../__snapshots__/config.snapshot.ts.snap     | 303 +++++++
 packages/sdk/scripts/tests/config.snapshot.ts | 128 +++
 packages/sdk/scripts/tests/scripts.spec.ts    | 483 ++++++++++
 packages/sdk/scripts/tsconfig.json            |  13 +
 packages/sdk/scripts/tsdown.config.ts         |  22 +
 packages/ui/app-boot/README.md                |   4 +-
 pnpm-lock.yaml                                | 201 +++-
 scripts/check-workspace-constraints.ts        |  20 +
 scripts/verify-export-jsdoc.ts                | 103 ++-
 .../verify-package-readme-model-experience.ts |   3 +
 tsconfig.base.json                            |   1 +
 tsconfig.build.json                           |   5 +-
 tsconfig.json                                 |   5 +-
 vitest.snapshot.config.ts                     |   2 +-
 115 files changed, 11315 insertions(+), 27 deletions(-)
 create mode 100644 docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
 create mode 100644 docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
 create mode 100644 docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
 create mode 100644 docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
 create mode 100644 docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md
 create mode 100644 docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
 create mode 100644 packages/sdk/README.md
 create mode 100644 packages/sdk/create-sdk/README.md
 create mode 100644 packages/sdk/create-sdk/package.json
 create mode 100644 packages/sdk/create-sdk/src/args.ts
 create mode 100644 packages/sdk/create-sdk/src/bin.ts
 create mode 100644 packages/sdk/create-sdk/src/command.ts
 create mode 100644 packages/sdk/create-sdk/src/create-questions.ts
 create mode 100644 packages/sdk/create-sdk/src/create-wizard.ts
 create mode 100644 packages/sdk/create-sdk/src/index.ts
 create mode 100644 packages/sdk/create-sdk/src/project-scaffolder.ts
 create mode 100644 packages/sdk/create-sdk/src/templates/assets/created.txt.tpl
 create mode 100644 packages/sdk/create-sdk/src/templates/assets/install-question.txt.tpl
 create mode 100644 packages/sdk/create-sdk/src/templates/assets/next-steps.txt.tpl
 create mode 100644 packages/sdk/create-sdk/src/templates/assets/setup-failure.txt.tpl
 create mode 100644 packages/sdk/create-sdk/src/templates/assets/usage.txt.tpl
 create mode 100644 packages/sdk/create-sdk/src/templates/create-templates.ts
 create mode 100644 packages/sdk/create-sdk/tests/built-artifacts.e2e.ts
 create mode 100644 packages/sdk/create-sdk/tests/create.snapshot.ts
 create mode 100644 packages/sdk/create-sdk/tests/create.spec.ts
 create mode 100644 packages/sdk/create-sdk/tests/link-workspace.e2e.ts
 create mode 100644 packages/sdk/create-sdk/tsconfig.json
 create mode 100644 packages/sdk/create-sdk/tsdown.config.ts
 create mode 100644 packages/sdk/helper/README.md
 create mode 100644 packages/sdk/helper/package.json
 create mode 100644 packages/sdk/helper/src/documents/cordis-yaml-file.ts
 create mode 100644 packages/sdk/helper/src/documents/env-file.ts
 create mode 100644 packages/sdk/helper/src/documents/package-json-file.ts
 create mode 100644 packages/sdk/helper/src/documents/pnpm-workspace-file.ts
 create mode 100644 packages/sdk/helper/src/documents/project-file.ts
 create mode 100644 packages/sdk/helper/src/documents/tsconfig-file.ts
 create mode 100644 packages/sdk/helper/src/features/builtin/app.ts
 create mode 100644 packages/sdk/helper/src/features/builtin/helpers.ts
 create mode 100644 packages/sdk/helper/src/features/builtin/index.ts
 create mode 100644 packages/sdk/helper/src/features/builtin/provider.ts
 create mode 100644 packages/sdk/helper/src/features/builtin/spine.ts
 create mode 100644 packages/sdk/helper/src/features/define-feature.ts
 create mode 100644 packages/sdk/helper/src/features/feature-configurator.ts
 create mode 100644 packages/sdk/helper/src/features/feature.ts
 create mode 100644 packages/sdk/helper/src/features/registry.ts
 create mode 100644 packages/sdk/helper/src/features/resources.ts
 create mode 100644 packages/sdk/helper/src/ids.ts
 create mode 100644 packages/sdk/helper/src/index.ts
 create mode 100644 packages/sdk/helper/src/package-managers/link-workspace.ts
 create mode 100644 packages/sdk/helper/src/package-managers/package-manager.ts
 create mode 100644 packages/sdk/helper/src/plugins/local-plugin-blueprint.ts
 create mode 100644 packages/sdk/helper/src/project/change-set.ts
 create mode 100644 packages/sdk/helper/src/project/npm-dependency-policy.ts
 create mode 100644 packages/sdk/helper/src/project/project-edit-session.ts
 create mode 100644 packages/sdk/helper/src/project/sdk-project.ts
 create mode 100644 packages/sdk/helper/src/project/types.ts
 create mode 100644 packages/sdk/helper/src/questions/clack-nested-multiselect.ts
 create mode 100644 packages/sdk/helper/src/questions/clack-prompt-port.ts
 create mode 100644 packages/sdk/helper/src/questions/prompt-port.ts
 create mode 100644 packages/sdk/helper/src/questions/question.ts
 create mode 100644 packages/sdk/helper/src/templates/assets/README.md.tpl
 create mode 100644 packages/sdk/helper/src/templates/assets/gitignore.tpl
 create mode 100644 packages/sdk/helper/src/templates/assets/index.ts.tpl
 create mode 100644 packages/sdk/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl
 create mode 100644 packages/sdk/helper/src/templates/assets/local-plugin.ts.tpl
 create mode 100644 packages/sdk/helper/src/templates/assets/local-tool.ts.tpl
 create mode 100644 packages/sdk/helper/src/templates/assets/package.json.tpl
 create mode 100644 packages/sdk/helper/src/templates/assets/persona.txt.tpl
 create mode 100644 packages/sdk/helper/src/templates/assets/tsconfig.base.json.tpl
 create mode 100644 packages/sdk/helper/src/templates/assets/tsdown.config.ts.tpl
 create mode 100644 packages/sdk/helper/src/templates/assets/yarnrc.yml.tpl
 create mode 100644 packages/sdk/helper/src/templates/project-template.ts
 create mode 100644 packages/sdk/helper/src/templates/template-assets.ts
 create mode 100644 packages/sdk/helper/src/templates/text-template.ts
 create mode 100644 packages/sdk/helper/tests/documents.spec.ts
 create mode 100644 packages/sdk/helper/tests/project.spec.ts
 create mode 100644 packages/sdk/helper/tests/questions.spec.ts
 create mode 100644 packages/sdk/helper/tsconfig.json
 create mode 100644 packages/sdk/helper/tsdown.config.ts
 create mode 100644 packages/sdk/scripts/README.md
 create mode 100644 packages/sdk/scripts/package.json
 create mode 100644 packages/sdk/scripts/src/args.ts
 create mode 100644 packages/sdk/scripts/src/bin.ts
 create mode 100644 packages/sdk/scripts/src/build.ts
 create mode 100644 packages/sdk/scripts/src/command.ts
 create mode 100644 packages/sdk/scripts/src/config.ts
 create mode 100644 packages/sdk/scripts/src/config/config-workflow.ts
 create mode 100644 packages/sdk/scripts/src/dev/tsdown-config.ts
 create mode 100644 packages/sdk/scripts/src/index.ts
 create mode 100644 packages/sdk/scripts/src/local-plugin-loader-hooks.ts
 create mode 100644 packages/sdk/scripts/src/runtime.ts
 create mode 100644 packages/sdk/scripts/src/templates/assets/config-install-failure.txt.tpl
 create mode 100644 packages/sdk/scripts/src/templates/assets/usage.txt.tpl
 create mode 100644 packages/sdk/scripts/src/templates/dsh-templates.ts
 create mode 100644 packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap
 create mode 100644 packages/sdk/scripts/tests/config.snapshot.ts
 create mode 100644 packages/sdk/scripts/tests/scripts.spec.ts
 create mode 100644 packages/sdk/scripts/tsconfig.json
 create mode 100644 packages/sdk/scripts/tsdown.config.ts

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 3ba3523be9..91fe7c6497 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1277,13 +1277,16 @@ Abstract service classes — a deployment loads a concrete implementation packag
 
 Imported as libraries by other packages; a `cordis.yml` cannot load them.
 
+- `@deepseek-ai/create-sdk` ([`packages/sdk/create-sdk/src/index.ts`](../packages/sdk/create-sdk/src/index.ts))
 - `@deepseek-ai/dsh-acp-snapshot` ([`packages/support/acp-snapshot/src/index.ts`](../packages/support/acp-snapshot/src/index.ts))
 - `@deepseek-ai/dsh-app-boot` ([`packages/ui/app-boot/src/index.ts`](../packages/ui/app-boot/src/index.ts))
 - `@deepseek-ai/dsh-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts))
+- `@deepseek-ai/dsh-helper` ([`packages/sdk/helper/src/index.ts`](../packages/sdk/helper/src/index.ts))
 - `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts))
 - `@deepseek-ai/dsh-jsonrpc-demo` ([`packages/examples/jsonrpc-demo/src/index.ts`](../packages/examples/jsonrpc-demo/src/index.ts))
 - `@deepseek-ai/dsh-loader-smoke` ([`packages/support/loader-smoke/src/index.ts`](../packages/support/loader-smoke/src/index.ts))
 - `@deepseek-ai/dsh-scope` ([`packages/core/scope/src/index.ts`](../packages/core/scope/src/index.ts))
+- `@deepseek-ai/dsh-scripts` ([`packages/sdk/scripts/src/index.ts`](../packages/sdk/scripts/src/index.ts))
 - `@deepseek-ai/dsh-subagent-inprocess` ([`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts))
 - `@deepseek-ai/dsh-subagent-subprocess` ([`packages/subagent/subagent-subprocess/src/index.ts`](../packages/subagent/subagent-subprocess/src/index.ts))
 - `@deepseek-ai/dsh-timeout` ([`packages/util/timeout/src/index.ts`](../packages/util/timeout/src/index.ts))
diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md
index f4827b6a47..120121e452 100644
--- a/docs/i18n/terminology.md
+++ b/docs/i18n/terminology.md
@@ -78,12 +78,14 @@
 | block | 块 | | | |
 | build target | 构建目标 | | | |
 | cancel | 取消 | | | |
-| capability | 能力 | | | |
+| feature | 功能 | | 能力 | SDK 产品与工程模型中的可管理产品单元 |
+| feature option | 功能选项 | | variant | 一项 SDK 功能内有限、可选择的实现或配置 |
 | checkpoint | 检查点 | | | |
 | chunk | 分片 | | | |
 | compaction | 压缩 | 压缩（compaction） | | |
 | companion tool | 配套工具 | | | |
-| config | 配置 | | | |
+| Cordis plugin config | Cordis 插件配置 | | | Cordis 插件公开的 `Config` 对象或配置结构 |
+| config key | 配置键 | | | Cordis 插件配置中的单个字段 |
 | consumer | 消费方 | | | |
 | content block | 内容块 | | | |
 | Cookbook | 实操手册 | | | 文档标题用语 |
@@ -91,10 +93,13 @@
 | counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指"另一侧"时可写「另一侧」 |
 | context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |
 | contract | 契约 | | | 如：`pairing contract` →`配对契约` |
+| Cordis config entry | Cordis 配置项 | | | 指 `cordis.yml` 插件列表中的一项；插件实现本身写`Cordis 插件` |
+| Cordis plugin | Cordis 插件 | | | Cordis 加载的插件实现，不指 `cordis.yml` 中的一项配置 |
 | coverage | 覆盖率 | | | |
 | crash recovery | 崩溃恢复 | | | |
 | deploy root | 部署根目录 | | | |
 | durability | 持久性 | | | |
+| feature requirement | 功能依赖 | | | 功能或功能选项通过 `requires` 声明的关系 |
 | enforcement frontier | 执行红线 | | 强制边界 | i18n 配对机制用语：manifest `required` 清单所划的门禁生效范围；与金标样例（style-samples ⑦）一致 |
 | event | 事件 | | | |
 | event log | 事件日志 | | | |
@@ -123,6 +128,7 @@
 | mod | 模组 | | | |
 | model provider | 模型提供方 | | | |
 | module | 模块 | | | |
+| npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |
 | orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |
 | orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |
 | package | 包 | 包（package） | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 199f11e8d3..82763bdc55 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -124,6 +124,10 @@ flowchart TD
     pkg_sandbox["sandbox"]
     pkg_sandbox_local["sandbox-local"]
   end
+  subgraph group_sdk["packages/sdk"]
+    pkg_helper["helper"]
+    pkg_scripts["scripts"]
+  end
   subgraph group_tasks["packages/tasks"]
     pkg_tasks["tasks"]
     pkg_tool_tasks["tool-tasks"]
@@ -135,6 +139,8 @@ flowchart TD
   end
   pkg_llm --> pkg_brand
   pkg_code_runtime_worker --> pkg_code_runtime
+  pkg_helper --> pkg_brand
+  pkg_scripts --> pkg_app_boot
   pkg_llm_deepseek --> pkg_llm
   pkg_llm_pi_ai --> pkg_llm
   pkg_session --> pkg_brand
@@ -381,6 +387,8 @@ flowchart TD
 | [`jsonrpc-demo`](../packages/examples/jsonrpc-demo) | `examples` | — |
 | [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand) |
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime) |
+| [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand) |
+| [`scripts`](../packages/sdk/scripts) | `sdk` | [`app-boot`](../packages/ui/app-boot) |
 | [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`llm`](../packages/llm/llm) |
 | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`llm`](../packages/llm/llm) |
 | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md
index 4913fd103e..a60579ef4c 100644
--- a/docs/rfc/INDEX.md
+++ b/docs/rfc/INDEX.md
@@ -13,6 +13,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Interactive side sessions and merge-back](proposed/feature/2026-07-08-interactive-side-sessions.md) | 2026-07-08 |
 | [SQLite FTS5 session search](proposed/feature/2026-07-10-sqlite-session-query-provider.md) | 2026-07-10 |
 | [Stream workflow progress through tool calls](proposed/feature/2026-07-13-stream-workflow-progress-through-tool-calls.md) | 2026-07-13 |
+| [Developer-owned SDK projects](proposed/feature/2026-07-14-sdk-developer-projects.md) | 2026-07-14 |
 
 ### Simplification
 
@@ -27,6 +28,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | Title | First proposed |
 |---|---|
 | [Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern)](proposed/architecture/2026-06-16-typed-event-schemas.md) | 2026-06-16 |
+| [SDK project editing architecture](proposed/architecture/2026-07-15-sdk-project-editing-architecture.md) | 2026-07-15 |
 
 ### Process
 
diff --git a/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
new file mode 100644
index 0000000000..036616cddb
--- /dev/null
+++ b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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
+2026-07-15-sdk-project-editing-architecture.md: 0a3751d9641e6d4c56d14b8d81ed578905c48c73
+2026-07-15-sdk-project-editing-architecture.zh.md: 6f6ec656bf0734cf81d6c69d9c0e163fb78a33b5
diff --git a/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
new file mode 100644
index 0000000000..0a3751d964
--- /dev/null
+++ b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
@@ -0,0 +1,129 @@
+# RFC: SDK project editing architecture
+
+Status: proposed
+
+English | [中文](2026-07-15-sdk-project-editing-architecture.zh.md)
+
+## Problem
+
+[Developer-owned SDK projects](../feature/2026-07-14-sdk-developer-projects.md) are created through create, adjusted through config, and built and run through commands such as start. Initial creation, configuration changes, and build and runtime commands all need to understand features, feature options, npm dependencies, Cordis config entries, environment variables, package managers, local plugins, and several project files. If each project-reading and project-writing workflow uses a separate interpretation protocol, the SDK developer workflows become difficult to maintain.
+
+## Proposal
+
+The SDK uses one shared object-oriented project model. `SdkProject` is a read-only snapshot, and `ProjectEditSession` is the only mutation and commit boundary. Feature objects own their feature options, relationships, resource contributions, and current-state inspection. Create and config orchestrate only their respective user workflows and modify projects through the same domain operations.
+
+Structured files are modified through document objects, while one-shot text artifacts are generated from complete templates. Questions are typed objects presented through clack. Diff calculation may remain an edit-session implementation detail, but it is not a public execution protocol that callers must assemble.
+
+## Terminology
+
+| Term | Usage in this RFC | Meaning |
+|---|---|---|
+| Feature | feature | A product unit curated and managed by the SDK; one feature may contain several feature options and contribute several Cordis config entries, npm dependencies, environment placeholders, and owned files |
+| Feature option | feature option | A finite selectable implementation or configuration shape within one feature; feature rules may make options fixed, exclusive, or additive |
+| Cordis plugin | Cordis plugin | A plugin implementation loaded by Cordis, usually exported by an npm package; it is not an item in `cordis.yml` |
+| Cordis config entry | Cordis config entry | One item in the `cordis.yml` plugin list, identified as an instance by `id` and referring to a Cordis plugin through `name` |
+| Cordis plugin config | Cordis plugin config | The configuration object or shape exposed by a Cordis plugin; an individual field owned and updated by a feature is a config key |
+| config key | config key | One field in Cordis plugin config; a feature updates only the config keys it declares as owned and preserves unknown config keys |
+| npm dependency | npm dependency | A package relationship in `package.json`; literal fields such as `dependencies` and `devDependencies` keep their names |
+| Feature requirement | feature requirement | A relationship declared through `requires` by a feature or feature option |
+
+## Package boundaries
+
+| Package | Responsibility | Does not own |
+|---|---|---|
+| `@deepseek-ai/dsh-helper` | Edit sessions, feature configuration, project-template rendering, package-manager adaptation, and prompt interaction adaptation | Booting Cordis applications or deciding create/config terminal workflows |
+| `@deepseek-ai/dsh-scripts` | `dsh start/dev/build/config`, process lifecycle, project entry loading, the config workflow, and its terminal-copy templates | Interpreting feature definitions directly or modifying YAML/JSON ASTs |
+| `@deepseek-ai/create-sdk` | Arguments, question order, initial project creation, installation finish, and terminal-copy templates for `npm create @deepseek-ai/sdk` | Becoming a generated project's runtime npm dependency or providing a library API |
+
+`@deepseek-ai/create-sdk` is the only exception to the repository's `@deepseek-ai/dsh-*` naming rule. npm's scoped-initializer convention requires that package name for `npm create @deepseek-ai/sdk`. The exception is a repository architecture fact and does not add a third developer product entrypoint.
+
+The three packages export only the narrow entrypoints consumed by adjacent layers and provide no `src/*` deep imports. The scripts library entrypoint and build-config subpath serve generated code and project build configuration, while the developer product contract remains the `dsh` commands.
+
+## Project aggregate and edit session
+
+`SdkProject.create(root, request)` constructs a new project snapshot that has not been written, while `SdkProject.open(root)` loads an existing project. Open requires only readable root `package.json` and `cordis.yml` files; every other file is an optional resource. Both paths return the same read-only aggregate and distinguish their source through explicit origin state.
+
+`project.edit()` clones project documents into a working copy. Domain commands such as install, configure, enable, disable, and addPlugin modify only the working copy. Each command immediately re-inspects its owning feature, and the final commit checks all relationships and files again.
+
+```text
+validate feature requirements and resource ownership
+  -> validate every affected document
+  -> compute changed and removed paths
+  -> compare existing files with the session's original text
+  -> write through one commit boundary
+  -> return a new SdkProject snapshot and ChangeSet
+```
+
+Validation failure or an external edit causes zero writes. “One commit” means only zero pre-write side effects and one write entrypoint. `ChangeSet` describes final feature, plugin, and file changes for Review & Apply and create completion.
+
+## Features and resource ownership
+
+A feature is a first-class behavior object. Shallow base classes implement install, configure, enable, disable, required/requires validation, and common state inspection. Features with fixed, exclusive, or additive feature options share these lifecycles. Only features whose resource contributions depend on project context or require custom round-tripping use dedicated behavior classes; other features declare their actual differences through standardized data.
+
+Each feature contributes stable-keyed Cordis config entries, npm dependencies, environment placeholders, and owned files. The registry rejects two features that declare the same resource key during initialization. Different feature options within one feature may share resources, which that feature resolves from the final option set.
+
+A Cordis config entry anchors feature installation. The npm package name assigns the entry to a feature, and the entry ID distinguishes several instances of one plugin package. An npm dependency without a feature-owned Cordis config entry leaves the feature uninstalled. Once a Cordis config entry exists, a missing npm dependency, unreadable Cordis plugin config, or resource conflict puts the feature into an inconsistent state; the config command shows diagnostics and refuses speculative modification.
+
+Configuring the same feature option updates only its owned config keys and preserves unknown keys. Replacing a feature option removes old resources that are exclusive and still confirmable. If an old resource cannot be confirmed or an owned file was modified by the developer, the whole operation fails.
+
+## Questions and workflows
+
+TypeScript `Question<T>` objects keep defaults, validation, applicability, and types together. `PromptPort` is the only interface between the domain layer and the terminal library, and helper provides one thin `ClackPromptPort`. Create and config inject their own command-line input and output streams and retain ownership of cancellation, return, and completion semantics in their workflows.
+
+Create keeps its stateful question order in one wizard, while config keeps final-state selection in one workflow. Both use the same feature configurator for feature options and dedicated inputs, so adding an ordinary feature, feature option, or parameter does not require changes to both entrypoints.
+
+## Project documents and templates
+
+Only structured files that helper reads or modifies have concrete document objects: `package.json`, `cordis.yml`, `.env`, `.env.example`, the root `tsconfig.json`, and the pnpm workspace file. Document objects own parsing, cloning, validation, and serialization. Concrete classes and modules use `*File` and `*-file.ts` names respectively. Business code does not manipulate YAML/JSON ASTs directly, and malformed shapes fail loudly at the owning document boundary.
+
+README, entrypoint code, build configuration, `.gitignore`, and other one-shot text artifacts use one complete template per real file. Complete product copy such as CLI usage, creation and recovery messages, installation and retry guidance, and the default persona also comes from package-local templates owned by the package that presents it.
+
+Helper provides the generic typed `TextTemplate` renderer, and caller packages load their own templates through package-local asset URLs.
+
+Templates use Handlebars strict mode and `noEscape` without custom processing. File owners encode typed values for the target language. Template source escapes interpolation as `\{{model}}` when it must emit the downstream literal unchanged.
+
+## Command and runtime boundary
+
+Scripts supports `dsh start/dev/build/config`. Start dynamically loads a module target and calls its named entrypoint. Dev adds TypeScript and local-workspace source resolution before following the same path. Build invokes the project's installed tsdown. Config opens one edit session and commits after Review & Apply. Generated projects run `tsc -b` directly for typechecking.
+
+HMR is an explicit Cordis config entry loaded by dev and start. Its required `node-addon-require-builtin` package is supplied transitively by the scripts package and is absent from the generated project's `package.json`.
+
+Dev and start execute the developer entrypoint, where developer code handles command-line arguments and cwd. Developers pass `--model=<name>` and `--resume=<session-id>` to start the standard flow.
+
+## Repository live-link mode
+
+Create-sdk retains a hidden `--link-workspace` option for Harness repository development and e2e. The parser accepts it, but help, public flag lists, and ordinary user documentation omit it. It accepts no repository-path parameter; the repository root is derived upward from the executing create-sdk module.
+
+Link mode preserves the ordinary project file shape. `@deepseek-ai/*` points into `packages/`, Cordis-related npm dependencies point into `vendor/`, and shared lower-level packages resolve to the same physical copy used by the repository so Cordis type merging cannot produce multiple module type definitions. npm uses `file:`, pnpm uses `link:` with automatic peer installation disabled, and Yarn uses `portal:` plus resolutions. Repository packages must be built first.
+
+## Future work
+
+- **Replaceable required spine roles.** The current `spine` owns the full implementation set, including SystemPrompt and LLMService, through one fixed feature option. Developers cannot replace or switch these roles and must edit Cordis config entries manually.
+- **Service contracts and package declarations.** When replacing a builtin service, a Cordis plugin currently cannot declare the services it provides through `provides` metadata, so the SDK cannot assist configuration during development or check compatibility at runtime. A corresponding protocol remains to be designed.
+- **Feature parameter descriptions.** Feature-specific inputs currently require handwritten declarations. The SDK cannot derive interactive parameters automatically from arbitrary Cordis plugin config or npm package.json information. Future declarative metadata may expose a limited parameter set without turning arbitrary Cordis plugin config into a generic form.
+- **SDK application-level configuration.** The current project resource model describes Cordis config entries and config keys owned by individual Cordis plugins, so every SDK-managed setting must belong to one plugin. Cross-plugin or whole-application settings have no independent persistence location. Future work must define an application-level configuration document and its ownership, read, and mutation boundaries.
+
+## Alternatives considered
+
+**Keep the static Catalog and central engine.** This minimizes the initial rewrite, but feature parameters, round-tripping, owned files, and create/config reuse continue to accumulate in one coordinator. Splitting files shortens the file without consolidating responsibility.
+
+**Use `wizard.json` and a generic Questionnaire.** Static forms cannot directly express feature requirements, option switches, existing-value refill, and project-resource changes. Types, gates, and dynamic options still connect through string registries and a procedural `run()`, creating another internal DSL.
+
+**Expose the live-link flag.** The mode depends on Harness monorepo layout and unpublished packages and serves repository development only. Making it public would create a project-creation contract that the SDK cannot support outside the repository.
+
+## Acceptance criteria
+
+- Create and config modify projects only through `SdkProject` and `ProjectEditSession`; any business, document, or concurrency validation failure before writing leaves the filesystem unchanged
+- Adding an ordinary feature, feature option, or parameter extends only its typed spec or owning behavior object, without adding a central switch to create or config workflows
+- Helper owns the feature model, npm dependency and other resource configuration, and inconsistent-state detection
+- Structured files change through `*File` document objects; one-shot files and complete product copy come from package-owned Handlebars templates, and business decisions do not enter a template DSL
+- `dsh start/dev/build/config` is the runtime product surface, typecheck uses `tsc -b` directly, HMR is not injected by command mode, and only the scripts package transitively supplies `node-addon-require-builtin`
+- `--link-workspace` exists only as a hidden repository-development option and preserves one module identity under npm, pnpm, and Yarn
+
+## Risks
+
+- Behavior objects and typed specs create two extension shapes. Dedicated classes must remain limited to features that truly depend on project context or custom behavior, or the design will grow a meaningless type hierarchy
+- Optimistic concurrency checks and pre-write validation cannot recover from an I/O failure during writing; callers must still report a possible partial commit to the developer
+- Hidden link mode depends on repository layout and package-manager link semantics and must change with either one
+- The Cordis loader resolves `node-addon-require-builtin` from its own module path, so the scripts package must continue to satisfy that optional peer under npm, pnpm, and Yarn npm dependency layouts
+- Handlebars `noEscape` makes typed model construction responsible for target-language encoding; new template fields must be escaped correctly at the owning boundary, and downstream Handlebars placeholders must be escaped explicitly in template source
diff --git a/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
new file mode 100644
index 0000000000..6f6ec656bf
--- /dev/null
+++ b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
@@ -0,0 +1,129 @@
+# RFC: SDK 工程编辑架构
+
+Status: proposed
+
+[English](2026-07-15-sdk-project-editing-architecture.md) | 中文
+
+## 问题
+
+[开发者拥有的 SDK 工程](../feature/2026-07-14-sdk-developer-projects.md) 由 create 创建，可以通过 config 调整，并由 start 等命令构建和运行。初始创建、配置调整和编译运行都需要理解功能、功能选项、NPM 依赖、Cordis 配置项、环境变量、包管理器、本地插件和多个项目文件。如果读写项目的各个流程分别使用不同的解析协议，SDK 开发者流程会变得难以维护。
+
+## 提案
+
+SDK 使用一个共享的面向对象工程模型。`SdkProject` 是只读快照，`ProjectEditSession` 是唯一修改与提交边界；功能对象负责自身的功能选项、关系、资源贡献和现状识别；create 与 config 只编排各自的用户流程，并通过同一组领域操作修改工程。
+
+结构化文件通过文档对象修改，一次性文本产物通过完整模板生成。问题由类型化对象表达，并使用 clack 交互。差异计算可以作为编辑会话的内部实现，但不成为要求调用方组装的公共执行协议。
+
+## 术语
+
+| 名词 | 本文用词 | 含义 |
+|---|---|---|
+| Feature | 功能 | SDK 人工策划和管理的产品单元；一项功能可以包含多个功能选项，并贡献多个 Cordis 配置项、NPM 依赖、环境变量占位和独占文件 |
+| Feature option | 功能选项 | 一项功能内有限、可选择的实现或配置形状；根据功能规则可以固定、互斥或多选 |
+| Cordis plugin | Cordis 插件 | Cordis 加载的插件实现，通常由一个 NPM 包导出；它不是 `cordis.yml` 中的一项配置 |
+| Cordis config entry | Cordis 配置项 | `cordis.yml` 插件列表中的一项，通过 `id` 标识实例并通过 `name` 指向 Cordis 插件 |
+| Cordis plugin config | Cordis 插件配置 | Cordis 插件公开的配置对象或配置结构；其中由功能拥有并更新的单个字段称为“配置键” |
+| config key | 配置键 | Cordis 插件配置中的单个字段；功能只更新自己声明拥有的配置键，并保留未知配置键 |
+| npm dependency | NPM 依赖 | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |
+| Feature requirement | 功能依赖 | 功能或功能选项通过 `requires` 声明的关系 |
+
+## Package 边界
+
+| Package | 责任 | 不负责 |
+|---|---|---|
+| `@deepseek-ai/dsh-helper` | 编辑会话、功能配置、工程模板渲染、包管理适配和 prompt 交互适配 | 启动 Cordis 应用或决定 create/config 的终端流程 |
+| `@deepseek-ai/dsh-scripts` | `dsh start/dev/build/config`、进程生命周期、项目入口加载、config 流程和所属终端文案模板 | 直接解释功能定义或修改 YAML/JSON AST |
+| `@deepseek-ai/create-sdk` | `npm create @deepseek-ai/sdk` 的参数、问题顺序、首次工程创建、安装收尾和所属终端文案模板 | 成为生成工程的运行时 NPM 依赖或提供库 API |
+
+`@deepseek-ai/create-sdk` 是仓库 `@deepseek-ai/dsh-*` 命名规则的唯一例外；npm scoped initializer 约定要求 `npm create @deepseek-ai/sdk` 对应这个 package 名。该例外是仓库架构事实，不增加第三个开发者产品入口。
+
+三个 package 只导出相邻层实际使用的最小入口，不提供 `src/*` 深路径。scripts 的库入口与构建配置子路径服务生成代码和项目构建配置，但开发者产品合同仍由 `dsh` 命令承担。
+
+## 工程聚合与编辑会话
+
+`SdkProject.create(root, request)` 构造尚未写盘的新工程快照，`SdkProject.open(root)` 加载已有工程。open 只要求根 `package.json` 与 `cordis.yml` 可读，其余文件是按需存在的资源；两条路径返回同一种只读聚合，并通过显式 origin 区分来源。
+
+`project.edit()` 克隆项目文档形成 working copy。install、configure、enable、disable 和 addPlugin 等领域命令只修改 working copy；命令完成后立即重新检查所属功能，最终 commit 再检查全部关系和文件。
+
+```text
+validate feature requirements and resource ownership
+  -> validate every affected document
+  -> compute changed and removed paths
+  -> compare existing files with the session's original text
+  -> write through one commit boundary
+  -> return a new SdkProject snapshot and ChangeSet
+```
+
+校验失败或检测到会话外修改时不写盘。“一次 commit”只表示写入前零副作用和单一写入口。`ChangeSet` 只描述功能、插件和文件的最终变化，用于 Review & Apply 与 create 收尾。
+
+## 功能与资源所有权
+
+功能是一等行为对象。浅层基类实现 install、configure、enable、disable、required/requires 校验和共同状态识别；固定功能选项、互斥功能选项与可多选功能选项共享这些生命周期。只有资源贡献依赖项目上下文或需要自定义 round-trip 的功能才使用专用行为类，其余功能通过标准化数据声明真正不同的部分。
+
+每项功能贡献带稳定 key 的 Cordis 配置项、NPM 依赖、环境变量占位和独占文件。注册表初始化时拒绝不同功能声明同一个资源 key；同一功能的不同功能选项可以共享资源，并由该功能根据最终选项集合处理。
+
+Cordis 配置项是功能安装锚点。NPM 包名判断配置项所属的功能，配置项 ID 区分同一插件包的多个实例；只有 NPM 依赖而没有功能拥有的 Cordis 配置项时，该功能仍视为未安装。Cordis 配置项存在后，缺失 NPM 依赖、无法读取的 Cordis 插件配置或资源冲突会使功能进入不一致状态，config 命令显示诊断并拒绝猜测式修改。
+
+同一功能选项只更新其声明拥有的配置键，保留未知键。替换功能选项会删除旧功能选项独占且仍可确认的资源；无法确认旧资源或发现独占文件被用户修改时，整个操作失败。
+
+## 问题与 workflow
+
+问题由 TypeScript `Question<T>` 对象表达，默认值、校验、适用条件和类型留在同一个对象中。`PromptPort` 是领域层与终端库之间的唯一接口，helper 提供一份薄 `ClackPromptPort`；create 和 config 注入各自的命令行输入输出流，并在各自流程中决定取消、返回和收尾语义。
+
+create 的有状态问题顺序留在一个向导中，config 的最终状态选择留在一个流程中。两者通过同一个功能配置器收集功能选项与专用输入，因此增加一项普通功能、功能选项或参数不要求同时修改两个入口。
+
+## 项目文档与模板
+
+只有需要读取或修改的结构化文件拥有具体文档对象，包括 `package.json`、`cordis.yml`、`.env`、`.env.example`、根 `tsconfig.json` 和 pnpm workspace 文件。文档对象拥有解析、克隆、校验和序列化行为；具体类与模块分别使用 `*File` 和 `*-file.ts` 命名，业务层不直接操作 YAML/JSON AST，异常形状在所属文档边界 fail loud。
+
+README、入口代码、构建配置、`.gitignore` 和其他一次性文本产物使用与真实文件一一对应的完整模板。CLI usage、创建结果与恢复提示、安装与重试指导以及默认 persona 等完整产品文案也由所属 package 的本地模板提供。
+
+helper 提供通用的数据类型化 `TextTemplate` 模板渲染器，调用 package 通过本地 asset URL 加载自己的模板。
+
+模板使用 Handlebars strict mode 与 `noEscape`，不进行自定义处理。文件对象负责把类型化数据值编码成目标语言文本；如果不希望插值，则源码以 `\{{model}}` 等转义形式输出下游。
+
+## 命令与运行边界
+
+scripts 支持 `dsh start/dev/build/config`。start 动态加载模块 target 并调用其命名入口；dev 在同一路径前增加 TypeScript 与本地 workspace 源码解析；build 调用工程安装的 tsdown；config 打开一个编辑会话并在 Review & Apply 后提交。typecheck 由生成工程直接执行 `tsc -b`。
+
+HMR 作为显式 Cordis 配置项由 dev 和 start 加载；它所需的 `node-addon-require-builtin` 由 scripts package 传递提供，不写入开发者工程的 `package.json`。
+
+dev/start 会执行开发者入口，在开发者代码中处理命令行参数、cwd，由开发者自行传入 `--model=<name>` 与 `--resume=<session-id>` 启动标准流程。
+
+## 仓库本地链接模式
+
+create-sdk 保留隐藏的 `--link-workspace` 选项供 Harness 仓库开发和 e2e 使用。该选项可以被解析，但不出现在 help、公开 flag 清单或普通用户文档中，也不接收仓库路径参数；仓库根从正在执行的 create-sdk 模块位置向上确定。
+
+链接模式保持普通工程的文件形状。`@deepseek-ai/*` 指向 `packages/`，Cordis 相关 NPM 依赖指向 `vendor/`，共享底层 package 锚定到仓库实际使用的同一物理拷贝，避免 Cordis 类型合并产生多个模块类型定义。npm 使用 `file:`，pnpm 使用 `link:` 并关闭自动 peer 安装，Yarn 使用 `portal:` 与 resolutions；仓库 package 需要先构建。
+
+## 后续工作
+
+- **可替换的 required 主干角色。** 当前 `spine` 以一个固定功能选项拥有整组实现，包含 SystemPrompt、LLMService 等。无法让开发者对其进行替换和切换，只能手工修改 Cordis 配置项。
+- **Service contract 与 package 声明。** 替换特定内建服务时，Cordis 插件目前无法通过 `provides` 元数据声明其提供的服务，因此 SDK 无法在开发阶段辅助配置，也无法在运行时检查兼容性。后续需要设计相应协议。
+- **功能参数描述。** 当前功能的专用输入必须手工声明；SDK 无法从任意 Cordis 插件配置或 NPM package.json 信息中自动推导可交互参数。后续可以定义有限的声明式参数元数据，但不把任意 Cordis 插件配置转换成通用表单。
+- **SDK 应用级配置。** 当前项目资源模型只描述 Cordis 配置项及单个 Cordis 插件拥有的配置键，因此所有受 SDK 管理的配置都必须归属某个插件。跨插件或面向整个 SDK 应用的设置没有独立持久化位置；后续需要定义应用级配置文档及其所有权、读取和修改边界。
+
+## 曾考虑的替代方案
+
+**保留静态 Catalog 与中心 engine。** 该方案改动最小，但功能参数、round-trip、独占文件和 create/config 复用都会继续进入同一个协调中心；拆文件只能缩短单文件，不能收拢职责。
+
+**使用 `wizard.json` 与通用 Questionnaire。** 静态表单无法直接表达功能依赖、选项切换、已有值回填和项目资源变化；类型、gate 和动态 option 最终仍要通过字符串 registry 与过程式 `run()` 连接，形成新的内部 DSL。
+
+**公开本地链接 flag。** 该模式依赖 Harness monorepo 布局和未发布 package，只服务仓库开发；公开后会形成无法对外兑现的项目创建合同，因此保持隐藏。
+
+## 验收标准
+
+- create 与 config 只通过 `SdkProject` 和 `ProjectEditSession` 修改工程，写入前的任何业务、文件或并发校验失败都不产生磁盘变化
+- 新增普通功能、功能选项或参数只扩展类型化 spec 或所属行为对象，create/config 流程不增加中央 switch
+- 功能模型、NPM 依赖与其他资源配置、不一致检测由 helper 统一实现
+- 结构化文件通过 `*File` 文档对象修改；一次性文件和完整产品文案通过所属 package 的 Handlebars 模板生成，业务决策不进入模板 DSL
+- `dsh start/dev/build/config` 是运行产品面，typecheck 直接使用 `tsc -b`，HMR 不通过命令隐式注入，`node-addon-require-builtin` 只由 scripts package 传递提供
+- `--link-workspace` 只作为隐藏的仓库开发选项存在，并对 npm、pnpm 和 Yarn 保持单一模块身份
+
+## 风险
+
+- 行为对象与类型化 spec 并存会形成两种扩展形状；专用类必须只用于确实依赖项目上下文或自定义的功能，否则会重新产生无意义的类型层次
+- 乐观并发检查与写前校验不能解决写入中途的 I/O 故障，调用方仍需向开发者报告可能的部分提交
+- 隐藏链接模式依赖仓库目录与 package manager 链接语义，仓库布局或工具行为变化时必须与实现一起更新
+- Cordis loader 从自身模块路径加载 `node-addon-require-builtin`；npm、pnpm 或 Yarn 的 NPM 依赖布局变化时，scripts package 必须继续满足该可选对等依赖（optional peer dependency）
+- Handlebars 的 `noEscape` 把目标语言编码责任交给 typed model 构造方；新增模板字段时必须在 owner 处完成正确转义，下游 Handlebars 占位符必须在模板源码中显式转义
diff --git a/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
new file mode 100644
index 0000000000..7b5a289e1e
--- /dev/null
+++ b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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
+2026-07-14-sdk-developer-projects.md: 4650b5df5d1dc85035d8029754ec60b7d7008d4c
+2026-07-14-sdk-developer-projects.zh.md: 613da4da930591fb13516b287f408ebc3b15b2c2
diff --git a/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md
new file mode 100644
index 0000000000..4650b5df5d
--- /dev/null
+++ b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md
@@ -0,0 +1,167 @@
+# RFC: Developer-owned SDK projects
+
+Status: proposed
+
+English | [中文](2026-07-14-sdk-developer-projects.zh.md)
+
+## Problem
+
+DeepSeek Harness composes features through Cordis plugins, but building a runnable project from an empty directory still requires a developer to understand npm dependencies, the `cordis.yml` plugin set, environment variables, TypeScript builds, local-plugin workspaces, and runtime entrypoints together. These manual steps constrain one another: omitting any one can produce a project that installs but cannot be developed, develops but cannot be built, or builds but cannot start.
+
+A one-shot generator reduces only the initial creation cost. If the generated result is hidden inside a preset or an uneditable CLI, advanced developers cannot reshape the plugin tree, change Cordis plugin config, or add project-specific behavior. If a generated project immediately leaves tool management altogether, developers must again maintain consistency across all npm dependencies and Cordis plugin config themselves.
+
+Initial creation and later configuration address the same builtin feature set. When those workflows maintain separate feature lists, feature options, and npm dependencies, new Cordis plugins, npm packages, and Cordis plugin config changes make them diverge. Projects also need an ordinary local-plugin development path that participates in development, build, and start flows.
+
+## Proposal
+
+The SDK creates an ordinary, explicit TypeScript/Cordis project owned by its developer. `cordis.yml` is the only runtime plugin tree; development and production read the same file. The generated `package.json`, `cordis.yml`, TypeScript entrypoint, build configuration, and `plugins/*` remain directly editable instead of being hidden behind a preset.
+
+The only developer product entrypoints are `npm create @deepseek-ai/sdk` and the `dsh` commands. The initializer performs initial creation, `dsh config` manages SDK-recognized builtin features afterward, and `dsh dev`, `dsh build`, and `dsh start` own development, build, and startup; this phase provides no `dsh create`. Create and config consume one manually authored feature definition, so each feature has one source for its feature options, npm dependencies, Cordis config entries, related files, and inspection rules. The [SDK project editing architecture](../architecture/2026-07-15-sdk-project-editing-architecture.md) defines terms such as feature and feature option.
+
+The SDK offers interaction for feature selection and finite feature options only; it does not turn arbitrary Cordis plugin config into a generic form. A feature collects the small number of dedicated inputs required by its feature options. All other Cordis plugin config remains in `cordis.yml`, with comments documenting common edits, for direct developer control.
+
+## Developer workflow
+
+Initial creation collects information in an order where earlier answers determine later questions: target directory and package identity, model provider and credentials, run interface, builtin features and feature options, an optional local plugin, package manager, and whether to install npm dependencies and build. Command-line arguments suppress questions they already answer. Create and config require an interactive TTY in this phase, and cancelling creation writes nothing to the target directory.
+
+```sh
+npm create @deepseek-ai/sdk my-agent
+cd my-agent
+npm exec dsh dev index.ts
+npm exec dsh config
+npm exec dsh build
+npm exec dsh start index.js
+```
+
+Create rejects every target path that already exists. After committing the project files, the CLI asks whether to install npm dependencies and build. An install or build failure preserves the generated project and prints commands that can retry the failed work.
+
+Create also offers one `none / plugin / tool` choice. `plugin` creates a fixed `plugins/plugin` Cordis plugin, while `tool` creates a fixed `plugins/tool` model-facing tool; one project creation includes at most one local plugin. The operation updates the workspace, root npm dependency, TypeScript reference, build configuration, and `cordis.yml` together, and any pre-write validation failure leaves the project absent.
+
+## Features supported during creation
+
+The table is the developer-visible support set for this phase. A `required` feature is always present but may still offer finite feature options; a `default` feature is preselected in the feature tree; an `optional` feature is selected explicitly. The table describes the product support set, while the runtime registry remains the implementation source of truth.
+
+| Feature | Create state | Feature options | Constraints and relationships |
+|---|---|---|---|
+| `provider` | required | `deepseek` (default) / `custom` | DeepSeek collects an API key; custom also collects a base URL, and a CLI option may override the model name |
+| `app` | required | `stdio` (default) / `acp` / `embed` | Selects the run interface |
+| `spine` | required | `default` | Timer, the LLM seam, session storage, system prompt, the tool registry, the agent registry, and the agent loop |
+| `bash` | required | `local` (default) / `sandbox` | The two feature options are exclusive and independent of the run interface, and both install the model-facing bash tool; sandbox installs the local sandbox provider and sandboxed bash backend |
+| `persistence` | required | `jsonl` (default) / `sqlite` | Every project selects exactly one persistence backend |
+| `hmr` | default | `default` | Loads `@cordisjs/plugin-hmr`; dev and start both enable it with the plugin defaults |
+| `fs` | default | `local` | Installs the local filesystem, policy, and model-facing tools; the process sandbox does not confine in-process fs tools |
+| `todo` | default | `default` | Provides the `todo_write` tool |
+| `skill` | default | `default` | Installs the skill registry, the local skill provider, and the model-facing skill tool |
+| `web` | optional | `deepseek` (default) / `exa` / `perplexity` / `fetch-only` | Search feature options are exclusive; Exa and Perplexity collect their API keys; timeout policy is recommended |
+| `subagent` | optional | `spawn` (default) / `fork`, multiple | This phase provides only in-process backends |
+| `workflow` | optional | `workerthread` | Requires the subagent `spawn` feature option |
+| `compact` | optional | `basic` | Uses SDK-provided context-compaction parameters |
+| `hooks` | optional | `claude` (default) / `codex`, multiple | Each feature option creates a separate editable configuration file |
+| `guard` | optional | `repeat-tool` | Provides repeated-tool-call reminders |
+| `timeout-policy` | optional | `default` | Applies a uniform policy to tools that declare timeout budgets |
+| `ask-user` | optional | `default` | Provides the `ask_user_question` tool; only `acp` and `stdio` can select it because those two feature options provide the injected user-interaction service |
+
+Both `bash` feature options apply to ACP, stdio, and embed and are not selected by the run interface. The sandbox feature option writes no active config key and therefore keeps `dsh-bash-sandbox`'s `read-only` default. Generated `cordis.yml` includes a commented example that developers can change explicitly to `workspace-write`:
+
+```yaml
+- id: bash
+  name: '@deepseek-ai/dsh-bash-sandbox'
+  # Uncomment to allow writes under the project workspace.
+  # config:
+  #   mode: workspace-write
+  #   workspaceRoot: !!js process.cwd()
+```
+
+Feature contributions reference only single-plugin npm packages and never bundle packages such as `agent-spine-demo`, `stdio-demo`, or `acp-demo`. Plugins outside the table are not managed by create in this phase; advanced developers may still compose them by editing the ordinary project files directly.
+
+## Generated project
+
+With default answers, an npm project uses the DeepSeek provider, the stdio interface, local bash, JSONL persistence, and the preselected hmr, fs, todo, and skill features. Its initial tree is:
+
+```text
+my-agent/
+├── .env
+├── .env.example
+├── .gitignore
+├── README.md
+├── cordis.yml
+├── index.ts
+├── package.json
+├── tsconfig.base.json
+├── tsconfig.json
+└── tsdown.config.ts
+```
+
+`.env.example` always exists, and the SDK keeps its placeholders aligned with the current feature set. A gitignored `.env` is also created when a secret is captured or the developer confirms an empty credential to fill later. The SDK only appends differently named variables that are not already present in `.env` and never updates or removes existing contents. Feature-option changes may remove obsolete `.env.example` placeholders, while old credentials remain in `.env` for the developer to manage. pnpm and Yarn projects add their required workspace files, but do not fork the runtime plugin tree or TypeScript entrypoint.
+
+Generated `package.json` provides the following scripts. `dev`, `build`, `start`, and `config` invoke `dsh`, while `typecheck` invokes TypeScript directly:
+
+| Script | Behavior |
+|---|---|
+| `dev` | Run `dsh dev index.ts`, registering development-time resolution for TypeScript and local workspace plugins |
+| `build` | Run `dsh build`, invoking the project's installed tsdown for the root entrypoint and `plugins/*` packages |
+| `typecheck` | Run `tsc -b` directly |
+| `start` | Run `dsh start index.js`, starting the built entrypoint without an implicit build |
+| `config` | Run `dsh config` to edit the current project's feature tree |
+
+`dsh start` and `dsh dev` accept a module target and forward arguments after `--` unchanged to the project entrypoint. Generic argument parsing uses Node `parseArgs()` with zero schema: valued flags use `--key=value`, bare flags become `true`, and `--no-*` becomes `false`.
+
+- Stdio projects pass the selected model through `--model=<name>` and create or resume an agent according to optional `--resume=<session-id>`;
+- ACP uses protocol `session/load`
+- Embed uses the model written into the generated code.
+
+Each feature-owned Cordis config entry keeps its developer-editable Cordis plugin config and explanatory comments in `cordis.yml`. When `dsh config` changes other features, it preserves unknown fields, formatting on untouched nodes, and comments. HMR is an ordinary leaf config entry: when the feature is selected, dev and start load the same watcher, and the command does not change the plugin tree implicitly.
+
+## Post-creation configuration
+
+`dsh config` requires only readable root `package.json` and `cordis.yml` files in the current directory. It inspects standard features and their current feature options, expresses the final desired state through one feature tree, and shows feature changes and affected files before Review & Apply.
+
+`dsh config` can install missing features, enable or disable installed features, and switch finite feature options. Required features cannot be removed. An npm dependency change runs the project package manager's install once after the file commit; installation failure does not roll back committed project files.
+
+The SDK modifies only Cordis config entries, config keys, npm dependencies, `.env.example` placeholders, and owned files explicitly owned by a feature. Updating the same feature option preserves unknown config keys in its Cordis config entries. Handwritten and third-party plugins support enable and disable by stable ID only. When a known feature has been edited into an incomplete, ambiguous, or otherwise unreadable shape, `dsh config` displays diagnostics and refuses automatic changes until the developer repairs it manually.
+
+One config session accumulates every change in an in-memory working copy. Before Apply, it validates feature relationships, resource conflicts, and document shapes, then compares each affected existing file with the text read when the session opened. Validation failure or an external edit causes zero writes. Once physical writes begin, the SDK does not provide cross-file transactional rollback.
+
+## Maintenance model
+
+The SDK curates its builtin support set instead of exposing npm packages automatically by npm dependency name or directory convention. One feature may compose several Cordis config entries, feature options may share resources, and a feature option may declare a feature requirement on another feature or a specific feature option. Adding an ordinary feature or feature option does not require changes to both create and config command workflows.
+
+## Future work
+
+- `dsh add [package-spec]` unifies local-plugin creation with external Cordis plugin installation: without a package or repository source it creates a local plugin/tool, while a supplied source adds the npm dependency and `cordis.yml` config entry; the source model leaves room for GitHub repositories and other extensions
+- Non-interactive create/config: both workflows require a TTY in this phase and provide no complete input contract for automation
+- More feature-specific inputs: this product surface exposes only finite feature options, secrets, and a few dedicated values in this phase rather than a generic parameter interface for Cordis plugin config
+
+## Alternatives considered
+
+**An opaque preset or generator-owned project.** This shortens initial creation but hides the real plugin tree and build boundaries, prevents advanced developers from composing Cordis plugins directly, and makes project behavior depend on the CLI version rather than committed project files.
+
+**A one-shot generator only.** Leaving all later maintenance manual redistributes feature requirements, feature-option switches, and multi-file updates. A config workflow over the shared registry retains continuing management for generated projects.
+
+**Separate `cordis.yml` files for development and production.** Two plugin trees mean a successful development run does not demonstrate that production loads the same features. Dev adds only TypeScript and local-workspace resolution; runtime configuration remains singular.
+
+**A generic form for arbitrary Cordis plugin config.** Cordis plugin config contains nested structures, expressions, and plugin-specific semantics. A generic form would become a second incomplete schema. The SDK manages finite feature options and dedicated secrets, while developers continue to edit complex config directly.
+
+**A private local-plugin discovery protocol.** Ordinary package-manager workspaces, root npm dependencies, TypeScript references, and Cordis config entries already express the complete relationship. Another discovery protocol would create hidden state understood only by the SDK.
+
+**A `dsh create` command for existing projects.** Create already provides one editable local-plugin skeleton, and later plugins can use ordinary workspace and Cordis mechanisms manually. A parallel command would add a second scaffolding product surface without adding composition functionality.
+
+**Automatically expose every new Cordis plugin as a builtin.** An npm package cannot say how several plugins compose into one product feature, nor can it derive exclusivity, feature requirements, secrets, interface applicability, or security constraints. The support set requires human curation; automation is suitable only for checking whether candidates have been classified.
+
+## Acceptance criteria
+
+- `npm create @deepseek-ai/sdk` collects project identity, provider, interface, features, an optional local plugin, package manager, and installation choice in the documented order, and cancellation leaves the target path absent
+- A default npm project has the documented tree and `dev`, `build`, `typecheck`, `start`, and `config` scripts, with dev and start sharing one `cordis.yml`
+- Create offers the documented features and feature options; local and sandbox bash are exclusive with local as the default, the sandbox Cordis config entry retains the editable commented config example, and HMR is selected by default and loaded by both dev and start
+- Create's `plugin` or `tool` choice creates at most one fixed-name local plugin and atomically updates its files and root-project relationships; this phase provides no `dsh create`
+- `dsh config` reads the same support set from an existing project, installs, enables, disables, and switches supported feature options, preserves unknown config and comments, and refuses to modify inconsistent config
+- `.env.example` reflects variables required by the current features; `.env` only appends missing differently named variables and never updates or removes existing contents
+- npm, pnpm, and Yarn workspaces install, build, and start; local plugins resolve from source under dev and from built output under start
+
+## Risks
+
+- Developers can edit a builtin into a shape the registry cannot recognize; the SDK stops automating that feature instead of guessing and overwriting config
+- Pre-write validation and external-edit detection do not provide transactional rollback once multi-file writes begin; an I/O failure can leave a partial commit requiring manual repair
+- The sandbox feature option depends on an available local sandbox backend for the target platform; an unavailable backend must fail closed instead of falling back to unsandboxed execution
+- HMR retains its filesystem watcher and hot-reload behavior under production start; this is the result of an explicit plugin choice, not an implicit development-only service
+- The append-only `.env` policy retains credentials that are no longer used; the SDK does not decide when user-owned secret data is safe to delete
diff --git a/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.zh.md b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
new file mode 100644
index 0000000000..613da4da93
--- /dev/null
+++ b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
@@ -0,0 +1,167 @@
+# RFC: 开发者拥有的 SDK 工程
+
+Status: proposed
+
+[English](2026-07-14-sdk-developer-projects.md) | 中文
+
+## 问题
+
+DeepSeek Harness 通过 Cordis 插件对功能进行组合，但从空目录开始搭建一个可运行工程仍要求开发者同时理解 NPM 依赖、`cordis.yml` 插件组、环境变量、TypeScript 构建、本地插件 workspace 和运行入口。手工步骤之间存在约束，漏掉任意一处都会得到能够安装却无法开发、能够开发却无法构建，或能够构建却无法启动的工程。
+
+一次性生成器只能降低首次创建成本。若生成结果隐藏在 preset 或不可编辑的 CLI（命令行界面）内部，高级开发者无法调整插件树、修改 Cordis 插件配置或增加项目特有行为；若创建后的工程完全脱离工具管理，开发者又必须重新承担所有 NPM 依赖和 Cordis 插件配置的一致性工作。
+
+初始创建和后续配置面对同一组内置功能。两条流程各自维护功能列表、功能选项和 NPM 依赖时，新增 Cordis 插件、NPM 包或调整配置会使二者逐渐分叉。工程还需要一条普通的本地插件开发路径，参与开发、构建和启动流程。
+
+## 提案
+
+SDK 创建一个普通、显式且归开发者所有的 TypeScript/Cordis 工程。`cordis.yml` 是唯一的运行时插件树；开发和生产读取同一份文件。工程中的 `package.json`、`cordis.yml`、TypeScript 入口、构建配置和 `plugins/*` 均可直接编辑，SDK 不把它们封装成不可见的 preset。
+
+开发者产品入口只有 `npm create @deepseek-ai/sdk` 和 `dsh` 命令。前者负责首次创建，`dsh config` 在创建后管理 SDK 能识别的内置功能，`dsh dev`、`dsh build` 与 `dsh start` 负责开发、构建和启动；本期不提供 `dsh create`。create 与 config 使用同一份人工编写的功能定义，因此一项功能的功能选项、NPM 依赖、Cordis 配置项、相关文件和识别规则只有一个来源。功能、功能选项等名词由 [SDK 工程编辑架构](../architecture/2026-07-15-sdk-project-editing-architecture.md) 的术语表定义。
+
+SDK 只为功能选择和有限功能选项提供交互，不尝试把任意 Cordis 插件配置变成通用表单。功能选项所需的少量专用输入由所属功能收集；其余 Cordis 插件配置留在 `cordis.yml` 中，并通过注释指明常用改法，由开发者直接修改。
+
+## 开发者流程
+
+首次创建按会影响后续问题集合的顺序收集信息：目标目录与 package 身份、模型提供方与凭据、运行接口、内置功能与功能选项、可选本地插件、包管理器，以及是否安装 NPM 依赖并构建。命令参数已提供的答案不重复询问；本期 create 和 config 都要求交互式 TTY，取消创建时不写入目标目录。
+
+```sh
+npm create @deepseek-ai/sdk my-agent
+cd my-agent
+npm exec dsh dev index.ts
+npm exec dsh config
+npm exec dsh build
+npm exec dsh start index.js
+```
+
+create 拒绝任何已经存在的目标路径。工程文件提交成功后，CLI 询问是否安装 NPM 依赖并构建；安装或构建失败时保留生成结果，并打印可以重新执行的命令。
+
+create 还提供一次 `none / plugin / tool` 选择。`plugin` 固定生成 `plugins/plugin` 的 Cordis 插件，`tool` 固定生成 `plugins/tool` 的模型工具；一次创建至多包含一个本地插件。生成操作同时更新 workspace、根 NPM 依赖、TypeScript reference、构建配置和 `cordis.yml`，任何写入前校验失败都不创建工程。
+
+## 创建时支持的功能
+
+下表是本期 create 面向开发者展示的支持集。`required` 始终存在但仍可切换有限功能选项；`default` 在选择树中预选；`optional` 由开发者主动选择。表格说明产品支持集，运行时注册表是实现的事实源。
+
+| 功能 | create 状态 | 功能选项 | 限制与关系 |
+|---|---|---|---|
+| `provider` | required | `deepseek`（默认）/ `custom` | DeepSeek 收集 API key；custom 另收集 base URL，模型名可由 CLI 参数覆盖 |
+| `app` | required | `stdio`（默认）/ `acp` / `embed` | 选择运行接口 |
+| `spine` | required | `default` | timer、LLM seam、会话存储、系统提示词、工具注册表、agent 注册表，以及 agent loop |
+| `bash` | required | `local`（默认）/ `sandbox` | 两个功能选项互斥、与运行接口正交，且都安装面向模型的 bash 工具；sandbox 安装本地沙箱提供方和沙箱 bash 后端 |
+| `persistence` | required | `jsonl`（默认）/ `sqlite` | 每个工程恰好选择一个持久化后端 |
+| `hmr` | default | `default` | 加载 `@cordisjs/plugin-hmr`；dev 和 start 都启用，使用插件默认配置 |
+| `fs` | default | `local` | 安装本地文件系统、策略和模型工具；进程沙箱不约束进程内 fs 工具 |
+| `todo` | default | `default` | 提供 `todo_write` 工具 |
+| `skill` | default | `default` | 安装 skill（技能）注册表、本地 skill 提供方和面向模型的 skill 工具 |
+| `web` | optional | `deepseek`（默认）/ `exa` / `perplexity` / `fetch-only` | 搜索功能选项互斥；Exa/Perplexity 收集各自 API key；建议同时启用 timeout policy |
+| `subagent` | optional | `spawn`（默认）/ `fork`，可多选 | 本期只提供进程内后端 |
+| `workflow` | optional | `workerthread` | 要求 subagent 的 `spawn` 功能选项 |
+| `compact` | optional | `basic` | 使用 SDK 提供的上下文压缩参数 |
+| `hooks` | optional | `claude`（默认）/ `codex`，可多选 | 各功能选项生成独立的可编辑配置文件 |
+| `guard` | optional | `repeat-tool` | 提供重复工具调用提醒 |
+| `timeout-policy` | optional | `default` | 对声明超时预算的工具执行统一策略 |
+| `ask-user` | optional | `default` | 提供 `ask_user_question` 工具；注入的 user-interaction 服务由 acp/stdio 两个功能选项提供，因此仅这两个接口可选 |
+
+`bash` 的两个功能选项都适用于 ACP、stdio 和 embed，不由运行接口决定。sandbox 功能选项不写任何生效的配置键，因而沿用 `dsh-bash-sandbox` 的 `read-only` 默认值；生成的 `cordis.yml` 保留注释示例，开发者可以显式改为 `workspace-write`：
+
+```yaml
+- id: bash
+  name: '@deepseek-ai/dsh-bash-sandbox'
+  # Uncomment to allow writes under the project workspace.
+  # config:
+  #   mode: workspace-write
+  #   workspaceRoot: !!js process.cwd()
+```
+
+功能贡献只引用单插件 NPM 包，绝不引用 `agent-spine-demo`、`stdio-demo`、`acp-demo` 这类组合 NPM 包。表格之外的插件不由本期 create 管理；开发者仍可直接编辑普通工程文件进行高级组合。
+
+## 生成工程
+
+使用默认答案创建 npm 工程时，provider 为 DeepSeek，运行接口为 stdio，bash 为 local，持久化为 JSONL，hmr、fs、todo 与 skill 处于选中状态。初始目录树为：
+
+```text
+my-agent/
+├── .env
+├── .env.example
+├── .gitignore
+├── README.md
+├── cordis.yml
+├── index.ts
+├── package.json
+├── tsconfig.base.json
+├── tsconfig.json
+└── tsdown.config.ts
+```
+
+`.env.example` 始终存在，并由 SDK 根据当前功能维护占位。收集到 secret 或开发者确认稍后填写空凭据时，同时生成 gitignored `.env`。SDK 只向 `.env` 追加尚不存在的不同名变量，绝不覆盖或删除已有内容；切换功能选项可以清理 `.env.example` 中不再需要的占位，但旧凭据仍留在 `.env` 中供开发者自行处理。pnpm 和 Yarn 工程增加各自所需的 workspace 配置文件，但运行时插件树和 TypeScript 入口不分叉。
+
+生成的 `package.json` 提供以下 scripts；其中 `dev`、`build`、`start` 与 `config` 调用 `dsh`，`typecheck` 直接调用 TypeScript：
+
+| script | 行为 |
+|---|---|
+| `dev` | 运行 `dsh dev index.ts`，为 TypeScript 和本地 workspace 插件注册开发期解析 |
+| `build` | 运行 `dsh build`，调用工程安装的 tsdown 构建根入口和 `plugins/*` package |
+| `typecheck` | 直接运行 `tsc -b` |
+| `start` | 运行 `dsh start index.js`，启动已构建入口且不隐式构建 |
+| `config` | 运行 `dsh config`，修改当前工程功能树 |
+
+`dsh start` 与 `dsh dev` 可以接收模块 target，并把 `--` 后的参数原样转发给工程入口。通用参数解析使用 Node `parseArgs()` 的零 schema 模式：带值 flag 采用 `--key=value`，bare flag 转换为 `true`，`--no-*` 转换为 `false`。
+
+- stdio 工程通过 `--model=<name>` 传入所选 model，并根据可选的 `--resume=<session-id>` 创建或恢复 agent；
+- acp 使用协议 `session/load`
+- embed 使用生成代码中的 model。
+
+每个功能拥有的 Cordis 配置项在 `cordis.yml` 中保留自己的可编辑 Cordis 插件配置和说明注释；`dsh config` 修改其他功能时必须保留未知字段、未修改节点的格式和注释。HMR（热模块替换）是普通叶子配置项：选择该功能后，dev 和 start 加载同一个 watcher，命令不隐式改变插件树。
+
+## 创建后的配置
+
+`dsh config` 只要求当前目录具有可读的根 `package.json` 与 `cordis.yml`。它检查标准功能及其当前功能选项，以一棵功能树表达最终目标状态，并在 Review & Apply 前展示功能变化和受影响文件。
+
+`dsh config` 可以安装缺失功能、启停已安装功能和切换有限功能选项。required 功能不能取消。改变 NPM 依赖后只运行一次项目包管理器安装；安装失败不回滚已经提交的工程文件。
+
+SDK 只修改功能明确拥有的 Cordis 配置项、配置键、NPM 依赖、`.env.example` 占位和独占文件。同一功能选项的更新保留 Cordis 配置项中的未知配置键；手写或第三方插件只支持按稳定 ID 启停。已知功能被手改成不完整、歧义或无法读取的形状时，`dsh config` 显示诊断并拒绝自动修改，直到开发者手工修复。
+
+一次 config 会话在内存工作区上累计全部修改。Apply 前完成功能关系、资源冲突和文件形状校验，并比较受影响文件与会话打开时的原文；校验失败或检测到外部修改时不写盘。实际写盘开始后不提供跨文件事务回滚。
+
+## 维护模型
+
+Builtin 支持集由 SDK 人工策划，不根据 NPM 依赖名称或目录约定自动暴露。一个功能可以组合多个 Cordis 配置项，功能选项可以共享资源，并声明对其他功能或特定功能选项的功能依赖；新增普通功能或功能选项不应要求同时修改 create 和 config 两个命令流程。
+
+## 后续工作
+
+- `dsh add [package-spec]`：统一本地插件创建与外部 Cordis 插件接入；未指定 package 或仓库来源时创建本地 plugin/tool，指定来源时增加 NPM 依赖和 `cordis.yml` 配置项，来源模型为 GitHub 仓库等扩展保留空间
+- 非交互 create/config：本期两个流程都要求 TTY，不提供供自动化调用的完整输入合同
+- 更多功能专用参数输入：本期产品只展示有限功能选项、secret 和少量专用值，不为 Cordis 插件配置提供通用参数界面
+
+## 曾考虑的替代方案
+
+**不可编辑的 preset 或生成器托管工程。** 该方案可以缩短初次创建路径，但会隐藏真实插件树和构建边界，使高级开发者无法直接组合 Cordis 插件，也让项目行为依赖 CLI 版本而不是检入的工程文件。
+
+**只提供一次性生成器。** 创建后完全依赖手工维护，会让功能依赖、功能选项切换和多文件更新再次分散；共享 registry 的 config 流程为生成工程保留持续管理机制。
+
+**为开发和生产维护两份 `cordis.yml`。** 两份插件树会使开发成功无法证明生产加载相同功能；dev 只增加 TypeScript 与本地 workspace 解析，运行配置保持唯一。
+
+**为任意 Cordis 插件配置生成通用表单。** Cordis 插件配置包含嵌套结构、表达式和插件特有语义，通用表单会形成第二套不完整 schema。SDK 只管理有限功能选项和专用 secret，复杂配置继续由开发者直接编辑。
+
+**使用私有协议发现本地插件。** 普通 package manager workspace、根 NPM 依赖、TypeScript references 和 Cordis 配置项已能表达完整关系；额外发现协议会创造只能由 SDK 理解的隐藏状态。
+
+**在现有工程中提供 `dsh create`。** create 已能生成一种可编辑的本地插件骨架，后续插件可以沿用普通 workspace 和 Cordis 机制手工添加；再提供同构命令会增加第二条脚手架产品面，却不增加新的组合功能。
+
+**把每个新 Cordis 插件自动暴露为 builtin。** package 无法说明多个插件如何组合成一项产品功能，也无法推导互斥关系、功能依赖、secret、接口适用性和安全限制；支持集需要人工策划，自动化只适合检查候选是否完成分类。
+
+## 验收标准
+
+- `npm create @deepseek-ai/sdk` 按本文顺序收集项目身份、provider、interface、功能、可选本地插件、包管理器和安装选择，并在取消时保持目标路径不存在
+- 默认 npm 工程具有本文目录树和 `dev`、`build`、`typecheck`、`start`、`config` scripts，且 dev/start 使用同一份 `cordis.yml`
+- create 展示本文功能及功能选项；`bash` 的 local/sandbox 二选一且默认 local，sandbox Cordis 配置项保留可编辑的注释配置示例；HMR 默认选中并同时由 dev/start 加载
+- create 的 `plugin` 或 `tool` 选择至多生成一个固定名称的本地插件，并原子更新插件文件与根工程关系；本期不提供 `dsh create`
+- `dsh config` 从现有工程读取同一支持集，能够安装、启停和切换支持的功能选项，保留未知配置与注释，并拒绝修改不一致配置
+- `.env.example` 反映当前功能所需变量；`.env` 只追加缺失的不同名变量，从不覆盖或清理已有内容
+- npm、pnpm 和 Yarn 生成的 workspace 能安装、构建和启动；本地插件在 dev 中使用源码，在 start 中使用构建产物
+
+## 风险
+
+- 开发者可以把 builtin 手改成 registry 无法识别的形状；SDK 选择停止自动化而不是猜测并覆盖配置
+- 多文件写入前的校验和外部修改检测不能提供写入阶段的事务回滚；I/O 中途失败可能留下需要人工修复的部分提交
+- sandbox 功能选项依赖目标平台存在可用的本地沙箱后端；后端不可用时必须 fail closed，不能退回无沙箱执行
+- HMR 在生产启动中也保持文件 watcher 和热重载行为；这是显式插件选择的结果，不是仅限开发环境的隐式服务
+- `.env` 的仅追加策略会保留已经不用的凭据，SDK 不判断这些用户数据何时可以安全删除
diff --git a/knip.json b/knip.json
index 71c9d1e01d..b978da3a76 100644
--- a/knip.json
+++ b/knip.json
@@ -97,6 +97,15 @@
     "packages/examples/jsonrpc-demo": {
       "project": ["src/**/*.ts"]
     },
+    "packages/sdk/create-sdk": {
+      "entry": ["src/bin.ts", "tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/**/*.snapshot.ts"],
+      "project": ["src/**/*.ts", "tests/**/*.ts"]
+    },
+    "packages/sdk/scripts": {
+      "entry": ["src/bin.ts", "tests/**/*.spec.ts", "tests/**/*.snapshot.ts"],
+      "project": ["src/**/*.ts", "tests/**/*.ts"],
+      "ignoreDependencies": ["node-addon-require-builtin"]
+    },
     "packages/subagent/subagent-spawn": {
       "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
       "project": ["src/**/*.ts", "tests/**/*.ts"]
diff --git a/packages/README.md b/packages/README.md
index 59a0a1a7c3..8f1bf3dde2 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -28,6 +28,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
 | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface |
 | [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, surface records, and bounded exact reads | Product — stable surface |
+| [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface |
 | [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, user-approval/user-interaction seams, ask-user tool | Product — stable surface |
 | [`examples/`](examples/README.md) | Demo bundles (agent-spine + stdio/ACP/JSON-RPC bins) the leaves load | Support — example infra |
 | [`support/`](support/README.md) | Support infrastructure (invariants, replay, Loader smokes) | Support — lower compatibility expectations |
diff --git a/packages/core/agent/tests/verify-export-jsdoc.spec.ts b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
index 2761351d10..cc361a956e 100644
--- a/packages/core/agent/tests/verify-export-jsdoc.spec.ts
+++ b/packages/core/agent/tests/verify-export-jsdoc.spec.ts
@@ -30,6 +30,22 @@ function fixture(files: Record<string, string>): string {
 const make = (content: string): string => fixture({ 'index.ts': content })
 
 describe('verify-export-jsdoc functions and consts', () => {
+  it('limits packages without src/* exports to declarations reachable from package entrypoints', () => {
+    const root = fixture({
+      'index.ts': "export { publicFn } from './internal.ts'\n",
+      'internal.ts': `
+export function publicFn(value: string): string { return value }
+export function hiddenFn(value: string): string { return value }
+`,
+    })
+    writeFileSync(join(root, 'packages/group/fix/package.json'), JSON.stringify({
+      exports: { '.': { types: './lib/types/index.d.ts', default: './lib/index.js' } },
+    }))
+    const violations = collectExportJsdocViolations(root)
+    expect(violations).toHaveLength(1)
+    expect(violations.every(violation => violation.includes('publicFn'))).toBe(true)
+  })
+
   it('accepts a fully documented surface', () => {
     expect(collectExportJsdocViolations(make(`
 /**
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
new file mode 100644
index 0000000000..a193206a65
--- /dev/null
+++ b/packages/sdk/README.md
@@ -0,0 +1,15 @@
+# SDK packages
+
+Developer tooling for creating, editing, building, and running DeepSeek Harness projects.
+
+The [feature RFC](../../docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md) owns the developer workflow; the [architecture RFC](../../docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md) owns the package and project-editing boundaries.
+
+| Package | Role |
+|---|---|
+| [`helper`](helper/README.md) | Project aggregate, edit session, builtin features, project documents, templates, package managers, and prompt abstraction |
+| [`scripts`](scripts/README.md) | The `dsh` launcher: `start`, `dev`, `build`, and interactive `config` |
+| [`create-sdk`](create-sdk/README.md) | The `npm create @deepseek-ai/sdk` initializer |
+
+`@deepseek-ai/create-sdk` is the one package-name exception to the repository's `@deepseek-ai/dsh-*` rule: npm's scoped initializer convention requires that name for `npm create @deepseek-ai/sdk`.
+
+Generated projects keep `cordis.yml` as the only runtime plugin tree. `dsh dev` adds TypeScript and local-workspace resolution around that same file; it does not create a development-only config.
diff --git a/packages/sdk/create-sdk/README.md b/packages/sdk/create-sdk/README.md
new file mode 100644
index 0000000000..66cddc030a
--- /dev/null
+++ b/packages/sdk/create-sdk/README.md
@@ -0,0 +1,19 @@
+# `@deepseek-ai/create-sdk`
+
+Interactive initializer for `npm create @deepseek-ai/sdk [directory]`. Directory/name/description have visible editable defaults. A tree picker selects features and configures finite options with Right/Left navigation; secret text follows only for selected options. Local plugin creation is one none/plugin/tool choice.
+
+The supported package surface is the `create-sdk` bin. The package root exports no symbols, and workflow, bin, source, and package-manifest subpaths are not exported.
+
+The initializer rejects every existing target path, creates one `SdkProject` edit session, validates and commits it, then asks whether to install NPM dependencies and build. Install or build failures keep the generated project and print a retry command.
+
+Public flags are `[directory]`, `--description`, `--provider`, `--base-url`, `--api-key`, `--model`, `--interface`, `--pm`, and `--install`/`--no-install`. Flags prefill matching questions, but creation always requires a TTY.
+
+The provider choice is DeepSeek or a custom endpoint backed by `llm-pi-ai`. DeepSeek asks only for an API key and uses the public endpoint plus `deepseek-v4-flash`; custom also asks for a base URL. An empty key requires confirmation and creates a commented empty `.env` variable so provider startup fails clearly until it is filled. Existing plugin defaults are omitted; required SDK presets remain typed against the owning package's Config.
+
+## Model Experience
+
+Indirectly, through the generated project composition and its selected runtime plugins.
+
+## Known Limitations and Deferred Work
+
+- **TTY-only creation** — flags prefill questions, but the wizard still requires an interactive terminal before it writes a project.
diff --git a/packages/sdk/create-sdk/package.json b/packages/sdk/create-sdk/package.json
new file mode 100644
index 0000000000..e23415f8dc
--- /dev/null
+++ b/packages/sdk/create-sdk/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "@deepseek-ai/create-sdk",
+  "description": "Create a DeepSeek Harness SDK project with npm create @deepseek-ai/sdk",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "bin": {
+    "create-sdk": "lib/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/bin.js",
+    "lib/assets",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-helper": "workspace:^",
+    "commander": "^15.0.0"
+  },
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/sdk/create-sdk/src/args.ts b/packages/sdk/create-sdk/src/args.ts
new file mode 100644
index 0000000000..521132caa9
--- /dev/null
+++ b/packages/sdk/create-sdk/src/args.ts
@@ -0,0 +1,84 @@
+/**
+ * Commander adapter for the create-sdk command surface.
+ *
+ * @module @deepseek-ai/create-sdk/args
+ */
+
+import { Command, Option } from 'commander'
+import type { PackageManagerName, RunInterface } from '@deepseek-ai/dsh-helper'
+
+/** Parsed create command flags before interactive resolution. */
+export interface CreateArgs {
+  directory?: string
+  description?: string
+  provider?: 'deepseek' | 'custom'
+  baseURL?: string
+  apiKey?: string
+  model?: string
+  runInterface?: RunInterface
+  packageManager?: PackageManagerName
+  install?: boolean
+  linkWorkspace?: boolean
+  help: boolean
+}
+
+interface CommanderCreateOptions {
+  description?: string
+  provider?: 'deepseek' | 'custom'
+  baseUrl?: string
+  apiKey?: string
+  model?: string
+  interface?: RunInterface
+  pm?: PackageManagerName
+  install?: boolean
+  linkWorkspace?: boolean
+  help?: boolean
+}
+
+function createProgram(): Command {
+  return new Command()
+    .name('create-sdk')
+    .description('Create a DeepSeek Harness SDK project')
+    .helpOption(false)
+    .showHelpAfterError(false)
+    .exitOverride()
+    .configureOutput({
+      /* v8 ignore next -- the command wrapper renders the package-owned usage template */
+      writeOut: () => {},
+      /* v8 ignore next -- Commander output is deliberately suppressed; errors are returned to the bin wrapper */
+      writeErr: () => {},
+    })
+    .argument('[directory]')
+    .option('-h, --help')
+    .option('--description <text>')
+    .addOption(new Option('--provider <name>').choices(['deepseek', 'custom']))
+    .option('--base-url <url>')
+    .option('--api-key <key>')
+    .option('--model <name>')
+    .addOption(new Option('--interface <name>').choices(['acp', 'stdio', 'embed']))
+    .addOption(new Option('--pm <name>').choices(['npm', 'pnpm', 'yarn']))
+    .addOption(new Option('--install').default(undefined))
+    .addOption(new Option('--no-install').default(undefined))
+    .option('--link-workspace')
+}
+
+/** Parse create-sdk positionals/options through Commander into a domain-neutral value. */
+export function parseCreateArgs(argv: readonly string[]): CreateArgs {
+  const program = createProgram()
+  program.parse([...argv], { from: 'user' })
+  const options = program.opts<CommanderCreateOptions>()
+  const directory = program.processedArgs[0] as string | undefined
+  return {
+    ...directory === undefined ? {} : { directory },
+    ...options.description === undefined ? {} : { description: options.description },
+    ...options.provider === undefined ? {} : { provider: options.provider },
+    ...options.baseUrl === undefined ? {} : { baseURL: options.baseUrl },
+    ...options.apiKey === undefined ? {} : { apiKey: options.apiKey },
+    ...options.model === undefined ? {} : { model: options.model },
+    ...options.interface === undefined ? {} : { runInterface: options.interface },
+    ...options.pm === undefined ? {} : { packageManager: options.pm },
+    ...options.install === undefined ? {} : { install: options.install },
+    ...options.linkWorkspace ? { linkWorkspace: true } : {},
+    help: options.help ?? false,
+  }
+}
diff --git a/packages/sdk/create-sdk/src/bin.ts b/packages/sdk/create-sdk/src/bin.ts
new file mode 100644
index 0000000000..7a04af8b84
--- /dev/null
+++ b/packages/sdk/create-sdk/src/bin.ts
@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Self-executing create-sdk command.
+ *
+ * @module @deepseek-ai/create-sdk/bin
+ */
+
+import { runCreateCommand } from './command.ts'
+
+process.exitCode = await runCreateCommand()
diff --git a/packages/sdk/create-sdk/src/command.ts b/packages/sdk/create-sdk/src/command.ts
new file mode 100644
index 0000000000..613eb62a4e
--- /dev/null
+++ b/packages/sdk/create-sdk/src/command.ts
@@ -0,0 +1,110 @@
+/**
+ * Internal create-sdk command composition used by the package bin.
+ *
+ * @module @deepseek-ai/create-sdk/command
+ */
+
+import { readFile } from 'node:fs/promises'
+import {
+  ClackPromptPort,
+  PromptCancelledError,
+  type PackageManagerVersionProbe,
+  type PromptPort,
+} from '@deepseek-ai/dsh-helper'
+import { parseCreateArgs } from './args.ts'
+import { CreateWizard, type ResolvedCreateRequest } from './create-wizard.ts'
+import { scaffoldProject, type ScaffoldResult } from './project-scaffolder.ts'
+import { CREATE_TEMPLATES, packageManagerTemplateModel } from './templates/create-templates.ts'
+
+/** Process and terminal slice used by the initializer. */
+export interface CreateCommandContext {
+  cwd: string
+  stdin: NodeJS.ReadStream
+  stdout: NodeJS.WriteStream
+  stderr: NodeJS.WriteStream
+  releaseVersion?: string
+  versionProbe?: PackageManagerVersionProbe
+  port?: PromptPort
+  setup?: (request: ResolvedCreateRequest) => Promise<void>
+}
+
+/** Read this initializer package's release version in source and built layouts. */
+export async function readCreateSdkVersion(): Promise<string> {
+  const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')) as { version?: unknown }
+  /* v8 ignore next -- this package's checked-in manifest always carries its version */
+  if (typeof manifest.version !== 'string') throw new Error('create-sdk package version is missing')
+  return manifest.version
+}
+
+/** Resolve, write, optionally install, and build one new project. */
+export async function createProject(
+  argv: readonly string[],
+  context: CreateCommandContext,
+): Promise<ScaffoldResult | undefined> {
+  const args = parseCreateArgs(argv)
+  if (args.help) {
+    context.stdout.write(CREATE_TEMPLATES.usage.render({}))
+    return undefined
+  }
+  if (!context.port && (!context.stdin.isTTY || !context.stdout.isTTY)) {
+    throw new Error('create-sdk requires an interactive TTY')
+  }
+  const wizard = new CreateWizard({
+    args,
+    /* v8 ignore next -- production TTY wiring is exercised by the built-bin smoke */
+    port: context.port ?? new ClackPromptPort(context.stdin, context.stdout),
+    cwd: context.cwd,
+    releaseVersion: context.releaseVersion ?? await readCreateSdkVersion(),
+    ...context.versionProbe ? { versionProbe: context.versionProbe } : {},
+  })
+  const resolved = await wizard.run()
+  const result = await scaffoldProject(resolved.directory, resolved.request)
+  context.stdout.write(CREATE_TEMPLATES.created.render({
+    name: resolved.request.name,
+    directory: resolved.directory,
+  }))
+  if (resolved.install) {
+    try {
+      if (context.setup) await context.setup(resolved)
+      else {
+        await resolved.request.packageManager.install(resolved.directory)
+        await resolved.request.packageManager.build(resolved.directory)
+      }
+    } catch (error) {
+      context.stderr.write(CREATE_TEMPLATES.setupFailure.render({
+        directory: resolved.directory,
+        error: String(error),
+        ...packageManagerTemplateModel(resolved.request.packageManager),
+      }))
+      throw error
+    }
+  }
+  context.stdout.write(CREATE_TEMPLATES.nextSteps.render({
+    directory: resolved.directory,
+    packageManager: resolved.request.packageManager.name,
+  }))
+  return result
+}
+
+/** Run the create command with process defaults and convert cancellation to a clean exit. */
+export async function runCreateCommand(
+  argv: readonly string[] = process.argv.slice(2),
+  context: CreateCommandContext = {
+    cwd: process.cwd(),
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+  },
+): Promise<number> {
+  try {
+    await createProject(argv, context)
+    return 0
+  } catch (error) {
+    if (error instanceof PromptCancelledError) {
+      context.stderr.write('create-sdk: cancelled\n')
+      return 1
+    }
+    context.stderr.write(`create-sdk: ${error instanceof Error ? error.message : String(error)}\n`)
+    return 1
+  }
+}
diff --git a/packages/sdk/create-sdk/src/create-questions.ts b/packages/sdk/create-sdk/src/create-questions.ts
new file mode 100644
index 0000000000..c53e6e227e
--- /dev/null
+++ b/packages/sdk/create-sdk/src/create-questions.ts
@@ -0,0 +1,205 @@
+/**
+ * Static create-sdk question sequence; dynamic feature/plugin loops remain
+ * in the wizard orchestrator.
+ *
+ * @module @deepseek-ai/create-sdk/create-questions
+ */
+
+import { existsSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+import {
+  ConfirmQuestion,
+  SecretQuestion,
+  SelectQuestion,
+  TextQuestion,
+  requireAnswer,
+  type PromptPort,
+  type Question,
+  type RunInterface,
+} from '@deepseek-ai/dsh-helper'
+import type { CreateArgs } from './args.ts'
+
+/** Answers that establish project identity and feature applicability. */
+export interface ProjectAnswers {
+  directory: string
+  name: string
+  description: string
+  provider: 'deepseek' | 'custom'
+  baseURL: string
+  apiKey: string
+  model: string
+  runInterface: RunInterface
+}
+
+interface ProjectAnswerState extends Partial<ProjectAnswers> {
+  readonly args: CreateArgs
+  readonly cwd: string
+}
+
+interface WizardStep<TState> {
+  run(port: PromptPort, state: TState): Promise<void>
+}
+
+function questionStep<TState, TValue>(options: {
+  question: (state: TState) => Question<TValue>
+  when?: (state: TState) => boolean
+  prefilled?: (state: TState) => TValue | undefined
+  apply: (state: TState, value: TValue) => void
+}): WizardStep<TState> {
+  return {
+    async run(port, state) {
+      if (options.when && !options.when(state)) return
+      const value = requireAnswer(await options.question(state).resolve(port, options.prefilled?.(state)))
+      options.apply(state, value)
+    },
+  }
+}
+
+/** Validate one required text answer. */
+function nonEmpty(value: string): string | undefined {
+  return value.trim().length === 0 ? 'A value is required' : undefined
+}
+
+function packageName(value: string): string | undefined {
+  if (!/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value)) {
+    return 'Use a lowercase npm package name'
+  }
+  return undefined
+}
+
+function projectDirectory(value: string, cwd: string): string | undefined {
+  const empty = nonEmpty(value)
+  if (empty) return empty
+  return existsSync(resolve(cwd, value)) ? 'Target already exists' : undefined
+}
+
+const API_KEY_STEP: WizardStep<ProjectAnswerState> = {
+  async run(port, state) {
+    let prefilled = state.args.apiKey
+    while (true) {
+      const apiKey = requireAnswer(await new SecretQuestion({
+        id: 'apiKey',
+        message: state.provider === 'custom' ? 'Custom provider API key' : 'DeepSeek API key',
+      }).resolve(port, prefilled))
+      if (apiKey.length > 0) {
+        state.apiKey = apiKey
+        return
+      }
+      const keepEmpty = requireAnswer(await new ConfirmQuestion({
+        id: 'apiKey.empty',
+        message: 'Keep the API key empty and fill .env later?',
+        initialValue: false,
+        tone: 'warning',
+      }).resolve(port))
+      if (keepEmpty) {
+        state.apiKey = ''
+        return
+      }
+      prefilled = undefined
+    }
+  },
+}
+
+const PROJECT_QUESTION_STEPS: readonly WizardStep<ProjectAnswerState>[] = [
+  questionStep({
+    question: state => new TextQuestion({
+      id: 'directory',
+      message: 'Where should the project be created?',
+      placeholder: 'my-agent',
+      defaultValue: 'my-agent',
+      validate: value => projectDirectory(value, state.cwd),
+    }),
+    prefilled: state => state.args.directory,
+    apply: (state, value) => { state.directory = resolve(state.cwd, value) },
+  }),
+  questionStep({
+    question: (state) => {
+      /* v8 ignore next -- the preceding directory step always populates this state */
+      if (!state.directory) throw new Error('directory must resolve before package name')
+      return new TextQuestion({
+        id: 'name',
+        message: 'Package name',
+        placeholder: basename(state.directory),
+        defaultValue: basename(state.directory),
+        validate: packageName,
+      })
+    },
+    apply: (state, value) => { state.name = value },
+  }),
+  questionStep({
+    question: (state) => {
+      /* v8 ignore next -- the preceding package-name step always populates this state */
+      if (!state.name) throw new Error('package name must resolve before description')
+      return new TextQuestion({
+        id: 'description',
+        message: 'Project description',
+        placeholder: `A DeepSeek Harness agent named ${state.name}`,
+        defaultValue: `A DeepSeek Harness agent named ${state.name}`,
+        validate: nonEmpty,
+      })
+    },
+    prefilled: state => state.args.description,
+    apply: (state, value) => { state.description = value },
+  }),
+  questionStep({
+    question: () => new SelectQuestion<'deepseek' | 'custom'>({
+      id: 'provider',
+      message: 'Model provider',
+      options: [
+        { value: 'deepseek', label: 'DeepSeek' },
+        { value: 'custom', label: 'Custom endpoint (pi-ai)' },
+      ],
+      initialValue: 'deepseek',
+    }),
+    prefilled: state => state.args.provider,
+    apply: (state, value) => { state.provider = value },
+  }),
+  questionStep({
+    question: () => new TextQuestion({
+      id: 'baseURL', message: 'Custom provider base URL', validate: nonEmpty,
+    }),
+    when: state => state.provider === 'custom' || state.args.baseURL !== undefined,
+    prefilled: state => state.args.baseURL,
+    apply: (state, value) => { state.baseURL = value },
+  }),
+  API_KEY_STEP,
+  questionStep({
+    question: () => new SelectQuestion<RunInterface>({
+      id: 'interface',
+      message: 'Run interface',
+      options: [
+        { value: 'acp', label: 'ACP server' },
+        { value: 'stdio', label: 'Terminal REPL' },
+        { value: 'embed', label: 'Embedded context' },
+      ],
+      initialValue: 'stdio',
+    }),
+    prefilled: state => state.args.runInterface,
+    apply: (state, value) => { state.runInterface = value },
+  }),
+]
+
+function completeAnswers(state: ProjectAnswerState): ProjectAnswers {
+  const keys = ['directory', 'name', 'description', 'provider', 'baseURL', 'apiKey', 'model', 'runInterface'] as const
+  for (const key of keys) {
+    /* v8 ignore next -- the fixed step list above populates every key or throws/cancels first */
+    if (state[key] === undefined) throw new Error(`create question did not resolve ${key}`)
+  }
+  return state as ProjectAnswerState & ProjectAnswers
+}
+
+/** Run the fixed project-context sequence in declaration order. */
+export async function collectProjectAnswers(
+  port: PromptPort,
+  args: CreateArgs,
+  cwd: string,
+): Promise<ProjectAnswers> {
+  const state: ProjectAnswerState = {
+    args,
+    cwd,
+    baseURL: args.baseURL ?? '',
+    model: args.model ?? 'deepseek-v4-flash',
+  }
+  for (const step of PROJECT_QUESTION_STEPS) await step.run(port, state)
+  return completeAnswers(state)
+}
diff --git a/packages/sdk/create-sdk/src/create-wizard.ts b/packages/sdk/create-sdk/src/create-wizard.ts
new file mode 100644
index 0000000000..8391fae1e4
--- /dev/null
+++ b/packages/sdk/create-sdk/src/create-wizard.ts
@@ -0,0 +1,222 @@
+/**
+ * Declarative create questions with dynamic feature and plugin orchestration.
+ *
+ * @module @deepseek-ai/create-sdk/create-wizard
+ */
+
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  FeatureConfigurator,
+  ConfirmQuestion,
+  LocalPluginBlueprint,
+  NpmPackageManager,
+  SelectQuestion,
+  featureId,
+  createBuiltinRegistry,
+  createPackageManager,
+  inferPackageManagerName,
+  probePackageManagerVersion,
+  requireAnswer,
+  type FeatureRegistry,
+  type FeatureSelection,
+  type LocalPluginKind,
+  type PackageManager,
+  type PackageManagerName,
+  type PackageManagerVersionProbe,
+  type ProjectCreationRequest,
+  type ProjectProfile,
+  type PromptPort,
+} from '@deepseek-ai/dsh-helper'
+import type { CreateArgs } from './args.ts'
+import { collectProjectAnswers, type ProjectAnswers } from './create-questions.ts'
+import { CREATE_TEMPLATES, packageManagerTemplateModel } from './templates/create-templates.ts'
+
+/** Fully resolved initializer request and post-create choice. */
+export interface ResolvedCreateRequest {
+  directory: string
+  request: ProjectCreationRequest
+  install: boolean
+}
+
+/** Create-specific orchestration around declarative questions and dynamic selections. */
+export class CreateWizard {
+  private readonly args: CreateArgs
+  private readonly port: PromptPort
+  private readonly cwd: string
+  private readonly releaseVersion: string
+  private readonly versionProbe: PackageManagerVersionProbe
+  private readonly userAgent: string
+  private readonly linkWorkspaceRoot: string | undefined
+
+  /** Bind parsed args and infrastructure to one wizard run. */
+  constructor(options: {
+    args: CreateArgs
+    port: PromptPort
+    cwd?: string
+    releaseVersion: string
+    versionProbe?: PackageManagerVersionProbe
+    userAgent?: string
+  }) {
+    this.args = options.args
+    this.port = options.port
+    this.cwd = resolve(options.cwd ?? process.cwd())
+    this.releaseVersion = options.releaseVersion
+    this.versionProbe = options.versionProbe ?? probePackageManagerVersion
+    /* v8 ignore next -- pnpm supplies npm_config_user_agent while direct invocations may omit it */
+    this.userAgent = options.userAgent ?? process.env.npm_config_user_agent ?? ''
+    this.linkWorkspaceRoot = options.args.linkWorkspace
+      ? fileURLToPath(new URL('../../../../', import.meta.url))
+      : undefined
+  }
+
+  /** Collect all answers before constructing any project files. */
+  async run(): Promise<ResolvedCreateRequest> {
+    const answers = await this.collectProjectAnswers()
+    const profile = this.provisionalProfile(answers)
+    const registry = createBuiltinRegistry(profile)
+    const features = await this.collectFeatures(profile, registry, answers)
+    const localPlugins = await this.collectPlugins()
+    const { manager, install } = await this.collectPackageManager()
+    return {
+      directory: answers.directory,
+      install,
+      request: {
+        name: answers.name,
+        description: answers.description,
+        runtime: { model: answers.model },
+        packageManager: manager,
+        releaseVersion: this.releaseVersion,
+        ...this.linkWorkspaceRoot ? { linkWorkspaceRoot: this.linkWorkspaceRoot } : {},
+        features,
+        localPlugins,
+      },
+    }
+  }
+
+  private async collectProjectAnswers(): Promise<ProjectAnswers> {
+    return collectProjectAnswers(this.port, this.args, this.cwd)
+  }
+
+  private provisionalProfile(answers: ProjectAnswers): ProjectProfile {
+    return {
+      name: answers.name,
+      description: answers.description,
+      runtime: { model: answers.model },
+      runInterface: answers.runInterface,
+      packageManager: new NpmPackageManager('10.0.0'),
+      releaseVersion: this.releaseVersion,
+      ...this.linkWorkspaceRoot ? { linkWorkspaceRoot: this.linkWorkspaceRoot } : {},
+    }
+  }
+
+  private async collectFeatures(
+    profile: ProjectProfile,
+    registry: FeatureRegistry,
+    answers: ProjectAnswers,
+  ): Promise<FeatureSelection[]> {
+    const configurator = new FeatureConfigurator(this.port)
+    const selections: FeatureSelection[] = [
+      {
+        id: featureId('provider'),
+        options: [answers.provider],
+        ...answers.baseURL ? { values: { baseURL: answers.baseURL } } : {},
+        secrets: { apiKey: answers.apiKey },
+      },
+      { id: featureId('spine'), options: ['default'] },
+      { id: featureId('app'), options: [answers.runInterface] },
+    ]
+    const configurable = registry.all().filter(feature => feature.id === 'bash'
+      || feature.id === 'persistence'
+      || (!feature.required && feature.isApplicable(profile)))
+    const selected = [...requireAnswer(await this.port.nestedMultiselect({
+      message: 'Select features',
+      options: configurable.map((feature) => {
+        const nested = feature.mode !== 'single'
+        const defaults = new Set(feature.defaultOptions(profile))
+        return {
+          value: feature.id,
+          label: feature.summary,
+          required: feature.required,
+          default: feature.required || feature.id === 'hmr' || feature.id === 'fs' || feature.id === 'todo'
+            || feature.id === 'skill',
+          ...nested ? {
+            choiceMode: feature.mode === 'multiple' ? 'multiple' as const : 'exclusive' as const,
+            choices: feature.options.map(option => ({
+              value: option.id,
+              label: option.label,
+              default: defaults.has(option.id),
+            })),
+          } : {},
+        }
+      }),
+    }))]
+    for (const { value: id } of [...selected]) {
+      const feature = registry.get(id)
+      for (const suggestedId of feature.suggests) {
+        if (selected.some(item => item.value === suggestedId)) continue
+        const suggested = registry.get(suggestedId)
+        const add = requireAnswer(await new ConfirmQuestion({
+          id: `${feature.id}.${suggested.id}`,
+          message: `Add the recommended ${suggested.summary.toLowerCase()} for ${feature.summary.toLowerCase()}?`,
+          initialValue: true,
+        }).resolve(this.port))
+        if (add) selected.push({ value: suggested.id, choices: suggested.defaultOptions(profile) })
+      }
+    }
+    const fixed = new Set(selections.map(selection => selection.id))
+    const choices = new Map<FeatureSelection['id'], readonly string[] | undefined>()
+    for (const feature of registry.all()) {
+      if (feature.required && feature.isApplicable(profile) && !fixed.has(feature.id)) {
+        choices.set(feature.id, feature.defaultOptions(profile))
+      }
+    }
+    for (const choice of selected) {
+      choices.set(choice.value, choice.choices.length > 0 ? choice.choices : undefined)
+    }
+    for (const [id, options] of choices) {
+      selections.push(await configurator.configure(
+        registry.get(id),
+        profile,
+        undefined,
+        options,
+      ))
+    }
+    return selections
+  }
+
+  private async collectPlugins(): Promise<LocalPluginBlueprint[]> {
+    const kind = requireAnswer(await new SelectQuestion<LocalPluginKind | 'none'>({
+      id: 'plugins.kind',
+      message: 'Local plugin',
+      options: [
+        { value: 'none', label: 'No local plugin' },
+        { value: 'plugin', label: 'Cordis plugin' },
+        { value: 'tool', label: 'Model-facing tool' },
+      ],
+      initialValue: 'none',
+    }).resolve(this.port))
+    return kind === 'none' ? [] : [new LocalPluginBlueprint(kind, kind)]
+  }
+
+  private async collectPackageManager(): Promise<{ manager: PackageManager; install: boolean }> {
+    const inferred = inferPackageManagerName(this.args.packageManager, this.userAgent)
+    const name = requireAnswer(await new SelectQuestion<PackageManagerName>({
+      id: 'packageManager',
+      message: 'Package manager',
+      options: [
+        { value: 'npm', label: 'npm' },
+        { value: 'pnpm', label: 'pnpm' },
+        { value: 'yarn', label: 'Yarn' },
+      ],
+      initialValue: inferred ?? 'npm',
+    }).resolve(this.port, inferred))
+    const manager = createPackageManager(name, await this.versionProbe(name, this.cwd))
+    const install = requireAnswer(await new ConfirmQuestion({
+      id: 'install',
+      message: CREATE_TEMPLATES.installQuestion.render(packageManagerTemplateModel(manager)).trimEnd(),
+      initialValue: true,
+    }).resolve(this.port, this.args.install))
+    return { manager, install }
+  }
+}
diff --git a/packages/sdk/create-sdk/src/index.ts b/packages/sdk/create-sdk/src/index.ts
new file mode 100644
index 0000000000..f931d956f6
--- /dev/null
+++ b/packages/sdk/create-sdk/src/index.ts
@@ -0,0 +1,7 @@
+/**
+ * The create-sdk package is a CLI initializer; its library entry exports no symbols.
+ *
+ * @module @deepseek-ai/create-sdk
+ */
+
+export {}
diff --git a/packages/sdk/create-sdk/src/project-scaffolder.ts b/packages/sdk/create-sdk/src/project-scaffolder.ts
new file mode 100644
index 0000000000..f17f04317d
--- /dev/null
+++ b/packages/sdk/create-sdk/src/project-scaffolder.ts
@@ -0,0 +1,41 @@
+/**
+ * Project creation use case over the shared SDK aggregate and edit session.
+ *
+ * @module @deepseek-ai/create-sdk/project-scaffolder
+ */
+
+import { stat } from 'node:fs/promises'
+import {
+  SdkProject,
+  createBuiltinRegistry,
+  type ChangeSet,
+  type ProjectCreationRequest,
+} from '@deepseek-ai/dsh-helper'
+
+/** Result of writing one new SDK project. */
+export interface ScaffoldResult {
+  project: SdkProject
+  changes: ChangeSet
+}
+
+/** Create a project entirely in memory, then validate and commit it once. */
+export async function scaffoldProject(root: string, request: ProjectCreationRequest): Promise<ScaffoldResult> {
+  let targetExists = true
+  try {
+    await stat(root)
+  } catch (error) {
+    /* v8 ignore else -- the other arm requires a filesystem permission/IO fault from stat */
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') targetExists = false
+    /* v8 ignore next -- paired with the ignored defensive stat-error arm above */
+    else throw error
+  }
+  if (targetExists) throw new Error(`target already exists: ${root}`)
+  const project = SdkProject.create(root, request)
+  const registry = createBuiltinRegistry(project.profile)
+  const edit = project.edit(registry)
+  for (const selection of request.features) {
+    edit.installFeature(registry.get(selection.id), selection)
+  }
+  for (const plugin of request.localPlugins) edit.addPlugin(plugin)
+  return edit.commit()
+}
diff --git a/packages/sdk/create-sdk/src/templates/assets/created.txt.tpl b/packages/sdk/create-sdk/src/templates/assets/created.txt.tpl
new file mode 100644
index 0000000000..9d4eff4e92
--- /dev/null
+++ b/packages/sdk/create-sdk/src/templates/assets/created.txt.tpl
@@ -0,0 +1 @@
+Created {{name}} in {{directory}}
diff --git a/packages/sdk/create-sdk/src/templates/assets/install-question.txt.tpl b/packages/sdk/create-sdk/src/templates/assets/install-question.txt.tpl
new file mode 100644
index 0000000000..4872f63df0
--- /dev/null
+++ b/packages/sdk/create-sdk/src/templates/assets/install-question.txt.tpl
@@ -0,0 +1 @@
+Run {{packageManager}} {{installArgs}} and then build the project?
diff --git a/packages/sdk/create-sdk/src/templates/assets/next-steps.txt.tpl b/packages/sdk/create-sdk/src/templates/assets/next-steps.txt.tpl
new file mode 100644
index 0000000000..247d1259aa
--- /dev/null
+++ b/packages/sdk/create-sdk/src/templates/assets/next-steps.txt.tpl
@@ -0,0 +1 @@
+Next: cd {{directory}} && {{packageManager}} start
diff --git a/packages/sdk/create-sdk/src/templates/assets/setup-failure.txt.tpl b/packages/sdk/create-sdk/src/templates/assets/setup-failure.txt.tpl
new file mode 100644
index 0000000000..7d1e06c820
--- /dev/null
+++ b/packages/sdk/create-sdk/src/templates/assets/setup-failure.txt.tpl
@@ -0,0 +1,2 @@
+Project files are ready, but setup failed: {{error}}
+Retry: cd {{directory}} && {{packageManager}} {{installArgs}} && {{packageManager}} {{buildArgs}}
diff --git a/packages/sdk/create-sdk/src/templates/assets/usage.txt.tpl b/packages/sdk/create-sdk/src/templates/assets/usage.txt.tpl
new file mode 100644
index 0000000000..2b734eb753
--- /dev/null
+++ b/packages/sdk/create-sdk/src/templates/assets/usage.txt.tpl
@@ -0,0 +1,11 @@
+Usage: create-sdk [directory] [options]
+
+Options:
+  --description <text>
+  --provider <deepseek|custom>
+  --base-url <url>
+  --api-key <key>
+  --model <name>
+  --interface <acp|stdio|embed>
+  --pm <npm|pnpm|yarn>
+  --install / --no-install
diff --git a/packages/sdk/create-sdk/src/templates/create-templates.ts b/packages/sdk/create-sdk/src/templates/create-templates.ts
new file mode 100644
index 0000000000..99a587ce89
--- /dev/null
+++ b/packages/sdk/create-sdk/src/templates/create-templates.ts
@@ -0,0 +1,59 @@
+/**
+ * Package-owned terminal templates for create-sdk.
+ *
+ * @module @deepseek-ai/create-sdk/templates/create-templates
+ */
+
+import {
+  TextTemplate,
+  type PackageManager,
+  type PackageManagerName,
+} from '@deepseek-ai/dsh-helper'
+
+interface CreatedTemplateModel {
+  name: string
+  directory: string
+}
+
+interface NextStepsTemplateModel {
+  directory: string
+  packageManager: PackageManagerName
+}
+
+interface SetupFailureTemplateModel extends PackageManagerTemplateModel {
+  directory: string
+  error: string
+}
+
+/** Package-manager execution data consumed by create-sdk templates. */
+export interface PackageManagerTemplateModel {
+  packageManager: PackageManagerName
+  installArgs: string
+  buildArgs: string
+}
+
+/**
+ * Map package-manager execution data into terminal-template fields.
+ * @param manager - selected package-manager strategy.
+ * @returns executable name and operation arguments.
+ */
+export function packageManagerTemplateModel(manager: PackageManager): PackageManagerTemplateModel {
+  return {
+    packageManager: manager.name,
+    installArgs: manager.installCommand().join(' '),
+    buildArgs: manager.buildCommand().join(' '),
+  }
+}
+
+/** Compiled create-sdk terminal templates. */
+export const CREATE_TEMPLATES = {
+  usage: TextTemplate.fromFile<Record<string, never>>(new URL('./assets/usage.txt.tpl', import.meta.url)),
+  created: TextTemplate.fromFile<CreatedTemplateModel>(new URL('./assets/created.txt.tpl', import.meta.url)),
+  nextSteps: TextTemplate.fromFile<NextStepsTemplateModel>(new URL('./assets/next-steps.txt.tpl', import.meta.url)),
+  setupFailure: TextTemplate.fromFile<SetupFailureTemplateModel>(
+    new URL('./assets/setup-failure.txt.tpl', import.meta.url),
+  ),
+  installQuestion: TextTemplate.fromFile<PackageManagerTemplateModel>(
+    new URL('./assets/install-question.txt.tpl', import.meta.url),
+  ),
+} as const
diff --git a/packages/sdk/create-sdk/tests/built-artifacts.e2e.ts b/packages/sdk/create-sdk/tests/built-artifacts.e2e.ts
new file mode 100644
index 0000000000..53a2b858ba
--- /dev/null
+++ b/packages/sdk/create-sdk/tests/built-artifacts.e2e.ts
@@ -0,0 +1,28 @@
+import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+import { describe, expect, it } from 'vitest'
+
+const execFileAsync = promisify(execFile)
+const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
+const createBin = join(repoRoot, 'packages/sdk/create-sdk/lib/bin.js')
+const scriptsBin = join(repoRoot, 'packages/sdk/scripts/lib/bin.js')
+
+describe.skipIf(!existsSync(createBin) || !existsSync(scriptsBin))(
+  'SDK built artifacts',
+  () => {
+    it('runs the published dsh bin help path under plain Node', async () => {
+      const result = await execFileAsync(process.execPath, [scriptsBin, '--help'], { encoding: 'utf8' })
+      expect(result.stdout).toContain('Usage: dsh <command>')
+      expect(result.stderr).toBe('')
+    })
+
+    it('runs the published create-sdk bin help path under plain Node', async () => {
+      const result = await execFileAsync(process.execPath, [createBin, '--help'], { encoding: 'utf8' })
+      expect(result.stdout).toContain('Usage: create-sdk [directory]')
+      expect(result.stderr).toBe('')
+    })
+  },
+)
diff --git a/packages/sdk/create-sdk/tests/create.snapshot.ts b/packages/sdk/create-sdk/tests/create.snapshot.ts
new file mode 100644
index 0000000000..1f7a13dd4e
--- /dev/null
+++ b/packages/sdk/create-sdk/tests/create.snapshot.ts
@@ -0,0 +1,397 @@
+import { describe, expect, it } from 'vitest'
+import {
+  featureId,
+  createPackageManager,
+  type NestedMultiSelectValue,
+  type PromptPort,
+} from '@deepseek-ai/dsh-helper'
+import type {
+  ConfirmPromptRequest,
+  MultiSelectPromptRequest,
+  NestedMultiSelectRequest,
+  PromptOutcome,
+  SecretPromptRequest,
+  SelectPromptRequest,
+  TextPromptRequest,
+} from '../../helper/src/questions/prompt-port.ts'
+import { parseCreateArgs } from '../src/args.ts'
+import { CreateWizard } from '../src/create-wizard.ts'
+import { CREATE_TEMPLATES, packageManagerTemplateModel } from '../src/templates/create-templates.ts'
+
+class RecordingPort implements PromptPort {
+  readonly transcript: unknown[] = []
+  readonly #answers: unknown[]
+
+  constructor(answers: unknown[]) { this.#answers = [...answers] }
+
+  answer<T>(record: unknown): Promise<PromptOutcome<T>> {
+    this.transcript.push(record)
+    return Promise.resolve({ status: 'answered', value: this.#answers.shift() as T })
+  }
+
+  text(request: TextPromptRequest): Promise<PromptOutcome<string>> {
+    return this.answer({
+      kind: 'text',
+      message: request.message,
+      defaultValue: request.defaultValue,
+      initialValue: request.initialValue,
+    })
+  }
+  secret(request: SecretPromptRequest): Promise<PromptOutcome<string>> {
+    return this.answer({ kind: 'secret', message: request.message })
+  }
+  select<T>(request: SelectPromptRequest<T>): Promise<PromptOutcome<T>> {
+    return this.answer({
+      kind: 'select', message: request.message, options: request.options.map(option => option.label),
+      initialValue: request.initialValue,
+    })
+  }
+  multiselect<T>(request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>> {
+    return this.answer({
+      kind: 'multiselect', message: request.message, options: request.options.map(option => option.label),
+      initialValues: request.initialValues,
+    })
+  }
+  confirm(request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>> {
+    return this.answer({ kind: 'confirm', message: request.message, initialValue: request.initialValue })
+  }
+  nestedMultiselect<TValue, TChoice>(
+    request: NestedMultiSelectRequest<TValue, TChoice>,
+  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> {
+    return this.answer({
+      kind: 'nested-multiselect',
+      message: request.message,
+      options: request.options.map(option => ({
+        label: option.label,
+        required: option.required,
+        default: option.default,
+        choices: option.choices?.map(choice => choice.label),
+      })),
+    })
+  }
+}
+
+describe('create-sdk terminal contract', () => {
+  it('renders package-manager-specific setup commands', () => {
+    const model = packageManagerTemplateModel(createPackageManager('yarn', '4.0.0'))
+    expect(CREATE_TEMPLATES.installQuestion.render(model)).toBe('Run yarn install and then build the project?\n')
+    expect(CREATE_TEMPLATES.setupFailure.render({
+      directory: '/workspace/agent',
+      error: 'offline',
+      ...model,
+    })).toContain('yarn install && yarn build')
+  })
+
+  it('pins the full unresolved question order and completion messages', async () => {
+    const port = new RecordingPort([
+      'my-agent',
+      'my-agent',
+      'Snapshot agent',
+      'deepseek',
+      'secret-key',
+      'acp',
+      [
+        { value: featureId('persistence'), choices: ['jsonl'] },
+        { value: featureId('hmr'), choices: [] },
+        { value: featureId('web'), choices: ['exa'] },
+        { value: featureId('workflow'), choices: [] },
+      ],
+      true,
+      'exa-key',
+      'none',
+      'npm',
+      false,
+    ])
+    const resolved = await new CreateWizard({
+      args: parseCreateArgs([]),
+      port,
+      cwd: '/workspace',
+      releaseVersion: '0.0.1',
+      userAgent: '',
+      versionProbe: async () => '10.0.0',
+    }).run()
+    expect({
+      prompts: port.transcript,
+      result: {
+        directory: resolved.directory,
+        name: resolved.request.name,
+        manager: resolved.request.packageManager.name,
+        install: resolved.install,
+        features: resolved.request.features.map(item => ({ id: item.id, options: item.options })),
+      },
+      messages: {
+        created: CREATE_TEMPLATES.created.render({
+          name: resolved.request.name,
+          directory: resolved.directory,
+        }),
+        next: CREATE_TEMPLATES.nextSteps.render({
+          directory: resolved.directory,
+          packageManager: resolved.request.packageManager.name,
+        }),
+        failure: CREATE_TEMPLATES.setupFailure.render({
+          directory: resolved.directory,
+          error: String(new Error('offline')),
+          ...packageManagerTemplateModel(resolved.request.packageManager),
+        }),
+      },
+    }).toMatchInlineSnapshot(`
+      {
+        "messages": {
+          "created": "Created my-agent in /workspace/my-agent
+      ",
+          "failure": "Project files are ready, but setup failed: Error: offline
+      Retry: cd /workspace/my-agent && npm install && npm run build
+      ",
+          "next": "Next: cd /workspace/my-agent && npm start
+      ",
+        },
+        "prompts": [
+          {
+            "defaultValue": "my-agent",
+            "initialValue": undefined,
+            "kind": "text",
+            "message": "Where should the project be created?",
+          },
+          {
+            "defaultValue": "my-agent",
+            "initialValue": undefined,
+            "kind": "text",
+            "message": "Package name",
+          },
+          {
+            "defaultValue": "A DeepSeek Harness agent named my-agent",
+            "initialValue": undefined,
+            "kind": "text",
+            "message": "Project description",
+          },
+          {
+            "initialValue": "deepseek",
+            "kind": "select",
+            "message": "Model provider",
+            "options": [
+              "DeepSeek",
+              "Custom endpoint (pi-ai)",
+            ],
+          },
+          {
+            "kind": "secret",
+            "message": "DeepSeek API key",
+          },
+          {
+            "initialValue": "stdio",
+            "kind": "select",
+            "message": "Run interface",
+            "options": [
+              "ACP server",
+              "Terminal REPL",
+              "Embedded context",
+            ],
+          },
+          {
+            "kind": "nested-multiselect",
+            "message": "Select features",
+            "options": [
+              {
+                "choices": [
+                  "Local executor",
+                  "Sandboxed executor",
+                ],
+                "default": true,
+                "label": "Command execution",
+                "required": true,
+              },
+              {
+                "choices": [
+                  "JSONL files",
+                  "SQLite database",
+                ],
+                "default": true,
+                "label": "Durable session storage",
+                "required": true,
+              },
+              {
+                "choices": undefined,
+                "default": true,
+                "label": "Hot-module reload",
+                "required": false,
+              },
+              {
+                "choices": undefined,
+                "default": true,
+                "label": "Read, write, and edit local files",
+                "required": false,
+              },
+              {
+                "choices": undefined,
+                "default": true,
+                "label": "Model-facing task tracking",
+                "required": false,
+              },
+              {
+                "choices": undefined,
+                "default": true,
+                "label": "Local skill discovery",
+                "required": false,
+              },
+              {
+                "choices": [
+                  "DeepSeek search",
+                  "Exa search",
+                  "Perplexity search",
+                  "Fetch only",
+                ],
+                "default": false,
+                "label": "Web search and fetch tools",
+                "required": false,
+              },
+              {
+                "choices": [
+                  "Fresh child agent",
+                  "Fork parent history",
+                ],
+                "default": false,
+                "label": "Delegate work to child agents",
+                "required": false,
+              },
+              {
+                "choices": undefined,
+                "default": false,
+                "label": "Scripted multi-agent workflows",
+                "required": false,
+              },
+              {
+                "choices": undefined,
+                "default": false,
+                "label": "Automatic context compaction",
+                "required": false,
+              },
+              {
+                "choices": [
+                  "Claude Code hooks",
+                  "Codex hooks",
+                ],
+                "default": false,
+                "label": "Run Claude Code or Codex hooks",
+                "required": false,
+              },
+              {
+                "choices": undefined,
+                "default": false,
+                "label": "Loop-hygiene reminders",
+                "required": false,
+              },
+              {
+                "choices": undefined,
+                "default": false,
+                "label": "Tool timeout policy",
+                "required": false,
+              },
+              {
+                "choices": undefined,
+                "default": false,
+                "label": "Ask the user from the model loop",
+                "required": false,
+              },
+            ],
+          },
+          {
+            "initialValue": true,
+            "kind": "confirm",
+            "message": "Add the recommended tool timeout policy for web search and fetch tools?",
+          },
+          {
+            "kind": "secret",
+            "message": "Exa API key",
+          },
+          {
+            "initialValue": "none",
+            "kind": "select",
+            "message": "Local plugin",
+            "options": [
+              "No local plugin",
+              "Cordis plugin",
+              "Model-facing tool",
+            ],
+          },
+          {
+            "initialValue": "npm",
+            "kind": "select",
+            "message": "Package manager",
+            "options": [
+              "npm",
+              "pnpm",
+              "Yarn",
+            ],
+          },
+          {
+            "initialValue": true,
+            "kind": "confirm",
+            "message": "Run npm install and then build the project?",
+          },
+        ],
+        "result": {
+          "directory": "/workspace/my-agent",
+          "features": [
+            {
+              "id": "provider",
+              "options": [
+                "deepseek",
+              ],
+            },
+            {
+              "id": "spine",
+              "options": [
+                "default",
+              ],
+            },
+            {
+              "id": "app",
+              "options": [
+                "acp",
+              ],
+            },
+            {
+              "id": "bash",
+              "options": [
+                "local",
+              ],
+            },
+            {
+              "id": "persistence",
+              "options": [
+                "jsonl",
+              ],
+            },
+            {
+              "id": "hmr",
+              "options": [
+                "default",
+              ],
+            },
+            {
+              "id": "web",
+              "options": [
+                "exa",
+              ],
+            },
+            {
+              "id": "workflow",
+              "options": [
+                "workerthread",
+              ],
+            },
+            {
+              "id": "timeout-policy",
+              "options": [
+                "default",
+              ],
+            },
+          ],
+          "install": false,
+          "manager": "npm",
+          "name": "my-agent",
+        },
+      }
+    `)
+  })
+})
diff --git a/packages/sdk/create-sdk/tests/create.spec.ts b/packages/sdk/create-sdk/tests/create.spec.ts
new file mode 100644
index 0000000000..c673395649
--- /dev/null
+++ b/packages/sdk/create-sdk/tests/create.spec.ts
@@ -0,0 +1,501 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { PassThrough, Writable } from 'node:stream'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  LocalPluginBlueprint,
+  featureId,
+  NpmPackageManager,
+  type NestedMultiSelectValue,
+  type PromptPort,
+} from '@deepseek-ai/dsh-helper'
+import type {
+  ConfirmPromptRequest,
+  MultiSelectPromptRequest,
+  NestedMultiSelectRequest,
+  PromptOutcome,
+  SecretPromptRequest,
+  SelectPromptRequest,
+  TextPromptRequest,
+} from '../../helper/src/questions/prompt-port.ts'
+import { parseCreateArgs } from '../src/args.ts'
+import {
+  createProject,
+  readCreateSdkVersion,
+  runCreateCommand,
+  type CreateCommandContext,
+} from '../src/command.ts'
+import { CreateWizard } from '../src/create-wizard.ts'
+import { scaffoldProject } from '../src/project-scaffolder.ts'
+
+class ScriptedPort implements PromptPort {
+  readonly requests: string[] = []
+  readonly #answers: unknown[]
+
+  constructor(answers: unknown[]) {
+    this.#answers = [...answers]
+  }
+
+  answer<T>(message: string): Promise<PromptOutcome<T>> {
+    this.requests.push(message)
+    const value = this.#answers.shift()
+    return Promise.resolve(value === ScriptedPort.cancel
+      ? { status: 'cancelled' }
+      : { status: 'answered', value: value as T })
+  }
+
+  async text(request: TextPromptRequest): Promise<PromptOutcome<string>> {
+    const outcome = await this.answer<string>(request.message)
+    if (outcome.status === 'cancelled') return outcome
+    const value = outcome.value || request.defaultValue || ''
+    const diagnostic = request.validate?.(value)
+    if (diagnostic) throw new Error(diagnostic)
+    return { status: 'answered', value }
+  }
+  secret(request: SecretPromptRequest): Promise<PromptOutcome<string>> { return this.answer(request.message) }
+  select<T>(request: SelectPromptRequest<T>): Promise<PromptOutcome<T>> { return this.answer(request.message) }
+  multiselect<T>(request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>> {
+    return this.answer(request.message)
+  }
+  confirm(request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>> { return this.answer(request.message) }
+  nestedMultiselect<TValue, TChoice>(
+    request: NestedMultiSelectRequest<TValue, TChoice>,
+  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> {
+    return this.answer(request.message)
+  }
+
+  static readonly cancel = Symbol('cancel')
+}
+
+const temporary: string[] = []
+const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
+
+interface GeneratedPackageManifest {
+  scripts?: Record<string, string>
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+}
+
+interface GeneratedTsConfig {
+  compilerOptions: {
+    types?: readonly string[]
+  }
+}
+
+function parseGeneratedPackageManifest(text: string): GeneratedPackageManifest {
+  return JSON.parse(text) as GeneratedPackageManifest
+}
+
+function parseGeneratedTsConfig(text: string): GeneratedTsConfig {
+  return JSON.parse(text) as GeneratedTsConfig
+}
+
+function commandContext(
+  cwd: string,
+  port?: PromptPort,
+  setup?: CreateCommandContext['setup'],
+): CreateCommandContext & { readStdout: () => string; readStderr: () => string } {
+  let stdout = ''
+  let stderr = ''
+  const input = Object.assign(new PassThrough(), { isTTY: true }) as unknown as NodeJS.ReadStream
+  const output = Object.assign(new Writable({
+    write(chunk, _encoding, callback) { stdout += String(chunk); callback() },
+  }), { isTTY: true }) as unknown as NodeJS.WriteStream
+  const error = new Writable({
+    write(chunk, _encoding, callback) { stderr += String(chunk); callback() },
+  }) as unknown as NodeJS.WriteStream
+  return {
+    cwd,
+    stdin: input,
+    stdout: output,
+    stderr: error,
+    releaseVersion: '0.0.1',
+    versionProbe: async () => '10.0.0',
+    ...port ? { port } : {},
+    ...setup ? { setup } : {},
+    readStdout: () => stdout,
+    readStderr: () => stderr,
+  }
+}
+
+afterEach(async () => {
+  await Promise.all(temporary.splice(0).map(path => rm(path, { recursive: true, force: true })))
+})
+
+describe('create arguments', () => {
+  it('parses public options and the private repository link mode', () => {
+    expect(parseCreateArgs([
+      'agent', '--description=demo', '--provider', 'deepseek', '--base-url=https://api.example',
+      '--api-key', 'key', '--model=m', '--interface', 'acp', '--pm=pnpm', '--no-install',
+      '--link-workspace',
+    ])).toEqual({
+      directory: 'agent',
+      description: 'demo',
+      provider: 'deepseek',
+      baseURL: 'https://api.example',
+      apiKey: 'key',
+      model: 'm',
+      runInterface: 'acp',
+      packageManager: 'pnpm',
+      install: false,
+      linkWorkspace: true,
+      help: false,
+    })
+    expect(parseCreateArgs(['--link-workspace']).linkWorkspace).toBe(true)
+    expect(() => parseCreateArgs(['--link-packages-workspace'])).toThrow("unknown option '--link-packages-workspace'")
+    expect(parseCreateArgs(['--provider=custom']).provider).toBe('custom')
+    expect(parseCreateArgs(['--help']).help).toBe(true)
+    expect(() => parseCreateArgs(['--interface=bad'])).toThrow('Allowed choices are acp, stdio, embed')
+    expect(() => parseCreateArgs(['--unknown'])).toThrow("unknown option '--unknown'")
+    expect(() => parseCreateArgs(['one', 'two'])).toThrow('too many arguments')
+  })
+
+  it('validates empty directories and package names', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'create-validation-'))
+    temporary.push(root)
+    await expect(new CreateWizard({
+      args: parseCreateArgs(['']), port: new ScriptedPort([]), cwd: root,
+      releaseVersion: '0.0.1', versionProbe: async () => '10.0.0',
+    }).run()).rejects.toThrow('A value is required')
+    await expect(new CreateWizard({
+      args: parseCreateArgs(['agent']), port: new ScriptedPort(['Invalid Name']), cwd: root,
+      releaseVersion: '0.0.1', versionProbe: async () => '10.0.0',
+    }).run()).rejects.toThrow('lowercase npm package name')
+  })
+
+  it('rejects an existing target before asking project questions', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'create-existing-target-'))
+    temporary.push(cwd)
+    await mkdir(join(cwd, 'taken'))
+    const port = new ScriptedPort([])
+    const wizard = new CreateWizard({
+      args: parseCreateArgs(['taken']),
+      port,
+      cwd,
+      releaseVersion: '0.0.1',
+      versionProbe: async () => '10.0.0',
+    })
+    await expect(wizard.run()).rejects.toThrow('directory: Target already exists')
+    expect(port.requests).toEqual([])
+  })
+})
+
+describe('CreateWizard and scaffolder', () => {
+  it('asks only unresolved questions in requirement-safe order', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'create-wizard-'))
+    temporary.push(cwd)
+    const port = new ScriptedPort([
+      'my-agent',
+      [
+        { value: featureId('persistence'), choices: ['sqlite'] },
+        { value: featureId('hmr'), choices: [] },
+        { value: featureId('fs'), choices: [] },
+        { value: featureId('web'), choices: ['exa'] },
+      ],
+      false,
+      'exa-key',
+      'tool',
+    ])
+    const args = parseCreateArgs([
+      'my-agent',
+      '--description=demo',
+      '--provider=deepseek',
+      '--api-key=deepseek-key',
+      '--model=deepseek-v4-flash',
+      '--interface=stdio',
+      '--pm=npm',
+      '--no-install',
+      '--link-workspace',
+    ])
+    const resolved = await new CreateWizard({
+      args,
+      port,
+      cwd,
+      releaseVersion: '0.0.1',
+      versionProbe: async () => '10.0.0',
+    }).run()
+    expect(port.requests).toEqual([
+      'Package name',
+      'Select features',
+      'Add the recommended tool timeout policy for web search and fetch tools?',
+      'Exa API key',
+      'Local plugin',
+    ])
+    expect(resolved.install).toBe(false)
+    expect(resolved.request.packageManager.name).toBe('npm')
+    expect(resolved.request.linkWorkspaceRoot).toBe(repoRoot)
+    expect(resolved.request.localPlugins[0]).toMatchObject({ name: 'tool', kind: 'tool' })
+    expect(resolved.request.features.find(item => item.id === 'web')).toMatchObject({
+      options: ['exa'], secrets: { apiKey: 'exa-key' },
+    })
+    expect(resolved.request.features.find(item => item.id === 'hmr')).toMatchObject({ options: ['default'] })
+  })
+
+  it('writes the project once and refuses every existing target', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'create-scaffold-'))
+    temporary.push(root)
+    const request = {
+      name: 'agent',
+      description: 'demo',
+      runtime: { model: 'deepseek-v4-flash' },
+      packageManager: new NpmPackageManager('10.0.0'),
+      releaseVersion: '0.0.1',
+      features: [
+        { id: featureId('provider'), options: ['deepseek'], secrets: { apiKey: 'key' } },
+        { id: featureId('bash'), options: ['local'] },
+        { id: featureId('app'), options: ['embed'] },
+        { id: featureId('persistence'), options: ['jsonl'] },
+      ],
+      localPlugins: [new LocalPluginBlueprint('plugin', 'plugin')],
+    }
+    const target = join(root, 'project')
+    const result = await scaffoldProject(target, request)
+    expect(result.changes.changedFiles).toContain('README.md')
+    const index = await readFile(join(target, 'index.ts'), 'utf8')
+    expect(index).toContain('SdkBootContext')
+    expect(index).toContain('ctx.agents.create')
+    expect(index).toContain('agentOptions: { model: "deepseek-v4-flash" }')
+    const tsconfig = parseGeneratedTsConfig(await readFile(join(target, 'tsconfig.base.json'), 'utf8'))
+    const manifest = parseGeneratedPackageManifest(await readFile(join(target, 'package.json'), 'utf8'))
+    expect(tsconfig.compilerOptions.types).toEqual(['node'])
+    expect(manifest.scripts).toEqual({
+      dev: 'dsh dev index.ts',
+      build: 'dsh build',
+      typecheck: 'tsc -b',
+      start: 'dsh start index.js',
+      config: 'dsh config',
+    })
+    expect(manifest.dependencies).not.toHaveProperty('node-addon-require-builtin')
+    expect(manifest.devDependencies?.['@types/node']).toBe('^22.20.0')
+    expect(await readFile(join(target, 'plugins/plugin/src/index.ts'), 'utf8')).toContain('export function apply')
+    const cordis = await readFile(join(target, 'cordis.yml'), 'utf8')
+    expect(cordis).toMatch(/^- id:/)
+    expect(cordis).not.toMatch(/^\[/)
+    const occupied = join(root, 'occupied')
+    await mkdir(occupied)
+    await expect(scaffoldProject(occupied, request)).rejects.toThrow('already exists')
+    await writeFile(join(occupied, 'keep'), 'x')
+    await expect(scaffoldProject(occupied, request)).rejects.toThrow('already exists')
+  })
+
+  it('installs workflow requirements before validating the next feature', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'create-workflow-requires-'))
+    temporary.push(cwd)
+    const port = new ScriptedPort([
+      'workflow-agent',
+      [
+        { value: featureId('persistence'), choices: ['jsonl'] },
+        { value: featureId('workflow'), choices: [] },
+      ],
+      'none',
+    ])
+    const resolved = await new CreateWizard({
+      args: parseCreateArgs([
+        'workflow-agent', '--description=test', '--provider=deepseek', '--api-key=key',
+        '--interface=embed', '--pm=npm', '--no-install',
+      ]),
+      port,
+      cwd,
+      releaseVersion: '0.0.1',
+      versionProbe: async () => '10.0.0',
+    }).run()
+    const result = await scaffoldProject(resolved.directory, resolved.request)
+    expect(result.project.cordis.entry('subagent-spawn')).toBeDefined()
+    expect(result.project.cordis.entry('tool-subagent')).toBeDefined()
+  })
+
+  it('confirms an empty provider key and leaves a documented .env placeholder', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'create-empty-key-'))
+    temporary.push(cwd)
+    const port = new ScriptedPort([
+      'empty-key-agent',
+      '',
+      true,
+      [{ value: featureId('persistence'), choices: ['jsonl'] }],
+      'none',
+    ])
+    const resolved = await new CreateWizard({
+      args: parseCreateArgs([
+        'empty-key-agent', '--description=test', '--provider=deepseek',
+        '--interface=embed', '--pm=npm', '--no-install',
+      ]),
+      port,
+      cwd,
+      releaseVersion: '0.0.1',
+      versionProbe: async () => '10.0.0',
+    }).run()
+    await scaffoldProject(resolved.directory, resolved.request)
+    expect(await readFile(join(resolved.directory, '.env'), 'utf8')).toBe(
+      '# Required before start; an empty value makes provider startup fail.\nDEEPSEEK_API_KEY=\n',
+    )
+    expect(port.requests).toContain('Keep the API key empty and fill .env later?')
+  })
+
+  it('collects custom provider inputs, retries an empty key, and accepts a recommendation', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'create-custom-inputs-'))
+    temporary.push(cwd)
+    const port = new ScriptedPort([
+      'custom-agent',
+      'test custom provider',
+      'custom',
+      'https://provider.example/v1',
+      '', false, 'custom-key',
+      'embed',
+      [
+        { value: featureId('persistence'), choices: ['jsonl'] },
+        { value: featureId('web'), choices: ['deepseek'] },
+      ],
+      true,
+      'none',
+      'npm',
+      false,
+    ])
+    const resolved = await new CreateWizard({
+      args: parseCreateArgs(['custom-agent']),
+      port,
+      cwd,
+      releaseVersion: '0.0.1',
+      versionProbe: async () => '10.0.0',
+      userAgent: '',
+    }).run()
+    expect(resolved.request.features.find(item => item.id === 'provider')).toMatchObject({
+      options: ['custom'], values: { baseURL: 'https://provider.example/v1' }, secrets: { apiKey: 'custom-key' },
+    })
+    expect(resolved.request.features.some(item => item.id === 'timeout-policy')).toBe(true)
+  })
+
+  it('does not re-suggest an already selected feature', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'create-selected-suggestion-'))
+    temporary.push(cwd)
+    const port = new ScriptedPort([
+      'agent',
+      [
+        { value: featureId('persistence'), choices: ['jsonl'] },
+        { value: featureId('web'), choices: ['deepseek'] },
+        { value: featureId('timeout-policy'), choices: ['default'] },
+      ],
+      'none',
+    ])
+    const resolved = await new CreateWizard({
+      args: parseCreateArgs([
+        'agent', '--description=test', '--provider=deepseek', '--api-key=key',
+        '--interface=embed', '--pm=npm', '--no-install',
+      ]),
+      port,
+      cwd,
+      releaseVersion: '0.0.1',
+      versionProbe: async () => '10.0.0',
+    }).run()
+    expect(resolved.request.features.filter(item => item.id === 'timeout-policy')).toHaveLength(1)
+  })
+
+  it('uses process defaults when constructor infrastructure is omitted', async () => {
+    const name = `default-infra-${String(process.pid)}`
+    const port = new ScriptedPort([
+      name, [{ value: featureId('persistence'), choices: ['jsonl'] }], 'none',
+    ])
+    const resolved = await new CreateWizard({
+      args: parseCreateArgs([
+        name, '--description=test', '--provider=deepseek', '--api-key=key',
+        '--interface=embed', '--pm=npm', '--no-install',
+      ]),
+      port,
+      releaseVersion: '0.0.1',
+    }).run()
+    expect(resolved.request.packageManager.name).toBe('npm')
+  })
+
+  it('reads the release batch from the initializer package', async () => {
+    await expect(readCreateSdkVersion()).resolves.toBe('0.0.1')
+  })
+})
+
+describe('create command composition', () => {
+  const argv = (directory: string, install: boolean): string[] => [
+    directory, '--description=test', '--provider=deepseek', '--api-key=key',
+    '--interface=embed', '--pm=npm', install ? '--install' : '--no-install',
+  ]
+
+  it('prints help before requiring a TTY and rejects non-interactive creation', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'create-command-help-'))
+    temporary.push(root)
+    const context = commandContext(root)
+    context.stdin.isTTY = false
+    context.stdout.isTTY = false
+    await expect(createProject(['--help'], context)).resolves.toBeUndefined()
+    expect(context.readStdout()).toContain('Usage: create-sdk')
+    expect(context.readStdout()).not.toContain('--link-workspace')
+    await expect(createProject(argv('agent', false), context)).rejects.toThrow('interactive TTY')
+    context.stdin.isTTY = true
+    await expect(createProject(argv('agent', false), context)).rejects.toThrow('interactive TTY')
+  })
+
+  it('creates through an injected prompt port and delegates optional setup', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'create-command-success-'))
+    temporary.push(root)
+    const port = new ScriptedPort([
+      'agent', [{ value: featureId('persistence'), choices: ['jsonl'] }], 'none',
+    ])
+    let setupDirectory = ''
+    const context = commandContext(root, port, async (request) => { setupDirectory = request.directory })
+    const result = await createProject(argv('agent', true), context)
+    expect(result?.project.root).toBe(join(root, 'agent'))
+    expect(setupDirectory).toBe(join(root, 'agent'))
+    expect(context.readStdout()).toContain('Created agent')
+    expect(context.readStdout()).toContain('Next: cd')
+    const noInstall = commandContext(root, new ScriptedPort([
+      'next', [{ value: featureId('persistence'), choices: ['jsonl'] }], 'none',
+    ]))
+    await expect(createProject(argv('next', false), noInstall)).resolves.toBeDefined()
+  })
+
+  it('uses the package manager setup path when no setup override is supplied', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'create-command-default-setup-'))
+    temporary.push(root)
+    const port = new ScriptedPort([
+      'agent', [{ value: featureId('persistence'), choices: ['jsonl'] }], 'none',
+    ])
+    const install = vi.spyOn(NpmPackageManager.prototype, 'install').mockResolvedValue()
+    const build = vi.spyOn(NpmPackageManager.prototype, 'build').mockResolvedValue()
+    const context = commandContext(root, port)
+    delete context.releaseVersion
+    delete context.versionProbe
+    await createProject(argv('agent', true), context)
+    expect(install).toHaveBeenCalledOnce()
+    expect(build).toHaveBeenCalledOnce()
+    install.mockRestore()
+    build.mockRestore()
+  })
+
+  it('reports setup failures after preserving generated files', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'create-command-failure-'))
+    temporary.push(root)
+    const port = new ScriptedPort([
+      'agent', [{ value: featureId('persistence'), choices: ['jsonl'] }], 'none',
+    ])
+    const context = commandContext(root, port, async () => { throw new Error('offline') })
+    await expect(createProject(argv('agent', true), context)).rejects.toThrow('offline')
+    expect(context.readStderr()).toContain('Project files are ready, but setup failed')
+    expect(context.readStderr()).toContain('npm install && npm run build')
+    const stringFailure = commandContext(root, new ScriptedPort([
+      'next', [{ value: featureId('persistence'), choices: ['jsonl'] }], 'none',
+    ]), async () => { throw 'offline-string' })
+    await expect(runCreateCommand(argv('next', true), stringFailure)).resolves.toBe(1)
+    expect(stringFailure.readStderr()).toContain('offline-string')
+  })
+
+  it('maps cancellation and ordinary errors to command exit codes', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'create-command-exit-'))
+    temporary.push(root)
+    const cancelled = commandContext(root, new ScriptedPort([ScriptedPort.cancel]))
+    await expect(runCreateCommand([], cancelled)).resolves.toBe(1)
+    expect(cancelled.readStderr()).toContain('cancelled')
+    const invalid = commandContext(root)
+    await expect(runCreateCommand(['--unknown'], invalid)).resolves.toBe(1)
+    expect(invalid.readStderr()).toContain('unknown option')
+    const help = commandContext(root)
+    await expect(runCreateCommand(['--help'], help)).resolves.toBe(0)
+  })
+})
diff --git a/packages/sdk/create-sdk/tests/link-workspace.e2e.ts b/packages/sdk/create-sdk/tests/link-workspace.e2e.ts
new file mode 100644
index 0000000000..d78993995d
--- /dev/null
+++ b/packages/sdk/create-sdk/tests/link-workspace.e2e.ts
@@ -0,0 +1,112 @@
+import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  LocalPluginBlueprint,
+  featureId,
+  createPackageManager,
+  type PackageManagerName,
+} from '@deepseek-ai/dsh-helper'
+import { scrubEnvironment } from '../../helper/src/package-managers/package-manager.ts'
+import { scaffoldProject } from '../src/project-scaffolder.ts'
+
+const execFileAsync = promisify(execFile)
+const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
+const builtScripts = join(repoRoot, 'packages/sdk/scripts/lib/bin.js')
+const temporary: string[] = []
+
+afterEach(async () => {
+  await Promise.all(temporary.splice(0).map(path => rm(path, { recursive: true, force: true })))
+})
+
+async function managerVersion(name: PackageManagerName): Promise<string | undefined> {
+  try {
+    return (await execFileAsync(name, ['--version'], { encoding: 'utf8' })).stdout.trim()
+  } catch {
+    // An unavailable optional manager skips only its own live-link case.
+    return undefined
+  }
+}
+
+const managers: PackageManagerName[] = ['npm', 'pnpm', 'yarn']
+
+describe.skipIf(!existsSync(builtScripts))('live-linked generated projects', () => {
+  for (const name of managers) {
+    it(`${name}: installs the local closure and resolves plugin TypeScript in dev`, async (context) => {
+      const version = await managerVersion(name)
+      if (!version) {
+        context.skip()
+        return
+      }
+      const parent = await mkdtemp(join(tmpdir(), `dsh-link-${name}-`))
+      const root = join(parent, 'project')
+      temporary.push(parent)
+      const manager = createPackageManager(name, version)
+      await scaffoldProject(root, {
+        name: `linked-${name}`,
+        description: 'link e2e',
+        runtime: { model: 'deepseek-v4-flash' },
+        packageManager: manager,
+        releaseVersion: '0.0.1',
+        linkWorkspaceRoot: repoRoot,
+        features: [
+          { id: featureId('provider'), options: ['deepseek'], secrets: { apiKey: 'test-key' } },
+          { id: featureId('bash'), options: ['local'] },
+          { id: featureId('app'), options: ['embed'] },
+          { id: featureId('persistence'), options: ['jsonl'] },
+        ],
+        localPlugins: [new LocalPluginBlueprint('probe', 'plugin')],
+      })
+      await writeFile(join(root, 'plugins/probe/src/index.ts'), `
+        import { writeFileSync } from 'node:fs'
+        import type { Context } from 'cordis'
+        export const name = 'probe'
+        export function apply(_ctx: Context): void {
+          writeFileSync(new URL('../../../plugin-loaded', import.meta.url), 'loaded\\n')
+        }
+      `)
+      const cacheRoot = join(tmpdir(), 'dsh-sdk-link-cache', name)
+      const commandEnvironment = {
+        ...scrubEnvironment(),
+        COREPACK_HOME: join(cacheRoot, 'corepack'),
+        XDG_CACHE_HOME: join(cacheRoot, 'cache'),
+        XDG_DATA_HOME: join(cacheRoot, 'data'),
+        npm_config_cache: join(cacheRoot, 'npm'),
+        pnpm_config_store_dir: join(cacheRoot, 'pnpm-store'),
+      }
+      await execFileAsync(name, manager.installCommand(), {
+        cwd: root,
+        env: commandEnvironment,
+        encoding: 'utf8',
+        timeout: 120_000,
+      })
+      await execFileAsync(name, manager.buildCommand(), {
+        cwd: root,
+        env: commandEnvironment,
+        encoding: 'utf8',
+        timeout: 120_000,
+      })
+      expect(existsSync(join(root, 'index.js'))).toBe(true)
+      expect(existsSync(join(root, 'plugins/probe/lib/index.js'))).toBe(true)
+      const dsh = join(root, 'node_modules/@deepseek-ai/dsh-scripts/lib/bin.js')
+      const run = await execFileAsync(process.execPath, [dsh, 'dev', 'index.ts'], {
+        cwd: root,
+        env: { ...commandEnvironment, DEEPSEEK_API_KEY: 'test-key' },
+        encoding: 'utf8',
+        timeout: 30_000,
+      })
+      expect(run.stderr).not.toContain('without inject')
+      expect(await readFile(join(root, 'plugin-loaded'), 'utf8')).toBe('loaded\n')
+      const manifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')) as {
+        dependencies: Record<string, string>
+      }
+      expect(manifest.dependencies.cordis).toMatch(name === 'npm' ? /^file:/ : name === 'pnpm' ? /^link:/ : /^portal:/)
+      expect(manifest.dependencies).not.toHaveProperty('node-addon-require-builtin')
+    }, 180_000)
+  }
+})
diff --git a/packages/sdk/create-sdk/tsconfig.json b/packages/sdk/create-sdk/tsconfig.json
new file mode 100644
index 0000000000..f77f711880
--- /dev/null
+++ b/packages/sdk/create-sdk/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../helper" },
+    { "path": "../../../vendor/cordis" }
+  ]
+}
diff --git a/packages/sdk/create-sdk/tsdown.config.ts b/packages/sdk/create-sdk/tsdown.config.ts
new file mode 100644
index 0000000000..cdf9ef6d4f
--- /dev/null
+++ b/packages/sdk/create-sdk/tsdown.config.ts
@@ -0,0 +1,14 @@
+import { defineConfig } from 'tsdown'
+
+/** Bundle the library and create bin, then mirror package-owned terminal templates. */
+export default defineConfig({
+  entry: ['lib/types/index.js', 'lib/types/bin.js'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+  copy: [{ from: 'src/templates/assets/*', to: 'lib/assets' }],
+})
diff --git a/packages/sdk/helper/README.md b/packages/sdk/helper/README.md
new file mode 100644
index 0000000000..3e1148e567
--- /dev/null
+++ b/packages/sdk/helper/README.md
@@ -0,0 +1,23 @@
+# `@deepseek-ai/dsh-helper`
+
+Shared project domain and infrastructure for `create-sdk` and `dsh config`. `SdkProject` is a read-only snapshot; `ProjectEditSession` is the only mutation and commit boundary. The [SDK architecture RFC](../../../docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md) owns the rationale.
+
+The package owns the builtin typed-spec catalog, provider/app behavior entities, structured project file objects, helper-owned project templates, the shared typed `TextTemplate` renderer, package-manager strategies, local-plugin blueprints, typed questions, and the clack prompt adapter. It never boots a Cordis application.
+
+All business and document validation completes before commit writes any affected file. Commit detects external edits made after the session opened, but deliberately provides no cross-file rollback after writing starts.
+
+Builtin features are provider, bash, app, persistence, HMR, filesystem, todo, skill, web, subagent, workflow, compaction, hooks, repeat-tool guard, timeout policy, and ask-user. The catalog owns feature options, required and non-default Cordis plugin config, feature requirements, resource contribution, and round-trip markers; create and config use the same registry and configurator.
+
+`SdkProject.open()` requires only readable root `package.json` and `cordis.yml`. A Cordis config entry anchors feature installation; a package present only through a linked NPM dependency closure leaves the feature absent. Once an owned Cordis config entry exists, an incomplete resource shape is `inconsistent` and cannot be modified automatically.
+
+`.env.example` follows the currently selected features. `.env` is append-only: helper may add a missing differently named variable, but never updates or removes existing content.
+
+The package root explicitly exports only the objects consumed by `create-sdk` and `dsh-scripts`; internal modules have no `src/*` or package-manifest subpath export.
+
+## Model Experience
+
+None, as the project domain edits files and never mounts a live agent or model request.
+
+## Known Limitations and Deferred Work
+
+- **Commit is not transactional across files** — external edits are detected before each write, but a later failure does not roll back files already written.
diff --git a/packages/sdk/helper/package.json b/packages/sdk/helper/package.json
new file mode 100644
index 0000000000..1452a1dbee
--- /dev/null
+++ b/packages/sdk/helper/package.json
@@ -0,0 +1,45 @@
+{
+  "name": "@deepseek-ai/dsh-helper",
+  "description": "Domain model and infrastructure for creating and editing DeepSeek Harness SDK projects",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/assets",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@clack/core": "^1.4.3",
+    "@clack/prompts": "^1.7.0",
+    "handlebars": "^4.7.9",
+    "jsonc-parser": "^3.3.1",
+    "yaml": "^2.9.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-compact-basic": "workspace:^",
+    "@deepseek-ai/dsh-hooks-claude": "workspace:^",
+    "@deepseek-ai/dsh-hooks-codex": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-sqlite": "workspace:^",
+    "@deepseek-ai/dsh-tool-subagent": "workspace:^",
+    "@deepseek-ai/dsh-tool-web": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/sdk/helper/src/documents/cordis-yaml-file.ts b/packages/sdk/helper/src/documents/cordis-yaml-file.ts
new file mode 100644
index 0000000000..2f00db5f80
--- /dev/null
+++ b/packages/sdk/helper/src/documents/cordis-yaml-file.ts
@@ -0,0 +1,188 @@
+/**
+ * Comment-preserving Cordis YAML document and `!!js` expression value.
+ *
+ * @module @deepseek-ai/dsh-helper/documents/cordis-yaml-file
+ */
+
+import {
+  Document, isMap, isSeq, parseDocument, visit, YAMLMap, YAMLSeq,
+  type ScalarTag,
+} from 'yaml'
+import { ProjectFile, withTrailingNewline } from './project-file.ts'
+
+/** Explicit JavaScript expression serialized with Cordis' `!!js` YAML tag. */
+export class JsExpression {
+  /** Expression source evaluated by the Cordis include loader. */
+  readonly source: string
+
+  /** Create an expression value. */
+  constructor(source: string) {
+    if (source.trim().length === 0) throw new Error('JavaScript expression must not be empty')
+    this.source = source
+  }
+
+  /** Return expression source for YAML scalar stringification. */
+  toString(): string {
+    return this.source
+  }
+}
+
+const JS_EXPRESSION_TAG: ScalarTag = {
+  tag: 'tag:yaml.org,2002:js',
+  identify: value => value instanceof JsExpression,
+  resolve: value => new JsExpression(value),
+  stringify: item => String(item.value),
+}
+
+/** Plain domain representation of one top-level Cordis config entry. */
+export interface CordisConfigEntry {
+  id: string
+  name: string
+  config?: Record<string, unknown>
+  disabled?: boolean
+}
+
+function parseYaml(text: string): Document.Parsed {
+  const document = parseDocument(text, {
+    customTags: [JS_EXPRESSION_TAG],
+    keepSourceTokens: true,
+    prettyErrors: true,
+  })
+  if (document.errors.length > 0) {
+    throw new Error(`invalid cordis.yml: ${document.errors.map(error => error.message).join('; ')}`)
+  }
+  if (!isSeq(document.contents)) throw new Error('invalid cordis.yml: root must be a sequence')
+  visit(document, { Collection: (_key, collection) => { collection.flow = false } })
+  return document
+}
+
+function entryFromValue(value: unknown): CordisConfigEntry {
+  /* v8 ignore next -- entries() calls this only after requiring a YAMLMap, whose JSON value is an object */
+  if (value === null || Array.isArray(value) || typeof value !== 'object') {
+    throw new Error('invalid cordis.yml entry: expected an object')
+  }
+  const entry = value as Record<string, unknown>
+  if (typeof entry.id !== 'string' || entry.id.length === 0) {
+    throw new Error('invalid cordis.yml entry: id must be a non-empty string')
+  }
+  if (typeof entry.name !== 'string' || entry.name.length === 0) {
+    throw new Error(`invalid cordis.yml entry ${entry.id}: name must be a non-empty string`)
+  }
+  if (entry.config !== undefined
+    && (entry.config === null || Array.isArray(entry.config) || typeof entry.config !== 'object')) {
+    throw new Error(`invalid cordis.yml entry ${entry.id}: plugin config must be an object`)
+  }
+  if (entry.disabled !== undefined && typeof entry.disabled !== 'boolean') {
+    throw new Error(`invalid cordis.yml entry ${entry.id}: disabled must be boolean`)
+  }
+  return {
+    id: entry.id,
+    name: entry.name,
+    ...entry.config !== undefined ? { config: entry.config as Record<string, unknown> } : {},
+    ...entry.disabled !== undefined ? { disabled: entry.disabled } : {},
+  }
+}
+
+/** Editable top-level cordis.yml using YAML's document API. */
+export class CordisYamlFile extends ProjectFile {
+  private readonly document: Document.Parsed
+
+  private constructor(document: Document.Parsed, originalText?: string) {
+    super('cordis.yml', originalText)
+    this.document = document
+  }
+
+  /** Create an empty Cordis config entry list. */
+  static create(): CordisYamlFile {
+    return new CordisYamlFile(parseYaml('[]\n'))
+  }
+
+  /** Parse an existing cordis.yml while retaining comments and scalar styles. */
+  static parse(text: string): CordisYamlFile {
+    return new CordisYamlFile(parseYaml(text), text)
+  }
+
+  /** Clone through YAML text so the edit session owns an independent AST. */
+  override clone(): CordisYamlFile {
+    return new CordisYamlFile(parseYaml(this.serialize()), this.originalText)
+  }
+
+  private sequence(): YAMLSeq {
+    /* v8 ignore next -- parseYaml and create both establish a sequence root */
+    if (!isSeq(this.document.contents)) throw new Error('cordis.yml root is not a sequence')
+    return this.document.contents
+  }
+
+  private entryNode(id: string): YAMLMap | undefined {
+    for (const item of this.sequence().items) {
+      if (!isMap(item)) continue
+      if (item.get('id') === id) return item
+    }
+    return undefined
+  }
+
+  /** Return defensive plain entry values in file order. */
+  entries(): CordisConfigEntry[] {
+    return this.sequence().items.map((item) => {
+      if (!isMap(item)) throw new Error('invalid cordis.yml: every entry must be a mapping')
+      return entryFromValue(item.toJSON())
+    })
+  }
+
+  /** Find one entry by stable id. */
+  entry(id: string): CordisConfigEntry | undefined {
+    return this.entries().find(entry => entry.id === id)
+  }
+
+  /** Add one new top-level entry, rejecting duplicate ids. */
+  addEntry(entry: CordisConfigEntry): void {
+    if (this.entryNode(entry.id)) throw new Error(`Cordis config entry already exists: ${entry.id}`)
+    this.sequence().items.push(this.document.createNode(entry))
+  }
+
+  /** Remove an entry by id and report whether it existed. */
+  removeEntry(id: string): boolean {
+    const sequence = this.sequence()
+    const index = sequence.items.findIndex(item => isMap(item) && item.get('id') === id)
+    if (index < 0) return false
+    sequence.items.splice(index, 1)
+    return true
+  }
+
+  /** Enable or disable an entry through the Loader-native field. */
+  setDisabled(id: string, disabled: boolean): void {
+    const node = this.entryNode(id)
+    if (!node) throw new Error(`Cordis config entry does not exist: ${id}`)
+    if (disabled) node.set('disabled', true)
+    else node.delete('disabled')
+  }
+
+  /** Replace only owned plugin config keys while retaining unknown user keys. */
+  updateOwnedConfig(id: string, ownedKeys: readonly string[], next: Record<string, unknown>): void {
+    const entry = this.entryNode(id)
+    if (!entry) throw new Error(`Cordis config entry does not exist: ${id}`)
+    let config: unknown = entry.get('config', true)
+    if (config === undefined || config === null) {
+      config = new YAMLMap()
+      entry.set('config', config)
+    }
+    if (!isMap(config)) throw new Error(`Cordis config entry ${id} plugin config is not a mapping`)
+    for (const key of ownedKeys) config.delete(key)
+    for (const [key, value] of Object.entries(next)) config.set(key, this.document.createNode(value))
+    if (config.items.length === 0) entry.delete('config')
+  }
+
+  /** Validate ids, names, plugin config maps, and id uniqueness. */
+  override validate(): void {
+    const seen = new Set<string>()
+    for (const entry of this.entries()) {
+      if (seen.has(entry.id)) throw new Error(`duplicate Cordis config entry id: ${entry.id}`)
+      seen.add(entry.id)
+    }
+  }
+
+  /** Serialize through the YAML document while retaining untouched trivia. */
+  override serialize(): string {
+    return withTrailingNewline(this.document.toString({ lineWidth: 0 }))
+  }
+}
diff --git a/packages/sdk/helper/src/documents/env-file.ts b/packages/sdk/helper/src/documents/env-file.ts
new file mode 100644
index 0000000000..5e076d0e34
--- /dev/null
+++ b/packages/sdk/helper/src/documents/env-file.ts
@@ -0,0 +1,111 @@
+/**
+ * Ownership-aware, line-preserving dotenv document.
+ *
+ * @module @deepseek-ai/dsh-helper/documents/env-file
+ */
+
+import { ProjectFile, withTrailingNewline } from './project-file.ts'
+
+interface ParsedVariable {
+  index: number
+  value: string
+}
+
+const VARIABLE = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/
+const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/** `.env` appends missing variables; `.env.example` supports managed replacement and removal. */
+export class EnvFile extends ProjectFile {
+  private readonly lines: string[]
+
+  private constructor(relativePath: '.env' | '.env.example', lines: string[], originalText?: string) {
+    super(relativePath, originalText)
+    this.lines = [...lines]
+  }
+
+  /** Create an empty environment file. */
+  static create(relativePath: '.env' | '.env.example'): EnvFile {
+    return new EnvFile(relativePath, [])
+  }
+
+  /** Parse an existing environment file without rewriting unknown lines. */
+  static parse(relativePath: '.env' | '.env.example', text: string): EnvFile {
+    const normalized = text.replace(/\n$/, '')
+    return new EnvFile(relativePath, normalized.length === 0 ? [] : normalized.split('\n'), text)
+  }
+
+  /** Clone the current line model. */
+  override clone(): EnvFile {
+    return new EnvFile(this.relativePath as '.env' | '.env.example', this.lines, this.originalText)
+  }
+
+  private variables(): Map<string, ParsedVariable[]> {
+    const values = new Map<string, ParsedVariable[]>()
+    this.lines.forEach((line, index) => {
+      const match = VARIABLE.exec(line)
+      if (!match) return
+      const name = match[1]
+      const value = match[2]
+      /* v8 ignore next -- both captures are mandatory in VARIABLE */
+      if (name === undefined || value === undefined) return
+      const occurrences = values.get(name) ?? []
+      occurrences.push({ index, value })
+      values.set(name, occurrences)
+    })
+    return values
+  }
+
+  /** Read the effective value; append-only `.env` accepts duplicates and uses the last declaration. */
+  get(name: string): string | undefined {
+    const occurrences = this.variables().get(name) ?? []
+    if (this.relativePath === '.env.example' && occurrences.length > 1) {
+      throw new Error(`${this.relativePath} contains duplicate variable ${name}`)
+    }
+    return occurrences.at(-1)?.value
+  }
+
+  /** Add or replace one SDK-managed `.env.example` variable while preserving unrelated lines. */
+  set(name: string, value: string): void {
+    if (this.relativePath !== '.env.example') throw new Error('.env is append-only')
+    if (!VARIABLE_NAME.test(name)) throw new Error(`invalid environment variable name: ${name}`)
+    const occurrences = this.variables().get(name) ?? []
+    if (occurrences.length > 1) throw new Error(`${this.relativePath} contains duplicate variable ${name}`)
+    const line = `${name}=${value}`
+    if (occurrences[0]) this.lines[occurrences[0].index] = line
+    else this.lines.push(line)
+  }
+
+  /** Append a missing `.env` variable and optional comment without changing any existing declaration. */
+  append(name: string, value: string, comment?: string): boolean {
+    if (this.relativePath !== '.env') throw new Error('.env.example is SDK-managed')
+    if (!VARIABLE_NAME.test(name)) throw new Error(`invalid environment variable name: ${name}`)
+    if (comment !== undefined && (!comment || comment.includes('\n'))) {
+      throw new Error('environment comment must be one non-empty line')
+    }
+    if (this.variables().has(name)) return false
+    if (comment) this.lines.push(`# ${comment}`)
+    this.lines.push(`${name}=${value}`)
+    return true
+  }
+
+  /** Remove one SDK-managed `.env.example` variable while retaining every other line. */
+  remove(name: string): void {
+    if (this.relativePath !== '.env.example') throw new Error('.env is append-only')
+    const occurrences = this.variables().get(name) ?? []
+    if (occurrences.length > 1) throw new Error(`${this.relativePath} contains duplicate variable ${name}`)
+    if (occurrences[0]) this.lines.splice(occurrences[0].index, 1)
+  }
+
+  /** Validate the managed placeholder file; append-only `.env` accepts duplicate declarations. */
+  override validate(): void {
+    if (this.relativePath === '.env') return
+    for (const [name, occurrences] of this.variables()) {
+      if (occurrences.length > 1) throw new Error(`${this.relativePath} contains duplicate variable ${name}`)
+    }
+  }
+
+  /** Serialize all retained lines with one trailing newline. */
+  override serialize(): string {
+    return withTrailingNewline(this.lines.join('\n'))
+  }
+}
diff --git a/packages/sdk/helper/src/documents/package-json-file.ts b/packages/sdk/helper/src/documents/package-json-file.ts
new file mode 100644
index 0000000000..d979906b96
--- /dev/null
+++ b/packages/sdk/helper/src/documents/package-json-file.ts
@@ -0,0 +1,159 @@
+/**
+ * Structured package.json document owned by an SDK project.
+ *
+ * @module @deepseek-ai/dsh-helper/documents/package-json-file
+ */
+
+import { ProjectFile, withTrailingNewline } from './project-file.ts'
+
+/** NPM dependency sections managed by the SDK. */
+export type NpmDependencySection = 'dependencies' | 'devDependencies'
+
+/** JSON shape retained by {@link PackageJsonFile}. */
+export interface PackageManifest {
+  name?: string
+  version?: string
+  private?: boolean
+  description?: string
+  type?: string
+  packageManager?: string
+  scripts?: Record<string, string>
+  dependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+  workspaces?: string[]
+  resolutions?: Record<string, string>
+  [key: string]: unknown
+}
+
+function parseManifest(text: string): PackageManifest {
+  let value: unknown
+  try {
+    value = JSON.parse(text)
+  } catch (error) {
+    throw new Error(`invalid package.json: ${String(error)}`)
+  }
+  if (value === null || Array.isArray(value) || typeof value !== 'object') {
+    throw new Error('invalid package.json: root must be an object')
+  }
+  return value as PackageManifest
+}
+
+function sortedRecord(value: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)))
+}
+
+/** Editable, deterministic package.json representation. */
+export class PackageJsonFile extends ProjectFile {
+  private readonly manifest: PackageManifest
+
+  private constructor(manifest: PackageManifest, originalText?: string) {
+    super('package.json', originalText)
+    this.manifest = structuredClone(manifest)
+  }
+
+  /** Create a new package manifest from a complete rendered template. */
+  static create(text: string): PackageJsonFile {
+    return new PackageJsonFile(parseManifest(text))
+  }
+
+  /** Parse an existing package.json document. */
+  static parse(text: string): PackageJsonFile {
+    return new PackageJsonFile(parseManifest(text), text)
+  }
+
+  /** Clone this document and its nested manifest data. */
+  override clone(): PackageJsonFile {
+    return new PackageJsonFile(this.manifest, this.originalText)
+  }
+
+  /** Return a defensive copy of the manifest. */
+  value(): Readonly<PackageManifest> {
+    return structuredClone(this.manifest)
+  }
+
+  /** Set one package script. */
+  setScript(name: string, command: string): void {
+    this.manifest.scripts ??= {}
+    this.manifest.scripts[name] = command
+  }
+
+  /** Set one NPM dependency in its runtime or development section. */
+  setNpmDependency(section: NpmDependencySection, name: string, spec: string): void {
+    this.manifest[section] ??= {}
+    this.manifest[section][name] = spec
+  }
+
+  /** Remove one NPM dependency from a section. */
+  removeNpmDependency(section: NpmDependencySection, name: string): void {
+    delete this.manifest[section]?.[name]
+  }
+
+  /** Read an NPM dependency spec from either managed section. */
+  npmDependency(name: string): { section: NpmDependencySection; spec: string } | undefined {
+    for (const section of ['dependencies', 'devDependencies'] as const) {
+      const spec = this.manifest[section]?.[name]
+      if (spec !== undefined) return { section, spec }
+    }
+    return undefined
+  }
+
+  /** Return all managed NPM dependency names. */
+  npmDependencyNames(): string[] {
+    return [...new Set([
+      ...Object.keys(this.manifest.dependencies ?? {}),
+      ...Object.keys(this.manifest.devDependencies ?? {}),
+    ])].sort()
+  }
+
+  /** Add a package-manager workspace glob. */
+  addWorkspace(pattern: string): void {
+    const workspaces = this.manifest.workspaces ??= []
+    if (!workspaces.includes(pattern)) workspaces.push(pattern)
+  }
+
+  /** Set or remove the packageManager field. */
+  setPackageManager(value: string | undefined): void {
+    if (value === undefined) delete this.manifest.packageManager
+    else this.manifest.packageManager = value
+  }
+
+  /** Pin a Yarn resolution used by live-link projects. */
+  setResolution(name: string, spec: string): void {
+    this.manifest.resolutions ??= {}
+    this.manifest.resolutions[name] = spec
+  }
+
+  /** Validate the fields the SDK relies on. */
+  override validate(): void {
+    if (!this.manifest.name || typeof this.manifest.name !== 'string') {
+      throw new Error('package.json name must be a non-empty string')
+    }
+    for (const section of ['scripts', 'dependencies', 'devDependencies'] as const) {
+      const value: unknown = this.manifest[section]
+      if (value === undefined) continue
+      if (value === null || Array.isArray(value) || typeof value !== 'object') {
+        throw new Error(`package.json ${section} must be an object`)
+      }
+      for (const [key, item] of Object.entries(value)) {
+        if (typeof item !== 'string' || item.length === 0) {
+          throw new Error(`package.json ${section}.${key} must be a non-empty string`)
+        }
+      }
+    }
+    if (this.manifest.workspaces !== undefined
+      && (!Array.isArray(this.manifest.workspaces) || this.manifest.workspaces.some(item => typeof item !== 'string'))) {
+      throw new Error('package.json workspaces must be an array of strings')
+    }
+  }
+
+  /** Serialize with deterministic managed maps and two-space JSON formatting. */
+  override serialize(): string {
+    const value: PackageManifest = structuredClone(this.manifest)
+    if (this.manifest.scripts) value.scripts = sortedRecord(this.manifest.scripts)
+    if (this.manifest.dependencies) value.dependencies = sortedRecord(this.manifest.dependencies)
+    if (this.manifest.devDependencies) value.devDependencies = sortedRecord(this.manifest.devDependencies)
+    if (this.manifest.workspaces) value.workspaces = [...this.manifest.workspaces].sort()
+    if (this.manifest.resolutions) value.resolutions = sortedRecord(this.manifest.resolutions)
+    return withTrailingNewline(JSON.stringify(value, null, 2))
+  }
+}
diff --git a/packages/sdk/helper/src/documents/pnpm-workspace-file.ts b/packages/sdk/helper/src/documents/pnpm-workspace-file.ts
new file mode 100644
index 0000000000..6e2cb25243
--- /dev/null
+++ b/packages/sdk/helper/src/documents/pnpm-workspace-file.ts
@@ -0,0 +1,76 @@
+/**
+ * Structured pnpm workspace configuration for generated SDK projects.
+ *
+ * @module @deepseek-ai/dsh-helper/documents/pnpm-workspace-file
+ */
+
+import { parse, stringify } from 'yaml'
+import { ProjectFile, withTrailingNewline } from './project-file.ts'
+
+/** Generated pnpm-workspace.yaml model. */
+export class PnpmWorkspaceFile extends ProjectFile {
+  private readonly packages = new Set<string>()
+  private autoInstallPeers = true
+
+  private constructor(originalText?: string) {
+    super('pnpm-workspace.yaml', originalText)
+  }
+
+  /** Create a pnpm workspace document. */
+  static create(): PnpmWorkspaceFile {
+    return new PnpmWorkspaceFile()
+  }
+
+  /** Parse the workspace fields the SDK owns. */
+  static parse(text: string): PnpmWorkspaceFile {
+    const value: unknown = parse(text)
+    if (value === null || Array.isArray(value) || typeof value !== 'object') {
+      throw new Error('pnpm-workspace.yaml root must be an object')
+    }
+    const input = value as Record<string, unknown>
+    if (!Array.isArray(input.packages) || input.packages.some(item => typeof item !== 'string')) {
+      throw new Error('pnpm-workspace.yaml packages must be an array of strings')
+    }
+    const document = new PnpmWorkspaceFile(text)
+    for (const pattern of input.packages) document.packages.add(pattern as string)
+    if (input.autoInstallPeers !== undefined && typeof input.autoInstallPeers !== 'boolean') {
+      throw new Error('pnpm-workspace.yaml autoInstallPeers must be boolean')
+    }
+    document.autoInstallPeers = input.autoInstallPeers !== false
+    return document
+  }
+
+  /** Clone workspace globs and peer-install policy. */
+  override clone(): PnpmWorkspaceFile {
+    const clone = new PnpmWorkspaceFile(this.originalText)
+    for (const pattern of this.packages) clone.packages.add(pattern)
+    clone.autoInstallPeers = this.autoInstallPeers
+    return clone
+  }
+
+  /** Add one package workspace glob. */
+  addPackage(pattern: string): void {
+    this.packages.add(pattern)
+  }
+
+  /** Disable registry peer auto-installation for live-link projects. */
+  disableAutoInstallPeers(): void {
+    this.autoInstallPeers = false
+  }
+
+  /** Validate workspace globs. */
+  override validate(): void {
+    for (const pattern of this.packages) {
+      if (pattern.trim().length === 0) throw new Error('pnpm workspace pattern must not be empty')
+    }
+  }
+
+  /** Serialize pnpm's workspace and peer policy. */
+  override serialize(): string {
+    return withTrailingNewline(stringify({
+      packages: [...this.packages].sort(),
+      ...this.autoInstallPeers ? {} : { autoInstallPeers: false },
+      allowBuilds: { esbuild: true },
+    }, { lineWidth: 0 }))
+  }
+}
diff --git a/packages/sdk/helper/src/documents/project-file.ts b/packages/sdk/helper/src/documents/project-file.ts
new file mode 100644
index 0000000000..c5ec38cc07
--- /dev/null
+++ b/packages/sdk/helper/src/documents/project-file.ts
@@ -0,0 +1,60 @@
+/**
+ * Base abstraction for one file in an SDK project snapshot.
+ *
+ * @module @deepseek-ai/dsh-helper/documents/project-file
+ */
+
+/** Return text with exactly one trailing newline. */
+export function withTrailingNewline(text: string): string {
+  return text.replace(/\n*$/, '') + '\n'
+}
+
+/** One cloneable, validatable project file. */
+export abstract class ProjectFile {
+  /** Project-relative POSIX path. */
+  readonly relativePath: string
+
+  /** Text observed when the document entered the snapshot; absent for a new file. */
+  readonly originalText: string | undefined
+
+  protected constructor(relativePath: string, originalText?: string) {
+    if (relativePath.startsWith('/') || relativePath.split('/').includes('..')) {
+      throw new Error(`project document path must stay inside the project: ${relativePath}`)
+    }
+    this.relativePath = relativePath
+    this.originalText = originalText
+  }
+
+  /** Clone the document for an isolated edit session. */
+  abstract clone(): ProjectFile
+
+  /** Validate the document's complete current state. */
+  abstract validate(): void
+
+  /** Serialize the complete current file. */
+  abstract serialize(): string
+}
+
+/** Immutable complete-text file used by one-shot artifacts. */
+export class TextProjectFile extends ProjectFile {
+  private readonly text: string
+
+  /** Create a complete-text project document. */
+  constructor(relativePath: string, text: string, originalText?: string) {
+    super(relativePath, originalText)
+    this.text = withTrailingNewline(text)
+  }
+
+  /** Clone this immutable document. */
+  override clone(): TextProjectFile {
+    return new TextProjectFile(this.relativePath, this.text, this.originalText)
+  }
+
+  /** Complete text artifacts have no extra structural validation. */
+  override validate(): void {}
+
+  /** Return the complete artifact text. */
+  override serialize(): string {
+    return this.text
+  }
+}
diff --git a/packages/sdk/helper/src/documents/tsconfig-file.ts b/packages/sdk/helper/src/documents/tsconfig-file.ts
new file mode 100644
index 0000000000..368b93eb43
--- /dev/null
+++ b/packages/sdk/helper/src/documents/tsconfig-file.ts
@@ -0,0 +1,89 @@
+/**
+ * Comment-preserving root tsconfig editor for local plugin references.
+ *
+ * @module @deepseek-ai/dsh-helper/documents/tsconfig-file
+ */
+
+import { applyEdits, modify, parse, type ParseError } from 'jsonc-parser'
+import { ProjectFile, withTrailingNewline } from './project-file.ts'
+
+const FORMAT = { insertSpaces: true, tabSize: 2, eol: '\n' }
+
+function parseConfig(text: string): Record<string, unknown> {
+  const errors: ParseError[] = []
+  const value: unknown = parse(text, errors, { allowTrailingComma: true, disallowComments: false })
+  if (errors.length > 0 || value === null || Array.isArray(value) || typeof value !== 'object') {
+    throw new Error('tsconfig.json is not a valid JSONC object')
+  }
+  return value as Record<string, unknown>
+}
+
+/** Root tsconfig document edited with jsonc-parser patches. */
+export class TsConfigFile extends ProjectFile {
+  private text: string
+
+  private constructor(text: string, originalText?: string) {
+    super('tsconfig.json', originalText)
+    this.text = withTrailingNewline(text)
+  }
+
+  /** Create the root project-reference config. */
+  static create(): TsConfigFile {
+    return new TsConfigFile(JSON.stringify({
+      extends: './tsconfig.base.json',
+      compilerOptions: { noEmit: true },
+      include: ['index.ts'],
+      references: [],
+    }, null, 2))
+  }
+
+  /** Parse an existing root tsconfig. */
+  static parse(text: string): TsConfigFile {
+    parseConfig(text)
+    return new TsConfigFile(text, text)
+  }
+
+  /** Clone the current JSONC text. */
+  override clone(): TsConfigFile {
+    return new TsConfigFile(this.text, this.originalText)
+  }
+
+  /** Add one project reference while retaining comments and formatting. */
+  addReference(path: string): void {
+    const value = parseConfig(this.text)
+    const references = value.references
+    if (references !== undefined && !Array.isArray(references)) {
+      throw new Error('tsconfig.json references must be an array')
+    }
+    const typed = (references ?? []) as unknown[]
+    for (const item of typed) {
+      if (item === null || Array.isArray(item) || typeof item !== 'object' || typeof (item as { path?: unknown }).path !== 'string') {
+        throw new Error('tsconfig.json references must contain { path: string } objects')
+      }
+    }
+    if (typed.some(item => (item as { path: string }).path === path)) return
+    this.text = applyEdits(this.text, modify(
+      this.text,
+      ['references', typed.length],
+      { path },
+      { formattingOptions: FORMAT, isArrayInsertion: true },
+    ))
+  }
+
+  /** Validate JSONC and the project-reference shape. */
+  override validate(): void {
+    const value = parseConfig(this.text)
+    if (value.references === undefined) return
+    if (!Array.isArray(value.references)) throw new Error('tsconfig.json references must be an array')
+    for (const item of value.references) {
+      if (item === null || Array.isArray(item) || typeof item !== 'object' || typeof (item as { path?: unknown }).path !== 'string') {
+        throw new Error('tsconfig.json references must contain { path: string } objects')
+      }
+    }
+  }
+
+  /** Return patched JSONC text. */
+  override serialize(): string {
+    return withTrailingNewline(this.text)
+  }
+}
diff --git a/packages/sdk/helper/src/features/builtin/app.ts b/packages/sdk/helper/src/features/builtin/app.ts
new file mode 100644
index 0000000000..8e20e82e44
--- /dev/null
+++ b/packages/sdk/helper/src/features/builtin/app.ts
@@ -0,0 +1,98 @@
+/**
+ * Required run-interface app feature.
+ *
+ * @module @deepseek-ai/dsh-helper/features/builtin/app
+ */
+
+import { featureId } from '../../ids.ts'
+import type { ProjectProfile } from '../../project/types.ts'
+import {
+  FeatureOption,
+  ExclusiveOptionFeature,
+} from '../feature.ts'
+import { ProjectContribution } from '../resources.ts'
+import { npmCordisConfigEntry, optionalString, requiredString } from './helpers.ts'
+
+const ID = featureId('app')
+
+class AppOption extends FeatureOption {
+  override readonly id: 'acp' | 'stdio' | 'embed'
+  override readonly label: string
+
+  constructor(id: 'acp' | 'stdio' | 'embed', label: string) {
+    super()
+    this.id = id
+    this.label = label
+  }
+
+  /** Identify options by their unique front door, not the shared interaction service. */
+  override markerConfigEntries(): readonly { id: string; name: string }[] {
+    switch (this.id) {
+      case 'acp': return [{ id: 'acp', name: '@deepseek-ai/dsh-acp' }]
+      case 'stdio': return [{ id: 'stdio', name: '@deepseek-ai/dsh-stdio' }]
+      case 'embed': return []
+    }
+  }
+
+  /** Embed is identified by the configured loop with no external front door. */
+  override matchesConfigEntries(entries: readonly { id: string; name: string }[], profile: ProjectProfile): boolean {
+    if (this.id !== 'embed') return super.matchesConfigEntries(entries, profile)
+    return entries.some(entry => entry.id === 'agent-loop' && entry.name === '@deepseek-ai/dsh-agent-loop')
+      && !entries.some(entry => entry.name === '@deepseek-ai/dsh-acp' || entry.name === '@deepseek-ai/dsh-stdio')
+  }
+
+  override contribution(profile: ProjectProfile): ProjectContribution {
+    switch (this.id) {
+      case 'acp':
+        return new ProjectContribution([
+          ...npmCordisConfigEntry(ID, {
+            id: 'user-interaction',
+            name: '@deepseek-ai/dsh-user-interaction',
+          }),
+          ...npmCordisConfigEntry(ID, {
+            id: 'acp',
+            name: '@deepseek-ai/dsh-acp',
+            config: { model: profile.runtime.model },
+          }, ['model'], config => requiredString(config, 'model')),
+        ])
+      case 'stdio':
+        return new ProjectContribution([
+          ...npmCordisConfigEntry(ID, {
+            id: 'user-interaction',
+            name: '@deepseek-ai/dsh-user-interaction',
+          }),
+          ...npmCordisConfigEntry(ID, {
+            id: 'stdio',
+            name: '@deepseek-ai/dsh-stdio',
+            config: {
+              welcome: 'agent REPL ready. Give it a coding task.',
+              agent: 'main',
+            },
+          }, ['welcome', 'agent'], config => [
+            ...optionalString(config, 'welcome'),
+            ...requiredString(config, 'agent'),
+          ]),
+        ])
+      case 'embed':
+        return new ProjectContribution([])
+    }
+  }
+}
+
+/** Required app selection represented by acp, stdio, or embed options. */
+export class AppFeature extends ExclusiveOptionFeature {
+  override readonly id = ID
+  override readonly summary = 'Run interface'
+  override readonly required = true
+  override readonly requires = [featureId('spine')]
+  override readonly options = [
+    new AppOption('acp', 'ACP server'),
+    new AppOption('stdio', 'Terminal REPL'),
+    new AppOption('embed', 'Embedded context'),
+  ]
+
+  /** Default to the profile's already selected front door. */
+  override defaultOptions(profile: ProjectProfile): readonly string[] {
+    return [profile.runInterface]
+  }
+}
diff --git a/packages/sdk/helper/src/features/builtin/helpers.ts b/packages/sdk/helper/src/features/builtin/helpers.ts
new file mode 100644
index 0000000000..384f6ffea8
--- /dev/null
+++ b/packages/sdk/helper/src/features/builtin/helpers.ts
@@ -0,0 +1,99 @@
+/**
+ * Small resource constructors shared by builtin feature modules.
+ *
+ * @module @deepseek-ai/dsh-helper/features/builtin/helpers
+ */
+
+import type { CordisConfigEntry } from '../../documents/cordis-yaml-file.ts'
+import { TextProjectFile } from '../../documents/project-file.ts'
+import { resourceKey } from '../../ids.ts'
+import type {
+  CordisConfigEntryResource,
+  EnvironmentResource,
+  OwnedFileResource,
+  NpmDependencyResource,
+} from '../resources.ts'
+
+/** Create a runtime NPM dependency resource. */
+function npmDependency(_owner: string, name: string): NpmDependencyResource {
+  return {
+    kind: 'npm-dependency',
+    key: resourceKey(`npm-dependency:${name}`),
+    name,
+    section: 'dependencies',
+  }
+}
+
+/** Create a Cordis config entry resource with explicitly owned config keys. */
+export function cordisConfigEntry(
+  _owner: string,
+  value: CordisConfigEntry,
+  ownedConfigKeys: readonly string[] = Object.keys(value.config ?? {}),
+  validateConfig?: CordisConfigEntryResource['validateConfig'],
+): CordisConfigEntryResource {
+  return {
+    kind: 'cordis-config-entry',
+    key: resourceKey(`cordis-config-entry:${value.id}`),
+    entry: value,
+    ownedConfigKeys,
+    ...validateConfig ? { validateConfig } : {},
+  }
+}
+
+/** Couple one bare-package Cordis config entry to its mandatory runtime NPM dependency. */
+export function npmCordisConfigEntry(
+  owner: string,
+  value: CordisConfigEntry,
+  ownedConfigKeys: readonly string[] = Object.keys(value.config ?? {}),
+  validateConfig?: CordisConfigEntryResource['validateConfig'],
+): readonly [NpmDependencyResource, CordisConfigEntryResource] {
+  return [
+    npmDependency(owner, value.name),
+    cordisConfigEntry(owner, value, ownedConfigKeys, validateConfig),
+  ]
+}
+
+/** Create a secret/environment binding resource. */
+export function environment(
+  _owner: string,
+  name: string,
+  value: string | undefined,
+  comment?: string,
+): EnvironmentResource {
+  return {
+    kind: 'environment',
+    key: resourceKey(`environment:${name}`),
+    name,
+    ...value === undefined ? {} : { value },
+    exampleValue: '',
+    ...comment === undefined ? {} : { comment },
+  }
+}
+
+/** Create an owned complete-text file that is removable only while unchanged. */
+export function ownedTextFile(_owner: string, path: string, text: string): OwnedFileResource {
+  return {
+    kind: 'owned-file',
+    key: resourceKey(`file:${path}`),
+    document: new TextProjectFile(path, text),
+    removeOnlyWhenUnchanged: true,
+  }
+}
+
+/** Validate a config key as a string when present. */
+export function optionalString(config: Readonly<Record<string, unknown>>, key: string): string[] {
+  return config[key] === undefined || typeof config[key] === 'string' ? [] : [`${key} must be a string`]
+}
+
+/** Validate a config key as a non-empty string when required. */
+export function requiredString(config: Readonly<Record<string, unknown>>, key: string): string[] {
+  return typeof config[key] === 'string' && config[key].length > 0 ? [] : [`${key} must be a non-empty string`]
+}
+
+/** Validate a config key as an array of strings. */
+export function stringArray(config: Readonly<Record<string, unknown>>, key: string): string[] {
+  const value = config[key]
+  return Array.isArray(value) && value.every(item => typeof item === 'string')
+    ? []
+    : [`${key} must be an array of strings`]
+}
diff --git a/packages/sdk/helper/src/features/builtin/index.ts b/packages/sdk/helper/src/features/builtin/index.ts
new file mode 100644
index 0000000000..abf4915f07
--- /dev/null
+++ b/packages/sdk/helper/src/features/builtin/index.ts
@@ -0,0 +1,359 @@
+/**
+ * Ordered builtin feature catalog: behavior entities only where project
+ * context changes the contribution, typed specs everywhere else.
+ *
+ * @module @deepseek-ai/dsh-helper/features/builtin
+ */
+
+import type { BasicCompactConfig } from '@deepseek-ai/dsh-compact-basic'
+import type { Config as ClaudeHooksConfig } from '@deepseek-ai/dsh-hooks-claude'
+import type { Config as CodexHooksConfig } from '@deepseek-ai/dsh-hooks-codex'
+import type { Config as JsonlConfig } from '@deepseek-ai/dsh-session-persistence-jsonl'
+import type { Config as SqliteConfig } from '@deepseek-ai/dsh-session-persistence-sqlite'
+import type { Config as ToolSubagentConfig } from '@deepseek-ai/dsh-tool-subagent'
+import type { Config as ToolWebConfig } from '@deepseek-ai/dsh-tool-web'
+import type { ProjectProfile } from '../../project/types.ts'
+import { defineFeatures } from '../define-feature.ts'
+import { FeatureRegistry } from '../registry.ts'
+import { AppFeature } from './app.ts'
+import { ProviderFeature } from './provider.ts'
+import { SpineFeature } from './spine.ts'
+
+const compactPreset = {
+  contextWindow: 128_000,
+  thresholdRatio: 0.8,
+  retainTokens: 20_480,
+  summarizationModel: '',
+  maxTokens: 8_192,
+  compactionRetries: 1,
+} satisfies BasicCompactConfig
+
+/**
+ * Build and definition-check the complete builtin set for one project profile.
+ * @param profile - project context used to validate conditional contributions.
+ * @returns ordered builtin feature registry.
+ */
+export function createBuiltinRegistry(profile: ProjectProfile): FeatureRegistry {
+  return new FeatureRegistry(defineFeatures([
+    new ProviderFeature(),
+    new SpineFeature(),
+    {
+      id: 'bash',
+      summary: 'Command execution',
+      mode: 'exclusive',
+      required: true,
+      baseResources: [{ kind: 'npm-cordis-config-entry', id: 'tool-bash', package: '@deepseek-ai/dsh-tool-bash' }],
+      options: [
+        {
+          id: 'local',
+          label: 'Local executor',
+          default: true,
+          resources: [{ kind: 'npm-cordis-config-entry', id: 'bash', package: '@deepseek-ai/dsh-bash-local' }],
+        },
+        {
+          id: 'sandbox',
+          label: 'Sandboxed executor',
+          resources: [
+            { kind: 'npm-cordis-config-entry', id: 'sandbox', package: '@deepseek-ai/dsh-sandbox-local' },
+            { kind: 'npm-cordis-config-entry', id: 'bash', package: '@deepseek-ai/dsh-bash-sandbox' },
+          ],
+        },
+      ],
+    },
+    new AppFeature(),
+    {
+      id: 'persistence',
+      summary: 'Durable session storage',
+      mode: 'exclusive',
+      required: true,
+      options: [
+        {
+          id: 'jsonl',
+          label: 'JSONL files',
+          default: true,
+          resources: [{
+            kind: 'npm-cordis-config-entry',
+            id: 'session-persistence',
+            package: '@deepseek-ai/dsh-session-persistence-jsonl',
+            config: { root: './.sessions' } satisfies JsonlConfig,
+          }],
+        },
+        {
+          id: 'sqlite',
+          label: 'SQLite database',
+          resources: [{
+            kind: 'npm-cordis-config-entry',
+            id: 'session-persistence',
+            package: '@deepseek-ai/dsh-session-persistence-sqlite',
+            config: { path: './.sessions/sessions.sqlite' } satisfies SqliteConfig,
+          }],
+        },
+      ],
+    },
+    {
+      id: 'hmr',
+      summary: 'Hot-module reload',
+      mode: 'single',
+      options: [{
+        id: 'default',
+        label: 'Cordis HMR',
+        default: true,
+        resources: [{ kind: 'npm-cordis-config-entry', id: 'hmr', package: '@cordisjs/plugin-hmr' }],
+      }],
+    },
+    {
+      id: 'fs',
+      summary: 'Read, write, and edit local files',
+      mode: 'single',
+      options: [{
+        id: 'local',
+        label: 'Local filesystem',
+        default: true,
+        resources: [
+          { kind: 'npm-cordis-config-entry', id: 'fs-local', package: '@deepseek-ai/dsh-fs-local' },
+          { kind: 'npm-cordis-config-entry', id: 'fs-policy', package: '@deepseek-ai/dsh-fs-policy' },
+          { kind: 'npm-cordis-config-entry', id: 'tool-fs', package: '@deepseek-ai/dsh-tool-fs' },
+        ],
+      }],
+    },
+    {
+      id: 'todo',
+      summary: 'Model-facing task tracking',
+      mode: 'single',
+      options: [{
+        id: 'default',
+        label: 'todo_write tool',
+        default: true,
+        resources: [{ kind: 'npm-cordis-config-entry', id: 'tool-todo', package: '@deepseek-ai/dsh-tool-todo' }],
+      }],
+    },
+    {
+      id: 'skill',
+      summary: 'Local skill discovery',
+      mode: 'single',
+      options: [{
+        id: 'default',
+        label: 'Local skills and skill tool',
+        default: true,
+        resources: [
+          { kind: 'npm-cordis-config-entry', id: 'skill', package: '@deepseek-ai/dsh-skill' },
+          { kind: 'npm-cordis-config-entry', id: 'skill-local', package: '@deepseek-ai/dsh-skill-local' },
+          { kind: 'npm-cordis-config-entry', id: 'tool-skill', package: '@deepseek-ai/dsh-tool-skill' },
+        ],
+      }],
+    },
+    {
+      id: 'web',
+      summary: 'Web search and fetch tools',
+      mode: 'exclusive',
+      suggests: ['timeout-policy'],
+      baseResources: [
+        { kind: 'npm-cordis-config-entry', id: 'web', package: '@deepseek-ai/dsh-web' },
+        { kind: 'npm-cordis-config-entry', id: 'web-fetch-local', package: '@deepseek-ai/dsh-web-fetch-local' },
+      ],
+      options: [
+        {
+          id: 'deepseek',
+          label: 'DeepSeek search',
+          default: true,
+          markers: [{ id: 'web-search-deepseek', name: '@deepseek-ai/dsh-web-search-deepseek' }],
+          resources: [
+            { kind: 'npm-cordis-config-entry', id: 'web-search-deepseek', package: '@deepseek-ai/dsh-web-search-deepseek' },
+            { kind: 'npm-cordis-config-entry', id: 'tool-web', package: '@deepseek-ai/dsh-tool-web' },
+          ],
+        },
+        {
+          id: 'exa',
+          label: 'Exa search',
+          secrets: [{ id: 'apiKey', environment: 'EXA_API_KEY', message: 'Exa API key', required: true }],
+          markers: [{ id: 'web-search-exa', name: '@deepseek-ai/dsh-web-search-exa' }],
+          resources: [
+            { kind: 'npm-cordis-config-entry', id: 'web-search-exa', package: '@deepseek-ai/dsh-web-search-exa' },
+            { kind: 'npm-cordis-config-entry', id: 'tool-web', package: '@deepseek-ai/dsh-tool-web' },
+          ],
+        },
+        {
+          id: 'perplexity',
+          label: 'Perplexity search',
+          secrets: [{
+            id: 'apiKey',
+            environment: 'PERPLEXITY_API_KEY',
+            message: 'Perplexity API key',
+            required: true,
+          }],
+          markers: [{ id: 'web-search-perplexity', name: '@deepseek-ai/dsh-web-search-perplexity' }],
+          resources: [
+            {
+              kind: 'npm-cordis-config-entry',
+              id: 'web-search-perplexity',
+              package: '@deepseek-ai/dsh-web-search-perplexity',
+            },
+            { kind: 'npm-cordis-config-entry', id: 'tool-web', package: '@deepseek-ai/dsh-tool-web' },
+          ],
+        },
+        {
+          id: 'fetch-only',
+          label: 'Fetch only',
+          markers: [{ id: 'tool-web', name: '@deepseek-ai/dsh-tool-web', config: { search: false } }],
+          resources: [{
+            kind: 'npm-cordis-config-entry',
+            id: 'tool-web',
+            package: '@deepseek-ai/dsh-tool-web',
+            config: { search: false } satisfies ToolWebConfig,
+          }],
+        },
+      ],
+    },
+    {
+      id: 'subagent',
+      summary: 'Delegate work to child agents',
+      mode: 'multiple',
+      baseResources: [{ kind: 'npm-cordis-config-entry', id: 'subagent', package: '@deepseek-ai/dsh-subagent' }],
+      options: [
+        {
+          id: 'spawn',
+          label: 'Fresh child agent',
+          default: true,
+          resources: [
+            { kind: 'npm-cordis-config-entry', id: 'subagent-spawn', package: '@deepseek-ai/dsh-subagent-spawn' },
+            {
+              kind: 'npm-cordis-config-entry',
+              id: 'tool-subagent',
+              package: '@deepseek-ai/dsh-tool-subagent',
+              config: { provider: 'spawn' } satisfies ToolSubagentConfig,
+            },
+          ],
+        },
+        {
+          id: 'fork',
+          label: 'Fork parent history',
+          resources: [
+            { kind: 'npm-cordis-config-entry', id: 'subagent-fork', package: '@deepseek-ai/dsh-subagent-fork' },
+            {
+              kind: 'npm-cordis-config-entry',
+              id: 'tool-subagent-fork',
+              package: '@deepseek-ai/dsh-tool-subagent',
+              config: { provider: 'fork', toolName: 'subagent_fork' } satisfies ToolSubagentConfig,
+            },
+          ],
+        },
+      ],
+    },
+    {
+      id: 'workflow',
+      summary: 'Scripted multi-agent workflows',
+      mode: 'single',
+      options: [{
+        id: 'workerthread',
+        label: 'Worker thread engine',
+        default: true,
+        requires: [{ id: 'subagent', options: ['spawn'] }],
+        resources: [
+          {
+            kind: 'npm-cordis-config-entry',
+            id: 'workflow-workerthread',
+            package: '@deepseek-ai/dsh-workflow-workerthread',
+          },
+          { kind: 'npm-cordis-config-entry', id: 'tool-workflow', package: '@deepseek-ai/dsh-tool-workflow' },
+        ],
+      }],
+    },
+    {
+      id: 'compact',
+      summary: 'Automatic context compaction',
+      mode: 'single',
+      options: [{
+        id: 'basic',
+        label: 'Basic compaction',
+        default: true,
+        resources: [{
+          kind: 'npm-cordis-config-entry',
+          id: 'compact-basic',
+          package: '@deepseek-ai/dsh-compact-basic',
+          config: compactPreset,
+        }],
+      }],
+    },
+    {
+      id: 'hooks',
+      summary: 'Run Claude Code or Codex hooks',
+      mode: 'multiple',
+      requires: [{ id: 'bash' }],
+      options: [
+        {
+          id: 'claude',
+          label: 'Claude Code hooks',
+          default: true,
+          resources: [
+            {
+              kind: 'npm-cordis-config-entry',
+              id: 'hooks-claude',
+              package: '@deepseek-ai/dsh-hooks-claude',
+              config: { configPath: './hooks.json' } satisfies ClaudeHooksConfig,
+            },
+            { kind: 'owned-file', path: 'hooks.json', text: '{}' },
+          ],
+        },
+        {
+          id: 'codex',
+          label: 'Codex hooks',
+          resources: [
+            {
+              kind: 'npm-cordis-config-entry',
+              id: 'hooks-codex',
+              package: '@deepseek-ai/dsh-hooks-codex',
+              config: { configPath: './codex-hooks.json' } satisfies CodexHooksConfig,
+            },
+            { kind: 'owned-file', path: 'codex-hooks.json', text: '{}' },
+          ],
+        },
+      ],
+    },
+    {
+      id: 'guard',
+      summary: 'Loop-hygiene reminders',
+      mode: 'single',
+      options: [{
+        id: 'repeat-tool',
+        label: 'Repeat-tool reminders',
+        default: true,
+        resources: [{
+          kind: 'npm-cordis-config-entry',
+          id: 'repeat-tool-guard',
+          package: '@deepseek-ai/dsh-repeat-tool-guard',
+        }],
+      }],
+    },
+    {
+      id: 'timeout-policy',
+      summary: 'Tool timeout policy',
+      mode: 'single',
+      options: [{
+        id: 'default',
+        label: 'Timeout policy',
+        default: true,
+        resources: [{
+          kind: 'npm-cordis-config-entry',
+          id: 'timeout-policy',
+          package: '@deepseek-ai/dsh-timeout-policy',
+        }],
+      }],
+    },
+    {
+      id: 'ask-user',
+      summary: 'Ask the user from the model loop',
+      mode: 'single',
+      supportedInterfaces: ['acp', 'stdio'],
+      options: [{
+        id: 'default',
+        label: 'ask_user_question tool',
+        default: true,
+        resources: [{
+          kind: 'npm-cordis-config-entry',
+          id: 'tool-ask-user',
+          package: '@deepseek-ai/dsh-tool-ask-user',
+        }],
+      }],
+    },
+  ]), profile)
+}
diff --git a/packages/sdk/helper/src/features/builtin/provider.ts b/packages/sdk/helper/src/features/builtin/provider.ts
new file mode 100644
index 0000000000..227d80088c
--- /dev/null
+++ b/packages/sdk/helper/src/features/builtin/provider.ts
@@ -0,0 +1,111 @@
+/**
+ * Required hand-rolled DeepSeek and custom pi-ai provider behavior.
+ *
+ * @module @deepseek-ai/dsh-helper/features/builtin/provider
+ */
+
+import { JsExpression } from '../../documents/cordis-yaml-file.ts'
+import { featureId } from '../../ids.ts'
+import type { FeatureSelection, ProjectProfile } from '../../project/types.ts'
+import {
+  FeatureOption,
+  ExclusiveOptionFeature,
+  type FeatureProjectView,
+} from '../feature.ts'
+import { ProjectContribution } from '../resources.ts'
+import { npmCordisConfigEntry, environment } from './helpers.ts'
+
+const ID = featureId('provider')
+const DEFAULT_MODEL = 'deepseek-v4-flash'
+const API_KEY_COMMENT = 'Required before start; an empty value makes provider startup fail.'
+
+class DeepSeekOption extends FeatureOption {
+  override readonly id = 'deepseek'
+  override readonly label = 'DeepSeek'
+  override readonly secrets = [{
+    id: 'apiKey',
+    environment: 'DEEPSEEK_API_KEY',
+    message: 'DeepSeek API key',
+    required: true,
+  }]
+
+  override contribution(_profile: ProjectProfile, secrets: Readonly<Record<string, string>>): ProjectContribution {
+    return new ProjectContribution([
+      ...npmCordisConfigEntry(ID, {
+        id: 'llm-deepseek',
+        name: '@deepseek-ai/dsh-llm-deepseek',
+        config: { apiKey: new JsExpression('process.env.DEEPSEEK_API_KEY') },
+      }, ['apiKey', 'baseURL', 'models']),
+      environment(ID, 'DEEPSEEK_API_KEY', secrets.apiKey, API_KEY_COMMENT),
+    ])
+  }
+}
+
+class CustomOption extends FeatureOption {
+  override readonly id = 'custom'
+  override readonly label = 'Custom endpoint (pi-ai)'
+  override readonly secrets = [{
+    id: 'apiKey',
+    environment: 'DEEPSEEK_API_KEY',
+    message: 'Custom provider API key',
+    required: true,
+  }]
+  override readonly inputs = [{
+    id: 'baseURL',
+    message: 'Custom provider base URL',
+  }]
+
+  override contribution(_profile: ProjectProfile, secrets: Readonly<Record<string, string>>): ProjectContribution {
+    return new ProjectContribution([
+      ...npmCordisConfigEntry(ID, {
+        id: 'llm-pi-ai',
+        name: '@deepseek-ai/dsh-llm-pi-ai',
+        config: { apiKey: new JsExpression('process.env.DEEPSEEK_API_KEY') },
+      }, ['apiKey', 'baseURL', 'models']),
+      environment(ID, 'DEEPSEEK_API_KEY', secrets.apiKey, API_KEY_COMMENT),
+    ])
+  }
+}
+
+/** Required provider feature with DeepSeek and custom pi-ai options. */
+export class ProviderFeature extends ExclusiveOptionFeature {
+  override readonly id = ID
+  override readonly summary = 'Model provider'
+  override readonly required = true
+  override readonly options = [new DeepSeekOption(), new CustomOption()]
+
+  /** Prefer the hand-rolled adapter and its public endpoint defaults. */
+  override defaultOptions(): readonly string[] {
+    return ['deepseek']
+  }
+
+  /** Recover literal endpoint overrides from either provider entry. */
+  override readSelection(project: FeatureProjectView, selection: FeatureSelection): FeatureSelection {
+    const base = super.readSelection(project, selection)
+    const entry = project.cordisConfigEntries().find(item => item.id === 'llm-deepseek' || item.id === 'llm-pi-ai')
+    const baseURL = entry?.config?.baseURL
+    return typeof baseURL === 'string' ? { ...base, values: { baseURL } } : base
+  }
+
+  /** Apply explicit endpoint/model overrides while omitting provider defaults. */
+  override contribution(selection: FeatureSelection, profile: ProjectProfile): ProjectContribution {
+    const contribution = super.contribution(selection, profile)
+    const baseURL = selection.values?.baseURL
+    if (baseURL !== undefined && typeof baseURL !== 'string') throw new Error('provider baseURL must be a string')
+    return new ProjectContribution(contribution.resources.map((resource) => {
+      if (resource.kind !== 'cordis-config-entry' || (resource.entry.id !== 'llm-deepseek'
+        && resource.entry.id !== 'llm-pi-ai')) return resource
+      return {
+        ...resource,
+        entry: {
+          ...resource.entry,
+          config: {
+            ...resource.entry.config,
+            ...baseURL ? { baseURL } : {},
+            ...profile.runtime.model === DEFAULT_MODEL ? {} : { models: [profile.runtime.model] },
+          },
+        },
+      }
+    }))
+  }
+}
diff --git a/packages/sdk/helper/src/features/builtin/spine.ts b/packages/sdk/helper/src/features/builtin/spine.ts
new file mode 100644
index 0000000000..caf066865e
--- /dev/null
+++ b/packages/sdk/helper/src/features/builtin/spine.ts
@@ -0,0 +1,55 @@
+/**
+ * Required agent-spine feature expressed as top-level Cordis config entries.
+ *
+ * @module @deepseek-ai/dsh-helper/features/builtin/spine
+ */
+
+import { featureId } from '../../ids.ts'
+import type { ProjectProfile } from '../../project/types.ts'
+import { loadHelperTemplate } from '../../templates/template-assets.ts'
+import { FeatureOption, FixedFeature } from '../feature.ts'
+import { ProjectContribution } from '../resources.ts'
+import { npmCordisConfigEntry, requiredString } from './helpers.ts'
+
+const ID = featureId('spine')
+const PERSONA = loadHelperTemplate<Record<string, never>>('persona.txt.tpl').render({}).trimEnd()
+
+function emptyAgentsDiagnostics(config: Readonly<Record<string, unknown>>): string[] {
+  const agents = config.agents
+  if (!Array.isArray(agents)) return ['agents must be an array']
+  return agents.length === 0 ? [] : ['agents must be empty']
+}
+
+class SpineOption extends FeatureOption {
+  override readonly id = 'default'
+  override readonly label = 'Default agent spine'
+
+  override contribution(_profile: ProjectProfile): ProjectContribution {
+    return new ProjectContribution([
+      ...npmCordisConfigEntry(ID, { id: 'timer', name: '@cordisjs/plugin-timer' }),
+      ...npmCordisConfigEntry(ID, { id: 'llm', name: '@deepseek-ai/dsh-llm' }),
+      ...npmCordisConfigEntry(ID, { id: 'session', name: '@deepseek-ai/dsh-session' }),
+      ...npmCordisConfigEntry(ID, {
+        id: 'system-prompt',
+        name: '@deepseek-ai/dsh-system-prompt',
+        config: { persona: PERSONA },
+      }, ['persona'], config => requiredString(config, 'persona')),
+      ...npmCordisConfigEntry(ID, { id: 'tools', name: '@deepseek-ai/dsh-tools' }, []),
+      ...npmCordisConfigEntry(ID, { id: 'agent', name: '@deepseek-ai/dsh-agent' }),
+      ...npmCordisConfigEntry(ID, { id: 'invariants', name: '@deepseek-ai/dsh-invariants' }),
+      ...npmCordisConfigEntry(ID, {
+        id: 'agent-loop',
+        name: '@deepseek-ai/dsh-agent-loop',
+        config: { agents: [] },
+      }, ['agents'], emptyAgentsDiagnostics),
+    ])
+  }
+}
+
+/** Required providerless agent spine without a composition bundle entry. */
+export class SpineFeature extends FixedFeature {
+  override readonly id = ID
+  override readonly summary = 'Agent runtime spine'
+  override readonly required = true
+  override readonly options = [new SpineOption()]
+}
diff --git a/packages/sdk/helper/src/features/define-feature.ts b/packages/sdk/helper/src/features/define-feature.ts
new file mode 100644
index 0000000000..9fd6ced1d2
--- /dev/null
+++ b/packages/sdk/helper/src/features/define-feature.ts
@@ -0,0 +1,283 @@
+/**
+ * Typed declarative definitions for features whose behavior is entirely
+ * the shared resource lifecycle.
+ *
+ * @module @deepseek-ai/dsh-helper/features/define-feature
+ */
+
+import type { CordisConfigEntry } from '../documents/cordis-yaml-file.ts'
+import { TextProjectFile } from '../documents/project-file.ts'
+import { featureId, resourceKey, type FeatureId } from '../ids.ts'
+import type { FeatureSelection, ProjectProfile, RunInterface } from '../project/types.ts'
+import {
+  Feature,
+  FeatureOption,
+  type FeatureRequirement,
+  type FeatureSecret,
+} from './feature.ts'
+import { ProjectContribution, type ProjectResource } from './resources.ts'
+
+/** Static NPM dependency in a declarative feature. */
+interface NpmDependencySpec {
+  kind: 'npm-dependency'
+  name: string
+  section?: 'dependencies' | 'devDependencies'
+}
+
+/** Bare-package Cordis config entry that also contributes its NPM dependency. */
+interface NpmCordisConfigEntrySpec {
+  kind: 'npm-cordis-config-entry'
+  id: string
+  package: string
+  config?: Readonly<Record<string, unknown>>
+  ownedConfigKeys?: readonly string[]
+}
+
+/** Relative or absolute file Cordis config entry with no NPM dependency. */
+interface FileCordisConfigEntrySpec {
+  kind: 'file-cordis-config-entry'
+  id: string
+  path: string
+  config?: Readonly<Record<string, unknown>>
+  ownedConfigKeys?: readonly string[]
+}
+
+/** Static complete file owned by one feature option. */
+interface OwnedFileSpec {
+  kind: 'owned-file'
+  path: string
+  text: string
+  removeOnlyWhenUnchanged?: boolean
+}
+
+/** Resource forms that require no feature-specific imperative code. */
+type FeatureResourceSpec =
+  | NpmDependencySpec
+  | NpmCordisConfigEntrySpec
+  | FileCordisConfigEntrySpec
+  | OwnedFileSpec
+
+/** Cordis config entry identity and optional plugin-config subset that identifies an option. */
+interface FeatureOptionMarkerSpec {
+  id: string
+  name: string
+  config?: Readonly<Record<string, unknown>>
+}
+
+/** Declarative requirement converted to branded domain identity at the boundary. */
+interface FeatureRequirementSpec {
+  id: string
+  options?: readonly string[]
+}
+
+/** One static option inside a typed feature definition. */
+interface FeatureOptionSpec {
+  id: string
+  label: string
+  default?: boolean
+  resources: readonly FeatureResourceSpec[]
+  secrets?: readonly FeatureSecret[]
+  markers?: readonly FeatureOptionMarkerSpec[]
+  requires?: readonly FeatureRequirementSpec[]
+}
+
+/** Complete declarative feature definition. */
+export interface FeatureSpec {
+  id: string
+  summary: string
+  mode: 'single' | 'exclusive' | 'multiple'
+  options: readonly FeatureOptionSpec[]
+  baseResources?: readonly FeatureResourceSpec[]
+  required?: boolean
+  requires?: readonly FeatureRequirementSpec[]
+  suggests?: readonly string[]
+  supportedInterfaces?: readonly RunInterface[]
+}
+
+function sameShape(expected: unknown, actual: unknown): boolean {
+  if (expected === null || actual === null) return expected === actual
+  if (Array.isArray(expected)) {
+    return Array.isArray(actual) && (expected.length === 0 || actual.every(item => sameShape(expected[0], item)))
+  }
+  if (typeof expected !== 'object') return typeof expected === typeof actual
+  if (typeof actual !== 'object' || Array.isArray(actual)) return false
+  return Object.entries(expected as Record<string, unknown>).every(
+    ([key, value]) => sameShape(value, (actual as Record<string, unknown>)[key]),
+  )
+}
+
+function configDiagnostics(
+  expected: Readonly<Record<string, unknown>> | undefined,
+): ((config: Readonly<Record<string, unknown>>) => readonly string[]) | undefined {
+  if (!expected || Object.keys(expected).length === 0) return undefined
+  return config => Object.entries(expected).flatMap(([key, value]) => sameShape(value, config[key])
+    ? []
+    : [`${key} has an incompatible value shape`])
+}
+
+function resourcesFromSpec(spec: FeatureResourceSpec): ProjectResource[] {
+  switch (spec.kind) {
+    case 'npm-dependency':
+      return [{
+        kind: 'npm-dependency',
+        key: resourceKey(`npm-dependency:${spec.name}`),
+        name: spec.name,
+        section: spec.section ?? 'dependencies',
+      }]
+    case 'npm-cordis-config-entry':
+    case 'file-cordis-config-entry': {
+      const config = spec.config ? { ...spec.config } : undefined
+      const validateConfig = configDiagnostics(config)
+      const name = spec.kind === 'npm-cordis-config-entry' ? spec.package : spec.path
+      return [
+        ...spec.kind === 'npm-cordis-config-entry'
+          ? [{
+            kind: 'npm-dependency' as const,
+            key: resourceKey(`npm-dependency:${spec.package}`),
+            name: spec.package,
+            section: 'dependencies' as const,
+          }]
+          : [],
+        {
+          kind: 'cordis-config-entry',
+          key: resourceKey(`cordis-config-entry:${spec.id}`),
+          entry: {
+            id: spec.id,
+            name,
+            ...config ? { config } : {},
+          },
+          ownedConfigKeys: spec.ownedConfigKeys ?? Object.keys(config ?? {}),
+          ...validateConfig ? { validateConfig } : {},
+        },
+      ]
+    }
+    case 'owned-file':
+      return [{
+        kind: 'owned-file',
+        key: resourceKey(`file:${spec.path}`),
+        document: new TextProjectFile(spec.path, spec.text),
+        removeOnlyWhenUnchanged: spec.removeOnlyWhenUnchanged ?? true,
+      }]
+  }
+}
+
+function isSubset(expected: Readonly<Record<string, unknown>>, actual: Readonly<Record<string, unknown>>): boolean {
+  return Object.entries(expected).every(([key, value]) => Object.is(actual[key], value))
+}
+
+class DefinedFeatureOption extends FeatureOption {
+  override readonly id: string
+  override readonly label: string
+  override readonly secrets: readonly FeatureSecret[]
+  private readonly spec: FeatureOptionSpec
+
+  constructor(spec: FeatureOptionSpec) {
+    super()
+    this.spec = spec
+    this.id = spec.id
+    this.label = spec.label
+    this.secrets = spec.secrets ?? []
+  }
+
+  override contribution(_profile: ProjectProfile, secrets: Readonly<Record<string, string>>): ProjectContribution {
+    return new ProjectContribution([
+      ...this.spec.resources.flatMap(resourcesFromSpec),
+      ...this.secrets.map(secret => ({
+        kind: 'environment' as const,
+        key: resourceKey(`environment:${secret.environment}`),
+        name: secret.environment,
+        ...secrets[secret.id] === undefined ? {} : { value: secrets[secret.id] },
+        exampleValue: '',
+      })),
+    ])
+  }
+
+  override markerConfigEntries(): readonly Pick<CordisConfigEntry, 'id' | 'name'>[] {
+    const markers = this.spec.markers ?? this.spec.resources.flatMap((resource) => {
+      switch (resource.kind) {
+        case 'npm-cordis-config-entry': return [{ id: resource.id, name: resource.package }]
+        case 'file-cordis-config-entry': return [{ id: resource.id, name: resource.path }]
+        default: return []
+      }
+    })
+    return markers.map(marker => ({ id: marker.id, name: marker.name }))
+  }
+
+  override matchesConfigEntries(entries: readonly CordisConfigEntry[]): boolean {
+    const markers = this.spec.markers
+    if (!markers) return this.markerConfigEntries().some(marker => entries.some(
+      entry => entry.id === marker.id && entry.name === marker.name,
+    ))
+    return markers.some(marker => entries.some(entry => entry.id === marker.id
+      && entry.name === marker.name
+      && (!marker.config || isSubset(marker.config, entry.config ?? {}))))
+  }
+}
+
+/** Feature entity backed by a typed static definition. */
+class DefinedFeature extends Feature {
+  override readonly id: FeatureId
+  override readonly summary: string
+  override readonly mode: FeatureSpec['mode']
+  override readonly options: readonly FeatureOption[]
+  override readonly required: boolean
+  override readonly requires: readonly FeatureId[]
+  override readonly suggests: readonly FeatureId[]
+  override readonly supportedInterfaces: readonly RunInterface[]
+  private readonly spec: FeatureSpec
+
+  /** Validate and materialize one declarative definition. */
+  constructor(spec: FeatureSpec) {
+    super()
+    this.spec = spec
+    this.id = featureId(spec.id)
+    this.summary = spec.summary
+    this.mode = spec.mode
+    this.options = spec.options.map(option => new DefinedFeatureOption(option))
+    const defaultCount = spec.options.filter(option => option.default).length
+    if (spec.mode === 'single' && (spec.options.length !== 1 || defaultCount !== 1)) {
+      throw new Error(`single feature ${spec.id} requires one default option`)
+    }
+    if (spec.mode === 'exclusive' && defaultCount !== 1) {
+      throw new Error(`exclusive feature ${spec.id} requires exactly one default option`)
+    }
+    if (spec.mode === 'multiple' && defaultCount === 0) {
+      throw new Error(`multiple feature ${spec.id} requires at least one default option`)
+    }
+    this.required = spec.required ?? false
+    this.requires = (spec.requires ?? []).map(requirement => featureId(requirement.id))
+    this.suggests = (spec.suggests ?? []).map(featureId)
+    this.supportedInterfaces = spec.supportedInterfaces ?? ['acp', 'stdio', 'embed']
+  }
+
+  override defaultOptions(): readonly string[] {
+    return this.spec.options.filter(option => option.default).map(option => option.id)
+  }
+
+  override baseContribution(): ProjectContribution {
+    return new ProjectContribution((this.spec.baseResources ?? []).flatMap(resourcesFromSpec))
+  }
+
+  override requirements(selection: FeatureSelection): readonly FeatureRequirement[] {
+    const selected = new Set(selection.options)
+    return [
+      ...(this.spec.requires ?? []),
+      ...this.spec.options.filter(option => selected.has(option.id)).flatMap(option => option.requires ?? []),
+    ].map(requirement => ({
+      id: featureId(requirement.id),
+      ...requirement.options ? { options: requirement.options } : {},
+    }))
+  }
+}
+
+/** Construct the shared lifecycle entity from a typed declarative definition. */
+export function defineFeature(spec: FeatureSpec): Feature {
+  return new DefinedFeature(spec)
+}
+
+/** Materialize one ordered catalog containing static specs and behavior entities. */
+export function defineFeatures(definitions: readonly (Feature | FeatureSpec)[]): Feature[] {
+  return definitions.map(definition => definition instanceof Feature
+    ? definition
+    : defineFeature(definition))
+}
diff --git a/packages/sdk/helper/src/features/feature-configurator.ts b/packages/sdk/helper/src/features/feature-configurator.ts
new file mode 100644
index 0000000000..47cc011d16
--- /dev/null
+++ b/packages/sdk/helper/src/features/feature-configurator.ts
@@ -0,0 +1,104 @@
+/**
+ * Shared option and secret question flow for create and config.
+ *
+ * @module @deepseek-ai/dsh-helper/features/feature-configurator
+ */
+
+import type { Feature } from './feature.ts'
+import type { FeatureSelection, ProjectProfile } from '../project/types.ts'
+import type { PromptPort } from '../questions/prompt-port.ts'
+import { requireAnswer } from '../questions/prompt-port.ts'
+import { MultiSelectQuestion, SecretQuestion, SelectQuestion, TextQuestion } from '../questions/question.ts'
+
+/** Resolve one feature selection without knowing which workflow requested it. */
+export class FeatureConfigurator {
+  private readonly port: PromptPort
+
+  /** Bind the configurator to the shared prompt boundary. */
+  constructor(port: PromptPort) {
+    this.port = port
+  }
+
+  /**
+   * Ask option and input questions, preserving current secrets on empty input.
+   * @param feature - feature whose options and inputs are collected.
+   * @param profile - target project context.
+   * @param current - currently installed selection, when configuring.
+   * @param prefilledOptions - options already chosen by a tree picker.
+   * @param prefilledSecrets - non-interactive secret values supplied by creation.
+   * @returns normalized selection with captured values and secrets.
+   */
+  async configure(
+    feature: Feature,
+    profile: ProjectProfile,
+    current?: FeatureSelection,
+    prefilledOptions?: readonly string[],
+    prefilledSecrets: Readonly<Record<string, string>> = {},
+  ): Promise<FeatureSelection> {
+    let options: readonly string[]
+    switch (feature.mode) {
+      case 'single':
+        options = feature.defaultOptions(profile)
+        break
+      case 'exclusive': {
+        const initialValue = current?.options[0] ?? feature.defaultOptions(profile)[0]
+        if (initialValue === undefined) throw new Error(`feature ${feature.id} has no default option`)
+        const question = new SelectQuestion({
+          id: `${feature.id}.option`,
+          message: `Choose ${feature.summary.toLowerCase()}`,
+          options: feature.options.map(option => ({ value: option.id, label: option.label })),
+          initialValue,
+        })
+        const prefilled = prefilledOptions?.[0]
+        options = [requireAnswer(await question.resolve(this.port, prefilled))]
+        break
+      }
+      case 'multiple': {
+        const question = new MultiSelectQuestion({
+          id: `${feature.id}.options`,
+          message: `Choose ${feature.summary.toLowerCase()}`,
+          options: feature.options.map(option => ({ value: option.id, label: option.label })),
+          initialValues: current?.options ?? feature.defaultOptions(profile),
+          required: true,
+        })
+        options = requireAnswer(await question.resolve(this.port, prefilledOptions))
+        break
+      }
+    }
+    const selected: FeatureSelection = {
+      id: feature.id,
+      options,
+    }
+    const values: Record<string, string> = {}
+    for (const input of feature.valueInputs(selected, profile)) {
+      const existing = current?.values?.[input.id]
+      if (existing !== undefined && typeof existing !== 'string') {
+        throw new Error(`${feature.id}.${input.id} current value must be a string`)
+      }
+      const question = new TextQuestion({
+        id: `${feature.id}.${input.id}`,
+        message: input.message,
+        ...existing === undefined ? {} : { initialValue: existing },
+        validate: value => value.trim().length === 0 ? 'A value is required' : undefined,
+      })
+      values[input.id] = requireAnswer(await question.resolve(this.port))
+    }
+    const base: FeatureSelection = Object.keys(values).length === 0
+      ? selected
+      : { ...selected, values }
+    const secrets = { ...current?.secrets }
+    for (const secret of feature.secrets(base, profile)) {
+      const existing = secrets[secret.id]
+      const question = new SecretQuestion({
+        id: `${feature.id}.${secret.id}`,
+        message: existing === undefined ? secret.message : `${secret.message} (leave empty to keep current)`,
+        validate: value => secret.required && existing === undefined && value.length === 0
+          ? 'A value is required'
+          : undefined,
+      })
+      const answer = requireAnswer(await question.resolve(this.port, prefilledSecrets[secret.id]))
+      if (answer.length > 0) secrets[secret.id] = answer
+    }
+    return Object.keys(secrets).length === 0 ? base : { ...base, secrets }
+  }
+}
diff --git a/packages/sdk/helper/src/features/feature.ts b/packages/sdk/helper/src/features/feature.ts
new file mode 100644
index 0000000000..fcbe64e052
--- /dev/null
+++ b/packages/sdk/helper/src/features/feature.ts
@@ -0,0 +1,340 @@
+/**
+ * Stateful builtin feature and option domain objects.
+ *
+ * @module @deepseek-ai/dsh-helper/features/feature
+ */
+
+import type { CordisConfigEntry } from '../documents/cordis-yaml-file.ts'
+import type { PackageManifest } from '../documents/package-json-file.ts'
+import type { FeatureId } from '../ids.ts'
+import type { FeatureSelection, ProjectProfile, RunInterface } from '../project/types.ts'
+import { ProjectContribution, type CordisConfigEntryResource, type ProjectResource } from './resources.ts'
+
+/** Read-only project surface used by feature inspection. */
+export interface FeatureProjectView {
+  readonly profile: ProjectProfile
+  cordisConfigEntries(): readonly CordisConfigEntry[]
+  packageManifest(): Readonly<PackageManifest>
+  hasDocument(path: string): boolean
+  readEnvironment(path: '.env' | '.env.example', name: string): string | undefined
+}
+
+/** Installation state visible to create/config workflows. */
+type FeatureInstallationState = 'absent' | 'enabled' | 'disabled' | 'inconsistent'
+
+/** Result of round-tripping one feature from a project snapshot. */
+export interface FeatureInstallation {
+  id: FeatureId
+  state: FeatureInstallationState
+  options: readonly string[]
+  selection?: FeatureSelection
+  diagnostics: readonly string[]
+}
+
+/** One final-state requirement on another builtin feature. */
+export interface FeatureRequirement {
+  id: FeatureId
+  options?: readonly string[]
+}
+
+/** One secret captured into an environment binding rather than Cordis plugin config. */
+export interface FeatureSecret {
+  id: string
+  environment: string
+  message: string
+  required: boolean
+}
+
+/** One visible string value requested only by options that own it. */
+export interface FeatureValueInput {
+  id: string
+  message: string
+}
+
+/** One selectable behavior option owned by a feature. */
+export abstract class FeatureOption {
+  abstract readonly id: string
+  abstract readonly label: string
+  readonly secrets: readonly FeatureSecret[] = []
+  readonly inputs: readonly FeatureValueInput[] = []
+
+  /** Contribute this option's project resources. */
+  abstract contribution(profile: ProjectProfile, secrets: Readonly<Record<string, string>>): ProjectContribution
+
+  /** Every Cordis config entry package owned by this option during inspection. */
+  ownedConfigEntries(profile: ProjectProfile): readonly Pick<CordisConfigEntry, 'id' | 'name'>[] {
+    return this.contribution(profile, {}).resources
+      .filter((resource): resource is CordisConfigEntryResource => resource.kind === 'cordis-config-entry')
+      .map(resource => ({ id: resource.entry.id, name: resource.entry.name }))
+  }
+
+  /** Cordis config entry identities that distinguish this option during inspection. */
+  markerConfigEntries(profile: ProjectProfile): readonly Pick<CordisConfigEntry, 'id' | 'name'>[] {
+    return this.ownedConfigEntries(profile)
+  }
+
+  /** Whether current owned Cordis config entries identify this option. */
+  matchesConfigEntries(entries: readonly CordisConfigEntry[], profile: ProjectProfile): boolean {
+    return this.markerConfigEntries(profile).some(marker => entries.some(
+      entry => entry.id === marker.id && entry.name === marker.name,
+    ))
+  }
+}
+
+/** How a feature's options compose. */
+export type FeatureOptionMode = 'single' | 'exclusive' | 'multiple'
+
+function packageNames(resources: readonly ProjectResource[]): Set<string> {
+  return new Set(resources
+    .filter((resource): resource is CordisConfigEntryResource => resource.kind === 'cordis-config-entry')
+    .map(resource => resource.entry.name))
+}
+
+function configDiagnostics(resource: CordisConfigEntryResource, entry: CordisConfigEntry): string[] {
+  /* v8 ignore next -- entries without validators have no diagnostics to compute */
+  if (!resource.validateConfig) return []
+  return [...resource.validateConfig(entry.config ?? {})].map(message => `${entry.id}: ${message}`)
+}
+
+/** A behavior-owning builtin feature with shallow option composition. */
+export abstract class Feature {
+  /** Stable registry identity. */
+  abstract readonly id: FeatureId
+  /** User-facing feature summary. */
+  abstract readonly summary: string
+  /** Option-selection rule. */
+  abstract readonly mode: FeatureOptionMode
+  /** Available behavior options. */
+  abstract readonly options: readonly FeatureOption[]
+  /** Whether every valid project must enable this feature. */
+  readonly required: boolean = false
+  /** Unconditional feature requirements. */
+  readonly requires: readonly FeatureId[] = []
+  /** Features recommended during creation. */
+  readonly suggests: readonly FeatureId[] = []
+  /** Front doors under which this feature is meaningful. */
+  readonly supportedInterfaces: readonly RunInterface[] = ['acp', 'stdio', 'embed']
+
+  /**
+   * Options selected when installation has no override.
+   * @param profile - project context controlling applicable defaults.
+   * @returns selected option ids.
+   */
+  abstract defaultOptions(profile: ProjectProfile): readonly string[]
+
+  /**
+   * Shared resources present for every installed option set.
+   * @param _profile - project context available to behavior features.
+   * @returns shared project contribution.
+   */
+  baseContribution(_profile: ProjectProfile): ProjectContribution {
+    return new ProjectContribution([])
+  }
+
+  /**
+   * Additional final-state requirements depending on selected options.
+   * @param _selection - normalized feature selection.
+   * @returns required features and option constraints.
+   */
+  requirements(_selection: FeatureSelection): readonly FeatureRequirement[] {
+    return this.requires.map(id => ({ id }))
+  }
+
+  /**
+   * Whether the feature may be selected for this project front door.
+   * @param profile - project context to check.
+   * @returns whether the feature applies.
+   */
+  isApplicable(profile: ProjectProfile): boolean {
+    return this.supportedInterfaces.includes(profile.runInterface)
+  }
+
+  /**
+   * Validate and normalize one requested option set.
+   * @param selection - requested feature and options.
+   * @param profile - project context for applicability and defaults.
+   * @returns deduplicated, sorted selection.
+   */
+  normalizeSelection(selection: FeatureSelection, profile: ProjectProfile): FeatureSelection {
+    if (selection.id !== this.id) throw new Error(`selection ${selection.id} does not belong to feature ${this.id}`)
+    if (!this.isApplicable(profile)) {
+      throw new Error(`feature ${this.id} is not available for ${profile.runInterface}`)
+    }
+    const available = new Set(this.options.map(option => option.id))
+    const options = [...new Set(selection.options.length > 0 ? selection.options : this.defaultOptions(profile))]
+    for (const option of options) {
+      if (!available.has(option)) throw new Error(`unknown ${this.id} option: ${option}`)
+    }
+    if (this.mode === 'single' && (options.length !== 1 || this.options.length !== 1)) {
+      throw new Error(`feature ${this.id} has one fixed option`)
+    }
+    if (this.mode === 'exclusive' && options.length !== 1) {
+      throw new Error(`feature ${this.id} requires exactly one option`)
+    }
+    if (this.mode === 'multiple' && options.length === 0) {
+      throw new Error(`feature ${this.id} requires at least one option`)
+    }
+    return { ...selection, options: options.sort() }
+  }
+
+  /**
+   * Build the complete selected resource contribution.
+   * @param selection - selected options and captured inputs.
+   * @param profile - target project context.
+   * @returns merged base and option resources.
+   */
+  contribution(selection: FeatureSelection, profile: ProjectProfile): ProjectContribution {
+    const normalized = this.normalizeSelection(selection, profile)
+    const selected = this.selectedOptions(normalized)
+      .map(option => option.contribution(profile, normalized.secrets ?? {}))
+    return ProjectContribution.merge(this.baseContribution(profile), ...selected)
+  }
+
+  /**
+   * All secret definitions required by one selected option set.
+   * @param selection - selected options.
+   * @param profile - target project context.
+   * @returns selected secret definitions.
+   */
+  secrets(selection: FeatureSelection, profile: ProjectProfile): readonly FeatureSecret[] {
+    const normalized = this.normalizeSelection(selection, profile)
+    return this.selectedOptions(normalized).flatMap(option => option.secrets)
+  }
+
+  /**
+   * All visible value definitions required by one selected option set.
+   * @param selection - selected options.
+   * @param profile - target project context.
+   * @returns selected visible-input definitions.
+   */
+  valueInputs(selection: FeatureSelection, profile: ProjectProfile): readonly FeatureValueInput[] {
+    const normalized = this.normalizeSelection(selection, profile)
+    return this.selectedOptions(normalized).flatMap(option => option.inputs)
+  }
+
+  private selectedOptions(selection: FeatureSelection): readonly FeatureOption[] {
+    return selection.options.map((id) => {
+      const option = this.options.find(candidate => candidate.id === id)
+      /* v8 ignore next -- normalizeSelection already membership-checks every selected id */
+      if (!option) throw new Error(`unknown ${this.id} option: ${id}`)
+      return option
+    })
+  }
+
+  /**
+   * Recover input and secret values after structural inspection.
+   * @param project - project snapshot being inspected.
+   * @param selection - structurally detected selection.
+   * @returns selection enriched with readable values.
+   */
+  readSelection(project: FeatureProjectView, selection: FeatureSelection): FeatureSelection {
+    const secrets = Object.fromEntries(this.secrets(selection, project.profile).flatMap((secret) => {
+      const value = project.readEnvironment('.env', secret.environment)
+      return value === undefined ? [] : [[secret.id, value]]
+    }))
+    return Object.keys(secrets).length === 0 ? selection : { ...selection, secrets }
+  }
+
+  /**
+   * Inspect current files and reject any partial or ambiguous owned shape.
+   * @param project - project snapshot to inspect.
+   * @returns installation state, selection, and diagnostics.
+   */
+  inspect(project: FeatureProjectView): FeatureInstallation {
+    const profile = project.profile
+    const allPackages = new Set<string>()
+    for (const option of this.options) {
+      for (const entry of option.ownedConfigEntries(profile)) allPackages.add(entry.name)
+    }
+    for (const name of packageNames(this.baseContribution(profile).resources)) allPackages.add(name)
+    const configEntries = project.cordisConfigEntries()
+    const ownedConfigEntries = configEntries.filter(entry => allPackages.has(entry.name))
+
+    const options = this.options
+      .filter(option => option.matchesConfigEntries(configEntries, profile))
+      .map(option => option.id)
+    if (ownedConfigEntries.length === 0 && options.length === 0) {
+      return { id: this.id, state: 'absent', options: [], diagnostics: [] }
+    }
+    let selection: FeatureSelection
+    try {
+      selection = this.normalizeSelection({ id: this.id, options }, profile)
+    } catch (error) {
+      return { id: this.id, state: 'inconsistent', options, diagnostics: [String(error)] }
+    }
+    selection = this.readSelection(project, selection)
+    const expected = this.contribution(selection, profile)
+    const expectedEntries = expected.resources
+      .filter((resource): resource is CordisConfigEntryResource => resource.kind === 'cordis-config-entry')
+    const diagnostics: string[] = []
+    for (const resource of expectedEntries) {
+      const actual = ownedConfigEntries.find(entry => entry.id === resource.entry.id && entry.name === resource.entry.name)
+      if (!actual) diagnostics.push(`missing Cordis config entry ${resource.entry.id} (${resource.entry.name})`)
+      else diagnostics.push(...configDiagnostics(resource, actual))
+    }
+    for (const actual of ownedConfigEntries) {
+      if (!expectedEntries.some(resource => resource.entry.id === actual.id && resource.entry.name === actual.name)) {
+        diagnostics.push(`unexpected owned Cordis config entry ${actual.id} (${actual.name})`)
+      }
+    }
+    const manifest = project.packageManifest()
+    for (const resource of expected.resources) {
+      switch (resource.kind) {
+        case 'npm-dependency':
+          if (!manifest[resource.section]?.[resource.name]) {
+            diagnostics.push(`missing package.json ${resource.section} entry ${resource.name}`)
+          }
+          break
+        case 'owned-file':
+          if (!project.hasDocument(resource.document.relativePath)) diagnostics.push(`missing owned file ${resource.document.relativePath}`)
+          break
+        case 'environment':
+          try {
+            if (project.readEnvironment('.env.example', resource.name) === undefined) {
+              diagnostics.push(`missing .env.example variable ${resource.name}`)
+            }
+          } catch (error) {
+            diagnostics.push(String(error))
+          }
+          break
+        case 'cordis-config-entry': break
+      }
+    }
+    const disabled = ownedConfigEntries.map(entry => entry.disabled === true)
+    if (disabled.some(Boolean) && disabled.some(value => !value)) {
+      diagnostics.push('owned Cordis config entries have mixed enabled states')
+    }
+    if (diagnostics.length > 0) {
+      return { id: this.id, state: 'inconsistent', options, diagnostics }
+    }
+    return {
+      id: this.id,
+      state: ownedConfigEntries.length > 0 && disabled.every(Boolean) ? 'disabled' : 'enabled',
+      options,
+      selection,
+      diagnostics: [],
+    }
+  }
+}
+
+/** Fixed one-option feature base. */
+export abstract class FixedFeature extends Feature {
+  override readonly mode = 'single'
+
+  /** Select the sole option. */
+  override defaultOptions(): readonly string[] {
+    const option = this.options[0]
+    if (!option) throw new Error(`simple feature ${this.id} has no option`)
+    return [option.id]
+  }
+}
+
+/** Mutually exclusive option feature base. */
+export abstract class ExclusiveOptionFeature extends Feature {
+  override readonly mode = 'exclusive'
+}
+
+/** Additive multi-option feature base. */
+export abstract class MultiOptionFeature extends Feature {
+  override readonly mode = 'multiple'
+}
diff --git a/packages/sdk/helper/src/features/registry.ts b/packages/sdk/helper/src/features/registry.ts
new file mode 100644
index 0000000000..5135f2e40c
--- /dev/null
+++ b/packages/sdk/helper/src/features/registry.ts
@@ -0,0 +1,87 @@
+/**
+ * Builtin feature registry and definition-time conflict checks.
+ *
+ * @module @deepseek-ai/dsh-helper/features/registry
+ */
+
+import type { FeatureId, ResourceKey } from '../ids.ts'
+import type { ProjectProfile } from '../project/types.ts'
+import type { Feature, FeatureProjectView } from './feature.ts'
+import type { CordisConfigEntryResource } from './resources.ts'
+
+/** Compile-time builtin feature collection. */
+export class FeatureRegistry {
+  private readonly features = new Map<FeatureId, Feature>()
+
+  /** Register and validate a complete builtin set. */
+  constructor(features: readonly Feature[], validationProfile: ProjectProfile) {
+    const owners = new Map<ResourceKey, FeatureId>()
+    for (const feature of features) {
+      if (this.features.has(feature.id)) throw new Error(`duplicate feature id: ${feature.id}`)
+      this.features.set(feature.id, feature)
+      const validationInterface = feature.supportedInterfaces[0]
+      if (!validationInterface) throw new Error(`feature ${feature.id} supports no run interface`)
+      const selections = feature.options.map(option => ({ id: feature.id, options: [option.id] }))
+      for (const selection of selections) {
+        const contribution = feature.contribution(selection, {
+          ...validationProfile,
+          runInterface: validationInterface,
+        })
+        for (const resource of contribution.resources) {
+          const owner = owners.get(resource.key)
+          if (owner && owner !== feature.id) {
+            throw new Error(`resource ${resource.key} is declared by both ${owner} and ${feature.id}`)
+          }
+          owners.set(resource.key, feature.id)
+        }
+      }
+    }
+  }
+
+  /**
+   * Return all builtins in display order.
+   * @returns all registered features.
+   */
+  all(): readonly Feature[] {
+    return [...this.features.values()]
+  }
+
+  /**
+   * Resolve one builtin or fail loud.
+   * @param id - stable feature identity.
+   * @returns registered feature.
+   */
+  get(id: FeatureId): Feature {
+    const feature = this.features.get(id)
+    if (!feature) throw new Error(`unknown feature: ${id}`)
+    return feature
+  }
+
+  /**
+   * Inspect every applicable builtin in display order.
+   * @param project - project view to inspect.
+   * @returns installation snapshots for applicable features.
+   */
+  inspect(project: FeatureProjectView): ReturnType<Feature['inspect']>[] {
+    return this.all()
+      .filter(feature => feature.isApplicable(project.profile))
+      .map(feature => feature.inspect(project))
+  }
+
+  /**
+   * Resolve the builtin that owns a Cordis package name for this profile.
+   * @param name - Loader package name.
+   * @param profile - project context controlling applicability.
+   * @returns owning feature, if the package is builtin-owned.
+   */
+  ownerOfPackage(name: string, profile: ProjectProfile): Feature | undefined {
+    return this.all().find((feature) => {
+      if (!feature.isApplicable(profile)) return false
+      const selections = feature.options.map(option => ({ id: feature.id, options: [option.id] }))
+      return selections.some(selection => feature.contribution(selection, profile).resources.some(
+        (resource): resource is CordisConfigEntryResource => resource.kind === 'cordis-config-entry'
+          && resource.entry.name === name,
+      ))
+    })
+  }
+}
diff --git a/packages/sdk/helper/src/features/resources.ts b/packages/sdk/helper/src/features/resources.ts
new file mode 100644
index 0000000000..dc6ecd2452
--- /dev/null
+++ b/packages/sdk/helper/src/features/resources.ts
@@ -0,0 +1,86 @@
+/**
+ * Resource vocabulary contributed by builtin SDK features.
+ *
+ * @module @deepseek-ai/dsh-helper/features/resources
+ */
+
+import type { CordisConfigEntry } from '../documents/cordis-yaml-file.ts'
+import type { ProjectFile } from '../documents/project-file.ts'
+import type { ResourceKey } from '../ids.ts'
+
+/** Runtime or development NPM dependency contribution. */
+export interface NpmDependencyResource {
+  kind: 'npm-dependency'
+  key: ResourceKey
+  name: string
+  section: 'dependencies' | 'devDependencies'
+}
+
+/** Owned Cordis config entry plus the config keys safe to update in place. */
+export interface CordisConfigEntryResource {
+  kind: 'cordis-config-entry'
+  key: ResourceKey
+  entry: CordisConfigEntry
+  ownedConfigKeys: readonly string[]
+  validateConfig?: (config: Readonly<Record<string, unknown>>) => readonly string[]
+}
+
+/** Environment variable reference and dotenv material. */
+export interface EnvironmentResource {
+  kind: 'environment'
+  key: ResourceKey
+  name: string
+  value?: string
+  exampleValue: string
+  comment?: string
+}
+
+/** Feature-exclusive complete file. */
+export interface OwnedFileResource {
+  kind: 'owned-file'
+  key: ResourceKey
+  document: ProjectFile
+  removeOnlyWhenUnchanged: boolean
+}
+
+/** Any resource a feature can add to a project. */
+export type ProjectResource =
+  | NpmDependencyResource
+  | CordisConfigEntryResource
+  | EnvironmentResource
+  | OwnedFileResource
+
+/** Complete resource contribution for one selected feature state. */
+export class ProjectContribution {
+  readonly resources: readonly ProjectResource[]
+
+  /** Validate and retain one feature-owned resource set. */
+  constructor(resources: readonly ProjectResource[]) {
+    const seen = new Set<ResourceKey>()
+    for (const resource of resources) {
+      if (seen.has(resource.key)) throw new Error(`duplicate contribution resource key: ${resource.key}`)
+      seen.add(resource.key)
+    }
+    this.resources = resources
+  }
+
+  /** Merge base and option contributions by stable key. */
+  static merge(...contributions: readonly ProjectContribution[]): ProjectContribution {
+    const resources = new Map<ResourceKey, ProjectResource>()
+    for (const contribution of contributions) {
+      for (const resource of contribution.resources) {
+        const previous = resources.get(resource.key)
+        if (previous && JSON.stringify(previous) !== JSON.stringify(resource)) {
+          throw new Error(`resource ${resource.key} has conflicting definitions inside one feature`)
+        }
+        resources.set(resource.key, resource)
+      }
+    }
+    return new ProjectContribution([...resources.values()])
+  }
+
+  /** Index resources by stable key. */
+  byKey(): ReadonlyMap<ResourceKey, ProjectResource> {
+    return new Map(this.resources.map(resource => [resource.key, resource]))
+  }
+}
diff --git a/packages/sdk/helper/src/ids.ts b/packages/sdk/helper/src/ids.ts
new file mode 100644
index 0000000000..4d671753ca
--- /dev/null
+++ b/packages/sdk/helper/src/ids.ts
@@ -0,0 +1,31 @@
+/**
+ * Branded identities owned by the SDK project domain.
+ *
+ * @module @deepseek-ai/dsh-helper/ids
+ */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Stable identity of a builtin SDK feature. */
+export type FeatureId = Branded<'FeatureId'>
+
+/**
+ * Construct a feature identity from its registry key.
+ * @param value - lowercase kebab-case registry key.
+ * @returns branded feature identity.
+ */
+export function featureId(value: string): FeatureId {
+  if (!/^[a-z][a-z0-9-]*$/.test(value)) {
+    throw new Error(`invalid feature id: ${JSON.stringify(value)}`)
+  }
+  return value as FeatureId
+}
+
+/** Stable identity of a resource contributed to an SDK project. */
+export type ResourceKey = Branded<'ResourceKey'>
+
+/** Construct a resource key from its owner-qualified value. */
+export function resourceKey(value: string): ResourceKey {
+  if (value.length === 0) throw new Error('resource key must not be empty')
+  return value as ResourceKey
+}
diff --git a/packages/sdk/helper/src/index.ts b/packages/sdk/helper/src/index.ts
new file mode 100644
index 0000000000..98c55c3f8b
--- /dev/null
+++ b/packages/sdk/helper/src/index.ts
@@ -0,0 +1,45 @@
+/**
+ * Shared domain and infrastructure for DeepSeek Harness SDK project tooling.
+ *
+ * @module @deepseek-ai/dsh-helper
+ */
+
+export { featureId } from './ids.ts'
+export { TextTemplate } from './templates/text-template.ts'
+export type {
+  FeatureSelection,
+  ProjectCreationRequest,
+  ProjectProfile,
+  RunInterface,
+} from './project/types.ts'
+export type { ChangeSet, ProjectCommitResult } from './project/change-set.ts'
+export { SdkProject } from './project/sdk-project.ts'
+export {
+  NodeCommandRunner,
+  NpmPackageManager,
+  createPackageManager,
+  inferPackageManagerName,
+  probePackageManagerVersion,
+} from './package-managers/package-manager.ts'
+export type {
+  CommandRunner,
+  PackageManager,
+  PackageManagerName,
+  PackageManagerVersionProbe,
+} from './package-managers/package-manager.ts'
+export { LocalPluginBlueprint } from './plugins/local-plugin-blueprint.ts'
+export type { LocalPluginKind } from './plugins/local-plugin-blueprint.ts'
+export type { Feature, FeatureInstallation } from './features/feature.ts'
+export type { FeatureRegistry } from './features/registry.ts'
+export { FeatureConfigurator } from './features/feature-configurator.ts'
+export { createBuiltinRegistry } from './features/builtin/index.ts'
+export { PromptCancelledError, requireAnswer } from './questions/prompt-port.ts'
+export type { NestedMultiSelectValue, PromptPort } from './questions/prompt-port.ts'
+export {
+  ConfirmQuestion,
+  SecretQuestion,
+  SelectQuestion,
+  TextQuestion,
+} from './questions/question.ts'
+export type { Question } from './questions/question.ts'
+export { ClackPromptPort } from './questions/clack-prompt-port.ts'
diff --git a/packages/sdk/helper/src/package-managers/link-workspace.ts b/packages/sdk/helper/src/package-managers/link-workspace.ts
new file mode 100644
index 0000000000..1a6b518fa9
--- /dev/null
+++ b/packages/sdk/helper/src/package-managers/link-workspace.ts
@@ -0,0 +1,137 @@
+/**
+ * Repository package discovery and NPM dependency-closure rewriting for live links.
+ *
+ * @module @deepseek-ai/dsh-helper/package-managers/link-workspace
+ */
+
+import { readFile, readdir } from 'node:fs/promises'
+import { existsSync, realpathSync } from 'node:fs'
+import { basename, dirname, join, relative, resolve, sep } from 'node:path'
+import type { PackageJsonFile, PackageManifest } from '../documents/package-json-file.ts'
+import { PnpmWorkspaceFile } from '../documents/pnpm-workspace-file.ts'
+import type { ProjectFile } from '../documents/project-file.ts'
+import type { PackageManager } from './package-manager.ts'
+
+interface WorkspacePackage {
+  directory: string
+  manifest: PackageManifest
+}
+
+function posixPath(path: string): string {
+  return path.split(sep).join('/')
+}
+
+function canonicalPath(path: string): string {
+  let existing = resolve(path)
+  const suffix: string[] = []
+  while (!existsSync(existing)) {
+    const parent = dirname(existing)
+    /* v8 ignore next -- every absolute path reaches the existing filesystem root */
+    if (parent === existing) throw new Error(`cannot resolve an existing ancestor for ${path}`)
+    suffix.unshift(basename(existing))
+    existing = parent
+  }
+  return resolve(realpathSync(existing), ...suffix)
+}
+
+async function packageDirectories(root: string): Promise<string[]> {
+  const result: string[] = []
+  for (const vendor of await readdir(join(root, 'vendor'), { withFileTypes: true })) {
+    if (vendor.isDirectory()) result.push(join(root, 'vendor', vendor.name))
+  }
+  for (const group of await readdir(join(root, 'packages'), { withFileTypes: true })) {
+    if (!group.isDirectory()) continue
+    for (const pkg of await readdir(join(root, 'packages', group.name), { withFileTypes: true })) {
+      if (pkg.isDirectory()) result.push(join(root, 'packages', group.name, pkg.name))
+    }
+  }
+  return result
+}
+
+/** Index of repository packages used by `--link-workspace`. */
+export class LinkWorkspace {
+  readonly root: string
+  private readonly packages: Map<string, WorkspacePackage>
+
+  private constructor(root: string, packages: Map<string, WorkspacePackage>) {
+    this.root = root
+    this.packages = packages
+  }
+
+  /** Scan vendor and package workspaces from a repository root. */
+  static async open(root: string): Promise<LinkWorkspace> {
+    const absolute = resolve(root)
+    const packages = new Map<string, WorkspacePackage>()
+    for (const directory of await packageDirectories(absolute)) {
+      let manifest: PackageManifest
+      try {
+        manifest = JSON.parse(await readFile(join(directory, 'package.json'), 'utf8')) as PackageManifest
+      } catch (error) {
+        throw new Error(`cannot read linked package at ${directory}: ${String(error)}`)
+      }
+      if (!manifest.name || typeof manifest.name !== 'string') continue
+      if (packages.has(manifest.name)) throw new Error(`duplicate linked package name: ${manifest.name}`)
+      packages.set(manifest.name, { directory, manifest })
+    }
+    if (!packages.has('cordis') || !packages.has('@deepseek-ai/dsh-scripts')) {
+      throw new Error(`not a DeepSeek Harness repository root: ${absolute}`)
+    }
+    return new LinkWorkspace(absolute, packages)
+  }
+
+  /** Expand direct NPM dependencies through all repository-local NPM dependency edges. */
+  closure(names: Iterable<string>): string[] {
+    const pending = [...names]
+    const result = new Set<string>()
+    while (pending.length > 0) {
+      const name = pending.pop()
+      if (!name || result.has(name)) continue
+      const pkg = this.packages.get(name)
+      /* v8 ignore next -- closure() only returns names present in this package map */
+      if (!pkg) continue
+      result.add(name)
+      const edges = {
+        ...pkg.manifest.dependencies,
+        ...pkg.manifest.peerDependencies as Record<string, string> | undefined,
+      }
+      for (const dependencyName of Object.keys(edges)) {
+        if (this.packages.has(dependencyName) && !result.has(dependencyName)) pending.push(dependencyName)
+      }
+    }
+    return [...result].sort()
+  }
+
+  /** Rewrite the full local closure to manager-specific live-link specs. */
+  apply(
+    projectRoot: string,
+    manifest: PackageJsonFile,
+    manager: PackageManager,
+    documents: readonly ProjectFile[],
+  ): void {
+    const canonicalProjectRoot = canonicalPath(projectRoot)
+    const names = this.closure(manifest.npmDependencyNames())
+    for (const name of names) {
+      const pkg = this.packages.get(name)
+      /* v8 ignore next -- closure() only returns names present in this package map */
+      if (!pkg) continue
+      const relativePath = posixPath(relative(canonicalProjectRoot, realpathSync(pkg.directory)))
+      const spec = manager.linkSpec(relativePath)
+      const current = manifest.npmDependency(name)
+      manifest.setNpmDependency(current?.section ?? 'dependencies', name, spec)
+      if (manager.name === 'yarn') manifest.setResolution(name, spec)
+    }
+    if (manager.name === 'pnpm') {
+      const workspace = documents.find((item): item is PnpmWorkspaceFile => item instanceof PnpmWorkspaceFile)
+      if (!workspace) throw new Error('pnpm link mode requires pnpm-workspace.yaml')
+      workspace.disableAutoInstallPeers()
+    }
+  }
+
+  /** Resolve a package directory for diagnostics and tests. */
+  packageDirectory(name: string): string | undefined {
+    const directory = this.packages.get(name)?.directory
+    return directory
+      ? resolve(dirname(directory), directory.split(sep).at(-1) as string)
+      : undefined
+  }
+}
diff --git a/packages/sdk/helper/src/package-managers/package-manager.ts b/packages/sdk/helper/src/package-managers/package-manager.ts
new file mode 100644
index 0000000000..a6f2fdd103
--- /dev/null
+++ b/packages/sdk/helper/src/package-managers/package-manager.ts
@@ -0,0 +1,280 @@
+/**
+ * Package-manager strategies for SDK project workspaces and child commands.
+ *
+ * @module @deepseek-ai/dsh-helper/package-managers/package-manager
+ */
+
+import { execFile, spawn } from 'node:child_process'
+import { promisify } from 'node:util'
+import type { PackageJsonFile } from '../documents/package-json-file.ts'
+import { PnpmWorkspaceFile } from '../documents/pnpm-workspace-file.ts'
+import type { ProjectFile } from '../documents/project-file.ts'
+
+/** Supported generated-project package managers. */
+export type PackageManagerName = 'npm' | 'pnpm' | 'yarn'
+
+/** Result from one child package-manager process. */
+export interface CommandResult {
+  exitCode: number | null
+  signal: NodeJS.Signals | null
+}
+
+/** Injectable subprocess boundary used by package-manager strategies. */
+export interface CommandRunner {
+  /** Run one executable without a shell and await process exit. */
+  run(command: string, args: readonly string[], cwd: string): Promise<CommandResult>
+}
+
+/** Injectable package-manager version probe used by project creation. */
+export type PackageManagerVersionProbe = (name: PackageManagerName, cwd: string) => Promise<string>
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * Read a manager version without forwarding ambient credentials.
+ * @param name - package-manager executable.
+ * @param cwd - working directory used for resolution.
+ * @returns trimmed version output.
+ */
+export async function probePackageManagerVersion(name: PackageManagerName, cwd: string): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync(name, ['--version'], {
+      cwd,
+      env: scrubEnvironment(),
+      encoding: 'utf8',
+    })
+    const version = stdout.trim()
+    if (!version) throw new Error('empty version output')
+    return version
+  } catch (error) {
+    throw new Error(`cannot run ${name} --version: ${String(error)}`)
+  }
+}
+
+/** Remove credential-shaped environment variables from spawned commands. */
+export function scrubEnvironment(environment: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  return Object.fromEntries(Object.entries(environment).filter(([name]) => !/(?:KEY|SECRET|TOKEN)/i.test(name)))
+}
+
+/** Node child-process command runner with inherited stdio and quiescent completion. */
+export class NodeCommandRunner implements CommandRunner {
+  /** Spawn one child and settle only after its exit. */
+  run(command: string, args: readonly string[], cwd: string): Promise<CommandResult> {
+    return new Promise((resolve, reject) => {
+      const child = spawn(command, [...args], {
+        cwd,
+        env: scrubEnvironment(),
+        stdio: 'inherit',
+        shell: false,
+      })
+      child.once('error', reject)
+      child.once('exit', (exitCode, signal) => { resolve({ exitCode, signal }) })
+    })
+  }
+}
+
+function major(version: string): number {
+  const match = /^(\d+)/.exec(version)
+  if (!match?.[1]) throw new Error(`invalid package manager version: ${JSON.stringify(version)}`)
+  return Number(match[1])
+}
+
+/** Behavior owned by one generated-project package manager. */
+export abstract class PackageManager {
+  /** Manager executable and project identity. */
+  abstract readonly name: PackageManagerName
+
+  /** Detected concrete manager version. */
+  readonly version: string
+
+  constructor(version: string) {
+    this.version = version
+  }
+
+  /** Validate the detected version against this SDK's supported floor. */
+  abstract validateVersion(): void
+
+  /**
+   * Configure root manifest fields and return manager-specific files.
+   * @param manifest - generated root manifest to update.
+   * @returns manager-specific companion documents.
+   */
+  abstract configureWorkspace(manifest: PackageJsonFile): ProjectFile[]
+
+  /**
+   * Build the NPM dependency spec for a local workspace plugin.
+   * @returns manager-specific local NPM dependency spec.
+   */
+  abstract localPluginSpec(): string
+
+  /**
+   * Resolve a repository live-link NPM dependency.
+   * @param relativePath - relative path from generated project to package.
+   * @returns manager-specific NPM dependency spec.
+   */
+  abstract linkSpec(relativePath: string): string
+
+  /**
+   * Build install command arguments.
+   * @returns arguments following the manager executable.
+   */
+  installCommand(): readonly string[] {
+    return ['install']
+  }
+
+  /**
+   * Build project-build command arguments.
+   * @returns arguments following the manager executable.
+   */
+  buildCommand(): readonly string[] {
+    return ['run', 'build']
+  }
+
+  /**
+   * Run NPM dependency installation and fail on non-zero or signalled exit.
+   * @param cwd - generated project directory.
+   * @param runner - optional subprocess boundary.
+   */
+  async install(cwd: string, runner: CommandRunner = new NodeCommandRunner()): Promise<void> {
+    await this.runChecked(runner, this.installCommand(), cwd, 'install')
+  }
+
+  /**
+   * Run the project build and fail on non-zero or signalled exit.
+   * @param cwd - generated project directory.
+   * @param runner - optional subprocess boundary.
+   */
+  async build(cwd: string, runner: CommandRunner = new NodeCommandRunner()): Promise<void> {
+    await this.runChecked(runner, this.buildCommand(), cwd, 'build')
+  }
+
+  private async runChecked(runner: CommandRunner, args: readonly string[], cwd: string, operation: string): Promise<void> {
+    const result = await runner.run(this.name, args, cwd)
+    if (result.signal !== null) {
+      throw new Error(`${this.name} ${operation} was killed by ${result.signal}`)
+    }
+    if (result.exitCode !== 0) {
+      throw new Error(`${this.name} ${operation} exited with code ${String(result.exitCode)}`)
+    }
+  }
+}
+
+/** npm workspace behavior. */
+export class NpmPackageManager extends PackageManager {
+  override readonly name = 'npm'
+
+  /** npm 10 is the supported floor at the repository's Node floor. */
+  override validateVersion(): void {
+    if (major(this.version) < 10) throw new Error(`npm >=10 is required, got ${this.version}`)
+  }
+
+  /** Configure package.json workspaces; npm needs no companion file. */
+  override configureWorkspace(manifest: PackageJsonFile): ProjectFile[] {
+    manifest.addWorkspace('plugins/*')
+    manifest.setPackageManager(undefined)
+    return []
+  }
+
+  /** npm resolves workspace packages through its ordinary wildcard. */
+  override localPluginSpec(): string {
+    return '*'
+  }
+
+  /** npm live links use file NPM dependencies. */
+  override linkSpec(relativePath: string): string {
+    return `file:${relativePath}`
+  }
+}
+
+/** pnpm workspace behavior. */
+export class PnpmPackageManager extends PackageManager {
+  override readonly name = 'pnpm'
+
+  /** pnpm 10 is the supported floor for strict NPM dependency-build policy. */
+  override validateVersion(): void {
+    if (major(this.version) < 10) throw new Error(`pnpm >=10 is required, got ${this.version}`)
+  }
+
+  /** Configure packageManager and a structured pnpm workspace file. */
+  override configureWorkspace(manifest: PackageJsonFile): ProjectFile[] {
+    manifest.setPackageManager(`pnpm@${this.version}`)
+    const workspace = PnpmWorkspaceFile.create()
+    workspace.addPackage('plugins/*')
+    return [workspace]
+  }
+
+  /** pnpm uses its explicit workspace protocol. */
+  override localPluginSpec(): string {
+    return 'workspace:*'
+  }
+
+  /** pnpm live links use link NPM dependencies. */
+  override linkSpec(relativePath: string): string {
+    return `link:${relativePath}`
+  }
+}
+
+/** Yarn Berry-compatible workspace behavior. */
+export class YarnPackageManager extends PackageManager {
+  override readonly name = 'yarn'
+
+  /** Yarn classic is excluded because the generated project relies on modern workspaces. */
+  override validateVersion(): void {
+    if (major(this.version) < 2) throw new Error(`Yarn >=2 is required, got ${this.version}`)
+  }
+
+  /** Configure packageManager and package.json workspaces. */
+  override configureWorkspace(manifest: PackageJsonFile): ProjectFile[] {
+    manifest.addWorkspace('plugins/*')
+    manifest.setPackageManager(`yarn@${this.version}`)
+    return []
+  }
+
+  /** Modern Yarn uses the workspace protocol. */
+  override localPluginSpec(): string {
+    return 'workspace:*'
+  }
+
+  /** Yarn live links use portal NPM dependencies to preserve package identity. */
+  override linkSpec(relativePath: string): string {
+    return `portal:${relativePath}`
+  }
+
+  /** Yarn runs scripts without the `run` token. */
+  override buildCommand(): readonly string[] {
+    return ['build']
+  }
+}
+
+/**
+ * Construct and validate one package-manager strategy.
+ * @param name - selected manager.
+ * @param version - detected concrete version.
+ * @returns validated strategy.
+ */
+export function createPackageManager(name: PackageManagerName, version: string): PackageManager {
+  let manager: PackageManager
+  switch (name) {
+    case 'npm': manager = new NpmPackageManager(version); break
+    case 'pnpm': manager = new PnpmPackageManager(version); break
+    case 'yarn': manager = new YarnPackageManager(version); break
+  }
+  manager.validateVersion()
+  return manager
+}
+
+/**
+ * Infer a package manager from an explicit choice or npm user-agent value.
+ * @param explicit - explicit CLI selection.
+ * @param userAgent - npm-compatible user-agent string.
+ * @returns selected or inferred manager name.
+ */
+export function inferPackageManagerName(
+  explicit: PackageManagerName | undefined,
+  userAgent: string | undefined = process.env.npm_config_user_agent,
+): PackageManagerName | undefined {
+  if (explicit) return explicit
+  const token = userAgent?.split(' ')[0]?.split('/')[0]
+  if (token === 'npm' || token === 'pnpm' || token === 'yarn') return token
+  return undefined
+}
diff --git a/packages/sdk/helper/src/plugins/local-plugin-blueprint.ts b/packages/sdk/helper/src/plugins/local-plugin-blueprint.ts
new file mode 100644
index 0000000000..616d0cedd8
--- /dev/null
+++ b/packages/sdk/helper/src/plugins/local-plugin-blueprint.ts
@@ -0,0 +1,123 @@
+/**
+ * Source blueprints for local Cordis plugins generated under `plugins/*`.
+ *
+ * @module @deepseek-ai/dsh-helper/plugins/local-plugin-blueprint
+ */
+
+import { TextProjectFile } from '../documents/project-file.ts'
+import type { CordisConfigEntry } from '../documents/cordis-yaml-file.ts'
+import { resolveNpmDependency } from '../project/npm-dependency-policy.ts'
+import { loadHelperTemplate } from '../templates/template-assets.ts'
+
+/** Supported generated local-plugin shapes. */
+export type LocalPluginKind = 'plugin' | 'tool'
+
+function kebab(value: string): string {
+  const result = value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+  if (!result || !/^[a-z]/.test(result)) throw new Error(`invalid local plugin name: ${JSON.stringify(value)}`)
+  return result
+}
+
+function packageName(projectName: string, pluginName: string): string {
+  if (projectName.startsWith('@')) {
+    const separator = projectName.indexOf('/')
+    if (separator > 1 && separator < projectName.length - 1) {
+      return `${projectName.slice(0, separator)}/${projectName.slice(separator + 1)}-${pluginName}`
+    }
+  }
+  return `${projectName}-${pluginName}`
+}
+
+interface LocalPluginTemplateContext {
+  pluginName: string
+  toolName: string
+  toolTitle: string
+}
+
+const PLUGIN_SOURCE = loadHelperTemplate<LocalPluginTemplateContext>('local-plugin.ts.tpl')
+const TOOL_SOURCE = loadHelperTemplate<LocalPluginTemplateContext>('local-tool.ts.tpl')
+const PLUGIN_TSDOWN = loadHelperTemplate<LocalPluginTemplateContext>('local-plugin-tsdown.config.ts.tpl')
+
+/** One local plugin's derived package, source, build, and runtime entry. */
+export class LocalPluginBlueprint {
+  /** Normalized local package and Cordis config entry name. */
+  readonly name: string
+  /** Generated plugin source shape. */
+  readonly kind: LocalPluginKind
+
+  /** Normalize and validate one local plugin request. */
+  constructor(name: string, kind: LocalPluginKind) {
+    this.name = kebab(name)
+    this.kind = kind
+  }
+
+  /** Root-relative plugin directory. */
+  get directory(): string {
+    return `plugins/${this.name}`
+  }
+
+  /**
+   * Derive an npm package name from the root project identity.
+   * @param projectName - generated root package name.
+   * @returns local plugin package name.
+   */
+  packageName(projectName: string): string {
+    return packageName(projectName, this.name)
+  }
+
+  /**
+   * Build the runtime Cordis config entry for this local package.
+   * @param projectName - generated root package name.
+   * @returns Loader entry referencing the local package.
+   */
+  cordisConfigEntry(projectName: string): CordisConfigEntry {
+    return { id: this.name, name: this.packageName(projectName) }
+  }
+
+  /**
+   * Render the complete local package files.
+   * @param projectName - generated root package name.
+   * @param releaseVersion - SDK dependency version.
+   * @returns local manifest, configs, and source documents.
+   */
+  documents(projectName: string, releaseVersion: string): TextProjectFile[] {
+    const name = this.packageName(projectName)
+    const toolName = this.name.replaceAll('-', '_')
+    const cordisSpec = resolveNpmDependency('cordis', 'devDependencies', releaseVersion).spec
+    const manifest = {
+      name,
+      version: '0.0.0',
+      private: true,
+      type: 'module',
+      main: 'lib/index.js',
+      types: 'lib/index.d.ts',
+      exports: { '.': { types: './lib/index.d.ts', default: './lib/index.js' } },
+      peerDependencies: {
+        ...this.kind === 'tool' ? { '@deepseek-ai/dsh-tools': `^${releaseVersion}` } : {},
+        cordis: cordisSpec,
+      },
+      devDependencies: {
+        cordis: cordisSpec,
+      },
+    }
+    const tsconfig = {
+      extends: '../../tsconfig.base.json',
+      compilerOptions: { rootDir: 'src', outDir: 'lib/types' },
+      include: ['src'],
+    }
+    const context: LocalPluginTemplateContext = {
+      pluginName: this.name,
+      toolName,
+      toolTitle: toolName.replaceAll('_', ' '),
+    }
+    return [
+      new TextProjectFile(`${this.directory}/package.json`, JSON.stringify(manifest, null, 2)),
+      new TextProjectFile(`${this.directory}/tsconfig.json`, JSON.stringify(tsconfig, null, 2)),
+      new TextProjectFile(`${this.directory}/tsdown.config.ts`, PLUGIN_TSDOWN.render(context)),
+      new TextProjectFile(
+        `${this.directory}/src/index.ts`,
+        (this.kind === 'tool' ? TOOL_SOURCE : PLUGIN_SOURCE).render(context),
+      ),
+    ]
+  }
+}
diff --git a/packages/sdk/helper/src/project/change-set.ts b/packages/sdk/helper/src/project/change-set.ts
new file mode 100644
index 0000000000..d6207a8df1
--- /dev/null
+++ b/packages/sdk/helper/src/project/change-set.ts
@@ -0,0 +1,26 @@
+/**
+ * Result summary for one SDK project edit session.
+ *
+ * @module @deepseek-ai/dsh-helper/project/change-set
+ */
+
+import type { FeatureId } from '../ids.ts'
+
+/** Immutable description of committed or pending project changes. */
+export interface ChangeSet {
+  addedFeatures: readonly FeatureId[]
+  enabledFeatures: readonly FeatureId[]
+  disabledFeatures: readonly FeatureId[]
+  configuredFeatures: readonly FeatureId[]
+  addedPlugins: readonly string[]
+  enabledPlugins: readonly string[]
+  disabledPlugins: readonly string[]
+  changedFiles: readonly string[]
+  npmDependenciesChanged: boolean
+}
+
+/** Result of committing one project edit session. */
+export interface ProjectCommitResult<TProject> {
+  project: TProject
+  changes: ChangeSet
+}
diff --git a/packages/sdk/helper/src/project/npm-dependency-policy.ts b/packages/sdk/helper/src/project/npm-dependency-policy.ts
new file mode 100644
index 0000000000..a8877826e2
--- /dev/null
+++ b/packages/sdk/helper/src/project/npm-dependency-policy.ts
@@ -0,0 +1,62 @@
+/**
+ * NPM dependency baseline and version policy for generated SDK projects.
+ *
+ * @module @deepseek-ai/dsh-helper/project/npm-dependency-policy
+ */
+
+import type { NpmDependencySection } from '../documents/package-json-file.ts'
+
+/** One NPM dependency spec selected by the SDK release policy. */
+export interface ResolvedNpmDependency {
+  section: NpmDependencySection
+  spec: string
+}
+
+/** NPM dependency maps rendered into a newly created root package.json. */
+export interface BaselineNpmDependencies {
+  dependencies: Readonly<Record<string, string>>
+  devDependencies: Readonly<Record<string, string>>
+}
+
+const EXTERNAL_NPM_DEPENDENCY_SPECS: Readonly<Record<string, string>> = {
+  '@cordisjs/plugin-hmr': '^1.0.15',
+  '@cordisjs/plugin-timer': '^1.1.2',
+  '@types/node': '^22.20.0',
+  cordis: '^4.0.0-rc.7',
+  tsdown: '^0.22.2',
+  tsx: '^4.22.4',
+  typescript: '^6.0.3',
+}
+
+const BASELINE_NPM_DEPENDENCY_NAMES: Readonly<Record<NpmDependencySection, readonly string[]>> = {
+  dependencies: ['@deepseek-ai/dsh-scripts', 'cordis'],
+  devDependencies: ['@types/node', 'tsdown', 'tsx', 'typescript'],
+}
+
+/** Resolve one package to its generated-project section and version spec. */
+export function resolveNpmDependency(
+  name: string,
+  requestedSection: NpmDependencySection,
+  releaseVersion: string,
+): ResolvedNpmDependency {
+  if (name.startsWith('@deepseek-ai/dsh-')) {
+    return { section: requestedSection, spec: `^${releaseVersion}` }
+  }
+  const spec = EXTERNAL_NPM_DEPENDENCY_SPECS[name]
+  if (spec) return { section: requestedSection, spec }
+  throw new Error(`no generated-project NPM dependency policy for ${name}`)
+}
+
+/** Build the root package.json NPM dependency maps from the shared version policy. */
+export function baselineNpmDependencies(releaseVersion: string): BaselineNpmDependencies {
+  return {
+    dependencies: Object.fromEntries(BASELINE_NPM_DEPENDENCY_NAMES.dependencies.map((name) => {
+      const dependency = resolveNpmDependency(name, 'dependencies', releaseVersion)
+      return [name, dependency.spec]
+    })),
+    devDependencies: Object.fromEntries(BASELINE_NPM_DEPENDENCY_NAMES.devDependencies.map((name) => {
+      const dependency = resolveNpmDependency(name, 'devDependencies', releaseVersion)
+      return [name, dependency.spec]
+    })),
+  }
+}
diff --git a/packages/sdk/helper/src/project/project-edit-session.ts b/packages/sdk/helper/src/project/project-edit-session.ts
new file mode 100644
index 0000000000..2fb3cc4c77
--- /dev/null
+++ b/packages/sdk/helper/src/project/project-edit-session.ts
@@ -0,0 +1,542 @@
+/**
+ * Isolated domain-command and commit boundary for SDK project changes.
+ *
+ * @module @deepseek-ai/dsh-helper/project/project-edit-session
+ */
+
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import type {
+  Feature,
+  FeatureInstallation,
+  FeatureProjectView,
+  FeatureRequirement,
+} from '../features/feature.ts'
+import type { FeatureRegistry } from '../features/registry.ts'
+import type { ProjectResource } from '../features/resources.ts'
+import { CordisYamlFile, type CordisConfigEntry } from '../documents/cordis-yaml-file.ts'
+import { EnvFile } from '../documents/env-file.ts'
+import { PackageJsonFile, type PackageManifest } from '../documents/package-json-file.ts'
+import { ProjectFile } from '../documents/project-file.ts'
+import { TsConfigFile } from '../documents/tsconfig-file.ts'
+import type { FeatureId, ResourceKey } from '../ids.ts'
+import { LinkWorkspace } from '../package-managers/link-workspace.ts'
+import type { LocalPluginBlueprint } from '../plugins/local-plugin-blueprint.ts'
+import type { FeatureSelection, ProjectProfile } from './types.ts'
+import { resolveNpmDependency } from './npm-dependency-policy.ts'
+import type { ChangeSet, ProjectCommitResult } from './change-set.ts'
+import type { SdkProject } from './sdk-project.ts'
+
+interface MutableFeatureState {
+  selection?: FeatureSelection
+  state: FeatureInstallation['state']
+}
+
+function sameText(left: ProjectFile, right: ProjectFile | undefined): boolean {
+  return right !== undefined && left.serialize() === right.serialize()
+}
+
+function npmDependencyShape(manifest: Readonly<PackageManifest>): string {
+  return JSON.stringify({
+    /* v8 ignore next -- generated manifests always carry the managed dependency maps */
+    dependencies: manifest.dependencies ?? {},
+    /* v8 ignore next -- generated manifests always carry the managed dependency maps */
+    devDependencies: manifest.devDependencies ?? {},
+  })
+}
+
+function asError(error: unknown): Error {
+  /* v8 ignore else -- node:fs promise APIs reject Error objects */
+  if (error instanceof Error) return error
+  /* v8 ignore next -- node:fs promise APIs reject Error objects */
+  return new Error(String(error))
+}
+
+function canUpdateResource(previous: ProjectResource, next: ProjectResource): boolean {
+  if (previous.kind !== next.kind) return false
+  switch (previous.kind) {
+    case 'npm-dependency': return previous.name === (next as typeof previous).name
+    case 'cordis-config-entry': {
+      const candidate = next as typeof previous
+      return previous.entry.name === candidate.entry.name
+    }
+    case 'environment': return previous.name === (next as typeof previous).name
+    case 'owned-file': return previous.document.relativePath === (next as typeof previous).document.relativePath
+  }
+}
+
+/** Mutable working copy that applies feature and local-plugin domain commands. */
+export class ProjectEditSession implements FeatureProjectView {
+  readonly profile: ProjectProfile
+  private readonly source: SdkProject
+  private readonly registry: FeatureRegistry
+  private readonly documents: Map<string, ProjectFile>
+  private readonly removed = new Map<string, ProjectFile>()
+  private readonly states = new Map<FeatureId, MutableFeatureState>()
+  private readonly added = new Set<FeatureId>()
+  private readonly enabled = new Set<FeatureId>()
+  private readonly disabled = new Set<FeatureId>()
+  private readonly configured = new Set<FeatureId>()
+  private readonly addedPlugins = new Set<string>()
+  private readonly enabledPlugins = new Set<string>()
+  private readonly disabledPlugins = new Set<string>()
+  private committed = false
+
+  /** Clone one project snapshot into an isolated working copy. */
+  constructor(source: SdkProject, registry: FeatureRegistry) {
+    this.source = source
+    this.registry = registry
+    this.profile = source.profile
+    this.documents = source.cloneDocuments()
+    for (const feature of registry.all()) {
+      if (!feature.isApplicable(this.profile)) continue
+      const installation = feature.inspect(this)
+      this.states.set(feature.id, {
+        state: installation.state,
+        ...installation.selection ? { selection: installation.selection } : {},
+      })
+    }
+  }
+
+  /** Root manifest value for feature inspection. */
+  packageManifest(): Readonly<PackageManifest> {
+    return this.manifest().value()
+  }
+
+  /** Cordis config entries for feature and custom-plugin inspection. */
+  cordisConfigEntries(): readonly CordisConfigEntry[] {
+    return this.cordis().entries()
+  }
+
+  /** Whether one managed document exists in the working copy. */
+  /* jscpd:ignore-start -- FeatureProjectView deliberately has symmetric snapshot/edit implementations. */
+  hasDocument(path: string): boolean {
+    return this.documents.has(path)
+  }
+
+  /** Read one unique working-copy environment variable. */
+  readEnvironment(path: '.env' | '.env.example', name: string): string | undefined {
+    const document = this.documents.get(path)
+    if (!document) return undefined
+    if (!(document instanceof EnvFile)) throw new Error(`${path} is not an environment document`)
+    return document.get(name)
+  }
+  /* jscpd:ignore-end */
+
+  /** Inspect every applicable builtin against the current working copy. */
+  inspections(): readonly FeatureInstallation[] {
+    return this.registry.inspect(this)
+  }
+
+  /** Install a builtin and recursively satisfy its declared requirements. */
+  installFeature(feature: Feature, selection: FeatureSelection): void {
+    this.assertOpen()
+    this.installFeatureRecursive(feature, selection, new Set())
+  }
+
+  /** Replace one installed builtin's feature-option and captured-input selection. */
+  configureFeature(feature: Feature, selection: FeatureSelection): void {
+    this.assertOpen()
+    const current = this.state(feature)
+    if (current.state === 'inconsistent') throw new Error(`feature ${feature.id} is inconsistent`)
+    if (current.state === 'absent' || !current.selection) {
+      this.installFeature(feature, selection)
+      return
+    }
+    const normalized = feature.normalizeSelection(selection, this.profile)
+    this.ensureRequirements(feature, normalized, new Set([feature.id]))
+    this.replaceContribution(
+      feature.contribution(current.selection, this.profile),
+      feature.contribution(normalized, this.profile),
+    )
+    current.selection = normalized
+    current.state = current.state === 'disabled' ? 'disabled' : 'enabled'
+    if (current.state === 'disabled') this.setFeatureDisabled(feature, normalized, true)
+    this.assertFeatureConsistent(feature)
+    this.configured.add(feature.id)
+  }
+
+  /** Enable all entries owned by one installed feature. */
+  enableFeature(feature: Feature): void {
+    this.assertOpen()
+    const current = this.state(feature)
+    if (current.state === 'inconsistent') throw new Error(`feature ${feature.id} is inconsistent`)
+    if (current.state === 'absent' || !current.selection) {
+      throw new Error(`feature ${feature.id} is not installed`)
+    }
+    this.setFeatureDisabled(feature, current.selection, false)
+    current.state = 'enabled'
+    this.assertFeatureConsistent(feature)
+    this.disabled.delete(feature.id)
+    this.enabled.add(feature.id)
+  }
+
+  /** Disable an optional feature without removing its configuration. */
+  disableFeature(feature: Feature): void {
+    this.assertOpen()
+    if (feature.required) throw new Error(`required feature ${feature.id} cannot be disabled`)
+    const current = this.state(feature)
+    if (current.state === 'inconsistent') throw new Error(`feature ${feature.id} is inconsistent`)
+    if (current.state === 'absent' || !current.selection) {
+      throw new Error(`feature ${feature.id} is not installed`)
+    }
+    const dependent = this.registry.all().find((candidate) => {
+      const state = this.states.get(candidate.id)
+      return state?.state === 'enabled' && state.selection
+        && candidate.requirements(state.selection).some(requirement => requirement.id === feature.id)
+    })
+    if (dependent) throw new Error(`feature ${feature.id} is required by ${dependent.id}`)
+    this.setFeatureDisabled(feature, current.selection, true)
+    current.state = 'disabled'
+    this.assertFeatureConsistent(feature)
+    this.enabled.delete(feature.id)
+    this.disabled.add(feature.id)
+  }
+
+  /** Add a generated local plugin and all four of its project registrations. */
+  addPlugin(blueprint: LocalPluginBlueprint): void {
+    this.assertOpen()
+    const manifest = this.manifest()
+    const cordis = this.cordis()
+    const tsconfig = this.documents.get('tsconfig.json')
+    if (!(tsconfig instanceof TsConfigFile)) {
+      throw new Error('adding a local plugin requires a valid tsconfig.json')
+    }
+    const packageName = blueprint.packageName(this.profile.name)
+    if (manifest.npmDependency(packageName)) throw new Error(`root NPM dependency already exists: ${packageName}`)
+    const entry = blueprint.cordisConfigEntry(this.profile.name)
+    if (cordis.entry(entry.id)) throw new Error(`Cordis config entry already exists: ${entry.id}`)
+    const documents = blueprint.documents(this.profile.name, this.profile.releaseVersion)
+    for (const document of documents) {
+      if (this.documents.has(document.relativePath)) {
+        throw new Error(`local plugin file already exists: ${document.relativePath}`)
+      }
+    }
+    for (const document of documents) this.documents.set(document.relativePath, document)
+    manifest.setNpmDependency('dependencies', packageName, this.profile.packageManager.localPluginSpec())
+    tsconfig.addReference(`./${blueprint.directory}`)
+    cordis.addEntry(entry)
+    this.addedPlugins.add(entry.id)
+  }
+
+  /** Enable or disable one custom/manual Cordis config entry by stable id. */
+  setCustomPluginDisabled(id: string, disabled: boolean): void {
+    this.assertOpen()
+    const entry = this.cordis().entry(id)
+    if (!entry) throw new Error(`Cordis config entry does not exist: ${id}`)
+    if (this.registry.ownerOfPackage(entry.name, this.profile)) {
+      throw new Error(`Cordis config entry ${id} belongs to a builtin feature`)
+    }
+    this.cordis().setDisabled(id, disabled)
+    if (disabled) {
+      this.enabledPlugins.delete(id)
+      this.disabledPlugins.add(id)
+    } else {
+      this.disabledPlugins.delete(id)
+      this.enabledPlugins.add(id)
+    }
+  }
+
+  /** Summarize all pending domain and file changes. */
+  changes(): ChangeSet {
+    const changedFiles = new Set<string>()
+    for (const [path, document] of this.documents) {
+      if (this.source.origin === 'create' || !sameText(document, this.source.document(path))) changedFiles.add(path)
+    }
+    for (const path of this.removed.keys()) changedFiles.add(path)
+    return {
+      addedFeatures: [...this.added].sort(),
+      enabledFeatures: [...this.enabled].sort(),
+      disabledFeatures: [...this.disabled].sort(),
+      configuredFeatures: [...this.configured].sort(),
+      addedPlugins: [...this.addedPlugins].sort(),
+      enabledPlugins: [...this.enabledPlugins].sort(),
+      disabledPlugins: [...this.disabledPlugins].sort(),
+      changedFiles: [...changedFiles].sort(),
+      npmDependenciesChanged: npmDependencyShape(this.manifest().value())
+        !== npmDependencyShape(this.source.packageManifest()),
+    }
+  }
+
+  /** Validate, detect external edits, write affected files, and return a fresh snapshot. */
+  async commit(): Promise<ProjectCommitResult<SdkProject>> {
+    this.assertOpen()
+    if (this.profile.linkWorkspaceRoot) {
+      const workspace = await LinkWorkspace.open(this.profile.linkWorkspaceRoot)
+      workspace.apply(
+        this.source.root,
+        this.manifest(),
+        this.profile.packageManager,
+        [...this.documents.values()],
+      )
+    }
+    this.validateFinalState()
+    const changes = this.changes()
+    await this.assertUnchanged(changes.changedFiles)
+    await mkdir(this.source.root, { recursive: true })
+    for (const path of changes.changedFiles) {
+      const document = this.documents.get(path)
+      const absolute = resolve(this.source.root, path)
+      if (!document) {
+        await unlink(absolute)
+        continue
+      }
+      await mkdir(dirname(absolute), { recursive: true })
+      await writeFile(absolute, document.serialize(), 'utf8')
+    }
+    this.committed = true
+    return { project: await this.source.reopen(), changes }
+  }
+
+  private installFeatureRecursive(
+    feature: Feature,
+    selection: FeatureSelection,
+    stack: Set<FeatureId>,
+  ): void {
+    if (stack.has(feature.id)) throw new Error(`cyclic feature requirement involving ${feature.id}`)
+    const current = this.state(feature)
+    if (current.state === 'inconsistent') throw new Error(`feature ${feature.id} is inconsistent`)
+    if (current.state !== 'absent' && current.selection) {
+      this.configureFeature(feature, selection)
+      if (current.state === 'disabled') this.enableFeature(feature)
+      return
+    }
+    const normalized = feature.normalizeSelection(selection, this.profile)
+    const nextStack = new Set(stack).add(feature.id)
+    this.ensureRequirements(feature, normalized, nextStack)
+    this.replaceContribution(undefined, feature.contribution(normalized, this.profile))
+    current.selection = normalized
+    current.state = 'enabled'
+    this.assertFeatureConsistent(feature)
+    this.added.add(feature.id)
+  }
+
+  private ensureRequirements(feature: Feature, selection: FeatureSelection, stack: Set<FeatureId>): void {
+    for (const requirement of feature.requirements(selection)) {
+      const required = this.registry.get(requirement.id)
+      const state = this.state(required)
+      if (state.state === 'inconsistent') throw new Error(`required feature ${required.id} is inconsistent`)
+      if (state.state === 'absent' || !state.selection) {
+        this.installFeatureRecursive(required, {
+          id: required.id,
+          options: requirement.options ?? required.defaultOptions(this.profile),
+        }, stack)
+      } else {
+        const next = this.selectionWithRequiredOptions(required, state.selection, requirement)
+        if (next !== state.selection) this.configureFeature(required, next)
+        if (state.state === 'disabled') this.enableFeature(required)
+      }
+    }
+  }
+
+  private selectionWithRequiredOptions(
+    feature: Feature,
+    selection: FeatureSelection,
+    requirement: FeatureRequirement,
+  ): FeatureSelection {
+    if (!requirement.options || requirement.options.every(option => selection.options.includes(option))) {
+      return selection
+    }
+    if (feature.mode !== 'multiple') {
+      throw new Error(`${feature.id} does not satisfy the option requirement from another feature`)
+    }
+    return { ...selection, options: [...new Set([...selection.options, ...requirement.options])] }
+  }
+
+  private replaceContribution(
+    previous: ReturnType<Feature['contribution']> | undefined,
+    next: ReturnType<Feature['contribution']>,
+  ): void {
+    const previousByKey = previous?.byKey() ?? new Map<ResourceKey, ProjectResource>()
+    const nextByKey = next.byKey()
+    for (const [key, resource] of previousByKey) {
+      const replacement = nextByKey.get(key)
+      if (!replacement || !canUpdateResource(resource, replacement)) this.removeResource(resource)
+    }
+    for (const [key, resource] of nextByKey) {
+      const previousResource = previousByKey.get(key)
+      this.applyResource(
+        resource,
+        previousResource && canUpdateResource(previousResource, resource) ? previousResource : undefined,
+      )
+    }
+  }
+
+  private applyResource(resource: ProjectResource, previous: ProjectResource | undefined): void {
+    switch (resource.kind) {
+      case 'npm-dependency': {
+        const dependency = resolveNpmDependency(resource.name, resource.section, this.profile.releaseVersion)
+        this.manifest().setNpmDependency(dependency.section, resource.name, dependency.spec)
+        return
+      }
+      case 'cordis-config-entry': {
+        const current = this.cordis().entry(resource.entry.id)
+        if (!current) this.cordis().addEntry(resource.entry)
+        else {
+          if (current.name !== resource.entry.name) {
+            throw new Error(`Cordis config entry ${resource.entry.id} is owned by ${current.name}, not ${resource.entry.name}`)
+          }
+          this.cordis().updateOwnedConfig(
+            resource.entry.id,
+            resource.ownedConfigKeys,
+            resource.entry.config ?? {},
+          )
+          this.cordis().setDisabled(resource.entry.id, false)
+        }
+        return
+      }
+      case 'environment': {
+        this.environment('.env.example').set(resource.name, resource.exampleValue)
+        /* v8 ignore else -- an omitted secret intentionally materializes only its example placeholder */
+        if (resource.value !== undefined) {
+          const environment = this.environment('.env')
+          environment.append(
+            resource.name,
+            resource.value,
+            resource.value === '' ? resource.comment : undefined,
+          )
+        }
+        return
+      }
+      case 'owned-file': {
+        const existing = this.documents.get(resource.document.relativePath)
+        if (!existing) {
+          this.documents.set(resource.document.relativePath, resource.document.clone())
+          this.removed.delete(resource.document.relativePath)
+          return
+        }
+        if (!previous || previous.kind !== 'owned-file') {
+          throw new Error(`feature-owned file already exists: ${resource.document.relativePath}`)
+        }
+        if (previous.document.serialize() === resource.document.serialize()) return
+        if (existing.serialize() !== previous.document.serialize()) {
+          throw new Error(`feature-owned file was modified: ${resource.document.relativePath}`)
+        }
+        throw new Error(`updating feature-owned files is not supported: ${resource.document.relativePath}`)
+      }
+    }
+  }
+
+  private removeResource(resource: ProjectResource): void {
+    switch (resource.kind) {
+      case 'npm-dependency':
+        this.manifest().removeNpmDependency(resource.section, resource.name)
+        return
+      case 'cordis-config-entry': {
+        const entry = this.cordis().entry(resource.entry.id)
+        if (!entry || entry.name !== resource.entry.name) {
+          throw new Error(`cannot confirm old Cordis resource ${resource.entry.id}`)
+        }
+        this.cordis().removeEntry(resource.entry.id)
+        return
+      }
+      case 'environment':
+        this.environment('.env.example').remove(resource.name)
+        return
+      case 'owned-file': {
+        const document = this.documents.get(resource.document.relativePath)
+        if (!document) throw new Error(`owned file is missing: ${resource.document.relativePath}`)
+        if (resource.removeOnlyWhenUnchanged && document.serialize() !== resource.document.serialize()) {
+          throw new Error(`owned file was modified: ${resource.document.relativePath}`)
+        }
+        this.documents.delete(resource.document.relativePath)
+        if (this.source.document(resource.document.relativePath)) {
+          this.removed.set(resource.document.relativePath, document)
+        }
+      }
+    }
+  }
+
+  private setFeatureDisabled(feature: Feature, selection: FeatureSelection, disabled: boolean): void {
+    for (const resource of feature.contribution(selection, this.profile).resources) {
+      if (resource.kind === 'cordis-config-entry') this.cordis().setDisabled(resource.entry.id, disabled)
+    }
+  }
+
+  private validateFinalState(): void {
+    for (const document of this.documents.values()) document.validate()
+    for (const feature of this.registry.all()) {
+      if (!feature.isApplicable(this.profile)) continue
+      const installation = feature.inspect(this)
+      /* v8 ignore next 3 -- public domain commands assert feature consistency before final validation */
+      if (installation.state === 'inconsistent') {
+        throw new Error(`feature ${feature.id} is inconsistent: ${installation.diagnostics.join('; ')}`)
+      }
+      /* v8 ignore next 3 -- required features are installed by creation and cannot be disabled by public commands */
+      if (feature.required && installation.state !== 'enabled') {
+        throw new Error(`required feature ${feature.id} must be installed and enabled`)
+      }
+      if (installation.state !== 'enabled' || !installation.selection) continue
+      for (const requirement of feature.requirements(installation.selection)) {
+        const required = this.registry.get(requirement.id).inspect(this)
+        /* v8 ignore next 3 -- ensureRequirements establishes enabled requirements before contributions change */
+        if (required.state !== 'enabled') {
+          throw new Error(`feature ${feature.id} requires enabled ${requirement.id}`)
+        }
+        for (const option of requirement.options ?? []) {
+          /* v8 ignore next 3 -- selectionWithRequiredOptions establishes required options before commit */
+          if (!required.options.includes(option)) {
+            throw new Error(`feature ${feature.id} requires ${requirement.id} option ${option}`)
+          }
+        }
+      }
+    }
+  }
+
+  private assertFeatureConsistent(feature: Feature): void {
+    const installation = feature.inspect(this)
+    /* v8 ignore next 3 -- resource application either succeeds completely or throws at the owning operation */
+    if (installation.state === 'inconsistent') {
+      throw new Error(`feature ${feature.id} is inconsistent: ${installation.diagnostics.join('; ')}`)
+    }
+  }
+
+  private async assertUnchanged(paths: readonly string[]): Promise<void> {
+    for (const path of paths) {
+      const source = this.source.document(path)
+      const absolute = resolve(this.source.root, path)
+      try {
+        const current = await readFile(absolute, 'utf8')
+        if (source?.originalText === undefined || current !== source.originalText) {
+          throw new Error(`project file changed outside this edit session: ${path}`)
+        }
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code
+        if (code === 'ENOENT' && source?.originalText === undefined) continue
+        if (error instanceof Error && error.message.startsWith('project file changed outside')) throw error
+        throw new Error(`cannot verify project file ${path}: ${asError(error).message}`)
+      }
+    }
+  }
+
+  private state(feature: Feature): MutableFeatureState {
+    const state = this.states.get(feature.id)
+    if (!state) throw new Error(`feature ${feature.id} is not applicable to this project`)
+    return state
+  }
+
+  private manifest(): PackageJsonFile {
+    const document = this.documents.get('package.json')
+    if (!(document instanceof PackageJsonFile)) throw new Error('project package.json is missing')
+    return document
+  }
+
+  private cordis(): CordisYamlFile {
+    const document = this.documents.get('cordis.yml')
+    if (!(document instanceof CordisYamlFile)) throw new Error('project cordis.yml is missing')
+    return document
+  }
+
+  private environment(path: '.env' | '.env.example'): EnvFile {
+    const existing = this.documents.get(path)
+    if (existing instanceof EnvFile) return existing
+    if (existing) throw new Error(`${path} is not an environment document`)
+    const document = EnvFile.create(path)
+    this.documents.set(path, document)
+    return document
+  }
+
+  private assertOpen(): void {
+    if (this.committed) throw new Error('project edit session has already committed')
+  }
+}
diff --git a/packages/sdk/helper/src/project/sdk-project.ts b/packages/sdk/helper/src/project/sdk-project.ts
new file mode 100644
index 0000000000..21d5510117
--- /dev/null
+++ b/packages/sdk/helper/src/project/sdk-project.ts
@@ -0,0 +1,319 @@
+/**
+ * Read-only aggregate for one generated or existing SDK project.
+ *
+ * @module @deepseek-ai/dsh-helper/project/sdk-project
+ */
+
+import { access, readFile } from 'node:fs/promises'
+import { basename, resolve } from 'node:path'
+import { CordisYamlFile, type CordisConfigEntry } from '../documents/cordis-yaml-file.ts'
+import { EnvFile } from '../documents/env-file.ts'
+import { PackageJsonFile, type PackageManifest } from '../documents/package-json-file.ts'
+import { PnpmWorkspaceFile } from '../documents/pnpm-workspace-file.ts'
+import { ProjectFile, TextProjectFile } from '../documents/project-file.ts'
+import { TsConfigFile } from '../documents/tsconfig-file.ts'
+import {
+  createPackageManager,
+  type PackageManager,
+  type PackageManagerName,
+} from '../package-managers/package-manager.ts'
+import {
+  createPackageJsonDoc,
+  createProjectArtifacts,
+  type ProjectTemplateContext,
+} from '../templates/project-template.ts'
+import type { ProjectCreationRequest, ProjectProfile, RunInterface } from './types.ts'
+import type { FeatureRegistry } from '../features/registry.ts'
+import { ProjectEditSession } from './project-edit-session.ts'
+
+/** Whether a project snapshot describes uncommitted creation or files on disk. */
+export type ProjectOrigin = 'create' | 'disk'
+
+const OPTIONAL_DOCUMENTS = [
+  '.env',
+  '.env.example',
+  'tsconfig.json',
+  'pnpm-workspace.yaml',
+  'hooks.json',
+  'codex-hooks.json',
+] as const
+
+function runInterface(entries: readonly CordisConfigEntry[]): RunInterface {
+  if (entries.some(entry => entry.name === '@deepseek-ai/dsh-acp')) return 'acp'
+  if (entries.some(entry => entry.name === '@deepseek-ai/dsh-stdio')) return 'stdio'
+  return 'embed'
+}
+
+function runtimeModel(entries: readonly CordisConfigEntry[]): string {
+  const acp = entries.find(entry => entry.name === '@deepseek-ai/dsh-acp')
+  if (typeof acp?.config?.model === 'string' && acp.config.model.length > 0) return acp.config.model
+  const provider = entries.find(entry => entry.name === '@deepseek-ai/dsh-llm-deepseek'
+    || entry.name === '@deepseek-ai/dsh-llm-pi-ai')
+  const models = provider?.config?.models
+  if (Array.isArray(models) && typeof models[0] === 'string') return models[0]
+  return 'deepseek-v4-flash'
+}
+
+function releaseVersion(manifest: Readonly<PackageManifest>): string {
+  const spec = manifest.dependencies?.['@deepseek-ai/dsh-scripts']
+  const match = spec && /(?:^|[^0-9])(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/.exec(spec)
+  return match?.[1] ?? '0.0.1'
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await access(path)
+    return true
+  } catch (error) {
+    /* v8 ignore else -- the other arm requires a filesystem permission/IO fault from access */
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+    /* v8 ignore next -- paired with the ignored defensive access-error arm above */
+    throw error
+  }
+}
+
+async function detectPackageManager(root: string, manifest: Readonly<PackageManifest>): Promise<PackageManager> {
+  let name: PackageManagerName = 'npm'
+  let version = '10.0.0'
+  const field = manifest.packageManager
+  if (field) {
+    const match = /^(npm|pnpm|yarn)@(.+)$/.exec(field)
+    if (!match?.[1] || !match[2]) throw new Error(`invalid packageManager field: ${field}`)
+    name = match[1] as PackageManagerName
+    version = match[2]
+  } else if (await pathExists(resolve(root, 'pnpm-lock.yaml'))) {
+    name = 'pnpm'
+    version = '10.0.0'
+  } else if (await pathExists(resolve(root, 'yarn.lock'))) {
+    name = 'yarn'
+    version = '2.0.0'
+  }
+  return createPackageManager(name, version)
+}
+
+function linkedRepositoryRoot(root: string, manifest: Readonly<PackageManifest>): string | undefined {
+  const spec = manifest.dependencies?.['@deepseek-ai/dsh-scripts']
+  const match = /^(?:file|link|portal):(.+)\/packages\/sdk\/scripts\/?$/.exec(spec ?? '')
+  return match?.[1] ? resolve(root, match[1]) : undefined
+}
+
+function parseOptionalDocument(path: string, text: string): ProjectFile {
+  try {
+    switch (path) {
+      case '.env': return EnvFile.parse('.env', text)
+      case '.env.example': return EnvFile.parse('.env.example', text)
+      case 'tsconfig.json': return TsConfigFile.parse(text)
+      case 'pnpm-workspace.yaml': return PnpmWorkspaceFile.parse(text)
+      default: return new TextProjectFile(path, text, text)
+    }
+  } catch {
+    // Optional malformed resources do not invalidate the project aggregate;
+    // an operation that needs their structure checks the concrete document type.
+    return new TextProjectFile(path, text, text)
+  }
+}
+
+function templateContext(profile: ProjectProfile): ProjectTemplateContext {
+  return {
+    name: profile.name,
+    description: profile.description,
+    releaseVersion: profile.releaseVersion,
+    model: profile.runtime.model,
+    modelLiteral: JSON.stringify(profile.runtime.model),
+    isAcp: profile.runInterface === 'acp',
+    isStdio: profile.runInterface === 'stdio',
+    isEmbed: profile.runInterface === 'embed',
+    packageManager: profile.packageManager.name,
+    installArgs: profile.packageManager.installCommand().join(' '),
+    buildArgs: profile.packageManager.buildCommand().join(' '),
+  }
+}
+
+/** A project snapshot whose documents can only be changed through {@link ProjectEditSession}. */
+export class SdkProject {
+  /** Absolute project directory. */
+  readonly root: string
+  /** Whether this snapshot is an uncommitted blueprint or disk state. */
+  readonly origin: ProjectOrigin
+  /** Project identity, runtime, interface, and package-manager context. */
+  readonly profile: ProjectProfile
+  private readonly documents: ReadonlyMap<string, ProjectFile>
+
+  private constructor(
+    root: string,
+    origin: ProjectOrigin,
+    profile: ProjectProfile,
+    documents: ReadonlyMap<string, ProjectFile>,
+  ) {
+    this.root = resolve(root)
+    this.origin = origin
+    this.profile = profile
+    this.documents = documents
+  }
+
+  /**
+   * Build an in-memory project blueprint without touching the target directory.
+   * @param root - target project directory.
+   * @param request - complete creation request.
+   * @returns uncommitted project snapshot.
+   */
+  static create(root: string, request: ProjectCreationRequest): SdkProject {
+    const app = request.features.find(selection => selection.id === 'app')
+    const selectedInterface = app?.options[0]
+    if (selectedInterface !== 'acp' && selectedInterface !== 'stdio' && selectedInterface !== 'embed') {
+      throw new Error('project creation requires one app feature option')
+    }
+    const profile: ProjectProfile = {
+      name: request.name,
+      description: request.description,
+      runtime: request.runtime,
+      runInterface: selectedInterface,
+      packageManager: request.packageManager,
+      releaseVersion: request.releaseVersion,
+      ...request.linkWorkspaceRoot ? { linkWorkspaceRoot: resolve(request.linkWorkspaceRoot) } : {},
+    }
+    const templates = templateContext(profile)
+    const manifest = createPackageJsonDoc(templates)
+    const documents = new Map<string, ProjectFile>()
+    documents.set(manifest.relativePath, manifest)
+    documents.set('cordis.yml', CordisYamlFile.create())
+    documents.set('.env.example', EnvFile.create('.env.example'))
+    documents.set('tsconfig.json', TsConfigFile.create())
+    for (const document of request.packageManager.configureWorkspace(manifest)) {
+      documents.set(document.relativePath, document)
+    }
+    for (const document of createProjectArtifacts(templates)) {
+      documents.set(document.relativePath, document)
+    }
+    return new SdkProject(root, 'create', profile, documents)
+  }
+
+  /**
+   * Load an existing project from required and SDK-managed optional files.
+   * @param root - existing project directory.
+   * @returns disk-backed project snapshot.
+   */
+  static async open(root: string): Promise<SdkProject> {
+    const absolute = resolve(root)
+    const [manifestText, cordisText] = await Promise.all([
+      readFile(resolve(absolute, 'package.json'), 'utf8'),
+      readFile(resolve(absolute, 'cordis.yml'), 'utf8'),
+    ])
+    const manifest = PackageJsonFile.parse(manifestText)
+    const cordis = CordisYamlFile.parse(cordisText)
+    const value = manifest.value()
+    const manager = await detectPackageManager(absolute, value)
+    const entries = cordis.entries()
+    const linkWorkspaceRoot = linkedRepositoryRoot(absolute, value)
+    const profile: ProjectProfile = {
+      name: value.name ?? basename(absolute),
+      description: typeof value.description === 'string' ? value.description : '',
+      runtime: { model: runtimeModel(entries) },
+      runInterface: runInterface(entries),
+      packageManager: manager,
+      releaseVersion: releaseVersion(value),
+      ...linkWorkspaceRoot ? { linkWorkspaceRoot } : {},
+    }
+    const documents = new Map<string, ProjectFile>([
+      ['package.json', manifest],
+      ['cordis.yml', cordis],
+    ])
+    await Promise.all(OPTIONAL_DOCUMENTS.map(async (path) => {
+      try {
+        const text = await readFile(resolve(absolute, path), 'utf8')
+        documents.set(path, parseOptionalDocument(path, text))
+      } catch (error) {
+        /* v8 ignore next -- optional-file reads fail normally only with ENOENT; other IO faults surface */
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+      }
+    }))
+    return new SdkProject(absolute, 'disk', profile, documents)
+  }
+
+  /**
+   * Read the root package manifest defensively.
+   * @returns cloned manifest value.
+   */
+  packageManifest(): Readonly<PackageManifest> {
+    return this.packageJson.value()
+  }
+
+  /**
+   * Read Cordis config entries defensively in file order.
+   * @returns cloned Cordis config entries.
+   */
+  cordisConfigEntries(): readonly CordisConfigEntry[] {
+    return this.cordis.entries()
+  }
+
+  /**
+   * Check whether this snapshot contains one managed document.
+   * @param path - project-relative document path.
+   * @returns whether the document is loaded.
+   */
+  hasDocument(path: string): boolean {
+    return this.documents.has(path)
+  }
+
+  /**
+   * Read one environment variable from a loaded dotenv document.
+   * @param path - environment file to read.
+   * @param name - variable name.
+   * @returns variable value when present.
+   */
+  readEnvironment(path: '.env' | '.env.example', name: string): string | undefined {
+    const document = this.documents.get(path)
+    if (!document) return undefined
+    if (!(document instanceof EnvFile)) throw new Error(`${path} is not an environment document`)
+    return document.get(name)
+  }
+
+  /** Read the root package document. */
+  get packageJson(): PackageJsonFile {
+    const document = this.documents.get('package.json')
+    if (!(document instanceof PackageJsonFile)) throw new Error('project package.json is missing or invalid')
+    return document
+  }
+
+  /** Read the root Cordis document. */
+  get cordis(): CordisYamlFile {
+    const document = this.documents.get('cordis.yml')
+    if (!(document instanceof CordisYamlFile)) throw new Error('project cordis.yml is missing or invalid')
+    return document
+  }
+
+  /**
+   * Return one managed document without exposing the aggregate map.
+   * @param path - project-relative document path.
+   * @returns loaded document when present.
+   */
+  document(path: string): ProjectFile | undefined {
+    return this.documents.get(path)
+  }
+
+  /**
+   * Create the only mutable boundary for this snapshot.
+   * @param registry - feature catalog governing edits.
+   * @returns isolated edit session.
+   */
+  edit(registry: FeatureRegistry): ProjectEditSession {
+    return new ProjectEditSession(this, registry)
+  }
+
+  /**
+   * Clone every managed document for an isolated edit session.
+   * @returns project-relative document map.
+   */
+  cloneDocuments(): Map<string, ProjectFile> {
+    return new Map([...this.documents].map(([path, document]) => [path, document.clone()]))
+  }
+
+  /**
+   * Reload this aggregate from committed disk state.
+   * @returns fresh disk-backed snapshot.
+   */
+  reopen(): Promise<SdkProject> {
+    return SdkProject.open(this.root)
+  }
+
+}
diff --git a/packages/sdk/helper/src/project/types.ts b/packages/sdk/helper/src/project/types.ts
new file mode 100644
index 0000000000..44d06d508c
--- /dev/null
+++ b/packages/sdk/helper/src/project/types.ts
@@ -0,0 +1,48 @@
+/**
+ * Shared creation and project-profile values for SDK project editing.
+ *
+ * @module @deepseek-ai/dsh-helper/project/types
+ */
+
+import type { PackageManager } from '../package-managers/package-manager.ts'
+import type { LocalPluginBlueprint } from '../plugins/local-plugin-blueprint.ts'
+import type { FeatureId } from '../ids.ts'
+
+/** Runtime front door selected for a generated project. */
+export type RunInterface = 'acp' | 'stdio' | 'embed'
+
+/** Values shared by the required provider and app features. */
+interface ProjectRuntimeOptions {
+  model: string
+}
+
+/** Selected options and captured secrets for one feature. */
+export interface FeatureSelection {
+  id: FeatureId
+  options: readonly string[]
+  values?: Readonly<Record<string, unknown>>
+  secrets?: Readonly<Record<string, string>>
+}
+
+/** Stable context available to project and feature objects. */
+export interface ProjectProfile {
+  name: string
+  description: string
+  runtime: ProjectRuntimeOptions
+  runInterface: RunInterface
+  packageManager: PackageManager
+  releaseVersion: string
+  linkWorkspaceRoot?: string
+}
+
+/** Fully collected create request; it contains intent, never rendered file text. */
+export interface ProjectCreationRequest {
+  name: string
+  description: string
+  runtime: ProjectRuntimeOptions
+  packageManager: PackageManager
+  releaseVersion: string
+  linkWorkspaceRoot?: string
+  features: readonly FeatureSelection[]
+  localPlugins: readonly LocalPluginBlueprint[]
+}
diff --git a/packages/sdk/helper/src/questions/clack-nested-multiselect.ts b/packages/sdk/helper/src/questions/clack-nested-multiselect.ts
new file mode 100644
index 0000000000..1633bdedf7
--- /dev/null
+++ b/packages/sdk/helper/src/questions/clack-nested-multiselect.ts
@@ -0,0 +1,304 @@
+/**
+ * Tree-shaped Clack picker for root checkboxes with finite child options.
+ *
+ * @module @deepseek-ai/dsh-helper/questions/clack-nested-multiselect
+ */
+
+import { styleText } from 'node:util'
+import type { Readable, Writable } from 'node:stream'
+import { Prompt, isCancel } from '@clack/core'
+import {
+  S_BAR,
+  S_BAR_END,
+  S_CHECKBOX_ACTIVE,
+  S_CHECKBOX_INACTIVE,
+  S_CHECKBOX_SELECTED,
+  S_RADIO_ACTIVE,
+  S_RADIO_INACTIVE,
+  symbol,
+  symbolBar,
+} from '@clack/prompts'
+import type {
+  NestedMultiSelectOption,
+  NestedMultiSelectRequest,
+  NestedMultiSelectValue,
+  PromptOutcome,
+} from './prompt-port.ts'
+
+interface NestedPromptOptions<TValue, TChoice> extends NestedMultiSelectRequest<TValue, TChoice> {
+  input: Readable
+  output: Writable
+}
+
+class NestedPrompt<TValue, TChoice> extends Prompt<readonly NestedMultiSelectValue<TValue, TChoice>[]> {
+  readonly options: readonly NestedMultiSelectOption<TValue, TChoice>[]
+  private readonly selected = new Set<TValue>()
+  private readonly selectedChoices = new Map<TValue, Set<TChoice>>()
+  private readonly initialSelected: Set<TValue>
+  private readonly initialChoices: Map<TValue, Set<TChoice>>
+  private readonly showChanges: boolean
+  private layer: 'root' | 'choices' = 'root'
+  private rootCursor = 0
+  private choiceCursor = 0
+
+  constructor(options: NestedPromptOptions<TValue, TChoice>) {
+    super({
+      input: options.input,
+      output: options.output,
+      validate: value => NestedPrompt.validate(options.options, value),
+      render(this: Prompt<readonly NestedMultiSelectValue<TValue, TChoice>[]>) {
+        return (this as NestedPrompt<TValue, TChoice>).renderFrame(options.message)
+      },
+    }, false)
+    this.options = options.options
+    this.showChanges = options.showChanges ?? false
+    for (const option of options.options) {
+      if (option.required || option.default) this.selected.add(option.value)
+      this.selectedChoices.set(option.value, new Set(
+        option.choices?.filter(choice => choice.default).map(choice => choice.value) ?? [],
+      ))
+    }
+    this.initialSelected = new Set(this.selected)
+    this.initialChoices = new Map([...this.selectedChoices].map(([value, choices]) => [
+      value, new Set(choices),
+    ]))
+    this.updateValue()
+    this.on('cursor', (action) => { this.handleAction(action) })
+  }
+
+  private static validate<TValue, TChoice>(
+    options: readonly NestedMultiSelectOption<TValue, TChoice>[],
+    value: readonly NestedMultiSelectValue<TValue, TChoice>[] | undefined,
+  ): string | undefined {
+    /* v8 ignore next -- NestedPrompt initializes its value before submission validation */
+    const selected = new Map(value?.map(item => [item.value, item.choices]) ?? [])
+    for (const option of options) {
+      if (option.disabled) continue
+      /* v8 ignore next -- required options initialize selected and cannot be toggled off */
+      if (option.required && !selected.has(option.value)) return `${option.label} is required`
+      if (!selected.has(option.value) || !option.choiceMode) continue
+      const choices = selected.get(option.value)
+      /* v8 ignore next -- selected.has above guarantees the map value exists */
+      if (!choices) continue
+      const count = choices.length
+      if (option.choiceMode === 'exclusive' && count !== 1) return `Choose one ${option.label} option`
+      if (option.choiceMode === 'multiple' && count === 0) return `Choose at least one ${option.label} option`
+    }
+    return undefined
+  }
+
+  protected override _shouldSubmit(): boolean {
+    if (this.layer === 'choices') {
+      this.leaveChoices()
+      return false
+    }
+    return true
+  }
+
+  private handleAction(action: string | undefined): void {
+    if (this.layer === 'root') this.handleRootAction(action)
+    else this.handleChoiceAction(action)
+    this.updateValue()
+  }
+
+  private handleRootAction(action: string | undefined): void {
+    if (action === 'up') this.rootCursor = this.move(this.rootCursor, -1, this.options.length)
+    if (action === 'down') this.rootCursor = this.move(this.rootCursor, 1, this.options.length)
+    const option = this.options[this.rootCursor]
+    /* v8 ignore next -- Clack cannot emit a cursor action when the option list is empty */
+    if (!option) return
+    if (action === 'space' && !option.required && !option.disabled) {
+      if (this.selected.has(option.value)) this.selected.delete(option.value)
+      else this.selected.add(option.value)
+    }
+    if (action === 'right' && !option.disabled && option.choices && option.choices.length > 0) {
+      this.selected.add(option.value)
+      this.layer = 'choices'
+      const selected = this.selectedChoices.get(option.value)
+      const selectedIndex = option.choices.findIndex(choice => selected?.has(choice.value))
+      this.choiceCursor = Math.max(selectedIndex, 0)
+    }
+  }
+
+  private handleChoiceAction(action: string | undefined): void {
+    const rootOption = this.options[this.rootCursor]
+    /* v8 ignore next -- the choices layer is entered only from a concrete root option */
+    if (!rootOption) return
+    /* v8 ignore next -- the choices layer is entered only for a non-empty choices array */
+    const choices = rootOption.choices ?? []
+    if (action === 'left') {
+      this.leaveChoices()
+      return
+    }
+    if (action === 'up') this.choiceCursor = this.move(this.choiceCursor, -1, choices.length)
+    if (action === 'down') this.choiceCursor = this.move(this.choiceCursor, 1, choices.length)
+    if ((action === 'up' || action === 'down') && rootOption.choiceMode === 'exclusive') {
+      const choice = choices[this.choiceCursor]
+      /* v8 ignore else -- a cursor in the non-empty choices layer always addresses a choice */
+      if (choice) this.selectedChoices.set(rootOption.value, new Set([choice.value]))
+    }
+    if (action !== 'space' && action !== 'right') return
+    const choice = choices[this.choiceCursor]
+    /* v8 ignore next -- the choices layer requires a non-empty choice list */
+    if (!choice) return
+    /* v8 ignore next -- every root option initializes its choice set in the constructor */
+    const selected = this.selectedChoices.get(rootOption.value) ?? new Set<TChoice>()
+    if (rootOption.choiceMode === 'exclusive') {
+      selected.clear()
+      selected.add(choice.value)
+    } else if (selected.has(choice.value)) selected.delete(choice.value)
+    else selected.add(choice.value)
+    this.selectedChoices.set(rootOption.value, selected)
+  }
+
+  private move(cursor: number, offset: number, length: number): number {
+    /* v8 ignore next -- cursor movement is emitted only for a non-empty displayed list */
+    if (length === 0) return 0
+    return (cursor + offset + length) % length
+  }
+
+  private updateValue(): void {
+    this._setValue(this.options.filter(option => this.selected.has(option.value)).map(option => ({
+      value: option.value,
+      /* v8 ignore next -- every root option initializes its choice set in the constructor */
+      choices: [...this.selectedChoices.get(option.value) ?? []],
+    })))
+  }
+
+  private renderFrame(message: string): string {
+    const header = `${symbolBar(this.state)}  ${message}`
+    if (this.state === 'submit') {
+      /* v8 ignore next -- NestedPrompt initializes its value before it can submit */
+      const summary = (this.value ?? []).map(item => this.options.find(option => option.value === item.value)?.label)
+        .filter(Boolean).join(', ') || 'none'
+      return `${symbol(this.state)}  ${message}\n${styleText('gray', S_BAR)}  ${styleText('dim', summary)}`
+    }
+    if (this.state === 'cancel') return `${symbol(this.state)}  ${message}`
+    const body = this.layer === 'root' ? this.renderRoot() : this.renderChoices()
+    const instructions = this.layer === 'root'
+      ? `${styleText('dim', '↑/↓')} navigate  ${styleText('dim', 'Space')} select  ${styleText('dim', '→')} configure  ${styleText('dim', 'Enter')} confirm`
+      : `${styleText('dim', '↑/↓')} navigate  ${styleText('dim', 'Space/→')} select  ${styleText('dim', '←/Enter')} back`
+    const error = this.state === 'error' ? `\n${styleText('yellow', `${S_BAR_END}  ${this.error}`)}` : ''
+    return `${header}\n${styleText('cyan', S_BAR)}  ${body.join(`\n${styleText('cyan', S_BAR)}  `)}\n${styleText('cyan', S_BAR_END)}  ${instructions}${error}`
+  }
+
+  private renderRoot(): string[] {
+    return this.options.map((option, index) => {
+      const active = index === this.rootCursor
+      const selected = this.selected.has(option.value)
+      const focus = active ? styleText('cyan', '›') : ' '
+      const checkbox = selected
+        ? styleText('green', S_CHECKBOX_SELECTED)
+        : styleText('dim', active ? S_CHECKBOX_ACTIVE : S_CHECKBOX_INACTIVE)
+      const choices = option.choices?.filter(choice => this.selectedChoices.get(option.value)?.has(choice.value))
+        .map(choice => choice.label).join(', ')
+      const suffix = option.choices?.length
+        ? ` ${styleText('dim', `* →${choices ? ` ${choices}` : ''}`)}`
+        : ''
+      const required = option.required ? ` ${styleText('yellow', '(required)')}` : ''
+      const issue = this.choiceIssue(option)
+      const warningText = option.warning ?? issue
+      const warning = warningText ? ` ${styleText('yellow', `▲ ${warningText}`)}` : ''
+      const changed = this.optionChanged(option)
+      const change = changed ? ` ${styleText('yellow', '● changed')}` : ''
+      const label = active
+        ? styleText('cyan', option.label)
+        : changed
+          ? styleText('yellow', option.label)
+          : selected ? styleText('green', option.label) : styleText('dim', option.label)
+      const line = `${focus} ${checkbox} ${label}${required}${suffix}${warning}${change}`
+      return option.disabled ? styleText('gray', line) : line
+    })
+  }
+
+  private renderChoices(): string[] {
+    const rootOption = this.options[this.rootCursor]
+    /* v8 ignore next -- renderChoices runs only after entering from a concrete root option */
+    if (!rootOption) return []
+    /* v8 ignore next -- every root option initializes its choice set in the constructor */
+    const selected = this.selectedChoices.get(rootOption.value) ?? new Set<TChoice>()
+    const issue = this.choiceIssue(rootOption)
+    const changed = this.optionChanged(rootOption)
+    const header = styleText('dim', `${rootOption.label} options`)
+      + (issue ? ` ${styleText('yellow', `▲ ${issue}`)}` : '')
+      + (changed ? ` ${styleText('yellow', '● changed')}` : '')
+    const choices = rootOption.choices
+    /* v8 ignore next -- the choices layer is entered only for a non-empty choices array */
+    if (!choices) return [header]
+    return [
+      header,
+      ...choices.map((choice, index) => {
+        const active = index === this.choiceCursor
+        const checked = selected.has(choice.value)
+        const choiceChanged = this.choiceChanged(rootOption.value, choice.value)
+        const focus = active ? styleText('cyan', '›') : ' '
+        const marker = rootOption.choiceMode === 'exclusive'
+          ? checked ? styleText('green', S_RADIO_ACTIVE) : styleText('dim', S_RADIO_INACTIVE)
+          : checked ? styleText('green', S_CHECKBOX_SELECTED) : styleText('dim', S_CHECKBOX_INACTIVE)
+        const label = active
+          ? styleText('cyan', choice.label)
+          : choiceChanged
+            ? styleText('yellow', choice.label)
+            : checked ? styleText('green', choice.label) : styleText('dim', choice.label)
+        const change = choiceChanged ? ` ${styleText('yellow', '●')}` : ''
+        return `${focus} ${marker} ${label}${change}`
+      }),
+    ]
+  }
+
+  private optionChanged(option: NestedMultiSelectOption<TValue, TChoice>): boolean {
+    if (!this.showChanges) return false
+    const selected = this.selected.has(option.value)
+    const initiallySelected = this.initialSelected.has(option.value)
+    if (selected !== initiallySelected) return true
+    if (!selected) return false
+    /* v8 ignore next -- every root option initializes both current and baseline option sets */
+    const current = this.selectedChoices.get(option.value) ?? new Set<TChoice>()
+    /* v8 ignore next -- every root option initializes both current and baseline option sets */
+    const initial = this.initialChoices.get(option.value) ?? new Set<TChoice>()
+    return current.size !== initial.size || [...current].some(value => !initial.has(value))
+  }
+
+  private choiceChanged(value: TValue, choice: TChoice): boolean {
+    if (!this.showChanges) return false
+    return this.selectedChoices.get(value)?.has(choice) !== this.initialChoices.get(value)?.has(choice)
+  }
+
+  private choiceIssue(option: NestedMultiSelectOption<TValue, TChoice>): string | undefined {
+    if (option.disabled || !this.selected.has(option.value) || !option.choiceMode) return undefined
+    /* v8 ignore next -- every root option initializes its choice set in the constructor */
+    const count = this.selectedChoices.get(option.value)?.size ?? 0
+    if (option.choiceMode === 'exclusive' && count !== 1) return 'choose one'
+    if (option.choiceMode === 'multiple' && count === 0) return 'choose at least one'
+    return undefined
+  }
+
+  private leaveChoices(): boolean {
+    const option = this.options[this.rootCursor]
+    /* v8 ignore next -- leaveChoices runs only after entering from a concrete root option */
+    if (!option) return false
+    const issue = this.choiceIssue(option)
+    if (issue) {
+      this.error = `${option.label}: ${issue}`
+      this.state = 'error'
+      return false
+    }
+    this.error = ''
+    this.layer = 'root'
+    return true
+  }
+}
+
+/** Run the nested picker with Clack's standard cancellation symbol. */
+export async function clackNestedMultiselect<TValue, TChoice>(
+  request: NestedPromptOptions<TValue, TChoice>,
+): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> {
+  const value = await new NestedPrompt(request).prompt()
+  return isCancel(value)
+    ? { status: 'cancelled' }
+    : {
+      status: 'answered',
+      /* v8 ignore next -- NestedPrompt initializes its value before it can submit */
+      value: value ?? [],
+    }
+}
diff --git a/packages/sdk/helper/src/questions/clack-prompt-port.ts b/packages/sdk/helper/src/questions/clack-prompt-port.ts
new file mode 100644
index 0000000000..c5ebff1427
--- /dev/null
+++ b/packages/sdk/helper/src/questions/clack-prompt-port.ts
@@ -0,0 +1,127 @@
+/**
+ * Thin @clack/prompts adapter for the shared prompt port.
+ *
+ * @module @deepseek-ai/dsh-helper/questions/clack-prompt-port
+ */
+
+import type { Readable, Writable } from 'node:stream'
+import { styleText } from 'node:util'
+import {
+  confirm,
+  isCancel,
+  multiselect,
+  password,
+  select,
+  text,
+  S_WARN,
+} from '@clack/prompts'
+import type { Option } from '@clack/prompts'
+import type {
+  ConfirmPromptRequest,
+  MultiSelectPromptRequest,
+  NestedMultiSelectRequest,
+  NestedMultiSelectValue,
+  PromptOutcome,
+  PromptPort,
+  SecretPromptRequest,
+  SelectPromptRequest,
+  TextPromptRequest,
+} from './prompt-port.ts'
+import { clackNestedMultiselect } from './clack-nested-multiselect.ts'
+
+function outcome<T>(value: T | symbol): PromptOutcome<T> {
+  return isCancel(value) ? { status: 'cancelled' } : { status: 'answered', value }
+}
+
+function clackOptions<T>(values: readonly import('./prompt-port.ts').PromptOption<T>[]): Option<T>[] {
+  return values.map(value => ({
+    value: value.value,
+    label: value.label,
+    ...value.hint === undefined ? {} : { hint: value.hint },
+    ...value.disabled === undefined ? {} : { disabled: value.disabled },
+  })) as Option<T>[]
+}
+
+/** Clack-backed prompt adapter with injectable streams for snapshots and tests. */
+export class ClackPromptPort implements PromptPort {
+  private readonly input: Readable
+  private readonly output: Writable
+
+  /** Bind all prompts to one input/output pair. */
+  constructor(input: Readable = process.stdin, output: Writable = process.stdout) {
+    this.input = input
+    this.output = output
+  }
+
+  /** Ask for visible text through clack. */
+  async text(request: TextPromptRequest): Promise<PromptOutcome<string>> {
+    return outcome(await text({
+      message: request.message,
+      ...request.placeholder === undefined ? {} : { placeholder: request.placeholder },
+      ...request.initialValue === undefined ? {} : { initialValue: request.initialValue },
+      ...request.defaultValue === undefined ? {} : { defaultValue: request.defaultValue },
+      ...request.validate === undefined
+        ? {}
+        : {
+          /* v8 ignore next -- value/default precedence is exercised through the adapter contract tests */
+          validate: value => request.validate?.(value || request.defaultValue || ''),
+        },
+      input: this.input,
+      output: this.output,
+    }))
+  }
+
+  /** Ask for a masked secret through clack. */
+  async secret(request: SecretPromptRequest): Promise<PromptOutcome<string>> {
+    return outcome(await password({
+      message: request.message,
+      ...request.validate === undefined ? {} : {
+        /* v8 ignore next -- @clack/password always calls validation with a string; fallback is defensive */
+        validate: value => request.validate?.(value ?? ''),
+      },
+      input: this.input,
+      output: this.output,
+    }))
+  }
+
+  /** Ask for one option through clack. */
+  async select<T>(request: SelectPromptRequest<T>): Promise<PromptOutcome<T>> {
+    return outcome(await select({
+      ...request,
+      options: clackOptions(request.options),
+      input: this.input,
+      output: this.output,
+    }))
+  }
+
+  /** Ask for multiple options through clack. */
+  async multiselect<T>(request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>> {
+    return outcome(await multiselect({
+      message: request.message,
+      options: clackOptions(request.options),
+      ...request.initialValues === undefined ? {} : { initialValues: [...request.initialValues] },
+      ...request.required === undefined ? {} : { required: request.required },
+      input: this.input,
+      output: this.output,
+    }))
+  }
+
+  /** Ask for confirmation through clack. */
+  async confirm(request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>> {
+    return outcome(await confirm({
+      message: request.tone === 'warning'
+        ? styleText('yellow', `${S_WARN} ${request.message}`)
+        : request.message,
+      ...request.initialValue === undefined ? {} : { initialValue: request.initialValue },
+      input: this.input,
+      output: this.output,
+    }))
+  }
+
+  /** Select root values and finite child options in one tree prompt. */
+  nestedMultiselect<TValue, TChoice>(
+    request: NestedMultiSelectRequest<TValue, TChoice>,
+  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> {
+    return clackNestedMultiselect({ ...request, input: this.input, output: this.output })
+  }
+}
diff --git a/packages/sdk/helper/src/questions/prompt-port.ts b/packages/sdk/helper/src/questions/prompt-port.ts
new file mode 100644
index 0000000000..f37fdff025
--- /dev/null
+++ b/packages/sdk/helper/src/questions/prompt-port.ts
@@ -0,0 +1,124 @@
+/**
+ * Terminal-prompt port shared by create and config workflows.
+ *
+ * @module @deepseek-ai/dsh-helper/questions/prompt-port
+ */
+
+/** One selectable prompt option. */
+export interface PromptOption<T> {
+  value: T
+  label: string
+  hint?: string
+  disabled?: boolean
+}
+
+/** Answer or explicit cancellation returned by every prompt. */
+export type PromptOutcome<T> =
+  | { status: 'answered'; value: T }
+  | { status: 'cancelled' }
+
+/** Input for one text prompt. */
+export interface TextPromptRequest {
+  message: string
+  placeholder?: string
+  initialValue?: string
+  defaultValue?: string
+  validate?: (value: string) => string | undefined
+}
+
+/** Input for one masked secret prompt. */
+export interface SecretPromptRequest {
+  message: string
+  validate?: (value: string) => string | undefined
+}
+
+/** Input for one single-choice prompt. */
+export interface SelectPromptRequest<T> {
+  message: string
+  options: readonly PromptOption<T>[]
+  initialValue?: T
+}
+
+/** Input for one additive multi-choice prompt. */
+export interface MultiSelectPromptRequest<T> {
+  message: string
+  options: readonly PromptOption<T>[]
+  initialValues?: readonly T[]
+  required?: boolean
+}
+
+/** Input for one yes/no prompt. */
+export interface ConfirmPromptRequest {
+  message: string
+  initialValue?: boolean
+  tone?: 'default' | 'warning'
+}
+
+/** One nested choice under a multi-select option. */
+interface NestedSelectChoice<T> {
+  value: T
+  label: string
+  default?: boolean
+}
+
+/** One root option with optional child option configuration. */
+export interface NestedMultiSelectOption<TValue, TChoice> {
+  value: TValue
+  label: string
+  required?: boolean
+  default?: boolean
+  disabled?: boolean
+  warning?: string
+  choiceMode?: 'exclusive' | 'multiple'
+  choices?: readonly NestedSelectChoice<TChoice>[]
+}
+
+/** Input for a tree-shaped feature-style picker. */
+export interface NestedMultiSelectRequest<TValue, TChoice> {
+  message: string
+  options: readonly NestedMultiSelectOption<TValue, TChoice>[]
+  showChanges?: boolean
+}
+
+/** One selected root option and its child options. */
+export interface NestedMultiSelectValue<TValue, TChoice> {
+  value: TValue
+  choices: readonly TChoice[]
+}
+
+/** Interaction boundary consumed by typed question objects. */
+export interface PromptPort {
+  /** Ask for one line of visible text. */
+  text(request: TextPromptRequest): Promise<PromptOutcome<string>>
+  /** Ask for one masked value. */
+  secret(request: SecretPromptRequest): Promise<PromptOutcome<string>>
+  /** Ask for exactly one option. */
+  select<T>(request: SelectPromptRequest<T>): Promise<PromptOutcome<T>>
+  /** Ask for zero or more options. */
+  multiselect<T>(request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>>
+  /** Ask for a boolean confirmation. */
+  confirm(request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>>
+  /** Select root options and configure finite child options in one tree prompt. */
+  nestedMultiselect<TValue, TChoice>(
+    request: NestedMultiSelectRequest<TValue, TChoice>,
+  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>>
+}
+
+/** Error used when a workflow chooses to turn prompt cancellation into command cancellation. */
+export class PromptCancelledError extends Error {
+  /** Create a stable cancellation error. */
+  constructor(message = 'operation cancelled') {
+    super(message)
+    this.name = 'PromptCancelledError'
+  }
+}
+
+/**
+ * Return an answered value or throw the shared cancellation error.
+ * @param outcome - prompt result to unwrap.
+ * @returns answered value.
+ */
+export function requireAnswer<T>(outcome: PromptOutcome<T>): T {
+  if (outcome.status === 'cancelled') throw new PromptCancelledError()
+  return outcome.value
+}
diff --git a/packages/sdk/helper/src/questions/question.ts b/packages/sdk/helper/src/questions/question.ts
new file mode 100644
index 0000000000..45697d7eb5
--- /dev/null
+++ b/packages/sdk/helper/src/questions/question.ts
@@ -0,0 +1,206 @@
+/**
+ * Typed question objects with prefill, validation, and prompt behavior together.
+ *
+ * @module @deepseek-ai/dsh-helper/questions/question
+ */
+
+import type { PromptOption, PromptOutcome, PromptPort } from './prompt-port.ts'
+
+function resolvePrefilled(
+  id: string,
+  value: string | undefined,
+  validate: ((value: string) => string | undefined) | undefined,
+): PromptOutcome<string> | undefined {
+  if (value === undefined) return undefined
+  const diagnostic = validate?.(value)
+  if (diagnostic) throw new Error(`${id}: ${diagnostic}`)
+  return { status: 'answered', value }
+}
+
+/** A typed business question resolved from prefilled input or one prompt call. */
+export abstract class Question<T> {
+  /** Stable question identity used in diagnostics. */
+  readonly id: string
+  /** User-facing prompt text. */
+  readonly message: string
+
+  protected constructor(id: string, message: string) {
+    this.id = id
+    this.message = message
+  }
+
+  /**
+   * Resolve a prefilled answer without prompting, or ask through the port.
+   * @param port - prompt interaction boundary.
+   * @param prefilled - optional value supplied by CLI or current project state.
+   * @returns answered or cancelled prompt outcome.
+   */
+  abstract resolve(port: PromptPort, prefilled?: T): Promise<PromptOutcome<T>>
+}
+
+/** Visible single-line text question. */
+export class TextQuestion extends Question<string> {
+  /** Light hint displayed when no text has been entered. */
+  readonly placeholder: string | undefined
+  /** Editable value displayed in the input. */
+  readonly initialValue: string | undefined
+  /** Value accepted when the user submits an empty input. */
+  readonly defaultValue: string | undefined
+  private readonly validate: ((value: string) => string | undefined) | undefined
+
+  /** Configure one text question. */
+  constructor(options: {
+    id: string
+    message: string
+    placeholder?: string
+    initialValue?: string
+    defaultValue?: string
+    validate?: (value: string) => string | undefined
+  }) {
+    super(options.id, options.message)
+    this.placeholder = options.placeholder
+    this.initialValue = options.initialValue
+    this.defaultValue = options.defaultValue
+    this.validate = options.validate
+  }
+
+  /** Validate prefilled text or ask for it. */
+  override async resolve(port: PromptPort, prefilled?: string): Promise<PromptOutcome<string>> {
+    const resolved = resolvePrefilled(this.id, prefilled, this.validate)
+    if (resolved) return resolved
+    return port.text({
+      message: this.message,
+      ...this.placeholder === undefined ? {} : { placeholder: this.placeholder },
+      ...this.initialValue === undefined ? {} : { initialValue: this.initialValue },
+      ...this.defaultValue === undefined ? {} : { defaultValue: this.defaultValue },
+      ...this.validate === undefined ? {} : { validate: this.validate },
+    })
+  }
+}
+
+/** Masked secret question whose empty-input semantics are set by its caller. */
+export class SecretQuestion extends Question<string> {
+  private readonly validate: ((value: string) => string | undefined) | undefined
+
+  /** Configure one secret question. */
+  constructor(options: {
+    id: string
+    message: string
+    validate?: (value: string) => string | undefined
+  }) {
+    super(options.id, options.message)
+    this.validate = options.validate
+  }
+
+  /** Validate a prefilled secret or ask for a masked value. */
+  override async resolve(port: PromptPort, prefilled?: string): Promise<PromptOutcome<string>> {
+    const resolved = resolvePrefilled(this.id, prefilled, this.validate)
+    if (resolved) return resolved
+    return port.secret({
+      message: this.message,
+      ...this.validate === undefined ? {} : { validate: this.validate },
+    })
+  }
+}
+
+/** Single-choice question. */
+export class SelectQuestion<T> extends Question<T> {
+  /** Available choices in display order. */
+  readonly options: readonly PromptOption<T>[]
+  /** Initially focused choice. */
+  readonly initialValue: T | undefined
+
+  /** Configure one single-choice question. */
+  constructor(options: {
+    id: string
+    message: string
+    options: readonly PromptOption<T>[]
+    initialValue?: T
+  }) {
+    super(options.id, options.message)
+    this.options = options.options
+    this.initialValue = options.initialValue
+  }
+
+  /** Validate a prefilled option or ask for one choice. */
+  override async resolve(port: PromptPort, prefilled?: T): Promise<PromptOutcome<T>> {
+    if (prefilled !== undefined) {
+      if (!this.options.some(option => Object.is(option.value, prefilled) && !option.disabled)) {
+        throw new Error(`${this.id}: unknown or disabled option ${String(prefilled)}`)
+      }
+      return { status: 'answered', value: prefilled }
+    }
+    return port.select({
+      message: this.message,
+      options: this.options,
+      ...this.initialValue === undefined ? {} : { initialValue: this.initialValue },
+    })
+  }
+}
+
+/** Additive multi-choice question. */
+export class MultiSelectQuestion<T> extends Question<readonly T[]> {
+  readonly options: readonly PromptOption<T>[]
+  readonly initialValues: readonly T[]
+  readonly required: boolean
+
+  /** Configure one multi-choice question. */
+  constructor(options: {
+    id: string
+    message: string
+    options: readonly PromptOption<T>[]
+    initialValues?: readonly T[]
+    required?: boolean
+  }) {
+    super(options.id, options.message)
+    this.options = options.options
+    this.initialValues = options.initialValues ?? []
+    this.required = options.required ?? false
+  }
+
+  /** Validate prefilled values or ask for an additive selection. */
+  override async resolve(port: PromptPort, prefilled?: readonly T[]): Promise<PromptOutcome<readonly T[]>> {
+    if (prefilled !== undefined) {
+      for (const value of prefilled) {
+        /* v8 ignore next -- unknown, disabled, and accepted values are each pinned by the question tests */
+        if (!this.options.some(option => Object.is(option.value, value) && option.disabled !== true)) {
+          throw new Error(`${this.id}: unknown or disabled option ${String(value)}`)
+        }
+      }
+      if (this.required && prefilled.length === 0) throw new Error(`${this.id}: choose at least one option`)
+      return { status: 'answered', value: prefilled }
+    }
+    return port.multiselect({
+      message: this.message,
+      options: this.options,
+      initialValues: this.initialValues,
+      required: this.required,
+    })
+  }
+}
+
+/** Boolean confirmation question. */
+export class ConfirmQuestion extends Question<boolean> {
+  /** Answer selected by pressing Enter. */
+  readonly initialValue: boolean
+  /** Visual severity used by the prompt adapter. */
+  readonly tone: 'default' | 'warning'
+
+  /** Configure one confirmation question. */
+  constructor(options: {
+    id: string
+    message: string
+    initialValue?: boolean
+    tone?: 'default' | 'warning'
+  }) {
+    super(options.id, options.message)
+    this.initialValue = options.initialValue ?? true
+    this.tone = options.tone ?? 'default'
+  }
+
+  /** Return a prefilled boolean or ask for confirmation. */
+  override async resolve(port: PromptPort, prefilled?: boolean): Promise<PromptOutcome<boolean>> {
+    if (prefilled !== undefined) return { status: 'answered', value: prefilled }
+    return port.confirm({ message: this.message, initialValue: this.initialValue, tone: this.tone })
+  }
+}
diff --git a/packages/sdk/helper/src/templates/assets/README.md.tpl b/packages/sdk/helper/src/templates/assets/README.md.tpl
new file mode 100644
index 0000000000..5d56d13a72
--- /dev/null
+++ b/packages/sdk/helper/src/templates/assets/README.md.tpl
@@ -0,0 +1,33 @@
+# {{name}}
+
+{{description}}
+
+Built with the DeepSeek Harness SDK using the {{model}} model.
+
+{{#if isAcp}}
+## Run as an ACP server
+
+Run `{{packageManager}} start` and configure your ACP client to launch this project. Standard output is reserved for ACP JSON-RPC.
+{{else}}
+{{#if isStdio}}
+## Run in a terminal
+
+Run `{{packageManager}} start` to start the interactive agent.
+{{else}}
+## Embed the harness
+
+Import and call the exported `main()` from `index.ts` in your host application.
+{{/if}}
+{{/if}}
+
+## Development
+
+Install NPM dependencies with `{{packageManager}} {{installArgs}}`, then use:
+
+- `dev`: `{{packageManager}} run dev`
+- `build`: `{{packageManager}} {{buildArgs}}`
+- `typecheck`: `{{packageManager}} run typecheck`
+- `start`: `{{packageManager}} start`
+- `config`: `{{packageManager}} run config`
+
+Edit `cordis.yml` to change the runtime plugin tree. Add or remove builtin features with `{{packageManager}} exec dsh config`.
diff --git a/packages/sdk/helper/src/templates/assets/gitignore.tpl b/packages/sdk/helper/src/templates/assets/gitignore.tpl
new file mode 100644
index 0000000000..30b03c75c5
--- /dev/null
+++ b/packages/sdk/helper/src/templates/assets/gitignore.tpl
@@ -0,0 +1,5 @@
+node_modules/
+lib/
+.env
+.sessions/
+*.tsbuildinfo
diff --git a/packages/sdk/helper/src/templates/assets/index.ts.tpl b/packages/sdk/helper/src/templates/assets/index.ts.tpl
new file mode 100644
index 0000000000..d0315db80c
--- /dev/null
+++ b/packages/sdk/helper/src/templates/assets/index.ts.tpl
@@ -0,0 +1,45 @@
+{{#if isAcp}}
+import { startSDK, type SdkBootContext } from '@deepseek-ai/dsh-scripts'
+{{else}}
+import { randomUUID } from 'node:crypto'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import { startSDK, type SdkBootContext } from '@deepseek-ai/dsh-scripts'
+{{/if}}
+
+/** Boot this project's cordis.yml when invoked by dsh-scripts. */
+export async function main(boot: SdkBootContext) {
+  const ctx = await startSDK(new URL('./cordis.yml', import.meta.url))
+{{#if isStdio}}
+  const model = boot.args.model
+  if (typeof model !== 'string' || model.length === 0) throw new Error('stdio startup requires --model=<name>')
+  const resume = boot.args.resume
+  if (resume !== undefined && (typeof resume !== 'string' || resume.length === 0)) {
+    throw new Error('stdio startup requires --resume=<session-id>')
+  }
+  if (resume === undefined) {
+    await ctx.agents.create({
+      agentId: AgentId('main'),
+      sessionId: SessionId(`main-session-${randomUUID()}`),
+      meta: { cwd: boot.cwd },
+      agentOptions: { model },
+    })
+  } else {
+    await ctx.agents.resume({
+      agentId: AgentId('main'),
+      resumeSessionId: SessionId(resume),
+      agentOptions: { model },
+    })
+  }
+{{else}}
+{{#if isEmbed}}
+  await ctx.agents.create({
+    agentId: AgentId('main'),
+    sessionId: SessionId(`main-session-${randomUUID()}`),
+    meta: { cwd: boot.cwd },
+    agentOptions: { model: {{modelLiteral}} },
+  })
+{{/if}}
+{{/if}}
+  return ctx
+}
diff --git a/packages/sdk/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl b/packages/sdk/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl
new file mode 100644
index 0000000000..d24fb6f870
--- /dev/null
+++ b/packages/sdk/helper/src/templates/assets/local-plugin-tsdown.config.ts.tpl
@@ -0,0 +1,13 @@
+import { defineConfig } from 'tsdown'
+import { PluginBuild } from '@deepseek-ai/dsh-scripts/dev/tsdown-config'
+
+export default defineConfig(PluginBuild({
+  entry: ['src/index.ts'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: true,
+  clean: false,
+}))
diff --git a/packages/sdk/helper/src/templates/assets/local-plugin.ts.tpl b/packages/sdk/helper/src/templates/assets/local-plugin.ts.tpl
new file mode 100644
index 0000000000..2f15bdef91
--- /dev/null
+++ b/packages/sdk/helper/src/templates/assets/local-plugin.ts.tpl
@@ -0,0 +1,9 @@
+/** Local Cordis plugin. */
+import type { Context } from 'cordis'
+
+export const name = '{{pluginName}}'
+
+/** Register this plugin's project-local behavior. */
+export function apply(ctx: Context): void {
+  ctx.effect(() => () => {})
+}
diff --git a/packages/sdk/helper/src/templates/assets/local-tool.ts.tpl b/packages/sdk/helper/src/templates/assets/local-tool.ts.tpl
new file mode 100644
index 0000000000..4333d41c70
--- /dev/null
+++ b/packages/sdk/helper/src/templates/assets/local-tool.ts.tpl
@@ -0,0 +1,17 @@
+/** Project-local model-facing tool. */
+import type { Context } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export const name = '{{pluginName}}'
+export const inject = ['tools']
+
+/** Register the {{toolName}} tool. */
+export function apply(ctx: Context): void {
+  ctx.tools.register(defineTool({
+    name: '{{toolName}}',
+    description: 'Project-local {{toolTitle}} tool.',
+    parameters: {},
+    execute: async () => [{ type: 'text', text: '{{toolName}} completed.' }],
+    presentCall: args => ({ card: 'generic', title: '{{toolTitle}}', kind: 'other', rawInput: args }),
+  }))
+}
diff --git a/packages/sdk/helper/src/templates/assets/package.json.tpl b/packages/sdk/helper/src/templates/assets/package.json.tpl
new file mode 100644
index 0000000000..759639053b
--- /dev/null
+++ b/packages/sdk/helper/src/templates/assets/package.json.tpl
@@ -0,0 +1,16 @@
+{
+  "name": {{name}},
+  "version": "0.0.0",
+  "private": true,
+  "description": {{description}},
+  "type": "module",
+  "scripts": {
+    "dev": {{devScript}},
+    "build": "dsh build",
+    "typecheck": "tsc -b",
+    "start": {{startScript}},
+    "config": "dsh config"
+  },
+  "dependencies": {{dependencies}},
+  "devDependencies": {{devDependencies}}
+}
diff --git a/packages/sdk/helper/src/templates/assets/persona.txt.tpl b/packages/sdk/helper/src/templates/assets/persona.txt.tpl
new file mode 100644
index 0000000000..b17a6e802a
--- /dev/null
+++ b/packages/sdk/helper/src/templates/assets/persona.txt.tpl
@@ -0,0 +1,3 @@
+You are a coding assistant powered by the \{{model}} model. Your working directory is \{{cwd}}.
+
+Verify your work by running the code or tests. Keep answers brief and factual.
diff --git a/packages/sdk/helper/src/templates/assets/tsconfig.base.json.tpl b/packages/sdk/helper/src/templates/assets/tsconfig.base.json.tpl
new file mode 100644
index 0000000000..f712277e9a
--- /dev/null
+++ b/packages/sdk/helper/src/templates/assets/tsconfig.base.json.tpl
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "declaration": true,
+    "composite": true,
+    "outDir": "lib",
+    "rootDir": ".",
+    "types": ["node"],
+    "skipLibCheck": true
+  }
+}
diff --git a/packages/sdk/helper/src/templates/assets/tsdown.config.ts.tpl b/packages/sdk/helper/src/templates/assets/tsdown.config.ts.tpl
new file mode 100644
index 0000000000..c923dd2d5b
--- /dev/null
+++ b/packages/sdk/helper/src/templates/assets/tsdown.config.ts.tpl
@@ -0,0 +1,13 @@
+import { defineConfig } from 'tsdown'
+import { ProjectBuild } from '@deepseek-ai/dsh-scripts/dev/tsdown-config'
+
+export default defineConfig(ProjectBuild({
+  entry: ['index.ts'],
+  outDir: '.',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+}))
diff --git a/packages/sdk/helper/src/templates/assets/yarnrc.yml.tpl b/packages/sdk/helper/src/templates/assets/yarnrc.yml.tpl
new file mode 100644
index 0000000000..3186f3f079
--- /dev/null
+++ b/packages/sdk/helper/src/templates/assets/yarnrc.yml.tpl
@@ -0,0 +1 @@
+nodeLinker: node-modules
diff --git a/packages/sdk/helper/src/templates/project-template.ts b/packages/sdk/helper/src/templates/project-template.ts
new file mode 100644
index 0000000000..a9686649ad
--- /dev/null
+++ b/packages/sdk/helper/src/templates/project-template.ts
@@ -0,0 +1,78 @@
+/**
+ * Strict Handlebars wrapper and complete-file SDK project artifacts.
+ *
+ * @module @deepseek-ai/dsh-helper/templates/project-template
+ */
+
+import { PackageJsonFile } from '../documents/package-json-file.ts'
+import { TextProjectFile } from '../documents/project-file.ts'
+import type { PackageManagerName } from '../package-managers/package-manager.ts'
+import { baselineNpmDependencies } from '../project/npm-dependency-policy.ts'
+import { loadHelperTemplate } from './template-assets.ts'
+import type { TextTemplate } from './text-template.ts'
+
+/** Stable typed view consumed by all generated text artifacts. */
+export interface ProjectTemplateContext {
+  name: string
+  description: string
+  releaseVersion: string
+  model: string
+  modelLiteral: string
+  isAcp: boolean
+  isStdio: boolean
+  isEmbed: boolean
+  packageManager: PackageManagerName
+  installArgs: string
+  buildArgs: string
+}
+
+/** Complete project-file template artifact. */
+export class TemplateArtifact<TModel extends object> extends TextProjectFile {
+  /** Render and own one complete project file. */
+  constructor(relativePath: string, template: TextTemplate<TModel>, model: TModel) {
+    super(relativePath, template.render(model))
+  }
+}
+
+const README_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('README.md.tpl')
+const PACKAGE_JSON_TEMPLATE = loadHelperTemplate<{
+  name: string
+  description: string
+  devScript: string
+  startScript: string
+  dependencies: string
+  devDependencies: string
+}>('package.json.tpl')
+const INDEX_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('index.ts.tpl')
+const TSDOWN_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('tsdown.config.ts.tpl')
+const TSCONFIG_BASE_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('tsconfig.base.json.tpl')
+const GITIGNORE_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('gitignore.tpl')
+const YARNRC_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('yarnrc.yml.tpl')
+
+/** Render the complete root package defaults before structured contributions merge. */
+export function createPackageJsonDoc(context: ProjectTemplateContext): PackageJsonFile {
+  const stdioModelArg = context.isStdio ? ` -- --model=${JSON.stringify(context.model)}` : ''
+  const npmDependencies = baselineNpmDependencies(context.releaseVersion)
+  return PackageJsonFile.create(PACKAGE_JSON_TEMPLATE.render({
+    name: JSON.stringify(context.name),
+    description: JSON.stringify(context.description),
+    devScript: JSON.stringify(`dsh dev index.ts${stdioModelArg}`),
+    startScript: JSON.stringify(`dsh start index.js${stdioModelArg}`),
+    dependencies: JSON.stringify(npmDependencies.dependencies),
+    devDependencies: JSON.stringify(npmDependencies.devDependencies),
+  }))
+}
+
+/** Build every one-shot project artifact from one template context. */
+export function createProjectArtifacts(context: ProjectTemplateContext): TemplateArtifact<ProjectTemplateContext>[] {
+  return [
+    new TemplateArtifact('README.md', README_TEMPLATE, context),
+    new TemplateArtifact('index.ts', INDEX_TEMPLATE, context),
+    new TemplateArtifact('tsdown.config.ts', TSDOWN_TEMPLATE, context),
+    new TemplateArtifact('tsconfig.base.json', TSCONFIG_BASE_TEMPLATE, context),
+    new TemplateArtifact('.gitignore', GITIGNORE_TEMPLATE, context),
+    ...context.packageManager === 'yarn'
+      ? [new TemplateArtifact('.yarnrc.yml', YARNRC_TEMPLATE, context)]
+      : [],
+  ]
+}
diff --git a/packages/sdk/helper/src/templates/template-assets.ts b/packages/sdk/helper/src/templates/template-assets.ts
new file mode 100644
index 0000000000..fbf7fbec45
--- /dev/null
+++ b/packages/sdk/helper/src/templates/template-assets.ts
@@ -0,0 +1,19 @@
+/**
+ * Asset loader for templates owned by dsh-helper.
+ *
+ * @module @deepseek-ai/dsh-helper/templates/template-assets
+ */
+
+import { TextTemplate } from './text-template.ts'
+
+/**
+ * Load one helper-owned template in source and bundled layouts.
+ * @param filename - basename under the helper template asset directory.
+ * @returns compiled typed template.
+ */
+export function loadHelperTemplate<TModel extends object>(filename: string): TextTemplate<TModel> {
+  if (filename.includes('/') || filename.includes('\\')) {
+    throw new Error(`helper template filename must not contain a directory: ${filename}`)
+  }
+  return TextTemplate.fromFile<TModel>(new URL(`./assets/${filename}`, import.meta.url))
+}
diff --git a/packages/sdk/helper/src/templates/text-template.ts b/packages/sdk/helper/src/templates/text-template.ts
new file mode 100644
index 0000000000..b5fa1652cc
--- /dev/null
+++ b/packages/sdk/helper/src/templates/text-template.ts
@@ -0,0 +1,44 @@
+/**
+ * Strict typed rendering for package-owned text templates.
+ *
+ * @module @deepseek-ai/dsh-helper/templates/text-template
+ */
+
+import { readFileSync } from 'node:fs'
+import Handlebars from 'handlebars'
+
+/** Strict Handlebars template with no HTML escaping or custom extensions. */
+export class TextTemplate<TModel extends object> {
+  private readonly renderer: Handlebars.TemplateDelegate<TModel>
+
+  /**
+   * Compile one template under the SDK's fixed rendering policy.
+   * @param source - complete template source.
+   */
+  constructor(source: string) {
+    const handlebars = Handlebars.create()
+    this.renderer = handlebars.compile<TModel>(source, {
+      strict: true,
+      noEscape: true,
+      preventIndent: true,
+    })
+  }
+
+  /**
+   * Load a template asset owned by the calling package.
+   * @param url - source or bundled asset URL.
+   * @returns compiled template.
+   */
+  static fromFile<T extends object>(url: URL): TextTemplate<T> {
+    return new TextTemplate<T>(readFileSync(url, 'utf8'))
+  }
+
+  /**
+   * Render text from one complete typed model.
+   * @param model - values referenced by the template.
+   * @returns rendered text.
+   */
+  render(model: TModel): string {
+    return this.renderer(model)
+  }
+}
diff --git a/packages/sdk/helper/tests/documents.spec.ts b/packages/sdk/helper/tests/documents.spec.ts
new file mode 100644
index 0000000000..5c7b483fa3
--- /dev/null
+++ b/packages/sdk/helper/tests/documents.spec.ts
@@ -0,0 +1,363 @@
+import { chmod, mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { CordisYamlFile, JsExpression } from '../src/documents/cordis-yaml-file.ts'
+import { EnvFile } from '../src/documents/env-file.ts'
+import { PackageJsonFile } from '../src/documents/package-json-file.ts'
+import { PnpmWorkspaceFile } from '../src/documents/pnpm-workspace-file.ts'
+import { TsConfigFile } from '../src/documents/tsconfig-file.ts'
+import { TextProjectFile, withTrailingNewline } from '../src/documents/project-file.ts'
+import { featureId, resourceKey } from '../src/ids.ts'
+import { LinkWorkspace } from '../src/package-managers/link-workspace.ts'
+import { LocalPluginBlueprint } from '../src/plugins/local-plugin-blueprint.ts'
+import {
+  NpmPackageManager,
+  NodeCommandRunner,
+  PnpmPackageManager,
+  YarnPackageManager,
+  createPackageManager,
+  inferPackageManagerName,
+  probePackageManagerVersion,
+  scrubEnvironment,
+  type CommandRunner,
+} from '../src/package-managers/package-manager.ts'
+import { createProjectArtifacts } from '../src/templates/project-template.ts'
+import { loadHelperTemplate } from '../src/templates/template-assets.ts'
+import { TextTemplate } from '../src/templates/text-template.ts'
+import { resolveNpmDependency } from '../src/project/npm-dependency-policy.ts'
+
+const temporary: string[] = []
+
+afterEach(async () => {
+  await Promise.all(temporary.splice(0).map(path => rm(path, { recursive: true, force: true })))
+})
+
+describe('structured project documents', () => {
+  it('normalizes trailing newlines and preserves managed package fields', () => {
+    expect(withTrailingNewline('a\n\n')).toBe('a\n')
+    const manifest = PackageJsonFile.parse('{"name":"demo","custom":1,"dependencies":{"z":"1"}}\n')
+    manifest.setScript('start', 'node index.js')
+    manifest.setNpmDependency('dependencies', 'a', '2')
+    manifest.setNpmDependency('devDependencies', 'typescript', '3')
+    manifest.removeNpmDependency('dependencies', 'z')
+    manifest.addWorkspace('plugins/*')
+    manifest.addWorkspace('plugins/*')
+    manifest.setPackageManager('pnpm@10.0.0')
+    manifest.setResolution('a', 'portal:../a')
+    manifest.validate()
+    expect(manifest.npmDependency('a')).toEqual({ section: 'dependencies', spec: '2' })
+    expect(manifest.npmDependencyNames()).toEqual(['a', 'typescript'])
+    expect(JSON.parse(manifest.serialize())).toMatchObject({
+      name: 'demo',
+      custom: 1,
+      dependencies: { a: '2' },
+      workspaces: ['plugins/*'],
+    })
+    manifest.setPackageManager(undefined)
+    expect(manifest.value().packageManager).toBeUndefined()
+    expect(() => PackageJsonFile.parse('[]')).toThrow('root must be an object')
+    expect(() => PackageJsonFile.parse('{')).toThrow('invalid package.json')
+    for (const [text, diagnostic] of [
+      ['{}', 'name must be'],
+      ['{"name":"x","scripts":null}', 'scripts must be an object'],
+      ['{"name":"x","dependencies":[]}', 'dependencies must be an object'],
+      ['{"name":"x","devDependencies":{"bad":""}}', 'must be a non-empty string'],
+      ['{"name":"x","workspaces":"bad"}', 'workspaces must be an array'],
+    ] as const) expect(() => { PackageJsonFile.parse(text).validate() }).toThrow(diagnostic)
+    const minimal = PackageJsonFile.parse('{"name":"x"}')
+    minimal.validate()
+    expect(minimal.npmDependency('missing')).toBeUndefined()
+    expect(minimal.serialize()).toBe('{\n  "name": "x"\n}\n')
+    expect(PackageJsonFile.parse('{"name":"x","devDependencies":{"a":"1"}}').npmDependencyNames()).toEqual(['a'])
+  })
+
+  it('round-trips Cordis comments and !!js while editing owned fields', () => {
+    const created = CordisYamlFile.create().clone()
+    created.addEntry({ id: 'created', name: 'created-package' })
+    expect(created.serialize()).toMatch(/^- id: created/m)
+    expect(created.serialize()).not.toMatch(/^\[/)
+    const flow = CordisYamlFile.parse('[{ id: flow, name: flow-package, config: { root: ./flow } }]\n')
+    expect(flow.serialize()).toContain('- id: flow\n  name: flow-package\n  config:\n    root: ./flow')
+    expect(flow.serialize()).not.toContain('{')
+    const document = CordisYamlFile.parse(`# lead
+- id: provider
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    custom: keep
+`)
+    const apiKey = document.entry('provider')?.config?.apiKey
+    expect(apiKey).toBeInstanceOf(JsExpression)
+    document.updateOwnedConfig('provider', ['apiKey'], { apiKey: new JsExpression('process.env.NEXT_KEY') })
+    document.setDisabled('provider', true)
+    document.addEntry({ id: 'tool', name: 'demo-tool' })
+    document.validate()
+    const text = document.serialize()
+    expect(text).toContain('# lead')
+    expect(text).toContain('!!js process.env.NEXT_KEY')
+    expect(text).toContain('custom: keep')
+    expect(document.removeEntry('tool')).toBe(true)
+    expect(document.removeEntry('tool')).toBe(false)
+    document.setDisabled('provider', false)
+    expect(document.entry('provider')?.disabled).toBeUndefined()
+    expect(() => { document.addEntry({ id: 'provider', name: 'duplicate' }) }).toThrow('already exists')
+    expect(() => CordisYamlFile.parse('{}')).toThrow('root must be a sequence')
+  })
+
+  it('rejects malformed Cordis config entries and missing mutation targets', () => {
+    expect(() => new JsExpression(' ')).toThrow('must not be empty')
+    expect(() => CordisYamlFile.parse('[')).toThrow('invalid cordis.yml')
+    for (const [text, diagnostic] of [
+      ['- nope\n', 'every entry must be a mapping'],
+      ['- name: pkg\n', 'id must be'],
+      ['- id: x\n', 'name must be'],
+      ['- id: x\n  name: pkg\n  config: nope\n', 'config must be'],
+      ['- id: x\n  name: pkg\n  disabled: nope\n', 'disabled must be'],
+    ] as const) expect(() => CordisYamlFile.parse(text).entries()).toThrow(diagnostic)
+    const duplicate = CordisYamlFile.parse('- id: x\n  name: one\n- id: x\n  name: two\n')
+    expect(() => { duplicate.validate() }).toThrow('duplicate Cordis config entry id')
+    const document = CordisYamlFile.create()
+    expect(() => { document.setDisabled('missing', true) }).toThrow('does not exist')
+    expect(() => { document.updateOwnedConfig('missing', [], {}) }).toThrow('does not exist')
+    document.addEntry({ id: 'plain', name: 'pkg' })
+    document.updateOwnedConfig('plain', [], { value: 1 })
+    expect(document.entry('plain')?.config).toEqual({ value: 1 })
+    document.updateOwnedConfig('plain', ['value'], {})
+    expect(document.entry('plain')?.config).toBeUndefined()
+    const scalar = CordisYamlFile.parse('- id: plain\n  name: pkg\n  config: value\n')
+    expect(() => { scalar.updateOwnedConfig('plain', [], {}) }).toThrow('config is not a mapping')
+    expect(() => { CordisYamlFile.parse('- nope\n').setDisabled('missing', true) }).toThrow('does not exist')
+  })
+
+  it('keeps .env append-only while managing .env.example strictly', () => {
+    const document = EnvFile.parse('.env', '# keep\nA=1\nexport B=2\n')
+    expect(document.get('A')).toBe('1')
+    expect(document.get('B')).toBe('2')
+    expect(document.append('A', 'next')).toBe(false)
+    expect(document.append('C', '', 'Required')).toBe(true)
+    expect(document.serialize()).toBe('# keep\nA=1\nexport B=2\n# Required\nC=\n')
+    expect(() => { document.append('bad-name', 'x') }).toThrow('invalid environment variable')
+    expect(() => { document.append('D', '', '') }).toThrow('non-empty line')
+    expect(() => { document.append('D', '', 'bad\ncomment') }).toThrow('non-empty line')
+    expect(() => { document.set('A', 'next') }).toThrow('.env is append-only')
+    expect(() => { document.remove('A') }).toThrow('.env is append-only')
+    const duplicateEnv = EnvFile.parse('.env', 'A=1\nA=2\n')
+    expect(duplicateEnv.get('A')).toBe('2')
+    expect(duplicateEnv.append('A', 'next')).toBe(false)
+    expect(() => { duplicateEnv.validate() }).not.toThrow()
+
+    const example = EnvFile.parse('.env.example', '# keep\nA=1\n')
+    example.set('A', 'next')
+    example.set('C', '')
+    example.remove('C')
+    expect(example.serialize()).toBe('# keep\nA=next\n')
+    expect(() => { example.append('C', '') }).toThrow('.env.example is SDK-managed')
+    expect(() => { example.set('bad-name', 'x') }).toThrow('invalid environment variable')
+    const duplicate = EnvFile.parse('.env.example', 'A=1\nA=2\n')
+    expect(() => { duplicate.validate() }).toThrow('duplicate variable A')
+    expect(() => duplicate.get('A')).toThrow('duplicate variable A')
+    expect(() => { duplicate.set('A', 'next') }).toThrow('duplicate variable A')
+    expect(() => { duplicate.remove('A') }).toThrow('duplicate variable A')
+    example.remove('missing')
+    expect(document.get('missing')).toBeUndefined()
+    expect(EnvFile.parse('.env', '').clone().serialize()).toBe('\n')
+  })
+
+  it('patches JSONC references without erasing comments', () => {
+    const document = TsConfigFile.parse(`{
+  // retained
+  "references": [{ "path": "./plugins/a" }]
+}`)
+    document.addReference('./plugins/a')
+    document.addReference('./plugins/b')
+    document.validate()
+    expect(document.serialize()).toContain('// retained')
+    expect(document.serialize()).toContain('./plugins/b')
+    expect(() => TsConfigFile.parse('{')).toThrow('valid JSONC object')
+    const malformed = TsConfigFile.parse('{"references": {}}')
+    expect(() => { malformed.addReference('./plugins/x') }).toThrow('must be an array')
+    const badItem = TsConfigFile.parse('{"references":[null]}')
+    expect(() => { badItem.addReference('./plugins/x') }).toThrow('must contain')
+    expect(() => { badItem.validate() }).toThrow('must contain')
+    const created = TsConfigFile.create()
+    created.validate()
+    expect(created.clone().serialize()).toContain('"references": []')
+    TsConfigFile.parse('{}').validate()
+    const noReferences = TsConfigFile.parse('{}')
+    noReferences.addReference('./plugin')
+    expect(noReferences.serialize()).toContain('./plugin')
+    expect(() => { TsConfigFile.parse('{"references":{}}').validate() }).toThrow('must be an array')
+  })
+
+  it('creates and parses pnpm workspace policy', () => {
+    const document = PnpmWorkspaceFile.create()
+    document.addPackage('plugins/*')
+    document.disableAutoInstallPeers()
+    document.validate()
+    expect(document.serialize()).toContain('autoInstallPeers: false')
+    const parsed = PnpmWorkspaceFile.parse(document.serialize())
+    expect(parsed.clone().serialize()).toBe(document.serialize())
+    expect(() => PnpmWorkspaceFile.parse('packages: nope')).toThrow('packages must be an array')
+    expect(() => PnpmWorkspaceFile.parse('[]')).toThrow('root must be an object')
+    expect(() => PnpmWorkspaceFile.parse('packages: []\nautoInstallPeers: nope')).toThrow('must be boolean')
+    const invalid = PnpmWorkspaceFile.create()
+    invalid.addPackage(' ')
+    expect(() => { invalid.validate() }).toThrow('must not be empty')
+    expect(PnpmWorkspaceFile.parse('packages: []\n').serialize()).not.toContain('autoInstallPeers')
+  })
+
+  it('renders strict complete-file templates without escaping code text', () => {
+    const template = new TextTemplate<{ value: string }>('value={{value}} missing={{missing}}')
+    expect(() => template.render({ value: '<code>' })).toThrow()
+    const valid = new TextTemplate<{ value: string }>('value={{value}}')
+    expect(valid.render({ value: '<code>' })).toBe('value=<code>')
+    expect(new TextTemplate<Record<string, never>>('\\{{model}}').render({})).toBe('{{model}}')
+    expect(() => new TextProjectFile('/absolute', 'x')).toThrow('stay inside')
+    expect(() => new TextProjectFile('../outside', 'x')).toThrow('stay inside')
+    expect(new TextProjectFile('inside', 'x').clone().serialize()).toBe('x\n')
+    expect(() => featureId('Bad Id')).toThrow('invalid feature id')
+    expect(() => resourceKey('')).toThrow('must not be empty')
+    expect(() => loadHelperTemplate('../bad.tpl')).toThrow('must not contain a directory')
+    expect(createProjectArtifacts({
+      name: 'demo', description: 'demo', releaseVersion: '0.0.1', model: 'model', modelLiteral: '"model"', packageManager: 'yarn',
+      isAcp: false, isStdio: false, isEmbed: true,
+      installArgs: 'install', buildArgs: 'build',
+    }).map(document => document.relativePath)).toContain('.yarnrc.yml')
+    expect(() => new LocalPluginBlueprint('---', 'plugin')).toThrow('invalid local plugin name')
+    expect(new LocalPluginBlueprint('tool', 'tool').packageName('@scope/project')).toBe('@scope/project-tool')
+    expect(new LocalPluginBlueprint('tool', 'tool').packageName('@invalid')).toBe('@invalid-tool')
+  })
+})
+
+describe('package manager strategies', () => {
+  it('owns workspace fields, execution commands, and supported version floors', () => {
+    const npm = new NpmPackageManager('10.1.0')
+    const pnpm = new PnpmPackageManager('10.2.0')
+    const yarn = new YarnPackageManager('4.0.0')
+    for (const manager of [npm, pnpm, yarn]) manager.validateVersion()
+    expect(npm.localPluginSpec()).toBe('*')
+    expect(npm.linkSpec('../x')).toBe('file:../x')
+    expect(npm.configureWorkspace(PackageJsonFile.create('{"name":"demo"}'))).toEqual([])
+    const pnpmManifest = PackageJsonFile.create('{"name":"demo"}')
+    expect(pnpm.configureWorkspace(pnpmManifest)[0]).toBeInstanceOf(PnpmWorkspaceFile)
+    expect(pnpm.localPluginSpec()).toBe('workspace:*')
+    expect(pnpm.linkSpec('../x')).toBe('link:../x')
+    const yarnManifest = PackageJsonFile.create('{"name":"demo"}')
+    expect(yarn.configureWorkspace(yarnManifest)).toEqual([])
+    expect(yarn.localPluginSpec()).toBe('workspace:*')
+    expect(yarn.linkSpec('../x')).toBe('portal:../x')
+    expect(yarn.buildCommand()).toEqual(['build'])
+    expect(npm.installCommand()).toEqual(['install'])
+    expect(npm.buildCommand()).toEqual(['run', 'build'])
+    expect(() => createPackageManager('npm', '9.0.0')).toThrow('npm >=10')
+    expect(() => createPackageManager('pnpm', '9.0.0')).toThrow('pnpm >=10')
+    expect(() => createPackageManager('yarn', '1.22.0')).toThrow('Yarn >=2')
+    expect(inferPackageManagerName(undefined, 'pnpm/10.0.0 node/v24')).toBe('pnpm')
+    expect(inferPackageManagerName(undefined, 'unknown/1')).toBeUndefined()
+    expect(inferPackageManagerName('yarn', undefined)).toBe('yarn')
+    expect(() => createPackageManager('npm', 'invalid')).toThrow('invalid package manager version')
+    expect(resolveNpmDependency('cordis', 'devDependencies', '0.0.1')).toEqual({
+      section: 'devDependencies', spec: '^4.0.0-rc.7',
+    })
+    expect(resolveNpmDependency('@cordisjs/plugin-hmr', 'dependencies', '0.0.1').spec).toBe('^1.0.15')
+    expect(resolveNpmDependency('@deepseek-ai/dsh-tools', 'dependencies', '1.2.3').spec).toBe('^1.2.3')
+    expect(() => resolveNpmDependency('unknown', 'dependencies', '0.0.1')).toThrow('no generated-project')
+  })
+
+  it('checks install/build process outcomes and scrubs credential-shaped names', async () => {
+    const calls: string[][] = []
+    const runner: CommandRunner = {
+      run: async (command, args) => {
+        calls.push([command, ...args])
+        return { exitCode: 0, signal: null }
+      },
+    }
+    const npm = new NpmPackageManager('10.0.0')
+    await npm.install('/tmp', runner)
+    await npm.build('/tmp', runner)
+    expect(calls).toEqual([['npm', 'install'], ['npm', 'run', 'build']])
+    const failed: CommandRunner = { run: async () => ({ exitCode: 2, signal: null }) }
+    await expect(npm.install('/tmp', failed)).rejects.toThrow('exited with code 2')
+    const killed: CommandRunner = { run: async () => ({ exitCode: null, signal: 'SIGTERM' }) }
+    await expect(npm.build('/tmp', killed)).rejects.toThrow('killed by SIGTERM')
+    expect(scrubEnvironment({ PATH: '/bin', API_KEY: 'secret', TOKEN_VALUE: 'secret' })).toEqual({ PATH: '/bin' })
+  })
+
+  it('probes versions and runs real child-process boundaries', async () => {
+    await expect(probePackageManagerVersion('npm', process.cwd())).resolves.toMatch(/^\d+/)
+    await expect(probePackageManagerVersion('npm', '/missing/dsh-cwd')).rejects.toThrow('cannot run npm --version')
+    const root = await mkdtemp(join(tmpdir(), 'dsh-empty-version-'))
+    temporary.push(root)
+    const executable = join(root, 'npm')
+    await writeFile(executable, '#!/bin/sh\nexit 0\n')
+    await chmod(executable, 0o755)
+    const before = process.env.PATH
+    process.env.PATH = root
+    await expect(probePackageManagerVersion('npm', root)).rejects.toThrow('empty version output')
+    process.env.PATH = before
+    const runner = new NodeCommandRunner()
+    await expect(runner.run(process.execPath, ['-e', ''], root)).resolves.toEqual({ exitCode: 0, signal: null })
+    await expect(runner.run('missing-dsh-command', [], root)).rejects.toThrow()
+  })
+
+  it('discovers and rewrites a repository-local NPM dependency closure', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-link-workspace-'))
+    temporary.push(root)
+    await mkdir(join(root, 'vendor', 'cordis'), { recursive: true })
+    await mkdir(join(root, 'packages', 'sdk', 'scripts'), { recursive: true })
+    await mkdir(join(root, 'packages', 'sdk', 'helper'), { recursive: true })
+    await writeFile(join(root, 'vendor', 'cordis', 'package.json'), JSON.stringify({ name: 'cordis' }))
+    await writeFile(join(root, 'packages', 'sdk', 'helper', 'package.json'), JSON.stringify({ name: '@deepseek-ai/dsh-helper' }))
+    await writeFile(join(root, 'packages', 'sdk', 'scripts', 'package.json'), JSON.stringify({
+      name: '@deepseek-ai/dsh-scripts', dependencies: { '@deepseek-ai/dsh-helper': '^0.0.1' }, peerDependencies: { cordis: '^4' },
+    }))
+    const workspace = await LinkWorkspace.open(root)
+    expect(workspace.closure(['@deepseek-ai/dsh-scripts'])).toEqual([
+      '@deepseek-ai/dsh-helper', '@deepseek-ai/dsh-scripts', 'cordis',
+    ])
+    const manifest = PackageJsonFile.create('{"name":"consumer","description":"test"}')
+    manifest.setNpmDependency('dependencies', '@deepseek-ai/dsh-scripts', '^0.0.1')
+    const pnpmWorkspace = PnpmWorkspaceFile.create()
+    workspace.apply(join(root, 'consumer'), manifest, new PnpmPackageManager('10.0.0'), [pnpmWorkspace])
+    expect(manifest.npmDependency('cordis')?.spec).toMatch(/^link:/)
+    expect(pnpmWorkspace.serialize()).toContain('autoInstallPeers: false')
+    expect(workspace.packageDirectory('cordis')).toBe(join(root, 'vendor', 'cordis'))
+    expect(await readFile(join(root, 'vendor', 'cordis', 'package.json'), 'utf8')).toContain('cordis')
+    expect(workspace.packageDirectory('missing')).toBeUndefined()
+    const yarnManifest = PackageJsonFile.create('{"name":"consumer"}')
+    yarnManifest.setNpmDependency('dependencies', '@deepseek-ai/dsh-scripts', '^0.0.1')
+    workspace.apply(join(root, 'consumer-yarn'), yarnManifest, new YarnPackageManager('4.0.0'), [])
+    expect(yarnManifest.value().resolutions).toBeDefined()
+    const pnpmManifest = PackageJsonFile.create('{"name":"consumer"}')
+    pnpmManifest.setNpmDependency('dependencies', '@deepseek-ai/dsh-scripts', '^0.0.1')
+    expect(() => { workspace.apply(join(root, 'consumer-pnpm'), pnpmManifest, new PnpmPackageManager('10.0.0'), []) })
+      .toThrow('requires pnpm-workspace.yaml')
+  })
+
+  it('rejects malformed linked repositories', async () => {
+    const missing = await mkdtemp(join(tmpdir(), 'dsh-link-missing-'))
+    temporary.push(missing)
+    await mkdir(join(missing, 'vendor'), { recursive: true })
+    await mkdir(join(missing, 'packages'), { recursive: true })
+    await expect(LinkWorkspace.open(missing)).rejects.toThrow('not a DeepSeek Harness repository root')
+    const unreadable = await mkdtemp(join(tmpdir(), 'dsh-link-unreadable-'))
+    temporary.push(unreadable)
+    await mkdir(join(unreadable, 'vendor', 'bad'), { recursive: true })
+    await mkdir(join(unreadable, 'packages'), { recursive: true })
+    await expect(LinkWorkspace.open(unreadable)).rejects.toThrow('cannot read linked package')
+    const unnamed = await mkdtemp(join(tmpdir(), 'dsh-link-unnamed-'))
+    temporary.push(unnamed)
+    await mkdir(join(unnamed, 'vendor', 'unnamed'), { recursive: true })
+    await mkdir(join(unnamed, 'packages'), { recursive: true })
+    await writeFile(join(unnamed, 'vendor', 'unnamed', 'package.json'), '{}')
+    await expect(LinkWorkspace.open(unnamed)).rejects.toThrow('not a DeepSeek Harness repository root')
+    const duplicate = await mkdtemp(join(tmpdir(), 'dsh-link-duplicate-'))
+    temporary.push(duplicate)
+    await mkdir(join(duplicate, 'vendor', 'one'), { recursive: true })
+    await mkdir(join(duplicate, 'packages', 'group', 'two'), { recursive: true })
+    await writeFile(join(duplicate, 'vendor', 'one', 'package.json'), '{"name":"duplicate"}')
+    await writeFile(join(duplicate, 'packages', 'group', 'two', 'package.json'), '{"name":"duplicate"}')
+    await expect(LinkWorkspace.open(duplicate)).rejects.toThrow('duplicate linked package name')
+  })
+})
diff --git a/packages/sdk/helper/tests/project.spec.ts b/packages/sdk/helper/tests/project.spec.ts
new file mode 100644
index 0000000000..a565c6998b
--- /dev/null
+++ b/packages/sdk/helper/tests/project.spec.ts
@@ -0,0 +1,855 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  FeatureOption,
+  ExclusiveOptionFeature,
+  MultiOptionFeature,
+  FixedFeature,
+  type FeatureProjectView,
+} from '../src/features/feature.ts'
+import { createBuiltinRegistry } from '../src/features/builtin/index.ts'
+import {
+  npmCordisConfigEntry,
+  cordisConfigEntry,
+  environment as environmentResource,
+  optionalString,
+  ownedTextFile,
+  requiredString,
+  stringArray,
+} from '../src/features/builtin/helpers.ts'
+import { defineFeatures, defineFeature } from '../src/features/define-feature.ts'
+import { FeatureRegistry } from '../src/features/registry.ts'
+import { ProjectContribution } from '../src/features/resources.ts'
+import type { CordisConfigEntryResource, ProjectResource } from '../src/features/resources.ts'
+import type { CordisConfigEntry } from '../src/documents/cordis-yaml-file.ts'
+import { TextProjectFile } from '../src/documents/project-file.ts'
+import { featureId, resourceKey } from '../src/ids.ts'
+import { NpmPackageManager } from '../src/package-managers/package-manager.ts'
+import { LocalPluginBlueprint } from '../src/plugins/local-plugin-blueprint.ts'
+import { SdkProject } from '../src/project/sdk-project.ts'
+import type {
+  FeatureSelection,
+  ProjectCreationRequest,
+  ProjectProfile,
+} from '../src/project/types.ts'
+
+const temporary: string[] = []
+const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
+
+afterEach(async () => {
+  await Promise.all(temporary.splice(0).map(path => rm(path, { recursive: true, force: true })))
+})
+
+function selection(id: string, options: readonly string[], secrets?: Record<string, string>): FeatureSelection {
+  return { id: featureId(id), options, ...secrets ? { secrets } : {} }
+}
+
+function request(
+  extra: readonly FeatureSelection[] = [],
+  plugins: readonly LocalPluginBlueprint[] = [],
+  app: 'acp' | 'stdio' | 'embed' = 'stdio',
+): ProjectCreationRequest {
+  return {
+    name: 'test-agent',
+    description: 'test project',
+    runtime: { model: 'deepseek-v4-flash' },
+    packageManager: new NpmPackageManager('10.0.0'),
+    releaseVersion: '0.0.1',
+    features: [
+      selection('provider', ['deepseek'], { apiKey: 'test-key' }),
+      selection('bash', ['local']),
+      selection('app', [app]),
+      selection('persistence', ['jsonl']),
+      ...extra,
+    ],
+    localPlugins: plugins,
+  }
+}
+
+async function createCommitted(
+  extra: readonly FeatureSelection[] = [],
+  plugins: readonly LocalPluginBlueprint[] = [],
+): Promise<SdkProject> {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-project-domain-'))
+  temporary.push(root)
+  const creation = request(extra, plugins)
+  const project = SdkProject.create(root, creation)
+  const registry = createBuiltinRegistry(project.profile)
+  const edit = project.edit(registry)
+  for (const item of creation.features) edit.installFeature(registry.get(item.id), item)
+  for (const plugin of plugins) edit.addPlugin(plugin)
+  return (await edit.commit()).project
+}
+
+describe('SdkProject and ProjectEditSession', () => {
+  it('derives existing-project profiles and tolerates malformed optional documents', async () => {
+    const make = async (
+      name: string,
+      manifest: Record<string, unknown>,
+      cordis: string,
+      extras: Record<string, string> = {},
+    ): Promise<SdkProject> => {
+      const root = await mkdtemp(join(tmpdir(), `${name}-`))
+      temporary.push(root)
+      await writeFile(join(root, 'package.json'), JSON.stringify(manifest))
+      await writeFile(join(root, 'cordis.yml'), cordis)
+      for (const [path, text] of Object.entries(extras)) await writeFile(join(root, path), text)
+      return SdkProject.open(root)
+    }
+    const acp = await make('dsh-open-acp', {
+      name: 'acp', description: 'ACP', packageManager: 'pnpm@10.1.0',
+      dependencies: { '@deepseek-ai/dsh-scripts': '^1.2.3' },
+    }, `- id: acp
+  name: '@deepseek-ai/dsh-acp'
+  config: { model: app-model }
+`, { '.env': 'KEY=value\n', 'tsconfig.json': '{bad', 'pnpm-workspace.yaml': 'bad' })
+    expect(acp.profile).toMatchObject({
+      runInterface: 'acp', runtime: { model: 'app-model' }, releaseVersion: '1.2.3', description: 'ACP',
+    })
+    expect(acp.profile.packageManager.name).toBe('pnpm')
+    expect(acp.readEnvironment('.env', 'KEY')).toBe('value')
+    expect(() => acp.readEnvironment('.env.example', 'KEY')).not.toThrow()
+    expect(acp.document('tsconfig.json')).toBeInstanceOf(TextProjectFile)
+    const stdio = await make('dsh-open-stdio', {}, `- id: provider
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config: { models: [provider-model] }
+- id: stdio
+  name: '@deepseek-ai/dsh-stdio'
+`, { 'yarn.lock': '' })
+    expect(stdio.profile.runInterface).toBe('stdio')
+    expect(stdio.profile.runtime.model).toBe('provider-model')
+    expect(stdio.profile.packageManager.name).toBe('yarn')
+    expect(stdio.profile.name).toBe(stdio.root.split('/').at(-1))
+    const pnpm = await make('dsh-open-pnpm', { name: 'pnpm' }, '[]\n', { 'pnpm-lock.yaml': '' })
+    expect(pnpm.profile.packageManager.name).toBe('pnpm')
+    const defaults = await make('dsh-open-default', { name: 'default', packageManager: 'npm@10.0.0' }, '[]\n')
+    expect(defaults.profile).toMatchObject({
+      runInterface: 'embed', runtime: { model: 'deepseek-v4-flash' }, releaseVersion: '0.0.1',
+    })
+    expect(() => SdkProject.create(defaults.root, { ...request(), features: [] })).toThrow('requires one app')
+    await expect(make('dsh-open-invalid-manager', { name: 'bad', packageManager: 'bad' }, '[]\n'))
+      .rejects.toThrow('invalid packageManager field')
+    const providerFallback = await make('dsh-open-provider-fallback', { name: 'fallback' }, `- id: stdio
+  name: '@deepseek-ai/dsh-stdio'
+  config: { model: '' }
+- id: provider
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config: { models: [fallback-model] }
+`)
+    expect(providerFallback.profile.runtime.model).toBe('fallback-model')
+    const pnpmRequest = { ...request(), packageManager: new (await import('../src/package-managers/package-manager.ts')).PnpmPackageManager('10.0.0') }
+    expect(SdkProject.create(join(defaults.root, 'pnpm'), pnpmRequest).hasDocument('pnpm-workspace.yaml')).toBe(true)
+  })
+
+  it('commits a complete blueprint and round-trips every installed feature', async () => {
+    const project = await createCommitted([
+      selection('hmr', ['default']),
+      selection('fs', ['local']),
+      selection('todo', ['default']),
+      selection('web', ['exa'], { apiKey: 'exa-key' }),
+      selection('subagent', ['fork']),
+      selection('workflow', ['workerthread']),
+      selection('hooks', ['claude', 'codex']),
+    ], [new LocalPluginBlueprint('sample', 'plugin'), new LocalPluginBlueprint('lookup', 'tool')])
+    const registry = createBuiltinRegistry(project.profile)
+    const inspections = registry.inspect(project)
+    expect(inspections.filter(item => item.state === 'enabled').map(item => item.id)).toEqual([
+      'provider', 'spine', 'bash', 'app', 'persistence', 'hmr', 'fs', 'todo', 'web', 'subagent', 'workflow', 'hooks',
+    ])
+    expect(inspections.find(item => item.id === 'subagent')?.options).toEqual(['spawn', 'fork'])
+    expect(project.cordisConfigEntries().map(entry => entry.id)).toContain('lookup')
+    const index = await readFile(join(project.root, 'index.ts'), 'utf8')
+    expect(index).toContain('SdkBootContext')
+    expect(index).toContain('agents.create')
+    expect(index).toContain('boot.args.resume')
+    expect(project.packageManifest().scripts).toEqual({
+      dev: 'dsh dev index.ts -- --model="deepseek-v4-flash"',
+      build: 'dsh build',
+      typecheck: 'tsc -b',
+      start: 'dsh start index.js -- --model="deepseek-v4-flash"',
+      config: 'dsh config',
+    })
+    expect(await readFile(join(project.root, '.env.example'), 'utf8')).toContain('EXA_API_KEY=')
+    expect(project.cordis.entry('stdio')?.config).toMatchObject({ agent: 'main' })
+    expect(project.cordis.entry('stdio')?.config).not.toHaveProperty('model')
+    expect(project.cordis.entry('agent-loop')?.config).toEqual({ agents: [] })
+    expect(project.cordis.entry('system-prompt')?.config?.persona).toContain('{{cwd}}')
+    expect(project.packageManifest().dependencies?.['@cordisjs/plugin-timer']).toBe('^1.1.2')
+    expect(project.packageManifest().dependencies?.['@cordisjs/plugin-hmr']).toBe('^1.0.15')
+    expect(project.packageManifest().dependencies).not.toHaveProperty('node-addon-require-builtin')
+    expect(project.cordis.entry('hmr')).toMatchObject({ name: '@cordisjs/plugin-hmr' })
+    expect(project.cordis.entry('llm-deepseek')?.config).not.toHaveProperty('baseURL')
+    expect(project.cordis.entry('llm-deepseek')?.config).not.toHaveProperty('models')
+  })
+
+  it('round-trips embed app projects without a front-door Cordis config entry', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-embed-app-'))
+    temporary.push(root)
+    const creation = request([], [], 'embed')
+    const project = SdkProject.create(root, creation)
+    const registry = createBuiltinRegistry(project.profile)
+    const edit = project.edit(registry)
+    for (const item of creation.features) edit.installFeature(registry.get(item.id), item)
+    const committed = (await edit.commit()).project
+    const app = createBuiltinRegistry(committed.profile).get(featureId('app')).inspect(committed)
+    expect(app).toMatchObject({ state: 'enabled', options: ['embed'] })
+    expect(app.selection).toEqual(selection('app', ['embed']))
+    expect(committed.cordis.entry('agent-loop')?.config).toEqual({ agents: [] })
+    expect(committed.cordis.entry('acp')).toBeUndefined()
+    expect(committed.cordis.entry('stdio')).toBeUndefined()
+  })
+
+  it('round-trips the custom pi-ai provider with explicit endpoint and default model', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-custom-provider-'))
+    temporary.push(root)
+    const base = request()
+    const creation: ProjectCreationRequest = {
+      ...base,
+      features: [
+        {
+          id: featureId('provider'),
+          options: ['custom'],
+          values: { baseURL: 'https://custom.example/v1' },
+          secrets: { apiKey: 'custom-key' },
+        },
+        ...base.features.filter(item => item.id !== 'provider'),
+      ],
+    }
+    const project = SdkProject.create(root, creation)
+    const registry = createBuiltinRegistry(project.profile)
+    const edit = project.edit(registry)
+    for (const item of creation.features) edit.installFeature(registry.get(item.id), item)
+    const committed = (await edit.commit()).project
+    expect(committed.cordis.entry('llm-pi-ai')).toMatchObject({
+      name: '@deepseek-ai/dsh-llm-pi-ai',
+      config: { baseURL: 'https://custom.example/v1' },
+    })
+    expect(committed.cordis.entry('llm-pi-ai')?.config).not.toHaveProperty('models')
+    expect(createBuiltinRegistry(committed.profile).get(featureId('provider')).inspect(committed)).toMatchObject({
+      state: 'enabled', options: ['custom'],
+    })
+  })
+
+  it('switches exclusive options and refuses disabling a required feature', async () => {
+    const project = await createCommitted([selection('subagent', ['spawn']), selection('workflow', ['workerthread'])])
+    const registry = createBuiltinRegistry(project.profile)
+    const edit = project.edit(registry)
+    const persistence = registry.get(featureId('persistence'))
+    edit.configureFeature(persistence, selection('persistence', ['sqlite']))
+    expect(() => { edit.disableFeature(registry.get(featureId('subagent'))) }).toThrow('required by workflow')
+    expect(() => { edit.disableFeature(registry.get(featureId('app'))) }).toThrow('required feature')
+    const committed = await edit.commit()
+    expect(committed.project.cordis.entry('session-persistence')?.name).toContain('sqlite')
+    expect(committed.changes.npmDependenciesChanged).toBe(true)
+  })
+
+  it('supports disabled feature reconfiguration and rejects invalid state operations', async () => {
+    const project = await createCommitted([selection('todo', ['default'])])
+    const registry = createBuiltinRegistry(project.profile)
+    const edit = project.edit(registry)
+    expect(edit.inspections()).not.toHaveLength(0)
+    const todo = registry.get(featureId('todo'))
+    edit.configureFeature(registry.get(featureId('web')), selection('web', ['deepseek']))
+    edit.disableFeature(todo)
+    edit.configureFeature(todo, selection('todo', ['default']))
+    edit.enableFeature(todo)
+    expect(() => { edit.enableFeature(registry.get(featureId('ask-user'))) }).toThrow('not installed')
+    expect(() => { edit.disableFeature(registry.get(featureId('ask-user'))) }).toThrow('not installed')
+    expect(() => { edit.setCustomPluginDisabled('missing', true) }).toThrow('does not exist')
+    const committed = await edit.commit()
+    expect(committed.changes.enabledFeatures).toContain('todo')
+    expect(() => { edit.enableFeature(todo) }).toThrow('already committed')
+  })
+
+  it('preserves custom entries and toggles only their Loader disabled state', async () => {
+    const project = await createCommitted([], [new LocalPluginBlueprint('sample', 'plugin')])
+    const registry = createBuiltinRegistry(project.profile)
+    const edit = project.edit(registry)
+    edit.setCustomPluginDisabled('sample', true)
+    expect(edit.cordisConfigEntries().find(entry => entry.id === 'sample')?.disabled).toBe(true)
+    expect(() => { edit.setCustomPluginDisabled('stdio', true) }).toThrow('builtin feature')
+    const next = (await edit.commit()).project
+    const enable = next.edit(createBuiltinRegistry(next.profile))
+    enable.setCustomPluginDisabled('sample', false)
+    expect((await enable.commit()).project.cordis.entry('sample')?.disabled).toBeUndefined()
+  })
+
+  it('rejects local plugin collisions and invalid optional document shapes', async () => {
+    const project = await createCommitted([], [new LocalPluginBlueprint('sample', 'plugin')])
+    const registry = createBuiltinRegistry(project.profile)
+    const npmDependencyConflict = project.edit(registry)
+    expect(() => { npmDependencyConflict.addPlugin(new LocalPluginBlueprint('sample', 'plugin')) })
+      .toThrow('NPM dependency already exists')
+    await writeFile(join(project.root, 'tsconfig.json'), 'not-json\n')
+    const malformed = await SdkProject.open(project.root)
+    expect(() => { malformed.edit(createBuiltinRegistry(malformed.profile)).addPlugin(
+      new LocalPluginBlueprint('other', 'plugin'),
+    ) }).toThrow('requires a valid tsconfig')
+    const entryProject = await createCommitted()
+    const entryEdit = entryProject.edit(createBuiltinRegistry(entryProject.profile))
+    ;(entryEdit as unknown as { cordis(): { addEntry(entry: CordisConfigEntry): void } }).cordis()
+      .addEntry({ id: 'sample', name: 'manual' })
+    expect(() => { entryEdit.addPlugin(new LocalPluginBlueprint('sample', 'plugin')) }).toThrow('entry already exists')
+    const fileEdit = entryProject.edit(createBuiltinRegistry(entryProject.profile))
+    ;(fileEdit as unknown as { documents: Map<string, TextProjectFile> }).documents
+      .set('plugins/other/package.json', new TextProjectFile('plugins/other/package.json', '{}'))
+    expect(() => { fileEdit.addPlugin(new LocalPluginBlueprint('other', 'plugin')) }).toThrow('file already exists')
+  })
+
+  it('reinstalls existing/disabled features and detects requirement cycles', async () => {
+    const project = await createCommitted([selection('todo', ['default']), selection('subagent', ['spawn'])])
+    const registry = createBuiltinRegistry(project.profile)
+    const edit = project.edit(registry)
+    const todo = registry.get(featureId('todo'))
+    edit.installFeature(todo, selection('todo', ['default']))
+    edit.disableFeature(todo)
+    edit.installFeature(todo, selection('todo', ['default']))
+    const subagent = registry.get(featureId('subagent'))
+    edit.disableFeature(subagent)
+    edit.installFeature(registry.get(featureId('workflow')), selection('workflow', ['workerthread']))
+    expect(edit.cordisConfigEntries().find(entry => entry.id === 'subagent-spawn')?.disabled).toBeUndefined()
+
+    class Cyclic extends FixedFeature {
+      override readonly summary = 'cyclic'
+      override readonly options = [new (class extends FeatureOption {
+        override readonly id = 'one'
+        override readonly label = 'One'
+        override contribution(): ProjectContribution { return new ProjectContribution([]) }
+      })()]
+      override readonly id
+      override readonly requires
+      constructor(id: string, required: string) {
+        super()
+        this.id = featureId(id)
+        this.requires = [featureId(required)]
+      }
+    }
+    const one = new Cyclic('cycle-one', 'cycle-two')
+    const two = new Cyclic('cycle-two', 'cycle-one')
+    const cycleRegistry = new FeatureRegistry([one, two], project.profile)
+    expect(() => { project.edit(cycleRegistry).installFeature(one, selection('cycle-one', ['one'])) })
+      .toThrow('cyclic feature requirement')
+  })
+
+  it('removes clean owned files and detects files disappearing before commit', async () => {
+    const project = await createCommitted([selection('hooks', ['claude', 'codex']), selection('todo', ['default'])])
+    const registry = createBuiltinRegistry(project.profile)
+    const remove = project.edit(registry)
+    remove.configureFeature(registry.get(featureId('hooks')), selection('hooks', ['codex']))
+    const committed = await remove.commit()
+    expect(committed.changes.changedFiles).toContain('hooks.json')
+    const edit = committed.project.edit(createBuiltinRegistry(committed.project.profile))
+    edit.disableFeature(createBuiltinRegistry(committed.project.profile).get(featureId('todo')))
+    await rm(join(committed.project.root, 'cordis.yml'))
+    await expect(edit.commit()).rejects.toThrow('cannot verify project file cordis.yml')
+  })
+
+  it('guards internal resource collisions and malformed aggregate documents', async () => {
+    const project = await createCommitted()
+    const registry = createBuiltinRegistry(project.profile)
+    const edit = project.edit(registry)
+    type Internals = {
+      documents: Map<string, TextProjectFile>
+      applyResource(resource: ProjectResource, previous: ProjectResource | undefined): void
+      removeResource(resource: ProjectResource): void
+      replaceContribution(previous: ProjectContribution | undefined, next: ProjectContribution): void
+      manifest(): unknown
+      cordis(): unknown
+      environment(path: '.env' | '.env.example'): unknown
+      state(feature: FixedFeature): unknown
+    }
+    const internals = edit as unknown as Internals
+    const collidingEntry: ProjectResource = {
+      kind: 'cordis-config-entry', key: resourceKey('cordis-config-entry:stdio'),
+      entry: { id: 'stdio', name: 'other-package' }, ownedConfigKeys: [],
+    }
+    expect(() => { internals.applyResource(collidingEntry, undefined) }).toThrow('is owned by')
+    const existingFile: ProjectResource = {
+      kind: 'owned-file', key: resourceKey('file:tsconfig.json'),
+      document: new TextProjectFile('tsconfig.json', 'replacement'), removeOnlyWhenUnchanged: true,
+    }
+    expect(() => { internals.applyResource(existingFile, undefined) }).toThrow('already exists')
+    internals.documents.set('owned.txt', new TextProjectFile('owned.txt', 'old'))
+    const previousFile: ProjectResource = {
+      ...existingFile, key: resourceKey('file:owned.txt'), document: new TextProjectFile('owned.txt', 'old'),
+    }
+    const nextFile: ProjectResource = {
+      ...existingFile, key: resourceKey('file:owned.txt'), document: new TextProjectFile('owned.txt', 'replacement'),
+    }
+    expect(() => { internals.applyResource(nextFile, previousFile) }).toThrow('updating feature-owned files')
+    internals.documents.set('owned.txt', new TextProjectFile('owned.txt', 'user edit'))
+    expect(() => { internals.applyResource(nextFile, previousFile) }).toThrow('was modified')
+    expect(() => { internals.removeResource({
+      ...existingFile, key: resourceKey('file:missing.txt'), document: new TextProjectFile('missing.txt', 'missing'),
+    }) }).toThrow('owned file is missing')
+    expect(() => { internals.removeResource({
+      kind: 'cordis-config-entry', key: resourceKey('cordis-config-entry:missing'),
+      entry: { id: 'missing', name: 'missing' }, ownedConfigKeys: [],
+    }) }).toThrow('cannot confirm old Cordis resource')
+    const transient: ProjectResource = {
+      kind: 'owned-file', key: resourceKey('file:transient.txt'),
+      document: new TextProjectFile('transient.txt', 'transient'), removeOnlyWhenUnchanged: true,
+    }
+    internals.applyResource(transient, undefined)
+    internals.removeResource(transient)
+    internals.replaceContribution(
+      new ProjectContribution([{ kind: 'npm-dependency', key: resourceKey('shared'), name: 'cordis', section: 'dependencies' }]),
+      new ProjectContribution([{
+        kind: 'cordis-config-entry', key: resourceKey('shared'), entry: { id: 'new', name: 'new' }, ownedConfigKeys: [],
+      }]),
+    )
+    internals.replaceContribution(
+      new ProjectContribution([{
+        kind: 'environment', key: resourceKey('environment:SAME'), name: 'SAME', value: 'old', exampleValue: '',
+      }]),
+      new ProjectContribution([{
+        kind: 'environment', key: resourceKey('environment:SAME'), name: 'SAME', value: 'new', exampleValue: '',
+      }]),
+    )
+    internals.documents.set('.env', new TextProjectFile('.env', 'bad'))
+    expect(() => edit.readEnvironment('.env', 'KEY')).toThrow('not an environment document')
+    expect(() => { internals.environment('.env') }).toThrow('not an environment document')
+    internals.documents.delete('package.json')
+    expect(() => { internals.manifest() }).toThrow('package.json is missing')
+    internals.documents.delete('cordis.yml')
+    expect(() => { internals.cordis() }).toThrow('cordis.yml is missing')
+    class Foreign extends FixedFeature {
+      override readonly id = featureId('foreign')
+      override readonly summary = 'foreign'
+      override readonly options = []
+    }
+    expect(() => { internals.state(new Foreign()) }).toThrow('not applicable')
+    const sourceDocuments = (project as unknown as { documents: Map<string, TextProjectFile> }).documents
+    sourceDocuments.set('.env', new TextProjectFile('.env', 'bad'))
+    expect(() => project.readEnvironment('.env', 'KEY')).toThrow('not an environment document')
+    sourceDocuments.delete('package.json')
+    expect(() => project.packageJson).toThrow('package.json is missing or invalid')
+    sourceDocuments.delete('cordis.yml')
+    expect(() => project.cordis).toThrow('cordis.yml is missing or invalid')
+  })
+
+  it('rejects external edits before writing any affected file', async () => {
+    const project = await createCommitted([selection('todo', ['default'])])
+    const registry = createBuiltinRegistry(project.profile)
+    const edit = project.edit(registry)
+    edit.disableFeature(registry.get(featureId('todo')))
+    const manifestBefore = await readFile(join(project.root, 'package.json'), 'utf8')
+    await writeFile(join(project.root, 'cordis.yml'), '# external\n[]\n')
+    await expect(edit.commit()).rejects.toThrow('changed outside this edit session')
+    expect(await readFile(join(project.root, 'package.json'), 'utf8')).toBe(manifestBefore)
+  })
+
+  it('rejects a create target file that appeared after the edit session opened', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-create-conflict-'))
+    temporary.push(root)
+    const creation = request()
+    const project = SdkProject.create(root, creation)
+    const registry = createBuiltinRegistry(project.profile)
+    const edit = project.edit(registry)
+    for (const item of creation.features) edit.installFeature(registry.get(item.id), item)
+    await writeFile(join(root, 'README.md'), 'external\n')
+    await expect(edit.commit()).rejects.toThrow('changed outside this edit session: README.md')
+  })
+
+  it('uses Cordis config entries as the installation anchor and rejects partial resources', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-inconsistent-'))
+    temporary.push(root)
+    await writeFile(join(root, 'package.json'), JSON.stringify({
+      name: 'partial', dependencies: { '@deepseek-ai/dsh-llm-deepseek': '^0.0.1' },
+    }))
+    await writeFile(join(root, 'cordis.yml'), '[]\n')
+    const project = await SdkProject.open(root)
+    const registry = createBuiltinRegistry(project.profile)
+    expect(registry.get(featureId('provider')).inspect(project)).toMatchObject({
+      state: 'absent', diagnostics: [],
+    })
+
+    const partialRoot = await mkdtemp(join(tmpdir(), 'dsh-entry-partial-'))
+    temporary.push(partialRoot)
+    await writeFile(join(partialRoot, 'package.json'), JSON.stringify({ name: 'partial-entry' }))
+    await writeFile(join(partialRoot, 'cordis.yml'), `- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: test
+`)
+    const partial = await SdkProject.open(partialRoot)
+    const installation = createBuiltinRegistry(partial.profile)
+      .get(featureId('provider')).inspect(partial)
+    expect(installation.state).toBe('inconsistent')
+    expect(installation.diagnostics).toContain('missing package.json dependencies entry @deepseek-ai/dsh-llm-deepseek')
+    const partialEdit = partial.edit(createBuiltinRegistry(partial.profile))
+    const provider = createBuiltinRegistry(partial.profile).get(featureId('provider'))
+    expect(() => { partialEdit.configureFeature(provider, selection('provider', ['deepseek'])) }).toThrow('inconsistent')
+    expect(() => { partialEdit.enableFeature(provider) }).toThrow('inconsistent')
+    expect(() => { partialEdit.disableFeature(provider) }).toThrow('required feature')
+  })
+
+  it('rejects inconsistent optional features and incompatible requirement options', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-optional-inconsistent-'))
+    temporary.push(root)
+    await writeFile(join(root, 'package.json'), '{"name":"partial"}')
+    await writeFile(join(root, 'cordis.yml'), `- id: web-search-exa
+  name: '@deepseek-ai/dsh-web-search-exa'
+`)
+    const project = await SdkProject.open(root)
+    const builtin = createBuiltinRegistry(project.profile)
+    const edit = project.edit(builtin)
+    const web = builtin.get(featureId('web'))
+    expect(() => { edit.disableFeature(web) }).toThrow('inconsistent')
+    expect(() => { edit.installFeature(web, selection('web', ['deepseek'])) }).toThrow('inconsistent')
+
+    class RequiresWeb extends FixedFeature {
+      override readonly id = featureId('requires-web')
+      override readonly summary = 'requires web'
+      override readonly requires = [featureId('web')]
+      override readonly options = [new (class extends FeatureOption {
+        override readonly id = 'one'
+        override readonly label = 'One'
+        override contribution(): ProjectContribution { return new ProjectContribution([]) }
+      })()]
+    }
+    const requiresWeb = new RequiresWeb()
+    const webRegistry = new FeatureRegistry([web, requiresWeb], project.profile)
+    expect(() => { project.edit(webRegistry).installFeature(requiresWeb, selection('requires-web', ['one'])) })
+      .toThrow('required feature web is inconsistent')
+
+    class RequiresAcp extends FixedFeature {
+      override readonly id = featureId('requires-acp')
+      override readonly summary = 'requires acp'
+      override readonly options = [new (class extends FeatureOption {
+        override readonly id = 'one'
+        override readonly label = 'One'
+        override contribution(): ProjectContribution { return new ProjectContribution([]) }
+      })()]
+      override requirements(): readonly [{ id: ReturnType<typeof featureId>; options: readonly string[] }] {
+        return [{ id: featureId('app'), options: ['acp'] }]
+      }
+    }
+    const requiring = new RequiresAcp()
+    const complete = await createCommitted()
+    const app = createBuiltinRegistry(complete.profile).get(featureId('app'))
+    const registry = new FeatureRegistry([app, requiring], complete.profile)
+    expect(() => { complete.edit(registry).installFeature(requiring, selection('requires-acp', ['one'])) })
+      .toThrow('does not satisfy the option requirement')
+  })
+
+  it('removes obsolete environment resources when switching options', async () => {
+    const project = await createCommitted([selection('web', ['exa'], { apiKey: 'exa' })])
+    const registry = createBuiltinRegistry(project.profile)
+    const edit = project.edit(registry)
+    edit.configureFeature(registry.get(featureId('web')), selection('web', ['deepseek']))
+    expect(edit.readEnvironment('.env.example', 'EXA_API_KEY')).toBeUndefined()
+  })
+
+  it('preserves duplicate and existing .env values while appending differently named secrets', async () => {
+    const project = await createCommitted()
+    const original = '# keep\nDEEPSEEK_API_KEY=first\nDEEPSEEK_API_KEY=second\n'
+    await writeFile(join(project.root, '.env'), original)
+    const reopened = await SdkProject.open(project.root)
+    const registry = createBuiltinRegistry(reopened.profile)
+    expect(registry.get(featureId('provider')).inspect(reopened)).toMatchObject({
+      state: 'enabled', selection: { secrets: { apiKey: 'second' } },
+    })
+    const edit = reopened.edit(registry)
+    edit.configureFeature(
+      registry.get(featureId('provider')),
+      selection('provider', ['deepseek'], { apiKey: 'replacement' }),
+    )
+    edit.installFeature(registry.get(featureId('web')), selection('web', ['exa'], { apiKey: 'exa-key' }))
+    const withExa = (await edit.commit()).project
+    expect(await readFile(join(withExa.root, '.env'), 'utf8')).toBe(`${original}EXA_API_KEY=exa-key\n`)
+    const nextRegistry = createBuiltinRegistry(withExa.profile)
+    const remove = withExa.edit(nextRegistry)
+    remove.configureFeature(nextRegistry.get(featureId('web')), selection('web', ['deepseek']))
+    await remove.commit()
+    expect(await readFile(join(withExa.root, '.env'), 'utf8')).toBe(`${original}EXA_API_KEY=exa-key\n`)
+  })
+
+  it('refuses to remove a feature-owned file after user edits', async () => {
+    const project = await createCommitted([selection('hooks', ['claude', 'codex'])])
+    await writeFile(join(project.root, 'hooks.json'), '{"hooks":{}}\n')
+    const reopened = await SdkProject.open(project.root)
+    const registry = createBuiltinRegistry(reopened.profile)
+    const edit = reopened.edit(registry)
+    expect(() => { edit.configureFeature(
+      registry.get(featureId('hooks')),
+      selection('hooks', ['codex']),
+    ) }).toThrow('owned file was modified: hooks.json')
+  })
+
+  it('does not mistake a linked NPM dependency closure for an installed feature', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-link-closure-inspection-'))
+    temporary.push(root)
+    const base = request([selection('hooks', ['claude'])])
+    const creation: ProjectCreationRequest = { ...base, linkWorkspaceRoot: repoRoot }
+    const project = SdkProject.create(root, creation)
+    const registry = createBuiltinRegistry(project.profile)
+    const edit = project.edit(registry)
+    for (const item of creation.features) edit.installFeature(registry.get(item.id), item)
+    const committed = (await edit.commit()).project
+    expect(committed.packageManifest().dependencies?.['@deepseek-ai/dsh-subagent']).toMatch(/^file:/)
+    expect(createBuiltinRegistry(committed.profile).get(featureId('subagent')).inspect(committed).state).toBe('absent')
+  })
+})
+
+describe('extension points', () => {
+  const profile: ProjectProfile = {
+    name: 'test', description: 'test', runtime: { model: 'm' }, runInterface: 'embed',
+    packageManager: new NpmPackageManager('10.0.0'), releaseVersion: '0.0.1',
+  }
+
+  it('rejects cross-feature resource ownership conflicts at registry construction', () => {
+    class TestOption extends FeatureOption {
+      override readonly id = 'default'
+      override readonly label = 'Default'
+      override contribution(): ProjectContribution {
+        return new ProjectContribution([{
+          kind: 'npm-dependency', key: resourceKey('npm-dependency:shared'), name: 'shared', section: 'dependencies',
+        }])
+      }
+    }
+    class TestFeature extends FixedFeature {
+      override readonly id
+      override readonly summary = 'test'
+      override readonly options = [new TestOption()]
+      constructor(id: string) {
+        super()
+        this.id = featureId(id)
+      }
+    }
+    expect(() => new FeatureRegistry([
+      new TestFeature('one'), new TestFeature('two'),
+    ], profile)).toThrow('declared by both one and two')
+    expect(new TestFeature('one').defaultOptions()).toEqual(['default'])
+    expect(() => new FeatureRegistry([
+      new TestFeature('one'), new TestFeature('one'),
+    ], profile)).toThrow('duplicate feature id')
+  })
+
+  it('validates selection modes and declarative feature definitions', () => {
+    const option = { id: 'one', label: 'One', default: true, resources: [] } as const
+    expect(() => defineFeature({ id: 'bad-single', summary: 'bad', mode: 'single', options: [] }))
+      .toThrow('requires one default option')
+    expect(() => defineFeature({
+      id: 'bad-exclusive', summary: 'bad', mode: 'exclusive', options: [{ ...option, default: false }],
+    })).toThrow('exactly one default option')
+    expect(() => defineFeature({
+      id: 'bad-multiple', summary: 'bad', mode: 'multiple', options: [{ ...option, default: false }],
+    })).toThrow('at least one default option')
+    const exclusive = defineFeature({
+      id: 'defined', summary: 'Defined', mode: 'exclusive', supportedInterfaces: ['embed'],
+      requires: [{ id: 'base' }], suggests: ['suggested'],
+      baseResources: [{ kind: 'npm-dependency', name: 'base', section: 'devDependencies' }],
+      options: [
+        {
+          id: 'one', label: 'One', default: true,
+          requires: [{ id: 'option', options: ['required'] }],
+          secrets: [{ id: 'token', environment: 'TOKEN', message: 'Token', required: true }],
+          resources: [
+            {
+              kind: 'npm-cordis-config-entry', id: 'one', package: 'one-package',
+              config: { nested: { value: 1 }, list: ['x'], nullable: null },
+            },
+            { kind: 'owned-file', path: 'one.txt', text: 'one', removeOnlyWhenUnchanged: false },
+          ],
+        },
+        {
+          id: 'two', label: 'Two', resources: [
+            { kind: 'file-cordis-config-entry', id: 'two', path: './two.ts' },
+          ],
+        },
+      ],
+    })
+    expect(exclusive.defaultOptions(profile)).toEqual(['one'])
+    expect(exclusive.isApplicable(profile)).toBe(true)
+    expect(exclusive.isApplicable({ ...profile, runInterface: 'stdio' })).toBe(false)
+    expect(exclusive.requirements(selection('defined', ['one']))).toEqual([
+      { id: 'base' }, { id: 'option', options: ['required'] },
+    ])
+    const contribution = exclusive.contribution({
+      id: featureId('defined'), options: ['one'], secrets: { token: 'secret' },
+    }, profile)
+    expect(contribution.resources.map(resource => resource.kind)).toEqual([
+      'npm-dependency', 'npm-dependency', 'cordis-config-entry', 'owned-file', 'environment',
+    ])
+    const entry = contribution.resources.find(resource => resource.kind === 'cordis-config-entry')
+    expect(entry?.validateConfig?.({ nested: { value: 2 }, list: ['a', 'b'], nullable: null })).toEqual([])
+    expect(entry?.validateConfig?.({ nested: [], list: 'bad' })).toHaveLength(3)
+    expect(() => exclusive.normalizeSelection(selection('other', ['one']), profile)).toThrow('does not belong')
+    expect(() => exclusive.normalizeSelection(selection('defined', ['one']), { ...profile, runInterface: 'stdio' }))
+      .toThrow('not available')
+    expect(() => exclusive.normalizeSelection(selection('defined', ['missing']), profile)).toThrow('unknown')
+    expect(() => exclusive.normalizeSelection(selection('defined', ['one', 'two']), profile)).toThrow('exactly one')
+    expect(defineFeatures([exclusive, {
+      id: 'fixed', summary: 'Fixed', mode: 'single', options: [option],
+    }])).toHaveLength(2)
+    expect(() => new FeatureRegistry([], profile).get(featureId('missing'))).toThrow('unknown feature')
+    expect(new FeatureRegistry([exclusive], profile).ownerOfPackage('one-package', { ...profile, runInterface: 'stdio' }))
+      .toBeUndefined()
+    class Unsupported extends FixedFeature {
+      override readonly id = featureId('unsupported')
+      override readonly summary = 'unsupported'
+      override readonly options = [new (class extends FeatureOption {
+        override readonly id = 'one'
+        override readonly label = 'One'
+        override contribution(): ProjectContribution { return new ProjectContribution([]) }
+      })()]
+      override readonly supportedInterfaces = []
+    }
+    expect(() => new FeatureRegistry([new Unsupported()], profile)).toThrow('supports no run interface')
+  })
+
+  it('covers feature base classes and resource conflict checks', () => {
+    class EmptySimple extends FixedFeature {
+      override readonly id = featureId('empty')
+      override readonly summary = 'empty'
+      override readonly options = []
+    }
+    expect(() => new EmptySimple().defaultOptions()).toThrow('has no option')
+    class BadSimple extends FixedFeature {
+      override readonly id = featureId('bad-simple')
+      override readonly summary = 'bad'
+      override readonly options = [new (class extends FeatureOption {
+        override readonly id = 'one'
+        override readonly label = 'One'
+        override contribution(): ProjectContribution { return new ProjectContribution([]) }
+      })(), new (class extends FeatureOption {
+        override readonly id = 'two'
+        override readonly label = 'Two'
+        override contribution(): ProjectContribution { return new ProjectContribution([]) }
+      })()]
+    }
+    expect(() => new BadSimple().normalizeSelection(selection('bad-simple', ['one']), profile)).toThrow('one fixed option')
+    class EmptyMulti extends MultiOptionFeature {
+      override readonly id = featureId('multi')
+      override readonly summary = 'multi'
+      override readonly options = []
+      override defaultOptions(): readonly string[] { return [] }
+    }
+    expect(() => new EmptyMulti().normalizeSelection(selection('multi', []), profile)).toThrow('at least one')
+    class EmptyExclusive extends ExclusiveOptionFeature {
+      override readonly id = featureId('exclusive')
+      override readonly summary = 'exclusive'
+      override readonly options = []
+      override defaultOptions(): readonly string[] { return [] }
+    }
+    expect(() => new EmptyExclusive().normalizeSelection(selection('exclusive', []), profile)).toThrow('exactly one')
+    const resource = {
+      kind: 'npm-dependency' as const, key: resourceKey('same'), name: 'one', section: 'dependencies' as const,
+    }
+    expect(() => new ProjectContribution([resource, resource])).toThrow('duplicate contribution')
+    expect(() => ProjectContribution.merge(
+      new ProjectContribution([resource]),
+      new ProjectContribution([{ ...resource, name: 'two' }]),
+    )).toThrow('conflicting definitions')
+    expect(ProjectContribution.merge(new ProjectContribution([resource]), new ProjectContribution([resource])).byKey().size)
+      .toBe(1)
+    expect(ownedTextFile('owner', 'file.txt', 'text').document).toBeInstanceOf(TextProjectFile)
+    expect(optionalString({ value: 1 }, 'value')).toHaveLength(1)
+    expect(optionalString({}, 'value')).toEqual([])
+    expect(requiredString({ value: 'x' }, 'value')).toEqual([])
+    expect(stringArray({ value: ['a'] }, 'value')).toEqual([])
+    expect(stringArray({ value: [1] }, 'value')).toHaveLength(1)
+    expect(cordisConfigEntry('owner', { id: 'entry', name: 'pkg' }).ownedConfigKeys).toEqual([])
+    expect(npmCordisConfigEntry('owner', { id: 'entry', name: 'pkg' })[1].ownedConfigKeys).toEqual([])
+    expect(environmentResource('owner', 'EMPTY', undefined)).not.toHaveProperty('value')
+    const builtins = createBuiltinRegistry(profile)
+    expect(builtins.get(featureId('app')).defaultOptions(profile)).toEqual(['embed'])
+    expect(builtins.get(featureId('hmr')).defaultOptions(profile)).toEqual(['default'])
+    const app = builtins.get(featureId('app'))
+    const acpEntry = builtins.get(featureId('app')).contribution(selection('app', ['acp']), profile).resources
+      .find((resource): resource is CordisConfigEntryResource =>
+        resource.kind === 'cordis-config-entry' && resource.entry.id === 'acp')
+    expect(acpEntry?.entry.id).toBe('acp')
+    expect(acpEntry?.validateConfig?.({ model: '' })).toHaveLength(1)
+    const embedOption = app.options.find(option => option.id === 'embed')
+    expect(embedOption?.markerConfigEntries(profile)).toEqual([])
+    expect(embedOption?.contribution(profile, {}).resources).toEqual([])
+    expect(embedOption?.matchesConfigEntries([
+      { id: 'agent-loop', name: '@deepseek-ai/dsh-agent-loop' },
+      { id: 'stdio', name: '@deepseek-ai/dsh-stdio' },
+    ], profile)).toBe(false)
+    const spineAgentLoop = builtins.get(featureId('spine')).contribution(selection('spine', ['default']), profile).resources
+      .find((resource): resource is CordisConfigEntryResource =>
+        resource.kind === 'cordis-config-entry' && resource.entry.id === 'agent-loop')
+    expect(spineAgentLoop?.validateConfig?.({ agents: 'main' })).toEqual(['agents must be an array'])
+    expect(spineAgentLoop?.validateConfig?.({ agents: ['main'] })).toEqual(['agents must be empty'])
+    expect(spineAgentLoop?.validateConfig?.({ agents: [] })).toEqual([])
+    expect(builtins.get(featureId('provider')).defaultOptions(profile)).toEqual(['deepseek'])
+    expect(() => builtins.get(featureId('provider')).contribution({
+      id: featureId('provider'), options: ['custom'], values: { baseURL: 1 },
+    }, profile)).toThrow('baseURL must be a string')
+    const alternateModel = builtins.get(featureId('provider')).contribution({
+      id: featureId('provider'), options: ['deepseek'],
+    }, { ...profile, runtime: { model: 'other' } }).resources
+      .find(resource => resource.kind === 'cordis-config-entry')
+    expect(alternateModel?.entry.config?.models).toEqual(['other'])
+    class RequiringSimple extends BadSimple {
+      override readonly requires = [featureId('npm-dependency')]
+    }
+    expect(new RequiringSimple().requirements(selection('bad-simple', ['one']))).toEqual([{ id: 'npm-dependency' }])
+    expect(builtins.get(featureId('bash')).defaultOptions(profile)).toEqual(['local'])
+  })
+
+  it('reports every inconsistent feature resource shape', () => {
+    const feature = defineFeature({
+      id: 'inspectable', summary: 'Inspectable', mode: 'single',
+      baseResources: [{ kind: 'file-cordis-config-entry', id: 'base', path: 'pkg' }],
+      options: [{
+        id: 'one', label: 'One', default: true,
+        secrets: [{ id: 'token', environment: 'TOKEN', message: 'Token', required: true }],
+        resources: [
+          { kind: 'file-cordis-config-entry', id: 'one', path: 'pkg', config: { value: 'x' } },
+          { kind: 'npm-dependency', name: 'dep' },
+          { kind: 'owned-file', path: 'owned.txt', text: 'owned' },
+        ],
+      }],
+    })
+    const view = (entries: readonly CordisConfigEntry[]): FeatureProjectView => ({
+      profile,
+      cordisConfigEntries: () => entries,
+      packageManifest: () => ({}),
+      hasDocument: () => false,
+      readEnvironment: (path) => {
+        if (path === '.env.example') throw new Error('bad env')
+        return 'secret'
+      },
+    })
+    expect(feature.inspect(view([])).state).toBe('absent')
+    const inconsistent = feature.inspect(view([
+      { id: 'one', name: 'pkg', config: { value: 1 } },
+      { id: 'extra', name: 'pkg', disabled: true },
+    ]))
+    expect(inconsistent.state).toBe('inconsistent')
+    expect(inconsistent.diagnostics.join('\n')).toContain('missing Cordis config entry base')
+    expect(inconsistent.diagnostics.join('\n')).toContain('unexpected owned Cordis config entry extra')
+    expect(inconsistent.diagnostics.join('\n')).toContain('missing package.json dependencies entry dep')
+    expect(inconsistent.diagnostics.join('\n')).toContain('missing owned file owned.txt')
+    expect(inconsistent.diagnostics.join('\n')).toContain('bad env')
+    expect(inconsistent.diagnostics.join('\n')).toContain('mixed enabled states')
+    expect(feature.inspect(view([{ id: 'unknown', name: 'pkg' }])).state).toBe('inconsistent')
+    const ambiguous = defineFeature({
+      id: 'ambiguous', summary: 'Ambiguous', mode: 'exclusive',
+      options: [
+        { id: 'one', label: 'One', default: true, resources: [], markers: [{ id: 'one', name: 'pkg' }] },
+        { id: 'two', label: 'Two', resources: [], markers: [{ id: 'two', name: 'pkg' }] },
+      ],
+    })
+    expect(ambiguous.inspect(view([{ id: 'one', name: 'pkg' }, { id: 'two', name: 'pkg' }])).state)
+      .toBe('inconsistent')
+    const noValidator = defineFeature({
+      id: 'no-validator', summary: 'No validator', mode: 'single',
+      options: [{
+        id: 'one', label: 'One', default: true,
+        resources: [{ kind: 'file-cordis-config-entry', id: 'plain', path: 'plain-package' }],
+      }],
+    })
+    expect(noValidator.inspect(view([{ id: 'plain', name: 'plain-package' }])).state).toBe('enabled')
+    const app = createBuiltinRegistry(profile).get(featureId('app'))
+    expect(app.inspect(view([{ id: 'acp', name: '@deepseek-ai/dsh-acp' }])).state)
+      .toBe('inconsistent')
+  })
+})
diff --git a/packages/sdk/helper/tests/questions.spec.ts b/packages/sdk/helper/tests/questions.spec.ts
new file mode 100644
index 0000000000..463f3b979f
--- /dev/null
+++ b/packages/sdk/helper/tests/questions.spec.ts
@@ -0,0 +1,453 @@
+import { PassThrough, Writable } from 'node:stream'
+import { stripVTControlCharacters } from 'node:util'
+import { S_CHECKBOX_SELECTED, S_RADIO_ACTIVE, S_WARN } from '@clack/prompts'
+import { describe, expect, it } from 'vitest'
+import { createBuiltinRegistry } from '../src/features/builtin/index.ts'
+import { FeatureConfigurator } from '../src/features/feature-configurator.ts'
+import { FeatureOption, ExclusiveOptionFeature } from '../src/features/feature.ts'
+import { ProjectContribution } from '../src/features/resources.ts'
+import { featureId } from '../src/ids.ts'
+import { NpmPackageManager } from '../src/package-managers/package-manager.ts'
+import { ClackPromptPort } from '../src/questions/clack-prompt-port.ts'
+import {
+  PromptCancelledError,
+  requireAnswer,
+  type ConfirmPromptRequest,
+  type MultiSelectPromptRequest,
+  type NestedMultiSelectRequest,
+  type NestedMultiSelectValue,
+  type PromptOutcome,
+  type PromptPort,
+  type SecretPromptRequest,
+  type SelectPromptRequest,
+  type TextPromptRequest,
+} from '../src/questions/prompt-port.ts'
+import {
+  ConfirmQuestion,
+  MultiSelectQuestion,
+  SecretQuestion,
+  SelectQuestion,
+  TextQuestion,
+} from '../src/questions/question.ts'
+import type { ProjectProfile } from '../src/project/types.ts'
+import { clackNestedMultiselect } from '../src/questions/clack-nested-multiselect.ts'
+
+function validateString(
+  outcome: PromptOutcome<string>,
+  validate: ((value: string) => string | undefined) | undefined,
+): PromptOutcome<string> {
+  if (outcome.status === 'answered') {
+    const diagnostic = validate?.(outcome.value)
+    if (diagnostic) throw new Error(diagnostic)
+  }
+  return outcome
+}
+
+class QueuePromptPort implements PromptPort {
+  readonly answers: unknown[]
+  readonly requests: string[] = []
+
+  constructor(answers: unknown[]) {
+    this.answers = [...answers]
+  }
+
+  next<T>(message: string): PromptOutcome<T> {
+    this.requests.push(message)
+    const value = this.answers.shift()
+    return value === QueuePromptPort.cancel ? { status: 'cancelled' } : { status: 'answered', value: value as T }
+  }
+
+  async text(request: TextPromptRequest): Promise<PromptOutcome<string>> {
+    return validateString(this.next<string>(request.message), request.validate)
+  }
+
+  async secret(request: SecretPromptRequest): Promise<PromptOutcome<string>> {
+    return validateString(this.next<string>(request.message), request.validate)
+  }
+
+  select<T>(request: SelectPromptRequest<T>): Promise<PromptOutcome<T>> {
+    return Promise.resolve(this.next(request.message))
+  }
+
+  multiselect<T>(request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>> {
+    return Promise.resolve(this.next(request.message))
+  }
+
+  confirm(request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>> {
+    return Promise.resolve(this.next(request.message))
+  }
+  nestedMultiselect<TValue, TChoice>(
+    request: NestedMultiSelectRequest<TValue, TChoice>,
+  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> {
+    return Promise.resolve(this.next(request.message))
+  }
+
+  static readonly cancel = Symbol('cancel')
+}
+
+describe('typed questions', () => {
+  it('uses and validates prefilled answers without prompting', async () => {
+    const port = new QueuePromptPort([])
+    const text = new TextQuestion({ id: 'name', message: 'Name', validate: value => value ? undefined : 'required' })
+    await expect(text.resolve(port, 'demo')).resolves.toEqual({ status: 'answered', value: 'demo' })
+    await expect(text.resolve(port, '')).rejects.toThrow('name: required')
+    const select = new SelectQuestion({
+      id: 'choice', message: 'Choice', options: [{ value: 'a', label: 'A' }], initialValue: 'a',
+    })
+    await expect(select.resolve(port, 'b')).rejects.toThrow('unknown or disabled option')
+    await expect(select.resolve(port, 'a')).resolves.toMatchObject({ value: 'a' })
+    const disabled = new SelectQuestion({
+      id: 'disabled', message: 'Disabled', options: [{ value: 'a', label: 'A', disabled: true }],
+    })
+    await expect(disabled.resolve(port, 'a')).rejects.toThrow('disabled option')
+    const multi = new MultiSelectQuestion({
+      id: 'many', message: 'Many', options: [{ value: 'a', label: 'A' }], required: true,
+    })
+    await expect(multi.resolve(port, [])).rejects.toThrow('choose at least one')
+    await expect(multi.resolve(port, ['missing'])).rejects.toThrow('unknown or disabled option')
+    await expect(new MultiSelectQuestion({
+      id: 'disabled-many', message: 'Disabled many', options: [{ value: 'a', label: 'A', disabled: true }],
+    }).resolve(port, ['a'])).rejects.toThrow('disabled option')
+    await expect(new MultiSelectQuestion({
+      id: 'optional', message: 'Optional', options: [{ value: 'a', label: 'A' }],
+    }).resolve(port, [])).resolves.toMatchObject({ value: [] })
+    const secret = new SecretQuestion({ id: 'secret', message: 'Secret', validate: value => value ? undefined : 'required' })
+    await expect(secret.resolve(port, 'value')).resolves.toMatchObject({ value: 'value' })
+    await expect(secret.resolve(port, '')).rejects.toThrow('secret: required')
+    await expect(new ConfirmQuestion({ id: 'confirm', message: 'Confirm' }).resolve(port, false))
+      .resolves.toEqual({ status: 'answered', value: false })
+    expect(port.requests).toEqual([])
+  })
+
+  it('delegates each interaction shape and propagates cancellation', async () => {
+    const port = new QueuePromptPort(['text', 'secret', 'a', ['a'], true, QueuePromptPort.cancel])
+    await expect(new TextQuestion({ id: 't', message: 'Text' }).resolve(port)).resolves.toMatchObject({ value: 'text' })
+    await expect(new SecretQuestion({ id: 's', message: 'Secret' }).resolve(port)).resolves.toMatchObject({ value: 'secret' })
+    await expect(new SelectQuestion({
+      id: 'one', message: 'One', options: [{ value: 'a', label: 'A' }],
+    }).resolve(port)).resolves.toMatchObject({ value: 'a' })
+    await expect(new MultiSelectQuestion({
+      id: 'many', message: 'Many', options: [{ value: 'a', label: 'A' }],
+    }).resolve(port)).resolves.toMatchObject({ value: ['a'] })
+    await expect(new ConfirmQuestion({ id: 'yes', message: 'Yes?' }).resolve(port)).resolves.toMatchObject({ value: true })
+    const cancelled = await new ConfirmQuestion({ id: 'cancel', message: 'Cancel?' }).resolve(port)
+    expect(() => requireAnswer(cancelled)).toThrow(PromptCancelledError)
+    const optionsPort = new QueuePromptPort(['full', 'a', ['a']])
+    await new TextQuestion({
+      id: 'full', message: 'Full', placeholder: 'p', initialValue: 'i', defaultValue: 'd', validate: () => undefined,
+    }).resolve(optionsPort)
+    await new SelectQuestion({
+      id: 'initial', message: 'Initial', options: [{ value: 'a', label: 'A' }], initialValue: 'a',
+    }).resolve(optionsPort)
+    await new MultiSelectQuestion({
+      id: 'initial-many', message: 'Initial many', options: [{ value: 'a', label: 'A' }],
+      initialValues: ['a'], required: true,
+    }).resolve(optionsPort)
+  })
+
+  it('accepts a visible placeholder default before required validation', async () => {
+    const input = new PassThrough()
+    const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
+    const pending = new ClackPromptPort(input, output).text({
+      message: 'Directory',
+      placeholder: 'my-agent',
+      defaultValue: 'my-agent',
+      validate: value => value ? undefined : 'required',
+    })
+    setTimeout(() => input.write('\r'), 0)
+    await expect(pending).resolves.toEqual({ status: 'answered', value: 'my-agent' })
+  })
+
+  it('renders warning confirmations with a yellow warning marker', async () => {
+    const input = new PassThrough()
+    let screen = ''
+    const output = new Writable({ write(chunk, _encoding, callback) { screen += String(chunk); callback() } })
+    const pending = new ClackPromptPort(input, output).confirm({
+      message: 'Keep empty?',
+      initialValue: true,
+      tone: 'warning',
+    })
+    setTimeout(() => input.write('\r'), 0)
+    await expect(pending).resolves.toEqual({ status: 'answered', value: true })
+    expect(stripVTControlCharacters(screen)).toContain(`${S_WARN} Keep empty?`)
+  })
+
+  it('adapts secret, select, multiselect, nested, and cancellation prompts', async () => {
+    const run = async <T>(
+      start: (port: ClackPromptPort) => Promise<PromptOutcome<T>>,
+      keys: string,
+    ): Promise<PromptOutcome<T>> => {
+      const input = new PassThrough()
+      const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
+      const pending = start(new ClackPromptPort(input, output))
+      setTimeout(() => input.write(keys), 0)
+      return pending
+    }
+    await expect(run(port => port.secret({ message: 'Secret', validate: value => value ? undefined : 'required' }), 'key\r'))
+      .resolves.toEqual({ status: 'answered', value: 'key' })
+    await expect(run(port => port.secret({ message: 'Secret' }), 'plain\r'))
+      .resolves.toEqual({ status: 'answered', value: 'plain' })
+    await expect(run(port => port.text({ message: 'Text', initialValue: 'seed' }), '\r'))
+      .resolves.toEqual({ status: 'answered', value: 'seed' })
+    let validated = 'unset'
+    await expect(run(port => port.text({
+      message: 'Empty', validate: (value) => { validated = value; return undefined },
+    }), '\r')).resolves.toEqual({ status: 'answered', value: '' })
+    expect(validated).toBe('')
+    await expect(run(port => port.select({
+      message: 'Select', options: [{ value: 'a', label: 'A', hint: 'hint' }, { value: 'b', label: 'B', disabled: true }],
+      initialValue: 'a',
+    }), '\r')).resolves.toEqual({ status: 'answered', value: 'a' })
+    await expect(run(port => port.multiselect({
+      message: 'Many', options: [{ value: 'a', label: 'A' }], initialValues: ['a'], required: true,
+    }), '\r')).resolves.toEqual({ status: 'answered', value: ['a'] })
+    await expect(run(port => port.multiselect({
+      message: 'Many', options: [{ value: 'a', label: 'A' }],
+    }), ' \r')).resolves.toEqual({ status: 'answered', value: ['a'] })
+    await expect(run(port => port.nestedMultiselect({
+      message: 'Nested', options: [{ value: 'a', label: 'A', default: true }],
+    }), '\r')).resolves.toEqual({ status: 'answered', value: [{ value: 'a', choices: [] }] })
+    await expect(run(port => port.confirm({ message: 'Cancel' }), '\u0003')).resolves.toEqual({ status: 'cancelled' })
+    expect(new ClackPromptPort()).toBeInstanceOf(ClackPromptPort)
+  })
+})
+
+describe('nested Clack picker', () => {
+  it('navigates root options, ignores disabled rows, and toggles optional rows', async () => {
+    const input = new PassThrough()
+    const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
+    const pending = clackNestedMultiselect({
+      message: 'Features', showChanges: true, input, output,
+      options: [
+        { value: 'required', label: 'Required', required: true },
+        { value: 'optional', label: 'Optional', default: true },
+        { value: 'added', label: 'Added' },
+        { value: 'disabled', label: 'Disabled', disabled: true, warning: 'disabled warning' },
+      ],
+    })
+    setTimeout(() => input.write('\x1b[A \x1b[B\x1b[B \x1b[B \x1b[A\r'), 0)
+    await expect(pending).resolves.toEqual({
+      status: 'answered',
+      value: [{ value: 'required', choices: [] }, { value: 'added', choices: [] }],
+    })
+  })
+
+  it('cancels from the root layer', async () => {
+    const input = new PassThrough()
+    const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
+    const pending = clackNestedMultiselect({
+      message: 'Features', input, output, options: [{ value: 'one', label: 'One' }],
+    })
+    setTimeout(() => input.write('\u0003'), 0)
+    await expect(pending).resolves.toEqual({ status: 'cancelled' })
+  })
+
+  it('enters an exclusive child with Right and commits the selected option', async () => {
+    const input = new PassThrough()
+    let screen = ''
+    const output = new Writable({ write(chunk, _encoding, callback) { screen += String(chunk); callback() } })
+    const pending = clackNestedMultiselect({
+      message: 'Features',
+      showChanges: true,
+      input,
+      output,
+      options: [
+        {
+          value: 'persistence',
+          label: 'Session storage',
+          required: true,
+          default: true,
+          choiceMode: 'exclusive',
+          choices: [
+            { value: 'jsonl', label: 'JSONL', default: true },
+            { value: 'sqlite', label: 'SQLite' },
+          ],
+        },
+        { value: 'fs', label: 'Filesystem', default: true },
+      ],
+    })
+    setTimeout(() => input.write('\x1b[C\x1b[B\x1b[A\x1b[B\x1b[C\r\r'), 0)
+    await expect(pending).resolves.toEqual({
+      status: 'answered',
+      value: [
+        { value: 'persistence', choices: ['sqlite'] },
+        { value: 'fs', choices: [] },
+      ],
+    })
+    const rendered = stripVTControlCharacters(screen)
+    expect(rendered).toContain(`› ${S_CHECKBOX_SELECTED} Session storage`)
+    expect(rendered).toContain(`› ${S_RADIO_ACTIVE} SQLite`)
+    expect(rendered).toContain('● changed')
+  })
+
+  it('highlights and blocks a selected multiple feature with no child option', async () => {
+    const input = new PassThrough()
+    let screen = ''
+    const output = new Writable({ write(chunk, _encoding, callback) { screen += String(chunk); callback() } })
+    const pending = clackNestedMultiselect({
+      message: 'Features',
+      input,
+      output,
+      options: [{
+        value: 'hooks',
+        label: 'Hooks',
+        default: true,
+        choiceMode: 'multiple',
+        choices: [
+          { value: 'claude', label: 'Claude', default: true },
+          { value: 'codex', label: 'Codex' },
+        ],
+      }],
+    })
+    setTimeout(() => input.write('\x1b[C \x1b[D \x1b[D\r'), 0)
+    await expect(pending).resolves.toEqual({
+      status: 'answered',
+      value: [{ value: 'hooks', choices: ['claude'] }],
+    })
+    expect(stripVTControlCharacters(screen)).toContain('▲ choose at least one')
+  })
+
+  it('blocks root submission for an exclusive feature with no selected option', async () => {
+    const input = new PassThrough()
+    let screen = ''
+    const output = new Writable({ write(chunk, _encoding, callback) { screen += String(chunk); callback() } })
+    const pending = clackNestedMultiselect({
+      message: 'Features', input, output,
+      options: [{
+        value: 'provider', label: 'Provider', default: true, choiceMode: 'exclusive',
+        choices: [{ value: 'one', label: 'One' }],
+      }],
+    })
+    setTimeout(() => input.write('\r\x1b[C\x1b[C\r\r'), 0)
+    await expect(pending).resolves.toEqual({
+      status: 'answered', value: [{ value: 'provider', choices: ['one'] }],
+    })
+    expect(stripVTControlCharacters(screen)).toContain('Choose one Provider option')
+  })
+
+  it('blocks root submission for a multiple feature with no selected option', async () => {
+    const input = new PassThrough()
+    const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
+    const pending = clackNestedMultiselect({
+      message: 'Features', input, output,
+      options: [{
+        value: 'hooks', label: 'Hooks', default: true, choiceMode: 'multiple',
+        choices: [{ value: 'one', label: 'One' }],
+      }],
+    })
+    setTimeout(() => input.write('\r\x1b[C \r\r'), 0)
+    await expect(pending).resolves.toEqual({
+      status: 'answered', value: [{ value: 'hooks', choices: ['one'] }],
+    })
+  })
+
+  it('renders an unchanged checked option while another child is focused', async () => {
+    const input = new PassThrough()
+    const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
+    const pending = clackNestedMultiselect({
+      message: 'Features', input, output,
+      options: [{
+        value: 'hooks', label: 'Hooks', default: true, choiceMode: 'multiple',
+        choices: [
+          { value: 'one', label: 'One', default: true },
+          { value: 'two', label: 'Two', default: true },
+        ],
+      }],
+    })
+    setTimeout(() => input.write('\x1b[C\x1b[B\x1b[D\r'), 0)
+    await expect(pending).resolves.toEqual({
+      status: 'answered', value: [{ value: 'hooks', choices: ['one', 'two'] }],
+    })
+  })
+
+  it('submits an empty optional selection', async () => {
+    const input = new PassThrough()
+    const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
+    const pending = clackNestedMultiselect({
+      message: 'Features', input, output, options: [{ value: 'one', label: 'One' }],
+    })
+    setTimeout(() => input.write('\r'), 0)
+    await expect(pending).resolves.toEqual({ status: 'answered', value: [] })
+  })
+})
+
+describe('feature configurator', () => {
+  const profile: ProjectProfile = {
+    name: 'demo',
+    description: 'demo',
+    runtime: { model: 'deepseek-v4-flash' },
+    runInterface: 'stdio',
+    packageManager: new NpmPackageManager('10.0.0'),
+    releaseVersion: '0.0.1',
+  }
+
+  it('shares exclusive, multiple, fixed, and secret behavior', async () => {
+    const registry = createBuiltinRegistry(profile)
+    const port = new QueuePromptPort(['sqlite', ['spawn', 'fork'], 'deepseek', 'new-key'])
+    const configurator = new FeatureConfigurator(port)
+    await expect(configurator.configure(registry.get(featureId('persistence')), profile)).resolves.toMatchObject({
+      options: ['sqlite'],
+    })
+    await expect(configurator.configure(registry.get(featureId('subagent')), profile)).resolves.toMatchObject({
+      options: ['spawn', 'fork'],
+    })
+    await expect(configurator.configure(
+      registry.get(featureId('provider')),
+      profile,
+      { id: featureId('provider'), options: ['deepseek'], secrets: { apiKey: 'old-key' } },
+    )).resolves.toMatchObject({ secrets: { apiKey: 'new-key' } })
+    expect(port.requests).toEqual([
+      'Choose durable session storage',
+      'Choose delegate work to child agents',
+      'Choose model provider',
+      'DeepSeek API key (leave empty to keep current)',
+    ])
+  })
+
+  it('validates feature values, defaults, and retained secrets', async () => {
+    const registry = createBuiltinRegistry(profile)
+    const fixed = new FeatureConfigurator(new QueuePromptPort([]))
+    await expect(fixed.configure(registry.get(featureId('bash')), profile, undefined, ['local'])).resolves.toMatchObject({
+      options: ['local'],
+    })
+    const requiredSecret = new FeatureConfigurator(new QueuePromptPort([]))
+    await expect(requiredSecret.configure(
+      registry.get(featureId('provider')), profile, undefined, ['deepseek'], { apiKey: '' },
+    )).rejects.toThrow('required')
+    const keep = new FeatureConfigurator(new QueuePromptPort(['deepseek', '']))
+    await expect(keep.configure(
+      registry.get(featureId('provider')),
+      profile,
+      { id: featureId('provider'), options: ['deepseek'], secrets: { apiKey: 'old' } },
+    )).resolves.toMatchObject({ secrets: { apiKey: 'old' } })
+    const custom = registry.get(featureId('provider'))
+    await expect(new FeatureConfigurator(new QueuePromptPort(['custom'])).configure(
+      custom,
+      profile,
+      { id: featureId('provider'), options: ['custom'], values: { baseURL: 1 }, secrets: { apiKey: 'old' } },
+    )).rejects.toThrow('current value must be a string')
+    await expect(new FeatureConfigurator(new QueuePromptPort(['custom', ''])).configure(
+      custom, profile, undefined,
+    )).rejects.toThrow('required')
+    await expect(new FeatureConfigurator(new QueuePromptPort(['custom', 'https://next', ''])).configure(
+      custom,
+      profile,
+      {
+        id: featureId('provider'), options: ['custom'],
+        values: { baseURL: 'https://old' }, secrets: { apiKey: 'old' },
+      },
+    )).resolves.toMatchObject({ values: { baseURL: 'https://next' }, secrets: { apiKey: 'old' } })
+    class EmptyExclusive extends ExclusiveOptionFeature {
+      override readonly id = featureId('empty-exclusive')
+      override readonly summary = 'Empty'
+      override readonly options = [new (class extends FeatureOption {
+        override readonly id = 'one'
+        override readonly label = 'One'
+        override contribution(): ProjectContribution { return new ProjectContribution([]) }
+      })()]
+      override defaultOptions(): readonly string[] { return [] }
+    }
+    await expect(new FeatureConfigurator(new QueuePromptPort([])).configure(new EmptyExclusive(), profile))
+      .rejects.toThrow('has no default option')
+  })
+})
diff --git a/packages/sdk/helper/tsconfig.json b/packages/sdk/helper/tsconfig.json
new file mode 100644
index 0000000000..e4a8604575
--- /dev/null
+++ b/packages/sdk/helper/tsconfig.json
@@ -0,0 +1,19 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../util/brand" },
+    { "path": "../../compact/compact-basic" },
+    { "path": "../../hooks/hooks-claude" },
+    { "path": "../../hooks/hooks-codex" },
+    { "path": "../../session-persistence/session-persistence-jsonl" },
+    { "path": "../../session-persistence/session-persistence-sqlite" },
+    { "path": "../../subagent/tool-subagent" },
+    { "path": "../../web/tool-web" },
+    { "path": "../../../vendor/cordis" }
+  ]
+}
diff --git a/packages/sdk/helper/tsdown.config.ts b/packages/sdk/helper/tsdown.config.ts
new file mode 100644
index 0000000000..cb8b9fafef
--- /dev/null
+++ b/packages/sdk/helper/tsdown.config.ts
@@ -0,0 +1,14 @@
+import { defineConfig } from 'tsdown'
+
+/** Bundle helper runtime and mirror template assets beside the bundle. */
+export default defineConfig({
+  entry: ['lib/types/index.js'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+  copy: [{ from: 'src/templates/assets/*', to: 'lib/assets' }],
+})
diff --git a/packages/sdk/scripts/README.md b/packages/sdk/scripts/README.md
new file mode 100644
index 0000000000..5b3b1908bc
--- /dev/null
+++ b/packages/sdk/scripts/README.md
@@ -0,0 +1,30 @@
+# `@deepseek-ai/dsh-scripts`
+
+The `dsh` launcher owns SDK project startup and configuration.
+
+| Command | Behavior |
+|---|---|
+| `dsh start [target] [-- args…]` | Import a module target and invoke `main(bootContext)`, or boot `cordis.yml` when omitted; arguments after `--` are forwarded |
+| `dsh dev [target] [-- args…]` | Register TypeScript and local-workspace source resolution, then use the start path |
+| `dsh build [args…]` | Invoke the project's installed tsdown with the project arguments |
+| `dsh config` | Open one interactive edit session, review accumulated changes, commit once, and install once when NPM dependencies changed |
+
+`ProjectBuild(tsdownConfig)` and `PluginBuild(tsdownConfig)` are exported only from `@deepseek-ai/dsh-scripts/dev/tsdown-config`. Development and production read the same `cordis.yml`.
+
+Generated project scripts invoke `dsh` for dev, build, start, and config; typecheck runs `tsc -b` directly. HMR remains an explicit `cordis.yml` feature loaded by both dev and start.
+
+The runtime library exports `startSDK(source)` to load `.env` and `cordis.yml` and return the live context, and `runSDK(target)` to import a project module and invoke its `main(bootContext)` (`runSDK()` without a target delegates to `startSDK('./cordis.yml')`). `SdkBootContext` carries the raw forwarded `argv`, generic `args`, the absolute launcher `cwd`, and the `start`/`dev` mode. The launcher declares no project options: Node `parseArgs()` runs with zero schema, so valued flags use `--key=value`, bare flags become booleans, `--no-cache` becomes `args.cache = false`, and option names retain Node's spelling (`--max-depth=3` → `args['max-depth']`).
+
+`start` never builds. `dev` registers the project-installed tsx transform plus an exact package-name map from `plugins/*/package.json` to each `src/index.ts`, then follows the same start path. `build` invokes the project-installed tsdown and forwards its arguments; an absent tsdown config is a successful no-op.
+
+`config` requires a TTY. One feature tree selects the desired enabled set; changed rows are highlighted, Right changes finite feature options, required rows cannot be deselected, inconsistent rows show diagnostics, and custom/manual Cordis config entries support enable/disable. The workflow reconciles that target into one edit session. Review & Apply commits once, then NPM dependency changes trigger one package-manager install. A failed install does not undo committed files.
+
+The root library exports `startSDK`, `runSDK`, and the `SdkBootArgs`/`SdkBootContext` types; command composition remains private to the bin. No `src/*`, bin, or package-manifest subpath is exported.
+
+## Model Experience
+
+Indirectly, through the project `cordis.yml` tree loaded by `start` or `dev`.
+
+## Known Limitations and Deferred Work
+
+- **Launcher arguments are schema-free** — `start` and `dev` preserve Node `parseArgs()` output rather than validating project-specific flags.
diff --git a/packages/sdk/scripts/package.json b/packages/sdk/scripts/package.json
new file mode 100644
index 0000000000..c74ab051cc
--- /dev/null
+++ b/packages/sdk/scripts/package.json
@@ -0,0 +1,54 @@
+{
+  "name": "@deepseek-ai/dsh-scripts",
+  "description": "DeepSeek Harness SDK launcher for start, dev, build, and project configuration",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "bin": {
+    "dsh": "lib/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./dev/tsdown-config": {
+      "types": "./lib/types/dev/tsdown-config.d.ts",
+      "default": "./lib/dev/tsdown-config.js"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/bin.js",
+    "lib/dev/tsdown-config.js",
+    "lib/local-plugin-loader-hooks.js",
+    "lib/assets",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-helper": "workspace:^",
+    "commander": "^15.0.0",
+    "node-addon-require-builtin": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
+    "cordis": "^4.0.0-rc.7",
+    "tsdown": "^0.22.2",
+    "tsx": "^4.22.4"
+  },
+  "peerDependenciesMeta": {
+    "tsdown": { "optional": true },
+    "tsx": { "optional": true }
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
+    "cordis": "^4.0.0-rc.7",
+    "tsdown": "^0.22.2",
+    "tsx": "^4.22.4"
+  }
+}
diff --git a/packages/sdk/scripts/src/args.ts b/packages/sdk/scripts/src/args.ts
new file mode 100644
index 0000000000..b23fe44870
--- /dev/null
+++ b/packages/sdk/scripts/src/args.ts
@@ -0,0 +1,70 @@
+/**
+ * Commander adapter for the dsh subcommand surface.
+ *
+ * @module @deepseek-ai/dsh-scripts/args
+ */
+
+import { parseArgs as parseNodeArgs } from 'node:util'
+import { Command } from 'commander'
+
+/** Commands implemented by the dsh launcher. */
+type DshCommand = 'start' | 'dev' | 'build' | 'config'
+
+/** Parsed dsh invocation. */
+export interface DshArgs {
+  command?: DshCommand
+  target?: string
+  forwarded: readonly string[]
+  help: boolean
+}
+
+/** Parse arbitrary project flags through Node's zero-schema argument parser. */
+export function parseSdkBootArgs(argv: readonly string[]): Record<string, string | boolean | undefined> {
+  return parseNodeArgs({
+    args: [...argv],
+    strict: false,
+    allowPositionals: true,
+    allowNegative: true,
+  }).values
+}
+
+/** Parse one launcher invocation through real Commander subcommands. */
+export function parseDshArgs(argv: readonly string[]): DshArgs {
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    return { forwarded: [], help: true }
+  }
+  const separator = argv.indexOf('--')
+  const launcherArgv = separator === -1 ? argv : argv.slice(0, separator)
+  const passthrough = separator === -1 ? [] : argv.slice(separator + 1)
+  let parsed: DshArgs | undefined
+  const program = new Command()
+    .name('dsh')
+    .helpOption(false)
+    .showHelpAfterError(false)
+    .exitOverride()
+    .configureOutput({
+      /* v8 ignore next -- the command wrapper renders the package-owned usage template */
+      writeOut: () => {},
+      /* v8 ignore next -- Commander errors are returned to the command wrapper */
+      writeErr: () => {},
+    })
+  program.command('start [target]').helpOption(false).action((target?: string) => {
+    parsed = { command: 'start', ...target ? { target } : {}, forwarded: [], help: false }
+  })
+  program.command('dev [target]').helpOption(false).action((target?: string) => {
+    parsed = { command: 'dev', ...target ? { target } : {}, forwarded: [], help: false }
+  })
+  program.command('build [args...]').helpOption(false).allowUnknownOption(true).action((args: string[] = []) => {
+    parsed = { command: 'build', forwarded: args, help: false }
+  })
+  program.command('config').helpOption(false).action(() => {
+    parsed = { command: 'config', forwarded: [], help: false }
+  })
+  program.parse([...launcherArgv], { from: 'user' })
+  /* v8 ignore next -- every registered Commander action above assigns parsed or Commander throws */
+  if (!parsed) throw new Error('dsh command did not resolve')
+  if (parsed.command === 'config' && passthrough.length > 0) {
+    throw new Error('dsh config does not accept forwarded arguments')
+  }
+  return { ...parsed, forwarded: [...parsed.forwarded, ...passthrough] }
+}
diff --git a/packages/sdk/scripts/src/bin.ts b/packages/sdk/scripts/src/bin.ts
new file mode 100644
index 0000000000..d08b872818
--- /dev/null
+++ b/packages/sdk/scripts/src/bin.ts
@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Self-executing dsh launcher.
+ *
+ * @module @deepseek-ai/dsh-scripts/bin
+ */
+
+import { runDshCommand } from './command.ts'
+
+process.exitCode = await runDshCommand()
diff --git a/packages/sdk/scripts/src/build.ts b/packages/sdk/scripts/src/build.ts
new file mode 100644
index 0000000000..f71832f75f
--- /dev/null
+++ b/packages/sdk/scripts/src/build.ts
@@ -0,0 +1,79 @@
+/**
+ * User-owned tsdown configuration wrappers and child-process invocation.
+ *
+ * @module @deepseek-ai/dsh-scripts/build
+ */
+
+import { createRequire } from 'node:module'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import type { UserConfig } from 'tsdown'
+import { NodeCommandRunner, type CommandRunner } from '@deepseek-ai/dsh-helper'
+
+function hasLocalPluginPackages(root: string): boolean {
+  const directory = resolve(root, 'plugins')
+  return existsSync(directory) && readdirSync(directory, { withFileTypes: true }).some(
+    item => item.isDirectory() && existsSync(resolve(directory, item.name, 'package.json')),
+  )
+}
+
+function hasTsdownConfig(root: string): boolean {
+  return ['tsdown.config.ts', 'tsdown.config.js', 'tsdown.config.mjs', 'tsdown.config.mts']
+    .some(name => existsSync(resolve(root, name)))
+}
+
+/**
+ * Preserve the developer's root config and append a separate workspace pass
+ * when generated local plugin packages exist.
+ * @param tsdownConfig - developer-owned root tsdown config.
+ * @returns root tsdown config and optional local-plugin workspace pass.
+ */
+export function ProjectBuild(tsdownConfig: UserConfig): UserConfig[] {
+  if (tsdownConfig.workspace !== undefined) {
+    throw new Error('ProjectBuild owns workspace discovery; remove config.workspace')
+  }
+  const root = resolve(tsdownConfig.cwd ?? process.cwd())
+  return hasLocalPluginPackages(root)
+    ? [{ ...tsdownConfig }, { workspace: { include: ['plugins/*'] } }]
+    : [{ ...tsdownConfig }]
+}
+
+/**
+ * Preserve a local plugin package's developer-owned tsdown config.
+ * @param tsdownConfig - developer-owned plugin tsdown config.
+ * @returns validated tsdown config copy.
+ */
+export function PluginBuild(tsdownConfig: UserConfig): UserConfig {
+  if (tsdownConfig.workspace !== undefined) throw new Error('PluginBuild does not accept nested workspace config')
+  return { ...tsdownConfig }
+}
+
+function resolveTsdownBin(cwd: string): string {
+  const require = createRequire(resolve(cwd, 'package.json'))
+  let manifestPath: string
+  try {
+    manifestPath = require.resolve('tsdown/package.json')
+  } catch (error) {
+    throw new Error(`dsh build requires tsdown in this project: ${String(error)}`)
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as { bin?: unknown }
+  const bin = typeof manifest.bin === 'string'
+    ? manifest.bin
+    : manifest.bin && typeof manifest.bin === 'object'
+      ? (manifest.bin as Record<string, unknown>).tsdown
+      : undefined
+  if (typeof bin !== 'string') throw new Error('installed tsdown package has no executable')
+  return resolve(dirname(manifestPath), bin)
+}
+
+/** Invoke the project's installed tsdown, forwarding all build arguments. */
+export async function runProjectBuild(
+  args: readonly string[],
+  cwd: string = process.cwd(),
+  runner: CommandRunner = new NodeCommandRunner(),
+): Promise<void> {
+  if (!hasTsdownConfig(cwd)) return
+  const result = await runner.run(process.execPath, [resolveTsdownBin(cwd), ...args], resolve(cwd))
+  if (result.signal) throw new Error(`tsdown was killed by ${result.signal}`)
+  if (result.exitCode !== 0) throw new Error(`tsdown exited with code ${String(result.exitCode)}`)
+}
diff --git a/packages/sdk/scripts/src/command.ts b/packages/sdk/scripts/src/command.ts
new file mode 100644
index 0000000000..13eec41d87
--- /dev/null
+++ b/packages/sdk/scripts/src/command.ts
@@ -0,0 +1,58 @@
+/**
+ * Internal dsh command composition used by the package bin.
+ *
+ * @module @deepseek-ai/dsh-scripts/command
+ */
+
+import { parseDshArgs } from './args.ts'
+import { runProjectBuild } from './build.ts'
+import { runConfigCommand, type ConfigCommandContext } from './config.ts'
+import { runSDK } from './runtime.ts'
+import { DSH_TEMPLATES } from './templates/dsh-templates.ts'
+
+/** Injectable process and command boundaries used by the dsh bin. */
+export interface DshCommandContext extends ConfigCommandContext {
+  cwd: string
+  stdin: NodeJS.ReadStream
+  stdout: NodeJS.WriteStream
+  stderr: NodeJS.WriteStream
+  run?: typeof runSDK
+  build?: typeof runProjectBuild
+  config?: typeof runConfigCommand
+}
+
+/** Run one parsed dsh command and return its process exit code. */
+export async function runDshCommand(
+  argv: readonly string[] = process.argv.slice(2),
+  context: DshCommandContext = {
+    cwd: process.cwd(),
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+  },
+): Promise<number> {
+  try {
+    const args = parseDshArgs(argv)
+    if (args.help || !args.command) {
+      context.stdout.write(DSH_TEMPLATES.usage.render({}))
+      return 0
+    }
+    const run = context.run ?? runSDK
+    const build = context.build ?? runProjectBuild
+    const config = context.config ?? runConfigCommand
+    switch (args.command) {
+      case 'start': await run(args.target, { cwd: context.cwd, argv: args.forwarded }); break
+      case 'dev': await run(args.target, { cwd: context.cwd, dev: true, argv: args.forwarded }); break
+      case 'build': await build(args.forwarded, context.cwd); break
+      case 'config': {
+        const result = await config(context)
+        if (result.installError) return 1
+        break
+      }
+    }
+    return 0
+  } catch (error) {
+    context.stderr.write(`dsh: ${error instanceof Error ? error.message : String(error)}\n`)
+    return 1
+  }
+}
diff --git a/packages/sdk/scripts/src/config.ts b/packages/sdk/scripts/src/config.ts
new file mode 100644
index 0000000000..bb0ab464c4
--- /dev/null
+++ b/packages/sdk/scripts/src/config.ts
@@ -0,0 +1,37 @@
+/**
+ * dsh config command composition.
+ *
+ * @module @deepseek-ai/dsh-scripts/config
+ */
+
+import {
+  ClackPromptPort,
+  SdkProject,
+  createBuiltinRegistry,
+  type PromptPort,
+} from '@deepseek-ai/dsh-helper'
+import { ConfigWorkflow, type ConfigWorkflowResult } from './config/config-workflow.ts'
+
+/** Process stream slice required by dsh config. */
+export interface ConfigCommandContext {
+  cwd: string
+  stdin: NodeJS.ReadStream
+  stdout: NodeJS.WriteStream
+  port?: PromptPort
+  install?: (project: SdkProject) => Promise<void>
+}
+
+/** Open and interactively edit one existing SDK project. */
+export async function runConfigCommand(context: ConfigCommandContext): Promise<ConfigWorkflowResult> {
+  if (!context.port && (!context.stdin.isTTY || !context.stdout.isTTY)) {
+    throw new Error('dsh config requires an interactive TTY')
+  }
+  const project = await SdkProject.open(context.cwd)
+  const registry = createBuiltinRegistry(project.profile)
+  return new ConfigWorkflow(
+    /* v8 ignore next -- production TTY wiring is exercised by the built-bin smoke */
+    context.port ?? new ClackPromptPort(context.stdin, context.stdout),
+    context.stdout,
+    context.install,
+  ).run(project, registry)
+}
diff --git a/packages/sdk/scripts/src/config/config-workflow.ts b/packages/sdk/scripts/src/config/config-workflow.ts
new file mode 100644
index 0000000000..e4e3476c3f
--- /dev/null
+++ b/packages/sdk/scripts/src/config/config-workflow.ts
@@ -0,0 +1,200 @@
+/**
+ * Tree-shaped existing-project feature workflow and single Apply boundary.
+ *
+ * @module @deepseek-ai/dsh-scripts/config/config-workflow
+ */
+
+import type { Writable } from 'node:stream'
+import {
+  FeatureConfigurator,
+  ConfirmQuestion,
+  requireAnswer,
+  type Feature,
+  type FeatureInstallation,
+  type FeatureRegistry,
+  type FeatureSelection,
+  type ChangeSet,
+  type NestedMultiSelectValue,
+  type ProjectCommitResult,
+  type PromptPort,
+  type SdkProject,
+} from '@deepseek-ai/dsh-helper'
+import { DSH_TEMPLATES } from '../templates/dsh-templates.ts'
+
+/** Config result, including an install failure that happened after commit. */
+export interface ConfigWorkflowResult {
+  commit?: ProjectCommitResult<SdkProject>
+  installError?: Error
+}
+
+function featureTarget(feature: Feature): string {
+  return `feature:${feature.id}`
+}
+
+function pluginTarget(id: string): string {
+  return `plugin:${id}`
+}
+
+function sameOptions(left: readonly string[], right: readonly string[]): boolean {
+  return [...left].sort().join('\0') === [...right].sort().join('\0')
+}
+
+/** Reconcile one tree selection into domain commands, then review and commit once. */
+export class ConfigWorkflow {
+  private readonly port: PromptPort
+  private readonly output: Writable
+  private readonly install: (project: SdkProject) => Promise<void>
+
+  /** Bind terminal prompts and descriptive output. */
+  constructor(
+    port: PromptPort,
+    output: Writable = process.stdout,
+    install: (project: SdkProject) => Promise<void> = project => project.profile.packageManager.install(project.root),
+  ) {
+    this.port = port
+    this.output = output
+    this.install = install
+  }
+
+  /** Select desired state, reconcile the working copy, review, and apply. */
+  async run(project: SdkProject, registry: FeatureRegistry): Promise<ConfigWorkflowResult> {
+    const edit = project.edit(registry)
+    const configurator = new FeatureConfigurator(this.port)
+    const features = registry.all().filter(feature => feature.isApplicable(project.profile))
+    const inspections = new Map(edit.inspections().map(item => [item.id, item]))
+    const custom = edit.cordisConfigEntries().filter(entry => !registry.ownerOfPackage(entry.name, project.profile))
+    const desired = requireAnswer(await this.port.nestedMultiselect<string, string>({
+      message: 'Configure the project',
+      showChanges: true,
+      options: [
+        ...features.map((feature) => {
+          const installation = inspections.get(feature.id)
+          /* v8 ignore next -- inspections() is built from this exact feature registry */
+          if (!installation) throw new Error(`feature inspection is missing: ${feature.id}`)
+          const inconsistent = installation.state === 'inconsistent'
+          const selectedOptions = new Set(installation.options.length > 0
+            ? installation.options
+            : feature.defaultOptions(project.profile))
+          return {
+            value: featureTarget(feature),
+            label: feature.summary,
+            required: feature.required,
+            default: feature.required || installation.state === 'enabled' || inconsistent,
+            disabled: inconsistent,
+            ...inconsistent ? { warning: installation.diagnostics.join('; ') } : {},
+            ...feature.mode === 'single' ? {} : {
+              choiceMode: feature.mode,
+              choices: feature.options.map(option => ({
+                value: option.id,
+                label: option.label,
+                default: selectedOptions.has(option.id),
+              })),
+            },
+          }
+        }),
+        ...custom.map(entry => ({
+          value: pluginTarget(entry.id),
+          label: `${entry.name} [custom]`,
+          default: !entry.disabled,
+        })),
+      ],
+    }))
+    const desiredByTarget = new Map(desired.map(item => [item.value, item]))
+
+    for (const feature of features) {
+      const installation = inspections.get(feature.id)
+      /* v8 ignore next -- inspections() is built from this exact feature registry */
+      if (!installation) throw new Error(`feature inspection is missing: ${feature.id}`)
+      if (installation.state === 'inconsistent') continue
+      const choice = desiredByTarget.get(featureTarget(feature))
+      if (!choice && !feature.required) continue
+      await this.enableOrConfigure(feature, installation, choice, project, edit, configurator)
+    }
+
+    for (const feature of [...features].reverse()) {
+      const installation = inspections.get(feature.id)
+      /* v8 ignore next -- inspections() is built from this exact feature registry */
+      if (!installation) throw new Error(`feature inspection is missing: ${feature.id}`)
+      if (feature.required || installation.state !== 'enabled'
+        || desiredByTarget.has(featureTarget(feature))) continue
+      edit.disableFeature(feature)
+    }
+
+    for (const entry of custom) {
+      const enabled = desiredByTarget.has(pluginTarget(entry.id))
+      if (enabled === !entry.disabled) continue
+      edit.setCustomPluginDisabled(entry.id, !enabled)
+    }
+
+    const changes = edit.changes()
+    if (changes.changedFiles.length === 0) {
+      this.output.write('No changes.\n')
+      return {}
+    }
+    this.renderReview(changes)
+    const apply = requireAnswer(await new ConfirmQuestion({
+      id: 'config.apply', message: 'Apply these changes?', initialValue: true,
+    }).resolve(this.port))
+    if (!apply) return {}
+    const commit = await edit.commit()
+    if (!commit.changes.npmDependenciesChanged) return { commit }
+    try {
+      await this.install(project)
+      return { commit }
+    } catch (error) {
+      const installError = error instanceof Error ? error : new Error(String(error))
+      const manager = project.profile.packageManager
+      this.output.write(DSH_TEMPLATES.configInstallFailure.render({
+        error: installError.message,
+        packageManager: manager.name,
+        installArgs: manager.installCommand().join(' '),
+      }))
+      return { commit, installError }
+    }
+  }
+
+  private async enableOrConfigure(
+    feature: Feature,
+    installation: FeatureInstallation,
+    choice: NestedMultiSelectValue<string, string> | undefined,
+    project: SdkProject,
+    edit: ReturnType<SdkProject['edit']>,
+    configurator: FeatureConfigurator,
+  ): Promise<void> {
+    const options = choice?.choices.length
+      ? choice.choices
+      : installation.options.length > 0
+        ? installation.options
+        : feature.defaultOptions(project.profile)
+    if (installation.state === 'absent') {
+      const selection = await configurator.configure(feature, project.profile, undefined, options)
+      edit.installFeature(feature, selection)
+      return
+    }
+    /* v8 ignore next -- non-absent/non-inconsistent inspections always carry their normalized selection */
+    if (!installation.selection) throw new Error(`feature ${feature.id} has no readable selection`)
+    if (!sameOptions(installation.options, options)) {
+      const selection: FeatureSelection = await configurator.configure(
+        feature,
+        project.profile,
+        installation.selection,
+        options,
+      )
+      edit.configureFeature(feature, selection)
+    }
+    if (installation.state === 'disabled') edit.enableFeature(feature)
+  }
+
+  private renderReview(changes: ChangeSet): void {
+    const lines = [
+      ...changes.addedFeatures.map(id => `Install feature: ${id}`),
+      ...changes.enabledFeatures.map(id => `Enable feature: ${id}`),
+      ...changes.disabledFeatures.map(id => `Disable feature: ${id}`),
+      ...changes.configuredFeatures.map(id => `Configure feature: ${id}`),
+      ...changes.enabledPlugins.map(id => `Enable custom plugin: ${id}`),
+      ...changes.disabledPlugins.map(id => `Disable custom plugin: ${id}`),
+      ...changes.changedFiles.map(path => `Change file: ${path}`),
+    ]
+    this.output.write(`${lines.join('\n')}\n`)
+  }
+}
diff --git a/packages/sdk/scripts/src/dev/tsdown-config.ts b/packages/sdk/scripts/src/dev/tsdown-config.ts
new file mode 100644
index 0000000000..15e5603cfa
--- /dev/null
+++ b/packages/sdk/scripts/src/dev/tsdown-config.ts
@@ -0,0 +1,7 @@
+/**
+ * Generated-project tsdown config wrappers.
+ *
+ * @module @deepseek-ai/dsh-scripts/dev/tsdown-config
+ */
+
+export { PluginBuild, ProjectBuild } from '../build.ts'
diff --git a/packages/sdk/scripts/src/index.ts b/packages/sdk/scripts/src/index.ts
new file mode 100644
index 0000000000..5180f885c8
--- /dev/null
+++ b/packages/sdk/scripts/src/index.ts
@@ -0,0 +1,7 @@
+/**
+ * Public DeepSeek Harness SDK runtime entry points.
+ *
+ * @module @deepseek-ai/dsh-scripts
+ */
+
+export { runSDK, startSDK, type SdkBootContext } from './runtime.ts'
diff --git a/packages/sdk/scripts/src/local-plugin-loader-hooks.ts b/packages/sdk/scripts/src/local-plugin-loader-hooks.ts
new file mode 100644
index 0000000000..b57a76da08
--- /dev/null
+++ b/packages/sdk/scripts/src/local-plugin-loader-hooks.ts
@@ -0,0 +1,27 @@
+/**
+ * Node module customization hook for project-local plugin package names.
+ *
+ * @module @deepseek-ai/dsh-scripts/local-plugin-loader-hooks
+ */
+
+import type { ResolveHookContext, ResolveFnOutput } from 'node:module'
+
+interface HookData {
+  mappings: Readonly<Record<string, string>>
+}
+
+let mappings: Readonly<Record<string, string>> = {}
+
+/** Receive the package-name to source-URL map from the launcher thread. */
+export function initialize(data: HookData): void {
+  mappings = { ...data.mappings }
+}
+
+/** Resolve exact local workspace package names to their TypeScript entry source. */
+export async function resolve(
+  specifier: string,
+  context: ResolveHookContext,
+  nextResolve: (specifier: string, context: ResolveHookContext) => Promise<ResolveFnOutput>,
+): Promise<ResolveFnOutput> {
+  return nextResolve(mappings[specifier] ?? specifier, context)
+}
diff --git a/packages/sdk/scripts/src/runtime.ts b/packages/sdk/scripts/src/runtime.ts
new file mode 100644
index 0000000000..fbd9a88726
--- /dev/null
+++ b/packages/sdk/scripts/src/runtime.ts
@@ -0,0 +1,137 @@
+/**
+ * Shared start/dev runtime and project-local module resolution.
+ *
+ * @module @deepseek-ai/dsh-scripts/runtime
+ */
+
+import { register as registerHook } from 'node:module'
+import { access, readFile, readdir } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import type { Context } from 'cordis'
+import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+import { parseSdkBootArgs } from './args.ts'
+
+/** Options that distinguish dev boot from production boot. */
+interface BootProjectOptions {
+  cwd?: string
+  dev?: boolean
+  argv?: readonly string[]
+}
+
+/** Startup context passed to a generated project's exported `main()`. */
+export interface SdkBootContext {
+  /** Developer arguments forwarded after the launcher's `--` separator. */
+  readonly argv: readonly string[]
+  /** SDK-recognized structured arguments parsed from {@link argv}. */
+  readonly args: Record<string, string | boolean | undefined>
+  /** Absolute project working directory selected by the launcher. */
+  readonly cwd: string
+  /** Whether the launcher is running the built or TypeScript development entry. */
+  readonly mode: 'start' | 'dev'
+}
+
+async function localPluginMappings(cwd: string): Promise<Record<string, string>> {
+  const mappings: Record<string, string> = {}
+  let directories
+  try {
+    directories = await readdir(resolve(cwd, 'plugins'), { withFileTypes: true })
+  } catch (error) {
+    /* v8 ignore else -- the other arm requires a filesystem permission/IO fault from readdir */
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return mappings
+    /* v8 ignore next -- paired with the ignored defensive readdir-error arm above */
+    throw error
+  }
+  for (const directory of directories) {
+    if (!directory.isDirectory()) continue
+    const root = resolve(cwd, 'plugins', directory.name)
+    let manifest: { name?: unknown }
+    try {
+      manifest = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8')) as { name?: unknown }
+      await access(resolve(root, 'src/index.ts'))
+    } catch (error) {
+      throw new Error(`cannot load local plugin metadata from ${root}: ${String(error)}`)
+    }
+    if (typeof manifest.name !== 'string' || manifest.name.length === 0) {
+      throw new Error(`local plugin package has no name: ${root}`)
+    }
+    if (mappings[manifest.name]) throw new Error(`duplicate local plugin package name: ${manifest.name}`)
+    mappings[manifest.name] = pathToFileURL(resolve(root, 'src/index.ts')).href
+  }
+  return mappings
+}
+
+/** Register tsx and exact local-plugin source mappings for the current process. */
+async function registerDevRuntime(cwd: string = process.cwd()): Promise<void> {
+  let registerTsx: typeof import('tsx/esm/api')['register']
+  try {
+    ({ register: registerTsx } = await import('tsx/esm/api'))
+  } catch (error) {
+    /* v8 ignore next -- tsx is a declared project NPM dependency; missing-package behavior is defensive */
+    throw new Error(`dsh dev requires the project's tsx NPM dependency: ${String(error)}`)
+  }
+  registerTsx()
+  const mappings = await localPluginMappings(resolve(cwd))
+  const hook = new URL(
+    /* v8 ignore next -- the .js arm is exercised by the built-bin smoke rather than source coverage */
+    import.meta.url.endsWith('.ts')
+      ? './local-plugin-loader-hooks.ts'
+      : './local-plugin-loader-hooks.js', import.meta.url)
+  registerHook(hook, { data: { mappings } })
+}
+
+/**
+ * Boot one cordis.yml after loading its sibling .env.
+ * @param source - file path or file URL to cordis.yml.
+ * @param options - working directory and development-runtime options.
+ * @returns live Cordis context.
+ */
+export async function startSDK(
+  source: string | URL = './cordis.yml',
+  options: BootProjectOptions = {},
+): Promise<Context> {
+  const cwd = resolve(options.cwd ?? process.cwd())
+  if (options.dev) await registerDevRuntime(cwd)
+  if (source instanceof URL && source.protocol !== 'file:') {
+    throw new Error(`cordis.yml URL must use file:, got ${source.protocol}`)
+  }
+  const requested = source instanceof URL ? fileURLToPath(source) : source
+  const absolute = resolveConfigPath(requested, undefined, cwd)
+  loadEnv('dsh', dirname(absolute))
+  installFailLoud('dsh')
+  return boot('dsh', absolute)
+}
+
+/**
+ * Import and invoke a module target's main(), or directly boot cordis.yml.
+ * @param target - module path relative to the project, or absent for cordis.yml.
+ * @param options - working directory and development-runtime options.
+ * @returns target main result or live Cordis context.
+ */
+export async function runSDK(
+  target: string | undefined,
+  options: BootProjectOptions = {},
+): Promise<unknown> {
+  /* v8 ignore next -- the bin always supplies cwd; direct consumers normally accept process.cwd() */
+  const cwd = resolve(options.cwd ?? process.cwd())
+  if (options.dev) await registerDevRuntime(cwd)
+  if (!target) return startSDK('./cordis.yml', { cwd })
+  const absolute = resolve(cwd, target)
+  try {
+    await access(absolute)
+  } catch (error) {
+    const hint = options.dev ? '' : ' Run dsh build first if this is a TypeScript project.'
+    throw new Error(`cannot start missing target ${target}.${hint} ${String(error)}`)
+  }
+  const module = await import(pathToFileURL(absolute).href) as { main?: (context: SdkBootContext) => unknown }
+  if (typeof module.main !== 'function') {
+    throw new Error(`dsh target ${target} must export function main()`)
+  }
+  const argv = [...options.argv ?? []]
+  return module.main({
+    argv,
+    args: parseSdkBootArgs(argv),
+    cwd,
+    mode: options.dev ? 'dev' : 'start',
+  })
+}
diff --git a/packages/sdk/scripts/src/templates/assets/config-install-failure.txt.tpl b/packages/sdk/scripts/src/templates/assets/config-install-failure.txt.tpl
new file mode 100644
index 0000000000..ee1da80f76
--- /dev/null
+++ b/packages/sdk/scripts/src/templates/assets/config-install-failure.txt.tpl
@@ -0,0 +1,2 @@
+Changes were committed, but install failed: {{error}}
+Retry: {{packageManager}} {{installArgs}}
diff --git a/packages/sdk/scripts/src/templates/assets/usage.txt.tpl b/packages/sdk/scripts/src/templates/assets/usage.txt.tpl
new file mode 100644
index 0000000000..b9680dddcf
--- /dev/null
+++ b/packages/sdk/scripts/src/templates/assets/usage.txt.tpl
@@ -0,0 +1,7 @@
+Usage: dsh <command> [options]
+
+Commands:
+  start [target] [-- args...]  Import a built module, or boot cordis.yml
+  dev [target] [-- args...]    Start with TypeScript and local-plugin source resolution
+  build [args...] Run the project's installed tsdown
+  config          Interactively edit project features
diff --git a/packages/sdk/scripts/src/templates/dsh-templates.ts b/packages/sdk/scripts/src/templates/dsh-templates.ts
new file mode 100644
index 0000000000..136ea5940a
--- /dev/null
+++ b/packages/sdk/scripts/src/templates/dsh-templates.ts
@@ -0,0 +1,21 @@
+/**
+ * Package-owned terminal templates for the dsh launcher.
+ *
+ * @module @deepseek-ai/dsh-scripts/templates/dsh-templates
+ */
+
+import { TextTemplate, type PackageManagerName } from '@deepseek-ai/dsh-helper'
+
+interface ConfigInstallFailureTemplateModel {
+  error: string
+  packageManager: PackageManagerName
+  installArgs: string
+}
+
+/** Compiled dsh terminal templates. */
+export const DSH_TEMPLATES = {
+  usage: TextTemplate.fromFile<Record<string, never>>(new URL('./assets/usage.txt.tpl', import.meta.url)),
+  configInstallFailure: TextTemplate.fromFile<ConfigInstallFailureTemplateModel>(
+    new URL('./assets/config-install-failure.txt.tpl', import.meta.url),
+  ),
+} as const
diff --git a/packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap b/packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap
new file mode 100644
index 0000000000..bab11ec455
--- /dev/null
+++ b/packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap
@@ -0,0 +1,303 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`dsh config terminal contract > pins the feature tree and Review & Apply output 1`] = `
+{
+  "committed": {
+    "addedFeatures": [
+      "todo",
+    ],
+    "addedPlugins": [],
+    "changedFiles": [
+      "cordis.yml",
+      "package.json",
+    ],
+    "configuredFeatures": [],
+    "disabledFeatures": [],
+    "disabledPlugins": [],
+    "enabledFeatures": [],
+    "enabledPlugins": [],
+    "npmDependenciesChanged": true,
+  },
+  "installs": 1,
+  "review": "Install feature: todo
+Change file: cordis.yml
+Change file: package.json
+",
+  "transcript": [
+    {
+      "kind": "nested-multiselect",
+      "message": "Configure the project",
+      "options": [
+        {
+          "choiceMode": "exclusive",
+          "choices": [
+            {
+              "default": true,
+              "label": "DeepSeek",
+              "value": "deepseek",
+            },
+            {
+              "default": false,
+              "label": "Custom endpoint (pi-ai)",
+              "value": "custom",
+            },
+          ],
+          "default": true,
+          "disabled": false,
+          "label": "Model provider",
+          "required": true,
+          "value": "feature:provider",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": undefined,
+          "choices": undefined,
+          "default": true,
+          "disabled": false,
+          "label": "Agent runtime spine",
+          "required": true,
+          "value": "feature:spine",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": "exclusive",
+          "choices": [
+            {
+              "default": true,
+              "label": "Local executor",
+              "value": "local",
+            },
+            {
+              "default": false,
+              "label": "Sandboxed executor",
+              "value": "sandbox",
+            },
+          ],
+          "default": true,
+          "disabled": false,
+          "label": "Command execution",
+          "required": true,
+          "value": "feature:bash",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": "exclusive",
+          "choices": [
+            {
+              "default": false,
+              "label": "ACP server",
+              "value": "acp",
+            },
+            {
+              "default": true,
+              "label": "Terminal REPL",
+              "value": "stdio",
+            },
+            {
+              "default": false,
+              "label": "Embedded context",
+              "value": "embed",
+            },
+          ],
+          "default": true,
+          "disabled": false,
+          "label": "Run interface",
+          "required": true,
+          "value": "feature:app",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": "exclusive",
+          "choices": [
+            {
+              "default": true,
+              "label": "JSONL files",
+              "value": "jsonl",
+            },
+            {
+              "default": false,
+              "label": "SQLite database",
+              "value": "sqlite",
+            },
+          ],
+          "default": true,
+          "disabled": false,
+          "label": "Durable session storage",
+          "required": true,
+          "value": "feature:persistence",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": undefined,
+          "choices": undefined,
+          "default": false,
+          "disabled": false,
+          "label": "Hot-module reload",
+          "required": false,
+          "value": "feature:hmr",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": undefined,
+          "choices": undefined,
+          "default": false,
+          "disabled": false,
+          "label": "Read, write, and edit local files",
+          "required": false,
+          "value": "feature:fs",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": undefined,
+          "choices": undefined,
+          "default": false,
+          "disabled": false,
+          "label": "Model-facing task tracking",
+          "required": false,
+          "value": "feature:todo",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": undefined,
+          "choices": undefined,
+          "default": false,
+          "disabled": false,
+          "label": "Local skill discovery",
+          "required": false,
+          "value": "feature:skill",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": "exclusive",
+          "choices": [
+            {
+              "default": true,
+              "label": "DeepSeek search",
+              "value": "deepseek",
+            },
+            {
+              "default": false,
+              "label": "Exa search",
+              "value": "exa",
+            },
+            {
+              "default": false,
+              "label": "Perplexity search",
+              "value": "perplexity",
+            },
+            {
+              "default": false,
+              "label": "Fetch only",
+              "value": "fetch-only",
+            },
+          ],
+          "default": false,
+          "disabled": false,
+          "label": "Web search and fetch tools",
+          "required": false,
+          "value": "feature:web",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": "multiple",
+          "choices": [
+            {
+              "default": true,
+              "label": "Fresh child agent",
+              "value": "spawn",
+            },
+            {
+              "default": false,
+              "label": "Fork parent history",
+              "value": "fork",
+            },
+          ],
+          "default": false,
+          "disabled": false,
+          "label": "Delegate work to child agents",
+          "required": false,
+          "value": "feature:subagent",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": undefined,
+          "choices": undefined,
+          "default": false,
+          "disabled": false,
+          "label": "Scripted multi-agent workflows",
+          "required": false,
+          "value": "feature:workflow",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": undefined,
+          "choices": undefined,
+          "default": false,
+          "disabled": false,
+          "label": "Automatic context compaction",
+          "required": false,
+          "value": "feature:compact",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": "multiple",
+          "choices": [
+            {
+              "default": true,
+              "label": "Claude Code hooks",
+              "value": "claude",
+            },
+            {
+              "default": false,
+              "label": "Codex hooks",
+              "value": "codex",
+            },
+          ],
+          "default": false,
+          "disabled": false,
+          "label": "Run Claude Code or Codex hooks",
+          "required": false,
+          "value": "feature:hooks",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": undefined,
+          "choices": undefined,
+          "default": false,
+          "disabled": false,
+          "label": "Loop-hygiene reminders",
+          "required": false,
+          "value": "feature:guard",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": undefined,
+          "choices": undefined,
+          "default": false,
+          "disabled": false,
+          "label": "Tool timeout policy",
+          "required": false,
+          "value": "feature:timeout-policy",
+          "warning": undefined,
+        },
+        {
+          "choiceMode": undefined,
+          "choices": undefined,
+          "default": false,
+          "disabled": false,
+          "label": "Ask the user from the model loop",
+          "required": false,
+          "value": "feature:ask-user",
+          "warning": undefined,
+        },
+      ],
+      "showChanges": true,
+    },
+    {
+      "initialValue": true,
+      "kind": "confirm",
+      "message": "Apply these changes?",
+    },
+  ],
+}
+`;
diff --git a/packages/sdk/scripts/tests/config.snapshot.ts b/packages/sdk/scripts/tests/config.snapshot.ts
new file mode 100644
index 0000000000..c6f6c64c6c
--- /dev/null
+++ b/packages/sdk/scripts/tests/config.snapshot.ts
@@ -0,0 +1,128 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Writable } from 'node:stream'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  NpmPackageManager,
+  SdkProject,
+  featureId,
+  createBuiltinRegistry,
+  type NestedMultiSelectValue,
+  type PromptPort,
+} from '@deepseek-ai/dsh-helper'
+import type {
+  ConfirmPromptRequest,
+  MultiSelectPromptRequest,
+  NestedMultiSelectRequest,
+  PromptOutcome,
+  SecretPromptRequest,
+  SelectPromptRequest,
+  TextPromptRequest,
+} from '../../helper/src/questions/prompt-port.ts'
+import { ConfigWorkflow } from '../src/config/config-workflow.ts'
+
+class RecordingPort implements PromptPort {
+  readonly transcript: unknown[] = []
+  readonly #answers: unknown[]
+
+  constructor(answers: unknown[]) { this.#answers = [...answers] }
+
+  answer<T>(record: unknown): Promise<PromptOutcome<T>> {
+    this.transcript.push(record)
+    return Promise.resolve({ status: 'answered', value: this.#answers.shift() as T })
+  }
+
+  text(request: TextPromptRequest): Promise<PromptOutcome<string>> {
+    return this.answer({ kind: 'text', message: request.message })
+  }
+  secret(request: SecretPromptRequest): Promise<PromptOutcome<string>> {
+    return this.answer({ kind: 'secret', message: request.message })
+  }
+  select<T>(request: SelectPromptRequest<T>): Promise<PromptOutcome<T>> {
+    return this.answer({
+      kind: 'select', message: request.message,
+      options: request.options.map(option => ({ value: option.value, label: option.label })),
+    })
+  }
+  multiselect<T>(request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>> {
+    return this.answer({ kind: 'multiselect', message: request.message })
+  }
+  confirm(request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>> {
+    return this.answer({ kind: 'confirm', message: request.message, initialValue: request.initialValue })
+  }
+  nestedMultiselect<TValue, TChoice>(
+    request: NestedMultiSelectRequest<TValue, TChoice>,
+  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> {
+    return this.answer({
+      kind: 'nested-multiselect',
+      message: request.message,
+      showChanges: request.showChanges,
+      options: request.options.map(option => ({
+        value: option.value,
+        label: option.label,
+        required: option.required,
+        default: option.default,
+        disabled: option.disabled,
+        warning: option.warning,
+        choiceMode: option.choiceMode,
+        choices: option.choices?.map(choice => ({
+          value: choice.value,
+          label: choice.label,
+          default: choice.default,
+        })),
+      })),
+    })
+  }
+}
+
+const temporary: string[] = []
+
+afterEach(async () => {
+  await Promise.all(temporary.splice(0).map(path => rm(path, { recursive: true, force: true })))
+})
+
+async function baseProject(): Promise<SdkProject> {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-config-snapshot-'))
+  temporary.push(root)
+  const request = {
+    name: 'snapshot-agent',
+    description: 'snapshot',
+    runtime: { model: 'deepseek-v4-flash' },
+    packageManager: new NpmPackageManager('10.0.0'),
+    releaseVersion: '0.0.1',
+    features: [
+      { id: featureId('provider'), options: ['deepseek'], secrets: { apiKey: 'key' } },
+      { id: featureId('bash'), options: ['local'] },
+      { id: featureId('app'), options: ['stdio'] },
+      { id: featureId('persistence'), options: ['jsonl'] },
+    ],
+    localPlugins: [],
+  }
+  const project = SdkProject.create(root, request)
+  const registry = createBuiltinRegistry(project.profile)
+  const edit = project.edit(registry)
+  for (const item of request.features) edit.installFeature(registry.get(item.id), item)
+  return (await edit.commit()).project
+}
+
+describe('dsh config terminal contract', () => {
+  it('pins the feature tree and Review & Apply output', async () => {
+    const project = await baseProject()
+    const registry = createBuiltinRegistry(project.profile)
+    const port = new RecordingPort([
+      [{ value: 'feature:todo', choices: [] }],
+      true,
+    ])
+    let output = ''
+    const stream = new Writable({ write(chunk, _encoding, callback) { output += String(chunk); callback() } })
+    let installs = 0
+    const result = await new ConfigWorkflow(port, stream, async () => { installs += 1 }).run(project, registry)
+    expect({
+      transcript: port.transcript,
+      review: output,
+      installs,
+      committed: result.commit?.changes,
+    }).toMatchSnapshot()
+  })
+})
diff --git a/packages/sdk/scripts/tests/scripts.spec.ts b/packages/sdk/scripts/tests/scripts.spec.ts
new file mode 100644
index 0000000000..572705f8fd
--- /dev/null
+++ b/packages/sdk/scripts/tests/scripts.spec.ts
@@ -0,0 +1,483 @@
+import { mkdtemp, mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { PassThrough, Writable } from 'node:stream'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  LocalPluginBlueprint,
+  NpmPackageManager,
+  SdkProject,
+  featureId,
+  createBuiltinRegistry,
+  type CommandRunner,
+  type NestedMultiSelectValue,
+  type ProjectCreationRequest,
+  type PromptPort,
+} from '@deepseek-ai/dsh-helper'
+import type {
+  ConfirmPromptRequest,
+  MultiSelectPromptRequest,
+  NestedMultiSelectRequest,
+  PromptOutcome,
+  SecretPromptRequest,
+  SelectPromptRequest,
+  TextPromptRequest,
+} from '../../helper/src/questions/prompt-port.ts'
+import { runSDK, startSDK } from '@deepseek-ai/dsh-scripts'
+import { parseDshArgs, parseSdkBootArgs } from '../src/args.ts'
+import { PluginBuild, ProjectBuild, runProjectBuild } from '../src/build.ts'
+import { runDshCommand, type DshCommandContext } from '../src/command.ts'
+import { runConfigCommand } from '../src/config.ts'
+import { ConfigWorkflow } from '../src/config/config-workflow.ts'
+import { initialize, resolve as resolveLocalPlugin } from '../src/local-plugin-loader-hooks.ts'
+
+const temporary: string[] = []
+
+afterEach(async () => {
+  await Promise.all(temporary.splice(0).map(path => rm(path, { recursive: true, force: true })))
+})
+
+class QueuePort implements PromptPort {
+  readonly #answers: unknown[]
+  constructor(answers: unknown[]) { this.#answers = [...answers] }
+  next<T>(): Promise<PromptOutcome<T>> {
+    return Promise.resolve({ status: 'answered', value: this.#answers.shift() as T })
+  }
+  text(_request: TextPromptRequest): Promise<PromptOutcome<string>> { return this.next() }
+  secret(_request: SecretPromptRequest): Promise<PromptOutcome<string>> { return this.next() }
+  select<T>(_request: SelectPromptRequest<T>): Promise<PromptOutcome<T>> { return this.next() }
+  multiselect<T>(_request: MultiSelectPromptRequest<T>): Promise<PromptOutcome<readonly T[]>> { return this.next() }
+  confirm(_request: ConfirmPromptRequest): Promise<PromptOutcome<boolean>> { return this.next() }
+  nestedMultiselect<TValue, TChoice>(
+    _request: NestedMultiSelectRequest<TValue, TChoice>,
+  ): Promise<PromptOutcome<readonly NestedMultiSelectValue<TValue, TChoice>[]>> { return this.next() }
+}
+
+function outputBuffer(): { stream: Writable; read: () => string } {
+  let text = ''
+  return {
+    stream: new Writable({ write(chunk, _encoding, callback) { text += String(chunk); callback() } }),
+    read: () => text,
+  }
+}
+
+function commandContext(cwd: string): DshCommandContext & { readStdout: () => string; readStderr: () => string } {
+  let stdout = ''
+  let stderr = ''
+  const stdin = Object.assign(new PassThrough(), { isTTY: true }) as unknown as NodeJS.ReadStream
+  const output = Object.assign(new Writable({
+    write(chunk, _encoding, callback) { stdout += String(chunk); callback() },
+  }), { isTTY: true }) as unknown as NodeJS.WriteStream
+  const error = new Writable({
+    write(chunk, _encoding, callback) { stderr += String(chunk); callback() },
+  }) as unknown as NodeJS.WriteStream
+  return {
+    cwd, stdin, stdout: output, stderr: error,
+    readStdout: () => stdout,
+    readStderr: () => stderr,
+  }
+}
+
+function creation(
+  extra: ProjectCreationRequest['features'] = [],
+  localPlugins: readonly LocalPluginBlueprint[] = [],
+): ProjectCreationRequest {
+  return {
+    name: 'config-agent',
+    description: 'config test',
+    runtime: { model: 'deepseek-v4-flash' },
+    packageManager: new NpmPackageManager('10.0.0'),
+    releaseVersion: '0.0.1',
+    features: [
+      { id: featureId('provider'), options: ['deepseek'], secrets: { apiKey: 'key' } },
+      { id: featureId('bash'), options: ['local'] },
+      { id: featureId('app'), options: ['embed'] },
+      { id: featureId('persistence'), options: ['jsonl'] },
+      ...extra,
+    ],
+    localPlugins,
+  }
+}
+
+async function committedProject(
+  extra: ProjectCreationRequest['features'] = [],
+  localPlugins: readonly LocalPluginBlueprint[] = [],
+): Promise<SdkProject> {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-config-workflow-'))
+  temporary.push(root)
+  const request = creation(extra, localPlugins)
+  const project = SdkProject.create(root, request)
+  const registry = createBuiltinRegistry(project.profile)
+  const edit = project.edit(registry)
+  for (const item of request.features) edit.installFeature(registry.get(item.id), item)
+  for (const plugin of localPlugins) edit.addPlugin(plugin)
+  return (await edit.commit()).project
+}
+
+describe('Commander launcher arguments', () => {
+  it('parses real subcommands and forwards arbitrary build options', () => {
+    expect(parseDshArgs([])).toMatchObject({ help: true })
+    expect(parseDshArgs(['start', 'index.js'])).toMatchObject({ command: 'start', target: 'index.js' })
+    expect(parseDshArgs(['dev'])).toEqual({ command: 'dev', forwarded: [], help: false })
+    expect(parseDshArgs(['build', '--watch', '--minify'])).toMatchObject({
+      command: 'build', forwarded: ['--watch', '--minify'],
+    })
+    expect(parseDshArgs(['start', 'index.js', '--', '--resume', 'session-1'])).toMatchObject({
+      command: 'start', target: 'index.js', forwarded: ['--resume', 'session-1'],
+    })
+    expect(parseDshArgs(['config'])).toMatchObject({ command: 'config' })
+    expect(parseDshArgs(['start'])).toEqual({ command: 'start', forwarded: [], help: false })
+    expect(parseDshArgs(['dev', 'index.ts'])).toMatchObject({ command: 'dev', target: 'index.ts' })
+    expect(parseDshArgs(['-h'])).toMatchObject({ help: true })
+    expect(() => parseDshArgs(['unknown'])).toThrow()
+    expect(() => parseDshArgs(['config', 'extra'])).toThrow()
+    expect(() => parseDshArgs(['config', '--', 'extra'])).toThrow('does not accept forwarded')
+    expect(parseSdkBootArgs([
+      '--model=mock', '--resume=session-1', '--custom=value', '--verbose', '--no-cache', '--max-depth=-1',
+    ])).toEqual({
+      model: 'mock', resume: 'session-1', custom: 'value', verbose: true, cache: false, 'max-depth': '-1',
+    })
+  })
+
+  it('dispatches every command and maps failures to exit codes', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-command-'))
+    temporary.push(root)
+    const context = commandContext(root)
+    const calls: unknown[] = []
+    context.run = async (target, options) => { calls.push(['run', target, options]); return undefined }
+    context.build = async (args, cwd) => { calls.push(['build', args, cwd]) }
+    context.config = async () => { calls.push(['config']); return {} }
+    await expect(runDshCommand(['start', 'index.js', '--', '--resume', 'session-1'], context)).resolves.toBe(0)
+    await expect(runDshCommand(['dev', 'index.ts'], context)).resolves.toBe(0)
+    await expect(runDshCommand(['build', '--watch'], context)).resolves.toBe(0)
+    await expect(runDshCommand(['config'], context)).resolves.toBe(0)
+    expect(calls).toHaveLength(4)
+    expect(calls[0]).toEqual(['run', 'index.js', { cwd: root, argv: ['--resume', 'session-1'] }])
+    expect(calls[1]).toEqual(['run', 'index.ts', { cwd: root, dev: true, argv: [] }])
+    context.config = async () => ({ installError: new Error('offline') })
+    await expect(runDshCommand(['config'], context)).resolves.toBe(1)
+    context.config = async () => { throw 'broken' }
+    await expect(runDshCommand(['config'], context)).resolves.toBe(1)
+    expect(context.readStderr()).toContain('broken')
+    await expect(runDshCommand(['unknown'], context)).resolves.toBe(1)
+    await expect(runDshCommand([], context)).resolves.toBe(0)
+    expect(context.readStdout()).toContain('Usage: dsh')
+
+    const defaults = commandContext(root)
+    await writeFile(join(root, 'main.mjs'), 'export function main() { return "ok" }\n')
+    await expect(runDshCommand(['start', 'main.mjs'], defaults)).resolves.toBe(0)
+    await expect(runDshCommand(['build'], defaults)).resolves.toBe(0)
+    defaults.port = new QueuePort([[]])
+    await expect(runDshCommand(['config'], defaults)).resolves.toBe(1)
+  })
+})
+
+describe('build profiles and invocation', () => {
+  it('discovers root and plugin targets and creates independent profiles', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-build-profile-'))
+    temporary.push(root)
+    await mkdir(join(root, 'plugins', 'one', 'src'), { recursive: true })
+    await writeFile(join(root, 'index.ts'), 'export {}\n')
+    await writeFile(join(root, 'plugins', 'one', 'package.json'), '{"name":"one"}\n')
+    await writeFile(join(root, 'plugins', 'one', 'src', 'index.ts'), 'export {}\n')
+    expect(ProjectBuild({ cwd: root, entry: ['index.ts'] })).toEqual([
+      { cwd: root, entry: ['index.ts'] },
+      { workspace: { include: ['plugins/*'] } },
+    ])
+    expect(PluginBuild({ entry: ['src/index.ts'], dts: true })).toEqual({ entry: ['src/index.ts'], dts: true })
+    expect(() => ProjectBuild({ workspace: true })).toThrow('owns workspace discovery')
+    expect(() => PluginBuild({ workspace: true })).toThrow('does not accept nested workspace')
+    expect(ProjectBuild({ cwd: join(root, 'empty'), entry: ['index.ts'] })).toEqual([
+      { cwd: join(root, 'empty'), entry: ['index.ts'] },
+    ])
+    expect(ProjectBuild({ entry: ['index.ts'] })[0]).toMatchObject({ entry: ['index.ts'] })
+  })
+
+  it('runs the project-installed tsdown and reports child failure', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-build-run-'))
+    temporary.push(root)
+    await writeFile(join(root, 'package.json'), '{"type":"module"}\n')
+    await writeFile(join(root, 'index.ts'), 'export {}\n')
+    await writeFile(join(root, 'tsdown.config.ts'), 'export default {}\n')
+    await mkdir(join(root, 'node_modules'), { recursive: true })
+    const manifest = fileURLToPath(import.meta.resolve('tsdown/package.json'))
+    await symlink(dirname(manifest), join(root, 'node_modules', 'tsdown'))
+    const calls: string[][] = []
+    const runner: CommandRunner = {
+      run: async (command, args) => {
+        calls.push([command, ...args])
+        return { exitCode: 0, signal: null }
+      },
+    }
+    await runProjectBuild(['--watch'], root, runner)
+    expect(calls[0]?.[0]).toBe(process.execPath)
+    expect(calls[0]?.at(-1)).toBe('--watch')
+    const failed: CommandRunner = { run: async () => ({ exitCode: 2, signal: null }) }
+    await expect(runProjectBuild([], root, failed)).rejects.toThrow('exited with code 2')
+    const killed: CommandRunner = { run: async () => ({ exitCode: null, signal: 'SIGTERM' }) }
+    await expect(runProjectBuild([], root, killed)).rejects.toThrow('killed by SIGTERM')
+  })
+
+  it('reports missing and malformed project tsdown executables', async () => {
+    const missing = await mkdtemp(join(tmpdir(), 'dsh-build-missing-'))
+    temporary.push(missing)
+    await writeFile(join(missing, 'package.json'), '{"type":"module"}')
+    await writeFile(join(missing, 'tsdown.config.ts'), 'export default {}\n')
+    await expect(runProjectBuild([], missing)).rejects.toThrow('requires tsdown')
+    const malformed = await mkdtemp(join(tmpdir(), 'dsh-build-malformed-'))
+    temporary.push(malformed)
+    await writeFile(join(malformed, 'package.json'), '{"type":"module"}')
+    await writeFile(join(malformed, 'tsdown.config.ts'), 'export default {}\n')
+    await mkdir(join(malformed, 'node_modules', 'tsdown'), { recursive: true })
+    await writeFile(join(malformed, 'node_modules', 'tsdown', 'package.json'), JSON.stringify({
+      name: 'tsdown', version: '0.0.0', exports: { './package.json': './package.json' }, bin: {},
+    }))
+    await expect(runProjectBuild([], malformed)).rejects.toThrow('has no executable')
+    await writeFile(join(malformed, 'node_modules', 'tsdown', 'package.json'), JSON.stringify({
+      name: 'tsdown', version: '0.0.0', exports: { './package.json': './package.json' },
+    }))
+    await expect(runProjectBuild([], malformed)).rejects.toThrow('has no executable')
+    const stringBin = await mkdtemp(join(tmpdir(), 'dsh-build-string-bin-'))
+    temporary.push(stringBin)
+    await writeFile(join(stringBin, 'package.json'), '{"type":"module"}')
+    await writeFile(join(stringBin, 'tsdown.config.js'), 'export default {}\n')
+    await mkdir(join(stringBin, 'node_modules', 'tsdown'), { recursive: true })
+    await writeFile(join(stringBin, 'node_modules', 'tsdown', 'package.json'), JSON.stringify({
+      name: 'tsdown', version: '0.0.0', exports: { './package.json': './package.json' }, bin: 'cli.js',
+    }))
+    await writeFile(join(stringBin, 'node_modules', 'tsdown', 'cli.js'), '')
+    let command = ''
+    await runProjectBuild([], stringBin, {
+      run: async (_node, args) => { command = args[0] ?? ''; return { exitCode: 0, signal: null } },
+    })
+    expect(command).toContain('cli.js')
+  })
+
+  it('returns a no-op for a project with no build targets and hints on a missing start target', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-no-build-'))
+    temporary.push(root)
+    let called = false
+    await runProjectBuild([], root, { run: async () => { called = true; return { exitCode: 0, signal: null } } })
+    expect(called).toBe(false)
+    await expect(runSDK('index.js', { cwd: root })).rejects.toThrow('Run dsh build first')
+  })
+
+  it('invokes the target module main export and rejects passive modules', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-module-main-'))
+    temporary.push(root)
+    await writeFile(join(root, 'main.mjs'), 'export function main(context) { return context }\n')
+    await writeFile(join(root, 'passive.mjs'), 'export const value = 1\n')
+    await expect(runSDK('main.mjs', {
+      cwd: root,
+      argv: ['--model=mock', '--resume=session-1', 'custom'],
+    })).resolves.toEqual({
+      argv: ['--model=mock', '--resume=session-1', 'custom'],
+      args: { model: 'mock', resume: 'session-1' }, cwd: root, mode: 'start',
+    })
+    await expect(runSDK('passive.mjs', { cwd: root })).rejects.toThrow('must export function main()')
+  })
+
+  it('boots empty Cordis configs and delegates targetless runs', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-start-sdk-'))
+    temporary.push(root)
+    await writeFile(join(root, 'cordis.yml'), '[]\n')
+    const byUrl = await startSDK(pathToFileURL(join(root, 'cordis.yml')))
+    await byUrl.fiber.dispose()
+    const byRun = await runSDK(undefined, { cwd: root }) as import('cordis').Context
+    await byRun.fiber.dispose()
+    const dev = await startSDK('./cordis.yml', { cwd: root, dev: true })
+    await dev.fiber.dispose()
+    await expect(startSDK(new URL('https://example.invalid/cordis.yml'), { cwd: root })).rejects.toThrow()
+  })
+
+  it('validates local plugin metadata in dev mode', async () => {
+    const malformed = await mkdtemp(join(tmpdir(), 'dsh-dev-malformed-'))
+    temporary.push(malformed)
+    await mkdir(join(malformed, 'plugins', 'bad'), { recursive: true })
+    await expect(runSDK('missing.ts', { cwd: malformed, dev: true })).rejects.toThrow('cannot load local plugin metadata')
+    const absent = await mkdtemp(join(tmpdir(), 'dsh-dev-absent-'))
+    temporary.push(absent)
+    await expect(runSDK('missing.ts', { cwd: absent, dev: true })).rejects.toThrow('cannot start missing target')
+
+    const unnamed = await mkdtemp(join(tmpdir(), 'dsh-dev-unnamed-'))
+    temporary.push(unnamed)
+    await mkdir(join(unnamed, 'plugins', 'bad', 'src'), { recursive: true })
+    await writeFile(join(unnamed, 'plugins', 'bad', 'package.json'), '{}')
+    await writeFile(join(unnamed, 'plugins', 'bad', 'src/index.ts'), 'export {}\n')
+    await expect(runSDK('missing.ts', { cwd: unnamed, dev: true })).rejects.toThrow('has no name')
+
+    const duplicate = await mkdtemp(join(tmpdir(), 'dsh-dev-duplicate-'))
+    temporary.push(duplicate)
+    for (const name of ['one', 'two']) {
+      await mkdir(join(duplicate, 'plugins', name, 'src'), { recursive: true })
+      await writeFile(join(duplicate, 'plugins', name, 'package.json'), '{"name":"same"}')
+      await writeFile(join(duplicate, 'plugins', name, 'src/index.ts'), 'export {}\n')
+    }
+    await expect(runSDK('missing.ts', { cwd: duplicate, dev: true })).rejects.toThrow('duplicate local plugin')
+
+    const valid = await mkdtemp(join(tmpdir(), 'dsh-dev-valid-'))
+    temporary.push(valid)
+    await mkdir(join(valid, 'plugins', 'one', 'src'), { recursive: true })
+    await writeFile(join(valid, 'plugins', 'README.md'), 'skip\n')
+    await writeFile(join(valid, 'plugins', 'one', 'package.json'), '{"name":"local"}')
+    await writeFile(join(valid, 'plugins', 'one', 'src/index.ts'), 'export {}\n')
+    await writeFile(join(valid, 'main.ts'), 'export function main() { return "dev" }\n')
+    await expect(runSDK('main.ts', { cwd: valid, dev: true })).resolves.toBe('dev')
+    await expect(runSDK('missing.ts', { cwd: valid, dev: true })).rejects.toThrow('cannot start missing target')
+  })
+
+  it('maps only exact local package names through the loader hook', async () => {
+    initialize({ mappings: { local: 'file:///tmp/local.ts' } })
+    const next = async (specifier: string) => ({ url: specifier, format: 'module' as const })
+    const context: import('node:module').ResolveHookContext = {
+      conditions: [], importAttributes: {}, parentURL: undefined,
+    }
+    await expect(resolveLocalPlugin('local', context, next)).resolves.toMatchObject({ url: 'file:///tmp/local.ts' })
+    await expect(resolveLocalPlugin('other', context, next)).resolves.toMatchObject({ url: 'other' })
+  })
+})
+
+describe('ConfigWorkflow', () => {
+  it('opens a project through the config command prompt seam', async () => {
+    const project = await committedProject()
+    const context = commandContext(project.root)
+    context.port = new QueuePort([[]])
+    context.install = async () => { throw new Error('install should not run') }
+    await expect(runConfigCommand(context)).resolves.toEqual({})
+    delete context.port
+    delete context.install
+    context.stdin.isTTY = false
+    await expect(runConfigCommand(context)).rejects.toThrow('interactive TTY')
+    context.stdin.isTTY = true
+    context.stdout.isTTY = false
+    await expect(runConfigCommand(context)).rejects.toThrow('interactive TTY')
+  })
+  it('accumulates a disable and commits only after Review & Apply', async () => {
+    const project = await committedProject([{ id: featureId('todo'), options: ['default'] }])
+    const registry = createBuiltinRegistry(project.profile)
+    const output = outputBuffer()
+    const workflow = new ConfigWorkflow(new QueuePort([
+      [], true,
+    ]), output.stream, async () => { throw new Error('install should not run') })
+    const result = await workflow.run(project, registry)
+    expect(result.commit?.project.cordis.entry('tool-todo')?.disabled).toBe(true)
+    expect(output.read()).toContain('Disable feature: todo')
+  })
+
+  it('installs once after NPM dependency changes and keeps committed files on install failure', async () => {
+    const project = await committedProject()
+    const registry = createBuiltinRegistry(project.profile)
+    const output = outputBuffer()
+    let installs = 0
+    const workflow = new ConfigWorkflow(new QueuePort([
+      [{ value: 'feature:todo', choices: [] }], true,
+    ]), output.stream, async () => {
+      installs += 1
+      throw new Error('offline')
+    })
+    const result = await workflow.run(project, registry)
+    expect(installs).toBe(1)
+    expect(result.installError?.message).toBe('offline')
+    expect(result.commit?.project.cordis.entry('tool-todo')).toBeDefined()
+    expect(output.read()).toContain('Changes were committed, but install failed')
+  })
+
+  it('cancels apply and enables a disabled feature without reinstalling', async () => {
+    const project = await committedProject([{ id: featureId('todo'), options: ['default'] }])
+    const registry = createBuiltinRegistry(project.profile)
+    const cancelled = await new ConfigWorkflow(new QueuePort([[], false]), outputBuffer().stream).run(project, registry)
+    expect(cancelled).toEqual({})
+    const disable = project.edit(registry)
+    disable.disableFeature(registry.get(featureId('todo')))
+    const disabled = (await disable.commit()).project
+    let installs = 0
+    const enabled = await new ConfigWorkflow(new QueuePort([
+      [{ value: 'feature:todo', choices: [] }], true,
+    ]), outputBuffer().stream, async () => { installs += 1 }).run(disabled, createBuiltinRegistry(disabled.profile))
+    expect(enabled.commit?.project.cordis.entry('tool-todo')?.disabled).toBeUndefined()
+    expect(installs).toBe(0)
+  })
+
+  it('toggles custom Cordis config entries without changing NPM dependencies', async () => {
+    const project = await committedProject([], [new LocalPluginBlueprint('sample', 'plugin')])
+    await expect(new ConfigWorkflow(new QueuePort([
+      [{ value: 'plugin:sample', choices: [] }],
+    ]), outputBuffer().stream).run(project, createBuiltinRegistry(project.profile))).resolves.toEqual({})
+    const output = outputBuffer()
+    const disabled = await new ConfigWorkflow(new QueuePort([[], true]), output.stream).run(
+      project, createBuiltinRegistry(project.profile),
+    )
+    expect(disabled.commit?.project.cordis.entry('sample')?.disabled).toBe(true)
+    expect(output.read()).toContain('Disable custom plugin: sample')
+    const next = disabled.commit?.project
+    if (!next) throw new Error('custom toggle did not commit')
+    const enabled = await new ConfigWorkflow(new QueuePort([
+      [{ value: 'plugin:sample', choices: [] }], true,
+    ]), outputBuffer().stream).run(next, createBuiltinRegistry(next.profile))
+    expect(enabled.commit?.project.cordis.entry('sample')?.disabled).toBeUndefined()
+  })
+
+  it('shows inconsistent features as diagnostic-only rows', async () => {
+    const complete = await committedProject()
+    await writeFile(join(complete.root, 'cordis.yml'), `${await readFile(join(complete.root, 'cordis.yml'), 'utf8')}- id: web-search-exa
+  name: '@deepseek-ai/dsh-web-search-exa'
+`)
+    const project = await SdkProject.open(complete.root)
+    const port = new QueuePort([[]])
+    await expect(new ConfigWorkflow(port, outputBuffer().stream).run(project, createBuiltinRegistry(project.profile)))
+      .resolves.toEqual({})
+  })
+
+  it('uses the default installer and normalizes non-Error install failures', async () => {
+    const project = await committedProject()
+    const install = vi.spyOn(NpmPackageManager.prototype, 'install').mockResolvedValue()
+    await new ConfigWorkflow(new QueuePort([
+      [{ value: 'feature:todo', choices: [] }], true,
+    ])).run(project, createBuiltinRegistry(project.profile))
+    expect(install).toHaveBeenCalledOnce()
+    install.mockRestore()
+    const next = await committedProject()
+    const failed = await new ConfigWorkflow(new QueuePort([
+      [{ value: 'feature:todo', choices: [] }], true,
+    ]), outputBuffer().stream, async () => { throw 'offline-string' }).run(next, createBuiltinRegistry(next.profile))
+    expect(failed.installError?.message).toBe('offline-string')
+  })
+
+  it('reconciles a child option selected in the feature tree', async () => {
+    const project = await committedProject()
+    const registry = createBuiltinRegistry(project.profile)
+    let installs = 0
+    const workflow = new ConfigWorkflow(new QueuePort([
+      [{ value: 'feature:persistence', choices: ['sqlite'] }], true,
+    ]), outputBuffer().stream, async () => { installs += 1 })
+    const result = await workflow.run(project, registry)
+    expect(result.commit?.project.cordis.entry('session-persistence')).toMatchObject({
+      name: '@deepseek-ai/dsh-session-persistence-sqlite',
+      config: { path: './.sessions/sessions.sqlite' },
+    })
+    expect(installs).toBe(1)
+  })
+
+  it('switches required provider and interface options', async () => {
+    const project = await committedProject()
+    const registry = createBuiltinRegistry(project.profile)
+    const workflow = new ConfigWorkflow(new QueuePort([
+      [
+        { value: 'feature:provider', choices: ['custom'] },
+        { value: 'feature:app', choices: ['stdio'] },
+        { value: 'feature:persistence', choices: ['jsonl'] },
+      ],
+      'https://provider.example/v1',
+      'custom-key',
+      true,
+    ]), outputBuffer().stream, async () => {})
+    const result = await workflow.run(project, registry)
+    const provider = result.commit?.project.cordis.entry('llm-pi-ai')
+    expect(provider?.config?.apiKey).toBeDefined()
+    expect(provider?.config?.baseURL).toBe('https://provider.example/v1')
+    expect(result.commit?.project.cordis.entry('stdio')).toBeDefined()
+    expect(result.commit?.project.cordis.entry('agent-loop')).toBeDefined()
+    expect(result.commit?.project.cordis.entry('agent-core')).toBeUndefined()
+  })
+})
diff --git a/packages/sdk/scripts/tsconfig.json b/packages/sdk/scripts/tsconfig.json
new file mode 100644
index 0000000000..848de9a314
--- /dev/null
+++ b/packages/sdk/scripts/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../helper" },
+    { "path": "../../ui/app-boot" },
+    { "path": "../../../vendor/cordis" }
+  ]
+}
diff --git a/packages/sdk/scripts/tsdown.config.ts b/packages/sdk/scripts/tsdown.config.ts
new file mode 100644
index 0000000000..2218faa7be
--- /dev/null
+++ b/packages/sdk/scripts/tsdown.config.ts
@@ -0,0 +1,22 @@
+import { defineConfig } from 'tsdown'
+
+/** Bundle each public or runtime entry and mirror package-owned terminal templates. */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
+    fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
+    copy: [{ from: 'src/templates/assets/*', to: 'lib/assets' }],
+  },
+  {
+    entry: ['lib/types/bin.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
+    fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
+  },
+  {
+    entry: ['lib/types/dev/tsdown-config.js'], outDir: 'lib/dev', format: ['esm'], platform: 'node',
+    target: 'es2024', fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
+  },
+  {
+    entry: ['lib/types/local-plugin-loader-hooks.js'], outDir: 'lib', format: ['esm'], platform: 'node',
+    target: 'es2024', fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
+  },
+])
diff --git a/packages/ui/app-boot/README.md b/packages/ui/app-boot/README.md
index e7145c24fc..5fed7b5023 100644
--- a/packages/ui/app-boot/README.md
+++ b/packages/ui/app-boot/README.md
@@ -12,7 +12,9 @@ Shared boot glue for the app bins ([`dsh-stdio-demo`](../../examples/stdio-demo/
 
 Two failure classes the guards handle: `loader.await()` swallows init rejections (`Promise.allSettled`) — Node still exits non-zero on the resulting unhandled rejection, and `installFailLoud` replaces the noisy dump with one labelled line and a guaranteed `exit(1)`; a failed plugin IMPORT is only logged by the Loader (the process would otherwise exit 0 on a usable config typo), leaving a fiber-less entry that `assertEntriesLoaded` turns into a `boot()` rejection.
 
-Bare plugin specifiers in a config (`@deepseek-ai/dsh-*`) resolve through the cordis Loader's internal module loader, using `node --expose-internals` or the optional `node-addon-require-builtin` fallback. the bins' subprocess smokes exercise that path, while this package's unit suite drives `boot()` in-process against configs with relative specifiers.
+Bare plugin specifiers in a config (`@deepseek-ai/dsh-*`, npm packages) resolve through the cordis Loader's internal module loader when Node runs with `--expose-internals` or the optional `node-addon-require-builtin` fallback is installed; without either, consumers must install plugins where plain Node import resolution can find them. Relative specifiers resolve against the config directory with no flag. The bins' subprocess smokes exercise the internal-loader path, while this package's unit suite drives `boot()` in-process against configs with relative specifiers.
+
+This package carries no loader hooks and no dev-mode surface: the `dsh-scripts` launcher ([`sdk/scripts`](../../sdk/scripts/README.md), with the shared project model in [`sdk/helper`](../../sdk/helper/README.md)) owns process startup, tsx registration, and local-plugin source resolution, and consumes these helpers for the boot sequence itself.
 
 ## Model Experience
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5da3d025d9..b1a3a78030 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -819,7 +819,7 @@ importers:
     dependencies:
       '@earendil-works/pi-ai':
         specifier: ^0.79.1
-        version: 0.79.3(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.21.0)(zod@4.4.3)
+        version: 0.79.3(ws@8.21.0)(zod@4.4.3)
       schemastery:
         specifier: ^3.18.0
         version: 3.18.0
@@ -890,6 +890,90 @@ importers:
         specifier: ^4.0.0-rc.7
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
+  packages/sdk/create-sdk:
+    dependencies:
+      '@deepseek-ai/dsh-helper':
+        specifier: workspace:^
+        version: link:../helper
+      commander:
+        specifier: ^15.0.0
+        version: 15.0.0
+    devDependencies:
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
+  packages/sdk/helper:
+    dependencies:
+      '@clack/core':
+        specifier: ^1.4.3
+        version: 1.4.3
+      '@clack/prompts':
+        specifier: ^1.7.0
+        version: 1.7.0
+      handlebars:
+        specifier: ^4.7.9
+        version: 4.7.9
+      jsonc-parser:
+        specifier: ^3.3.1
+        version: 3.3.1
+      yaml:
+        specifier: ^2.9.0
+        version: 2.9.0
+    devDependencies:
+      '@deepseek-ai/dsh-brand':
+        specifier: workspace:^
+        version: link:../../util/brand
+      '@deepseek-ai/dsh-compact-basic':
+        specifier: workspace:^
+        version: link:../../compact/compact-basic
+      '@deepseek-ai/dsh-hooks-claude':
+        specifier: workspace:^
+        version: link:../../hooks/hooks-claude
+      '@deepseek-ai/dsh-hooks-codex':
+        specifier: workspace:^
+        version: link:../../hooks/hooks-codex
+      '@deepseek-ai/dsh-session-persistence-jsonl':
+        specifier: workspace:^
+        version: link:../../session-persistence/session-persistence-jsonl
+      '@deepseek-ai/dsh-session-persistence-sqlite':
+        specifier: workspace:^
+        version: link:../../session-persistence/session-persistence-sqlite
+      '@deepseek-ai/dsh-tool-subagent':
+        specifier: workspace:^
+        version: link:../../subagent/tool-subagent
+      '@deepseek-ai/dsh-tool-web':
+        specifier: workspace:^
+        version: link:../../web/tool-web
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
+  packages/sdk/scripts:
+    dependencies:
+      '@deepseek-ai/dsh-helper':
+        specifier: workspace:^
+        version: link:../helper
+      commander:
+        specifier: ^15.0.0
+        version: 15.0.0
+      node-addon-require-builtin:
+        specifier: ^0.1.0
+        version: 0.1.0
+    devDependencies:
+      '@deepseek-ai/dsh-app-boot':
+        specifier: workspace:^
+        version: link:../../ui/app-boot
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+      tsdown:
+        specifier: ^0.22.2
+        version: 0.22.2(oxc-resolver@11.20.0)(publint@0.3.21)(tsx@4.22.4)(typescript@6.0.3)
+      tsx:
+        specifier: ^4.22.4
+        version: 4.22.4
+
   packages/session-persistence/session-persistence:
     devDependencies:
       '@deepseek-ai/dsh-session':
@@ -2366,6 +2450,14 @@ packages:
   '@chevrotain/types@11.1.2':
     resolution: {integrity: sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==}
 
+  '@clack/core@1.4.3':
+    resolution: {integrity: sha512-/kr3UWNtdJfxZtPgDqUOmG2pvwlmcLGheex5yiZKdwbzZJxhV+HMNR9QNmyY5cGwTNV6LrR7Jtp+KjhUAP1qBQ==}
+    engines: {node: '>= 20.12.0'}
+
+  '@clack/prompts@1.7.0':
+    resolution: {integrity: sha512-y7/yvZ2TPAnR9+jnc00klvNNLkJiXFFrQA/hlLCcxA9a2A4zQIOimyFQ9XfwYKiGD1fb5GY8vbKIIgO8d5Tb2A==}
+    engines: {node: '>= 20.12.0'}
+
   '@cordisjs/plugin-include@1.0.4':
     resolution: {integrity: sha512-b1Hm1wmue0v7d/jayoXoBjCV2J14XWTL5yyDZEYeL2L9HgcyTq6JbCw99ozSbei98uAbkwq/pBhimsp/HsySeg==}
     peerDependencies:
@@ -2967,10 +3059,6 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@pkgjs/parseargs@0.11.0':
-    resolution: {integrity: sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==}
-    engines: {node: '>=14'}
-
   '@protobufjs/aspromise@1.1.2':
     resolution: {integrity: sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==}
 
@@ -3649,6 +3737,10 @@ packages:
   color-name@1.1.4:
     resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
 
+  commander@15.0.0:
+    resolution: {integrity: sha512-z67u4ZhzCL/Tydu1lJARtEZYWbWaN7oYLHbsuzocr6y4N6WZAagG3RQ4FW61V1/0+jImpj293XfrcYnd1qxtPg==}
+    engines: {node: '>=22.12.0'}
+
   commander@7.2.0:
     resolution: {integrity: sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==}
     engines: {node: '>= 10'}
@@ -4107,9 +4199,18 @@ packages:
   fast-levenshtein@2.0.6:
     resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==}
 
+  fast-string-truncated-width@3.0.3:
+    resolution: {integrity: sha512-0jjjIEL6+0jag3l2XWWizO64/aZVtpiGE3t0Zgqxv0DPuxiMjvB3M24fCyhZUO4KomJQPj3LTSUnDP3GpdwC0g==}
+
+  fast-string-width@3.0.2:
+    resolution: {integrity: sha512-gX8LrtNEI5hq8DVUfRQMbr5lpaS4nMIWV+7XEbXk2b8kiQIizgnlr12B4dA3ZEx3308ze0O4Q1R+cHts8kyUJg==}
+
   fast-uri@3.1.3:
     resolution: {integrity: sha512-i70LwGWUduXqzicKXWshooq+sWL1K3WUU5rKZNG/0i3a1OSoX3HqhH5WbWwTmqWfor4urUakGPiRQcleRZTwOg==}
 
+  fast-wrap-ansi@0.2.2:
+    resolution: {integrity: sha512-7F2Fl+TjRSenLqlU3UjSH0iyqopqoZIu7eZVpEirP2g1GtWa2G/ecEmBdgz31+Mxr+ELclgg6sokpSFIQiZ02Q==}
+
   fast-xml-builder@1.2.0:
     resolution: {integrity: sha512-00aAWieqff+ZJhsXA4g1g7M8k+7AYoMUUHF+/zFb5U6Uv/P0Vl4QZo84/IcufzYalLuEj9928bXN9PbbFzMF0Q==}
 
@@ -4238,6 +4339,11 @@ packages:
   hachure-fill@0.5.2:
     resolution: {integrity: sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg==}
 
+  handlebars@4.7.9:
+    resolution: {integrity: sha512-4E71E0rpOaQuJR2A3xDZ+GM1HyWYv1clR58tC8emQNeQe3RH7MAzSbat+V0wG78LQBo6m6bzSG/L4pBuCsgnUQ==}
+    engines: {node: '>=0.4.7'}
+    hasBin: true
+
   has-flag@4.0.0:
     resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==}
     engines: {node: '>=8'}
@@ -4454,6 +4560,9 @@ packages:
   json-stable-stringify-without-jsonify@1.0.1:
     resolution: {integrity: sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==}
 
+  jsonc-parser@3.3.1:
+    resolution: {integrity: sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==}
+
   jsx-ast-utils-x@0.1.0:
     resolution: {integrity: sha512-eQQBjBnsVtGacsG9uJNB8qOr3yA8rga4wAaGG1qRcBzSIvfhERLrWxMAM1hp5fcS6Abo8M4+bUBTekYR0qTPQw==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
@@ -4815,6 +4924,9 @@ packages:
     resolution: {integrity: sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==}
     engines: {node: '>=16 || 14 >=14.17'}
 
+  minimist@1.2.8:
+    resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==}
+
   minipass@7.1.3:
     resolution: {integrity: sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==}
     engines: {node: '>=16 || 14 >=14.17'}
@@ -4838,6 +4950,9 @@ packages:
     resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==}
     engines: {node: '>= 0.6'}
 
+  neo-async@2.6.2:
+    resolution: {integrity: sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==}
+
   node-addon-landlock-run-linux-arm64@0.0.0-test.0:
     resolution: {integrity: sha512-oJsXcC33qKl9mWYx0n9YPJ2pUAoY39PoIX0Gx4lDrSCTEvENFrEaODAsQYNY+eEGpn9YMN7E+FOftvea3/1FqQ==}
     engines: {node: '>=20'}
@@ -5218,6 +5333,9 @@ packages:
     resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==}
     engines: {node: '>=14'}
 
+  sisteransi@1.0.5:
+    resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
+
   smol-toml@1.6.1:
     resolution: {integrity: sha512-dWUG8F5sIIARXih1DTaQAX4SsiTXhInKf1buxdY9DIg4ZYPZK5nGM1VRIYmEbDbsHt7USo99xSLFu5Q1IqTmsg==}
     engines: {node: '>= 18'}
@@ -5226,6 +5344,10 @@ packages:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
     engines: {node: '>=0.10.0'}
 
+  source-map@0.6.1:
+    resolution: {integrity: sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==}
+    engines: {node: '>=0.10.0'}
+
   stackback@0.0.2:
     resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
 
@@ -5403,6 +5525,11 @@ packages:
     engines: {node: '>=14.17'}
     hasBin: true
 
+  uglify-js@3.19.3:
+    resolution: {integrity: sha512-v3Xu+yuwBXisp6QYTcH4UbH+xYJXqnq2m/LtQVWKWzYc1iehYnLixoQDN9FH6/j9/oybfd6W9Ghwkl8+UMKTKQ==}
+    engines: {node: '>=0.8.0'}
+    hasBin: true
+
   unbash@3.0.0:
     resolution: {integrity: sha512-FeFPZ/WFT0mbRCuydiZzpPFlrYN8ZUpphQKoq4EeElVIYjYyGzPMxQR/simUwCOJIyVhpFk4RbtyO7RuMpMnHA==}
     engines: {node: '>=14'}
@@ -5577,6 +5704,9 @@ packages:
     resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
     engines: {node: '>=0.10.0'}
 
+  wordwrap@1.0.0:
+    resolution: {integrity: sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==}
+
   wrap-ansi@7.0.0:
     resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==}
     engines: {node: '>=10'}
@@ -5944,6 +6074,18 @@ snapshots:
 
   '@chevrotain/types@11.1.2': {}
 
+  '@clack/core@1.4.3':
+    dependencies:
+      fast-wrap-ansi: 0.2.2
+      sisteransi: 1.0.5
+
+  '@clack/prompts@1.7.0':
+    dependencies:
+      '@clack/core': 1.4.3
+      fast-string-width: 3.0.2
+      fast-wrap-ansi: 0.2.2
+      sisteransi: 1.0.5
+
   '@cordisjs/plugin-include@1.0.4(@cordisjs/plugin-loader@1.0.0-rc.5)(cordis@4.0.0-rc.7)':
     dependencies:
       '@cordisjs/plugin-loader': 1.0.0-rc.5(cordis@4.0.0-rc.7)(node-addon-require-builtin@0.1.0)
@@ -5995,11 +6137,11 @@ snapshots:
 
   '@csstools/css-tokenizer@4.0.0': {}
 
-  '@earendil-works/pi-ai@0.79.3(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.21.0)(zod@4.4.3)':
+  '@earendil-works/pi-ai@0.79.3(ws@8.21.0)(zod@4.4.3)':
     dependencies:
       '@anthropic-ai/sdk': 0.91.1(zod@4.4.3)
       '@aws-sdk/client-bedrock-runtime': 3.1048.0
-      '@google/genai': 1.52.0(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))
+      '@google/genai': 1.52.0
       '@mistralai/mistralai': 2.2.1
       '@smithy/node-http-handler': 4.7.3
       http-proxy-agent: 7.0.2
@@ -6157,14 +6299,12 @@ snapshots:
 
   '@exodus/bytes@1.15.1': {}
 
-  '@google/genai@1.52.0(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))':
+  '@google/genai@1.52.0':
     dependencies:
       google-auth-library: 10.7.0
       p-retry: 4.6.2
       protobufjs: 7.6.4
       ws: 8.21.0
-    optionalDependencies:
-      '@modelcontextprotocol/sdk': 1.29.0(zod@4.4.3)
     transitivePeerDependencies:
       - bufferutil
       - supports-color
@@ -6423,9 +6563,6 @@ snapshots:
   '@oxc-resolver/binding-win32-x64-msvc@11.20.0':
     optional: true
 
-  '@pkgjs/parseargs@0.11.0':
-    optional: true
-
   '@protobufjs/aspromise@1.1.2': {}
 
   '@protobufjs/base64@1.1.2': {}
@@ -7089,6 +7226,8 @@ snapshots:
 
   color-name@1.1.4: {}
 
+  commander@15.0.0: {}
+
   commander@7.2.0: {}
 
   commander@8.3.0: {}
@@ -7618,8 +7757,18 @@ snapshots:
 
   fast-levenshtein@2.0.6: {}
 
+  fast-string-truncated-width@3.0.3: {}
+
+  fast-string-width@3.0.2:
+    dependencies:
+      fast-string-truncated-width: 3.0.3
+
   fast-uri@3.1.3: {}
 
+  fast-wrap-ansi@0.2.2:
+    dependencies:
+      fast-string-width: 3.0.2
+
   fast-xml-builder@1.2.0:
     dependencies:
       path-expression-matcher: 1.5.0
@@ -7772,6 +7921,15 @@ snapshots:
 
   hachure-fill@0.5.2: {}
 
+  handlebars@4.7.9:
+    dependencies:
+      minimist: 1.2.8
+      neo-async: 2.6.2
+      source-map: 0.6.1
+      wordwrap: 1.0.0
+    optionalDependencies:
+      uglify-js: 3.19.3
+
   has-flag@4.0.0: {}
 
   has-symbols@1.1.0: {}
@@ -7876,8 +8034,6 @@ snapshots:
   jackspeak@3.4.3:
     dependencies:
       '@isaacs/cliui': 8.0.2
-    optionalDependencies:
-      '@pkgjs/parseargs': 0.11.0
 
   jiti@2.7.0: {}
 
@@ -7965,6 +8121,8 @@ snapshots:
 
   json-stable-stringify-without-jsonify@1.0.1: {}
 
+  jsonc-parser@3.3.1: {}
+
   jsx-ast-utils-x@0.1.0: {}
 
   jszip@3.10.1:
@@ -8489,6 +8647,8 @@ snapshots:
     dependencies:
       brace-expansion: 2.1.2
 
+  minimist@1.2.8: {}
+
   minipass@7.1.3: {}
 
   mri@1.2.0: {}
@@ -8501,6 +8661,8 @@ snapshots:
 
   negotiator@1.0.0: {}
 
+  neo-async@2.6.2: {}
+
   node-addon-landlock-run-linux-arm64@0.0.0-test.0:
     optional: true
 
@@ -8957,10 +9119,14 @@ snapshots:
 
   signal-exit@4.1.0: {}
 
+  sisteransi@1.0.5: {}
+
   smol-toml@1.6.1: {}
 
   source-map-js@1.2.1: {}
 
+  source-map@0.6.1: {}
+
   stackback@0.0.2: {}
 
   statuses@2.0.2: {}
@@ -9108,6 +9274,9 @@ snapshots:
 
   typescript@6.0.3: {}
 
+  uglify-js@3.19.3:
+    optional: true
+
   unbash@3.0.0: {}
 
   unconfig-core@7.5.0:
@@ -9281,6 +9450,8 @@ snapshots:
 
   word-wrap@1.2.5: {}
 
+  wordwrap@1.0.0: {}
+
   wrap-ansi@7.0.0:
     dependencies:
       ansi-styles: 4.3.0
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index 4dac840da2..c10dd1396c 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -116,11 +116,31 @@ const dshWorkerPackageFiles = [
   'src',
 ] as const
 
+const packageFileExtras: Readonly<Record<string, readonly string[]>> = {
+  '@deepseek-ai/dsh-helper': ['lib/assets'],
+  '@deepseek-ai/dsh-scripts': [
+    'lib/dev/tsdown-config.js',
+    'lib/local-plugin-loader-hooks.js',
+    'lib/assets',
+  ],
+}
+
 function sameStringList(actual: readonly string[] | undefined, expected: readonly string[]): boolean {
   return !!actual && actual.length === expected.length && actual.every((value, index) => value === expected[index])
 }
 
 function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] {
+  const extras = manifest.name ? packageFileExtras[manifest.name] ?? [] : []
+  if (extras.length > 0) {
+    return [
+      'lib/index.js',
+      ...manifest.bin ? ['lib/bin.js'] : [],
+      ...extras,
+      'lib/types/**/*.d.ts',
+      'lib/types/**/*.d.ts.map',
+      'src',
+    ]
+  }
   if (manifest.bin) return dshBinPackageFiles
   // A declared "./worker" subpath export sanctions the one extra runtime
   // bundle a worker-thread entry needs (and NodeNext/publint then validate
diff --git a/scripts/verify-export-jsdoc.ts b/scripts/verify-export-jsdoc.ts
index 44729e73f0..8ff42fa876 100644
--- a/scripts/verify-export-jsdoc.ts
+++ b/scripts/verify-export-jsdoc.ts
@@ -7,8 +7,8 @@
  * re-exports keep their docs at the declaring contract. Unknown forms fail closed.
  */
 
-import { existsSync, globSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { existsSync, globSync, readFileSync } from 'node:fs'
+import { relative, resolve, sep } from 'node:path'
 import ts from 'typescript'
 import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc } from './jsdoc.ts'
 
@@ -389,7 +389,13 @@ function checkDecl(
  * @param w - the walk state violations append to.
  * @param ambient - whether this scope is ambient (`declare` namespace or a declaration file), where members export implicitly.
  */
-function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk, ambient: boolean): void {
+function checkScope(
+  statements: readonly ts.Statement[],
+  prefix: string,
+  w: Walk,
+  ambient: boolean,
+  allowedNames?: ReadonlySet<string>,
+): void {
   const byName = new Map<string, ts.Statement[]>()
   const overloadSigs = new Set<string>()
   const add = (name: string, stmt: ts.Statement): void => {
@@ -455,7 +461,20 @@ function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk
       }
       continue
     }
-    if (isExported(stmt) || (ambient && !ts.isImportDeclaration(stmt))) request(stmt, null)
+    if (isExported(stmt) || (ambient && !ts.isImportDeclaration(stmt))) {
+      if (allowedNames === undefined) {
+        request(stmt, null)
+      } else if (ts.isVariableStatement(stmt)) {
+        for (const declaration of stmt.declarationList.declarations) {
+          if (ts.isIdentifier(declaration.name) && allowedNames.has(declaration.name.text)) {
+            request(stmt, declaration.name.text)
+          }
+        }
+      } else {
+        const name = declarationName(stmt) ?? 'default'
+        if (allowedNames.has(name)) request(stmt, null)
+      }
+    }
   }
   for (const stmt of statements) {
     const only = requested.get(stmt)
@@ -463,6 +482,67 @@ function checkScope(statements: readonly ts.Statement[], prefix: string, w: Walk
   }
 }
 
+function exportedTargets(value: unknown): string[] {
+  if (typeof value === 'string') return [value]
+  if (!value || typeof value !== 'object') return []
+  return Object.values(value).flatMap(exportedTargets)
+}
+
+function sourceEntry(target: string): string | undefined {
+  if (target.startsWith('./lib/types/') && target.endsWith('.d.ts')) {
+    return `src/${target.slice('./lib/types/'.length, -'.d.ts'.length)}.ts`
+  }
+  if (target.startsWith('./lib/') && target.endsWith('.js')) {
+    return `src/${target.slice('./lib/'.length, -'.js'.length)}.ts`
+  }
+  return undefined
+}
+
+function declarationName(declaration: ts.Node): string | undefined {
+  const name = (declaration as ts.NamedDeclaration).name
+  if (name && ts.isIdentifier(name)) return name.text
+  return undefined
+}
+
+/** Resolve the declarations reachable through packages that do not export src/*. */
+function restrictedPublicNames(
+  scanRoot: string,
+  rels: readonly string[],
+  program: ts.Program,
+  checker: ts.TypeChecker,
+): { restrictedPackages: Set<string>; namesByFile: Map<string, Set<string>> } {
+  const restrictedPackages = new Set<string>()
+  const namesByFile = new Map<string, Set<string>>()
+  const packages = new Set(rels.map(rel => rel.split('/').slice(0, 3).join('/')))
+  for (const packageDir of packages) {
+    const manifestPath = resolve(scanRoot, packageDir, 'package.json')
+    if (!existsSync(manifestPath)) continue
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as { exports?: Record<string, unknown> }
+    if (!manifest.exports || manifest.exports['./src/*'] !== undefined) continue
+    restrictedPackages.add(packageDir)
+    const entries = new Set(Object.values(manifest.exports).flatMap(exportedTargets).flatMap((target) => {
+      const entry = sourceEntry(target)
+      return entry ? [`${packageDir}/${entry}`] : []
+    }))
+    for (const entry of entries) {
+      const source = program.getSourceFile(resolve(scanRoot, entry))
+      const moduleSymbol = source && checker.getSymbolAtLocation(source)
+      if (!source || !moduleSymbol) continue
+      for (const exported of checker.getExportsOfModule(moduleSymbol)) {
+        const target = (exported.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(exported) : exported
+        for (const declaration of target.declarations ?? []) {
+          const name = declarationName(declaration)
+          const file = declaration.getSourceFile().fileName
+          const rel = relative(scanRoot, file).split(sep).join('/')
+          if (!name || !rel.startsWith(`${packageDir}/src/`)) continue
+          namesByFile.set(rel, new Set([...(namesByFile.get(rel) ?? []), name]))
+        }
+      }
+    }
+  }
+  return { restrictedPackages, namesByFile }
+}
+
 /**
  * Compiler options for the walk's program.
  *
@@ -495,15 +575,26 @@ function loadCompilerOptions(scanRoot: string): ts.CompilerOptions {
  */
 export function collectExportJsdocViolations(scanRoot: string = root): string[] {
   const violations: string[] = []
-  const rels = globSync('packages/*/*/src/**/*.ts', { cwd: scanRoot }).sort()
+  const rels = globSync('packages/*/*/src/**/*.ts', { cwd: scanRoot })
+    .map(path => path.split(sep).join('/'))
+    .sort()
   const program = ts.createProgram(rels.map(rel => resolve(scanRoot, rel)), loadCompilerOptions(scanRoot))
   const checker = program.getTypeChecker()
+  const { restrictedPackages, namesByFile } = restrictedPublicNames(scanRoot, rels, program, checker)
   for (const rel of rels) {
     const sf = program.getSourceFile(resolve(scanRoot, rel))
     if (!sf) continue // program root files always resolve; guard for narrowing
     // A script-style declaration file (no imports/exports) is one big ambient
     // scope; a module-style .d.ts still honors explicit export modifiers.
-    checkScope(sf.statements, '', { rel, sf, text: sf.text, checker, violations }, sf.isDeclarationFile && !ts.isExternalModule(sf))
+    const packageDir = rel.split('/').slice(0, 3).join('/')
+    const allowedNames = restrictedPackages.has(packageDir) ? namesByFile.get(rel) ?? new Set<string>() : undefined
+    checkScope(
+      sf.statements,
+      '',
+      { rel, sf, text: sf.text, checker, violations },
+      sf.isDeclarationFile && !ts.isExternalModule(sf),
+      allowedNames,
+    )
   }
   return violations
 }
diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts
index ca576ffc0f..8220324210 100644
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -48,6 +48,9 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/hooks/hook-protocol': { kind: 'indirect', reason: 'Only the hook bridge plugins render decoded hook output to a model.' },
   'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
   'packages/sandbox/sandbox-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-bash-sandbox and dsh-tool-bash.' },
+  'packages/sdk/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' },
+  'packages/sdk/helper': { kind: 'none', reason: 'The project domain edits files and registers no live agent or model surface.' },
+  'packages/sdk/scripts': { kind: 'indirect', reason: 'The launcher delegates model context to the loaded project plugin tree.' },
   'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers no model surface.' },
   'packages/skill/skill': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-skill.' },
   'packages/skill/skill-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-skill.' },
diff --git a/tsconfig.base.json b/tsconfig.base.json
index e8fe74d390..cf45d66cca 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -60,6 +60,7 @@
         "./packages/hooks/*/src",
         "./packages/session-persistence/*/src",
         "./packages/session-query/*/src",
+        "./packages/sdk/*/src",
         "./packages/ui/*/src",
         "./packages/examples/*/src",
         "./packages/util/*/src",
diff --git a/tsconfig.build.json b/tsconfig.build.json
index ed11defc2b..3a57169005 100644
--- a/tsconfig.build.json
+++ b/tsconfig.build.json
@@ -85,6 +85,9 @@
     { "path": "./packages/hooks/hook-protocol" },
     { "path": "./packages/hooks/hooks-claude" },
     { "path": "./packages/hooks/hooks-codex" },
-    { "path": "./packages/mcp/mcp-client" }
+    { "path": "./packages/mcp/mcp-client" },
+    { "path": "./packages/sdk/helper" },
+    { "path": "./packages/sdk/scripts" },
+    { "path": "./packages/sdk/create-sdk" }
   ]
 }
diff --git a/tsconfig.json b/tsconfig.json
index 4086480a8e..6585a987d6 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -96,6 +96,9 @@
     { "path": "./packages/hooks/hook-protocol" },
     { "path": "./packages/hooks/hooks-claude" },
     { "path": "./packages/hooks/hooks-codex" },
-    { "path": "./packages/mcp/mcp-client" }
+    { "path": "./packages/mcp/mcp-client" },
+    { "path": "./packages/sdk/helper" },
+    { "path": "./packages/sdk/scripts" },
+    { "path": "./packages/sdk/create-sdk" }
   ]
 }
diff --git a/vitest.snapshot.config.ts b/vitest.snapshot.config.ts
index 903cd3e129..dbc51eae41 100644
--- a/vitest.snapshot.config.ts
+++ b/vitest.snapshot.config.ts
@@ -20,7 +20,7 @@ export default defineConfig({
   // through the root tsconfig paths map; the native option cannot do this.
   plugins: [tsconfigPaths({ projects: ['./tsconfig.json'] })],
   test: {
-    include: ['examples/*/tests/**/*.snapshot.ts'],
+    include: ['examples/*/tests/**/*.snapshot.ts', 'packages/sdk/*/tests/**/*.snapshot.ts'],
     // Each test boots a subprocess; give it room, and run files one at a time
     // (a record run hits the live API, and replay subprocess boot is heavy).
     testTimeout: 120_000,

From e150bc446dbccc1e59749879f9edf78ecce2e07d Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 15 Jul 2026 21:06:01 +0800
Subject: [PATCH 44/48] fix(sdk): address project tooling review findings

---
 packages/sdk/create-sdk/src/command.ts        |  3 +-
 .../src/templates/assets/next-steps.txt.tpl   |  4 +
 .../src/templates/create-templates.ts         |  4 +-
 .../sdk/create-sdk/tests/create.snapshot.ts   |  3 +-
 packages/sdk/create-sdk/tests/create.spec.ts  |  1 +
 packages/sdk/helper/src/documents/env-file.ts |  2 +-
 .../helper/src/documents/package-json-file.ts | 10 +++
 .../sdk/helper/src/documents/project-file.ts  |  6 +-
 .../sdk/helper/src/features/builtin/app.ts    | 34 ++++++++-
 .../helper/src/features/builtin/helpers.ts    | 12 +++
 packages/sdk/helper/src/features/feature.ts   |  5 ++
 packages/sdk/helper/src/features/resources.ts | 10 +++
 .../src/project/project-edit-session.ts       | 35 ++++++++-
 .../sdk/helper/src/project/sdk-project.ts     | 26 ++-----
 .../src/templates/assets/package.json.tpl     |  2 -
 .../helper/src/templates/project-template.ts  | 53 ++++++++++---
 packages/sdk/helper/tests/documents.spec.ts   |  4 +-
 packages/sdk/helper/tests/project.spec.ts     | 74 ++++++++++++++++++-
 18 files changed, 241 insertions(+), 47 deletions(-)

diff --git a/packages/sdk/create-sdk/src/command.ts b/packages/sdk/create-sdk/src/command.ts
index 613eb62a4e..0c7076c90b 100644
--- a/packages/sdk/create-sdk/src/command.ts
+++ b/packages/sdk/create-sdk/src/command.ts
@@ -81,7 +81,8 @@ export async function createProject(
   }
   context.stdout.write(CREATE_TEMPLATES.nextSteps.render({
     directory: resolved.directory,
-    packageManager: resolved.request.packageManager.name,
+    setupRequired: !resolved.install,
+    ...packageManagerTemplateModel(resolved.request.packageManager),
   }))
   return result
 }
diff --git a/packages/sdk/create-sdk/src/templates/assets/next-steps.txt.tpl b/packages/sdk/create-sdk/src/templates/assets/next-steps.txt.tpl
index 247d1259aa..c3f237deb6 100644
--- a/packages/sdk/create-sdk/src/templates/assets/next-steps.txt.tpl
+++ b/packages/sdk/create-sdk/src/templates/assets/next-steps.txt.tpl
@@ -1 +1,5 @@
+{{#if setupRequired}}
+Next: cd {{directory}} && {{packageManager}} {{installArgs}} && {{packageManager}} {{buildArgs}} && {{packageManager}} start
+{{else}}
 Next: cd {{directory}} && {{packageManager}} start
+{{/if}}
diff --git a/packages/sdk/create-sdk/src/templates/create-templates.ts b/packages/sdk/create-sdk/src/templates/create-templates.ts
index 99a587ce89..efeaf759c6 100644
--- a/packages/sdk/create-sdk/src/templates/create-templates.ts
+++ b/packages/sdk/create-sdk/src/templates/create-templates.ts
@@ -15,9 +15,9 @@ interface CreatedTemplateModel {
   directory: string
 }
 
-interface NextStepsTemplateModel {
+interface NextStepsTemplateModel extends PackageManagerTemplateModel {
   directory: string
-  packageManager: PackageManagerName
+  setupRequired: boolean
 }
 
 interface SetupFailureTemplateModel extends PackageManagerTemplateModel {
diff --git a/packages/sdk/create-sdk/tests/create.snapshot.ts b/packages/sdk/create-sdk/tests/create.snapshot.ts
index 1f7a13dd4e..a5ea46db53 100644
--- a/packages/sdk/create-sdk/tests/create.snapshot.ts
+++ b/packages/sdk/create-sdk/tests/create.snapshot.ts
@@ -126,7 +126,8 @@ describe('create-sdk terminal contract', () => {
         }),
         next: CREATE_TEMPLATES.nextSteps.render({
           directory: resolved.directory,
-          packageManager: resolved.request.packageManager.name,
+          setupRequired: false,
+          ...packageManagerTemplateModel(resolved.request.packageManager),
         }),
         failure: CREATE_TEMPLATES.setupFailure.render({
           directory: resolved.directory,
diff --git a/packages/sdk/create-sdk/tests/create.spec.ts b/packages/sdk/create-sdk/tests/create.spec.ts
index c673395649..8233806ac5 100644
--- a/packages/sdk/create-sdk/tests/create.spec.ts
+++ b/packages/sdk/create-sdk/tests/create.spec.ts
@@ -449,6 +449,7 @@ describe('create command composition', () => {
       'next', [{ value: featureId('persistence'), choices: ['jsonl'] }], 'none',
     ]))
     await expect(createProject(argv('next', false), noInstall)).resolves.toBeDefined()
+    expect(noInstall.readStdout()).toContain('npm install && npm run build && npm start')
   })
 
   it('uses the package manager setup path when no setup override is supplied', async () => {
diff --git a/packages/sdk/helper/src/documents/env-file.ts b/packages/sdk/helper/src/documents/env-file.ts
index 5e076d0e34..d0e6ca8473 100644
--- a/packages/sdk/helper/src/documents/env-file.ts
+++ b/packages/sdk/helper/src/documents/env-file.ts
@@ -19,7 +19,7 @@ export class EnvFile extends ProjectFile {
   private readonly lines: string[]
 
   private constructor(relativePath: '.env' | '.env.example', lines: string[], originalText?: string) {
-    super(relativePath, originalText)
+    super(relativePath, originalText, relativePath === '.env' ? 0o600 : undefined)
     this.lines = [...lines]
   }
 
diff --git a/packages/sdk/helper/src/documents/package-json-file.ts b/packages/sdk/helper/src/documents/package-json-file.ts
index d979906b96..f565f383d2 100644
--- a/packages/sdk/helper/src/documents/package-json-file.ts
+++ b/packages/sdk/helper/src/documents/package-json-file.ts
@@ -77,6 +77,16 @@ export class PackageJsonFile extends ProjectFile {
     this.manifest.scripts[name] = command
   }
 
+  /** Read one package script. */
+  script(name: string): string | undefined {
+    return this.manifest.scripts?.[name]
+  }
+
+  /** Remove one package script. */
+  removeScript(name: string): void {
+    delete this.manifest.scripts?.[name]
+  }
+
   /** Set one NPM dependency in its runtime or development section. */
   setNpmDependency(section: NpmDependencySection, name: string, spec: string): void {
     this.manifest[section] ??= {}
diff --git a/packages/sdk/helper/src/documents/project-file.ts b/packages/sdk/helper/src/documents/project-file.ts
index c5ec38cc07..9be20c3395 100644
--- a/packages/sdk/helper/src/documents/project-file.ts
+++ b/packages/sdk/helper/src/documents/project-file.ts
@@ -17,12 +17,16 @@ export abstract class ProjectFile {
   /** Text observed when the document entered the snapshot; absent for a new file. */
   readonly originalText: string | undefined
 
-  protected constructor(relativePath: string, originalText?: string) {
+  /** Permission bits used only when the file is first created. */
+  readonly createMode: number | undefined
+
+  protected constructor(relativePath: string, originalText?: string, createMode?: number) {
     if (relativePath.startsWith('/') || relativePath.split('/').includes('..')) {
       throw new Error(`project document path must stay inside the project: ${relativePath}`)
     }
     this.relativePath = relativePath
     this.originalText = originalText
+    this.createMode = createMode
   }
 
   /** Clone the document for an isolated edit session. */
diff --git a/packages/sdk/helper/src/features/builtin/app.ts b/packages/sdk/helper/src/features/builtin/app.ts
index 8e20e82e44..a89f2c84ae 100644
--- a/packages/sdk/helper/src/features/builtin/app.ts
+++ b/packages/sdk/helper/src/features/builtin/app.ts
@@ -6,15 +6,41 @@
 
 import { featureId } from '../../ids.ts'
 import type { ProjectProfile } from '../../project/types.ts'
+import {
+  createAppPackageScripts,
+  createAppProjectArtifacts,
+  createProjectTemplateContext,
+} from '../../templates/project-template.ts'
 import {
   FeatureOption,
   ExclusiveOptionFeature,
 } from '../feature.ts'
-import { ProjectContribution } from '../resources.ts'
-import { npmCordisConfigEntry, optionalString, requiredString } from './helpers.ts'
+import { ProjectContribution, type ProjectResource } from '../resources.ts'
+import {
+  npmCordisConfigEntry,
+  optionalString,
+  ownedTextFile,
+  packageScript,
+  requiredString,
+} from './helpers.ts'
 
 const ID = featureId('app')
 
+function appProjectResources(
+  profile: ProjectProfile,
+  runInterface: 'acp' | 'stdio' | 'embed',
+): readonly ProjectResource[] {
+  const context = createProjectTemplateContext(profile, runInterface)
+  const scripts = createAppPackageScripts(context)
+  return [
+    ...createAppProjectArtifacts(context).map(document => (
+      ownedTextFile(ID, document.relativePath, document.serialize())
+    )),
+    packageScript(ID, 'dev', scripts.dev),
+    packageScript(ID, 'start', scripts.start),
+  ]
+}
+
 class AppOption extends FeatureOption {
   override readonly id: 'acp' | 'stdio' | 'embed'
   override readonly label: string
@@ -45,6 +71,7 @@ class AppOption extends FeatureOption {
     switch (this.id) {
       case 'acp':
         return new ProjectContribution([
+          ...appProjectResources(profile, this.id),
           ...npmCordisConfigEntry(ID, {
             id: 'user-interaction',
             name: '@deepseek-ai/dsh-user-interaction',
@@ -57,6 +84,7 @@ class AppOption extends FeatureOption {
         ])
       case 'stdio':
         return new ProjectContribution([
+          ...appProjectResources(profile, this.id),
           ...npmCordisConfigEntry(ID, {
             id: 'user-interaction',
             name: '@deepseek-ai/dsh-user-interaction',
@@ -74,7 +102,7 @@ class AppOption extends FeatureOption {
           ]),
         ])
       case 'embed':
-        return new ProjectContribution([])
+        return new ProjectContribution(appProjectResources(profile, this.id))
     }
   }
 }
diff --git a/packages/sdk/helper/src/features/builtin/helpers.ts b/packages/sdk/helper/src/features/builtin/helpers.ts
index 384f6ffea8..60f7530c61 100644
--- a/packages/sdk/helper/src/features/builtin/helpers.ts
+++ b/packages/sdk/helper/src/features/builtin/helpers.ts
@@ -12,6 +12,7 @@ import type {
   EnvironmentResource,
   OwnedFileResource,
   NpmDependencyResource,
+  PackageScriptResource,
 } from '../resources.ts'
 
 /** Create a runtime NPM dependency resource. */
@@ -24,6 +25,17 @@ function npmDependency(_owner: string, name: string): NpmDependencyResource {
   }
 }
 
+/** Create a feature-owned package script that is replaceable only while unchanged. */
+export function packageScript(_owner: string, name: string, command: string): PackageScriptResource {
+  return {
+    kind: 'package-script',
+    key: resourceKey(`package-script:${name}`),
+    name,
+    command,
+    removeOnlyWhenUnchanged: true,
+  }
+}
+
 /** Create a Cordis config entry resource with explicitly owned config keys. */
 export function cordisConfigEntry(
   _owner: string,
diff --git a/packages/sdk/helper/src/features/feature.ts b/packages/sdk/helper/src/features/feature.ts
index fcbe64e052..1335d8e29b 100644
--- a/packages/sdk/helper/src/features/feature.ts
+++ b/packages/sdk/helper/src/features/feature.ts
@@ -285,6 +285,11 @@ export abstract class Feature {
             diagnostics.push(`missing package.json ${resource.section} entry ${resource.name}`)
           }
           break
+        case 'package-script':
+          if (!manifest.scripts?.[resource.name]) {
+            diagnostics.push(`missing package.json script ${resource.name}`)
+          }
+          break
         case 'owned-file':
           if (!project.hasDocument(resource.document.relativePath)) diagnostics.push(`missing owned file ${resource.document.relativePath}`)
           break
diff --git a/packages/sdk/helper/src/features/resources.ts b/packages/sdk/helper/src/features/resources.ts
index dc6ecd2452..6528451e10 100644
--- a/packages/sdk/helper/src/features/resources.ts
+++ b/packages/sdk/helper/src/features/resources.ts
@@ -16,6 +16,15 @@ export interface NpmDependencyResource {
   section: 'dependencies' | 'devDependencies'
 }
 
+/** Feature-owned package script. */
+export interface PackageScriptResource {
+  kind: 'package-script'
+  key: ResourceKey
+  name: string
+  command: string
+  removeOnlyWhenUnchanged: boolean
+}
+
 /** Owned Cordis config entry plus the config keys safe to update in place. */
 export interface CordisConfigEntryResource {
   kind: 'cordis-config-entry'
@@ -46,6 +55,7 @@ export interface OwnedFileResource {
 /** Any resource a feature can add to a project. */
 export type ProjectResource =
   | NpmDependencyResource
+  | PackageScriptResource
   | CordisConfigEntryResource
   | EnvironmentResource
   | OwnedFileResource
diff --git a/packages/sdk/helper/src/project/project-edit-session.ts b/packages/sdk/helper/src/project/project-edit-session.ts
index 2fb3cc4c77..4e47a5a53f 100644
--- a/packages/sdk/helper/src/project/project-edit-session.ts
+++ b/packages/sdk/helper/src/project/project-edit-session.ts
@@ -56,6 +56,7 @@ function canUpdateResource(previous: ProjectResource, next: ProjectResource): bo
   if (previous.kind !== next.kind) return false
   switch (previous.kind) {
     case 'npm-dependency': return previous.name === (next as typeof previous).name
+    case 'package-script': return previous.name === (next as typeof previous).name
     case 'cordis-config-entry': {
       const candidate = next as typeof previous
       return previous.entry.name === candidate.entry.name
@@ -282,7 +283,10 @@ export class ProjectEditSession implements FeatureProjectView {
         continue
       }
       await mkdir(dirname(absolute), { recursive: true })
-      await writeFile(absolute, document.serialize(), 'utf8')
+      await writeFile(absolute, document.serialize(), {
+        encoding: 'utf8',
+        ...document.createMode === undefined ? {} : { mode: document.createMode },
+      })
     }
     this.committed = true
     return { project: await this.source.reopen(), changes }
@@ -369,6 +373,21 @@ export class ProjectEditSession implements FeatureProjectView {
         this.manifest().setNpmDependency(dependency.section, resource.name, dependency.spec)
         return
       }
+      case 'package-script': {
+        const manifest = this.manifest()
+        const current = manifest.script(resource.name)
+        if (!previous || previous.kind !== 'package-script') {
+          if (current !== undefined) throw new Error(`feature-owned package script already exists: ${resource.name}`)
+          manifest.setScript(resource.name, resource.command)
+          return
+        }
+        if (current === resource.command) return
+        if (current !== previous.command) {
+          throw new Error(`feature-owned package script was modified: ${resource.name}`)
+        }
+        manifest.setScript(resource.name, resource.command)
+        return
+      }
       case 'cordis-config-entry': {
         const current = this.cordis().entry(resource.entry.id)
         if (!current) this.cordis().addEntry(resource.entry)
@@ -412,7 +431,9 @@ export class ProjectEditSession implements FeatureProjectView {
         if (existing.serialize() !== previous.document.serialize()) {
           throw new Error(`feature-owned file was modified: ${resource.document.relativePath}`)
         }
-        throw new Error(`updating feature-owned files is not supported: ${resource.document.relativePath}`)
+        this.documents.set(resource.document.relativePath, resource.document.clone())
+        this.removed.delete(resource.document.relativePath)
+        return
       }
     }
   }
@@ -422,6 +443,16 @@ export class ProjectEditSession implements FeatureProjectView {
       case 'npm-dependency':
         this.manifest().removeNpmDependency(resource.section, resource.name)
         return
+      case 'package-script': {
+        const manifest = this.manifest()
+        const current = manifest.script(resource.name)
+        if (current === undefined) throw new Error(`owned package script is missing: ${resource.name}`)
+        if (resource.removeOnlyWhenUnchanged && current !== resource.command) {
+          throw new Error(`feature-owned package script was modified: ${resource.name}`)
+        }
+        manifest.removeScript(resource.name)
+        return
+      }
       case 'cordis-config-entry': {
         const entry = this.cordis().entry(resource.entry.id)
         if (!entry || entry.name !== resource.entry.name) {
diff --git a/packages/sdk/helper/src/project/sdk-project.ts b/packages/sdk/helper/src/project/sdk-project.ts
index 21d5510117..cd55ffe2e5 100644
--- a/packages/sdk/helper/src/project/sdk-project.ts
+++ b/packages/sdk/helper/src/project/sdk-project.ts
@@ -18,9 +18,9 @@ import {
   type PackageManagerName,
 } from '../package-managers/package-manager.ts'
 import {
+  createBaselineProjectArtifacts,
   createPackageJsonDoc,
-  createProjectArtifacts,
-  type ProjectTemplateContext,
+  createProjectTemplateContext,
 } from '../templates/project-template.ts'
 import type { ProjectCreationRequest, ProjectProfile, RunInterface } from './types.ts'
 import type { FeatureRegistry } from '../features/registry.ts'
@@ -36,6 +36,8 @@ const OPTIONAL_DOCUMENTS = [
   'pnpm-workspace.yaml',
   'hooks.json',
   'codex-hooks.json',
+  'README.md',
+  'index.ts',
 ] as const
 
 function runInterface(entries: readonly CordisConfigEntry[]): RunInterface {
@@ -113,22 +115,6 @@ function parseOptionalDocument(path: string, text: string): ProjectFile {
   }
 }
 
-function templateContext(profile: ProjectProfile): ProjectTemplateContext {
-  return {
-    name: profile.name,
-    description: profile.description,
-    releaseVersion: profile.releaseVersion,
-    model: profile.runtime.model,
-    modelLiteral: JSON.stringify(profile.runtime.model),
-    isAcp: profile.runInterface === 'acp',
-    isStdio: profile.runInterface === 'stdio',
-    isEmbed: profile.runInterface === 'embed',
-    packageManager: profile.packageManager.name,
-    installArgs: profile.packageManager.installCommand().join(' '),
-    buildArgs: profile.packageManager.buildCommand().join(' '),
-  }
-}
-
 /** A project snapshot whose documents can only be changed through {@link ProjectEditSession}. */
 export class SdkProject {
   /** Absolute project directory. */
@@ -172,7 +158,7 @@ export class SdkProject {
       releaseVersion: request.releaseVersion,
       ...request.linkWorkspaceRoot ? { linkWorkspaceRoot: resolve(request.linkWorkspaceRoot) } : {},
     }
-    const templates = templateContext(profile)
+    const templates = createProjectTemplateContext(profile)
     const manifest = createPackageJsonDoc(templates)
     const documents = new Map<string, ProjectFile>()
     documents.set(manifest.relativePath, manifest)
@@ -182,7 +168,7 @@ export class SdkProject {
     for (const document of request.packageManager.configureWorkspace(manifest)) {
       documents.set(document.relativePath, document)
     }
-    for (const document of createProjectArtifacts(templates)) {
+    for (const document of createBaselineProjectArtifacts(templates)) {
       documents.set(document.relativePath, document)
     }
     return new SdkProject(root, 'create', profile, documents)
diff --git a/packages/sdk/helper/src/templates/assets/package.json.tpl b/packages/sdk/helper/src/templates/assets/package.json.tpl
index 759639053b..9884f0913f 100644
--- a/packages/sdk/helper/src/templates/assets/package.json.tpl
+++ b/packages/sdk/helper/src/templates/assets/package.json.tpl
@@ -5,10 +5,8 @@
   "description": {{description}},
   "type": "module",
   "scripts": {
-    "dev": {{devScript}},
     "build": "dsh build",
     "typecheck": "tsc -b",
-    "start": {{startScript}},
     "config": "dsh config"
   },
   "dependencies": {{dependencies}},
diff --git a/packages/sdk/helper/src/templates/project-template.ts b/packages/sdk/helper/src/templates/project-template.ts
index a9686649ad..90ab46d51e 100644
--- a/packages/sdk/helper/src/templates/project-template.ts
+++ b/packages/sdk/helper/src/templates/project-template.ts
@@ -8,6 +8,7 @@ import { PackageJsonFile } from '../documents/package-json-file.ts'
 import { TextProjectFile } from '../documents/project-file.ts'
 import type { PackageManagerName } from '../package-managers/package-manager.ts'
 import { baselineNpmDependencies } from '../project/npm-dependency-policy.ts'
+import type { ProjectProfile, RunInterface } from '../project/types.ts'
 import { loadHelperTemplate } from './template-assets.ts'
 import type { TextTemplate } from './text-template.ts'
 
@@ -38,8 +39,6 @@ const README_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('README.md.tp
 const PACKAGE_JSON_TEMPLATE = loadHelperTemplate<{
   name: string
   description: string
-  devScript: string
-  startScript: string
   dependencies: string
   devDependencies: string
 }>('package.json.tpl')
@@ -49,25 +48,42 @@ const TSCONFIG_BASE_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('tscon
 const GITIGNORE_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('gitignore.tpl')
 const YARNRC_TEMPLATE = loadHelperTemplate<ProjectTemplateContext>('yarnrc.yml.tpl')
 
+/** Build the template model for one project and selected run interface. */
+export function createProjectTemplateContext(
+  profile: ProjectProfile,
+  runInterface: RunInterface = profile.runInterface,
+): ProjectTemplateContext {
+  return {
+    name: profile.name,
+    description: profile.description,
+    releaseVersion: profile.releaseVersion,
+    model: profile.runtime.model,
+    modelLiteral: JSON.stringify(profile.runtime.model),
+    isAcp: runInterface === 'acp',
+    isStdio: runInterface === 'stdio',
+    isEmbed: runInterface === 'embed',
+    packageManager: profile.packageManager.name,
+    installArgs: profile.packageManager.installCommand().join(' '),
+    buildArgs: profile.packageManager.buildCommand().join(' '),
+  }
+}
+
 /** Render the complete root package defaults before structured contributions merge. */
 export function createPackageJsonDoc(context: ProjectTemplateContext): PackageJsonFile {
-  const stdioModelArg = context.isStdio ? ` -- --model=${JSON.stringify(context.model)}` : ''
   const npmDependencies = baselineNpmDependencies(context.releaseVersion)
   return PackageJsonFile.create(PACKAGE_JSON_TEMPLATE.render({
     name: JSON.stringify(context.name),
     description: JSON.stringify(context.description),
-    devScript: JSON.stringify(`dsh dev index.ts${stdioModelArg}`),
-    startScript: JSON.stringify(`dsh start index.js${stdioModelArg}`),
     dependencies: JSON.stringify(npmDependencies.dependencies),
     devDependencies: JSON.stringify(npmDependencies.devDependencies),
   }))
 }
 
-/** Build every one-shot project artifact from one template context. */
-export function createProjectArtifacts(context: ProjectTemplateContext): TemplateArtifact<ProjectTemplateContext>[] {
+/** Build interface-independent one-shot project artifacts. */
+export function createBaselineProjectArtifacts(
+  context: ProjectTemplateContext,
+): TemplateArtifact<ProjectTemplateContext>[] {
   return [
-    new TemplateArtifact('README.md', README_TEMPLATE, context),
-    new TemplateArtifact('index.ts', INDEX_TEMPLATE, context),
     new TemplateArtifact('tsdown.config.ts', TSDOWN_TEMPLATE, context),
     new TemplateArtifact('tsconfig.base.json', TSCONFIG_BASE_TEMPLATE, context),
     new TemplateArtifact('.gitignore', GITIGNORE_TEMPLATE, context),
@@ -76,3 +92,22 @@ export function createProjectArtifacts(context: ProjectTemplateContext): Templat
       : [],
   ]
 }
+
+/** Build files owned by the selected app feature option. */
+export function createAppProjectArtifacts(
+  context: ProjectTemplateContext,
+): TemplateArtifact<ProjectTemplateContext>[] {
+  return [
+    new TemplateArtifact('README.md', README_TEMPLATE, context),
+    new TemplateArtifact('index.ts', INDEX_TEMPLATE, context),
+  ]
+}
+
+/** Build package scripts owned by the selected app feature option. */
+export function createAppPackageScripts(context: ProjectTemplateContext): Readonly<Record<'dev' | 'start', string>> {
+  const modelArg = context.isStdio ? ` -- --model=${JSON.stringify(context.model)}` : ''
+  return {
+    dev: `dsh dev index.ts${modelArg}`,
+    start: `dsh start index.js${modelArg}`,
+  }
+}
diff --git a/packages/sdk/helper/tests/documents.spec.ts b/packages/sdk/helper/tests/documents.spec.ts
index 5c7b483fa3..f71f016ab5 100644
--- a/packages/sdk/helper/tests/documents.spec.ts
+++ b/packages/sdk/helper/tests/documents.spec.ts
@@ -22,7 +22,7 @@ import {
   scrubEnvironment,
   type CommandRunner,
 } from '../src/package-managers/package-manager.ts'
-import { createProjectArtifacts } from '../src/templates/project-template.ts'
+import { createBaselineProjectArtifacts } from '../src/templates/project-template.ts'
 import { loadHelperTemplate } from '../src/templates/template-assets.ts'
 import { TextTemplate } from '../src/templates/text-template.ts'
 import { resolveNpmDependency } from '../src/project/npm-dependency-policy.ts'
@@ -219,7 +219,7 @@ describe('structured project documents', () => {
     expect(() => featureId('Bad Id')).toThrow('invalid feature id')
     expect(() => resourceKey('')).toThrow('must not be empty')
     expect(() => loadHelperTemplate('../bad.tpl')).toThrow('must not contain a directory')
-    expect(createProjectArtifacts({
+    expect(createBaselineProjectArtifacts({
       name: 'demo', description: 'demo', releaseVersion: '0.0.1', model: 'model', modelLiteral: '"model"', packageManager: 'yarn',
       isAcp: false, isStdio: false, isEmbed: true,
       installArgs: 'install', buildArgs: 'build',
diff --git a/packages/sdk/helper/tests/project.spec.ts b/packages/sdk/helper/tests/project.spec.ts
index a565c6998b..37c0c2f903 100644
--- a/packages/sdk/helper/tests/project.spec.ts
+++ b/packages/sdk/helper/tests/project.spec.ts
@@ -1,4 +1,4 @@
-import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { chmod, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -25,6 +25,7 @@ import { FeatureRegistry } from '../src/features/registry.ts'
 import { ProjectContribution } from '../src/features/resources.ts'
 import type { CordisConfigEntryResource, ProjectResource } from '../src/features/resources.ts'
 import type { CordisConfigEntry } from '../src/documents/cordis-yaml-file.ts'
+import { PackageJsonFile } from '../src/documents/package-json-file.ts'
 import { TextProjectFile } from '../src/documents/project-file.ts'
 import { featureId, resourceKey } from '../src/ids.ts'
 import { NpmPackageManager } from '../src/package-managers/package-manager.ts'
@@ -246,6 +247,44 @@ describe('SdkProject and ProjectEditSession', () => {
     expect(committed.changes.npmDependenciesChanged).toBe(true)
   })
 
+  it('switches app-owned files and scripts while protecting user edits', async () => {
+    const project = await createCommitted()
+    const registry = createBuiltinRegistry(project.profile)
+    const edit = project.edit(registry)
+    edit.configureFeature(registry.get(featureId('app')), selection('app', ['acp']))
+    const acp = (await edit.commit()).project
+    expect(acp.profile.runInterface).toBe('acp')
+    expect(acp.packageManifest().scripts).toMatchObject({
+      dev: 'dsh dev index.ts',
+      start: 'dsh start index.js',
+    })
+    expect(await readFile(join(acp.root, 'README.md'), 'utf8')).toContain('Run as an ACP server')
+    expect(await readFile(join(acp.root, 'index.ts'), 'utf8')).not.toContain('agents.create')
+
+    const acpRegistry = createBuiltinRegistry(acp.profile)
+    const embedEdit = acp.edit(acpRegistry)
+    embedEdit.configureFeature(acpRegistry.get(featureId('app')), selection('app', ['embed']))
+    const embed = (await embedEdit.commit()).project
+    expect(embed.profile.runInterface).toBe('embed')
+    expect(await readFile(join(embed.root, 'README.md'), 'utf8')).toContain('Embed the harness')
+    expect(await readFile(join(embed.root, 'index.ts'), 'utf8')).toContain('agents.create')
+
+    await writeFile(join(embed.root, 'README.md'), '# Custom README\n')
+    const modified = await SdkProject.open(embed.root)
+    const modifiedRegistry = createBuiltinRegistry(modified.profile)
+    expect(() => { modified.edit(modifiedRegistry).configureFeature(
+      modifiedRegistry.get(featureId('app')),
+      selection('app', ['stdio']),
+    ) }).toThrow('feature-owned file was modified: README.md')
+
+    const manifest = PackageJsonFile.parse(await readFile(join(embed.root, 'package.json'), 'utf8'))
+    manifest.removeScript('dev')
+    await writeFile(join(embed.root, 'package.json'), manifest.serialize())
+    const incomplete = await SdkProject.open(embed.root)
+    expect(createBuiltinRegistry(incomplete.profile).get(featureId('app')).inspect(incomplete).diagnostics)
+      .toContain('missing package.json script dev')
+  })
+
   it('supports disabled feature reconfiguration and rejects invalid state operations', async () => {
     const project = await createCommitted([selection('todo', ['default'])])
     const registry = createBuiltinRegistry(project.profile)
@@ -379,9 +418,29 @@ describe('SdkProject and ProjectEditSession', () => {
     const nextFile: ProjectResource = {
       ...existingFile, key: resourceKey('file:owned.txt'), document: new TextProjectFile('owned.txt', 'replacement'),
     }
-    expect(() => { internals.applyResource(nextFile, previousFile) }).toThrow('updating feature-owned files')
+    internals.applyResource(nextFile, previousFile)
+    expect(internals.documents.get('owned.txt')?.serialize()).toBe('replacement\n')
     internals.documents.set('owned.txt', new TextProjectFile('owned.txt', 'user edit'))
     expect(() => { internals.applyResource(nextFile, previousFile) }).toThrow('was modified')
+    const existingScript: ProjectResource = {
+      kind: 'package-script', key: resourceKey('package-script:build'),
+      name: 'build', command: 'other build', removeOnlyWhenUnchanged: true,
+    }
+    expect(() => { internals.applyResource(existingScript, undefined) }).toThrow('script already exists')
+    const transientScript: ProjectResource = {
+      kind: 'package-script', key: resourceKey('package-script:transient'),
+      name: 'transient', command: 'first', removeOnlyWhenUnchanged: true,
+    }
+    internals.applyResource(transientScript, undefined)
+    const nextScript: ProjectResource = { ...transientScript, command: 'second' }
+    internals.applyResource(nextScript, transientScript)
+    internals.applyResource(nextScript, transientScript)
+    ;(internals.manifest() as PackageJsonFile).setScript('transient', 'user edit')
+    expect(() => { internals.applyResource(transientScript, nextScript) }).toThrow('script was modified')
+    expect(() => { internals.removeResource(nextScript) }).toThrow('script was modified')
+    ;(internals.manifest() as PackageJsonFile).setScript('transient', 'second')
+    internals.removeResource(nextScript)
+    expect(() => { internals.removeResource(nextScript) }).toThrow('script is missing')
     expect(() => { internals.removeResource({
       ...existingFile, key: resourceKey('file:missing.txt'), document: new TextProjectFile('missing.txt', 'missing'),
     }) }).toThrow('owned file is missing')
@@ -546,8 +605,12 @@ describe('SdkProject and ProjectEditSession', () => {
 
   it('preserves duplicate and existing .env values while appending differently named secrets', async () => {
     const project = await createCommitted()
+    if (process.platform !== 'win32') {
+      expect((await stat(join(project.root, '.env'))).mode & 0o777).toBe(0o600)
+    }
     const original = '# keep\nDEEPSEEK_API_KEY=first\nDEEPSEEK_API_KEY=second\n'
     await writeFile(join(project.root, '.env'), original)
+    if (process.platform !== 'win32') await chmod(join(project.root, '.env'), 0o640)
     const reopened = await SdkProject.open(project.root)
     const registry = createBuiltinRegistry(reopened.profile)
     expect(registry.get(featureId('provider')).inspect(reopened)).toMatchObject({
@@ -561,6 +624,9 @@ describe('SdkProject and ProjectEditSession', () => {
     edit.installFeature(registry.get(featureId('web')), selection('web', ['exa'], { apiKey: 'exa-key' }))
     const withExa = (await edit.commit()).project
     expect(await readFile(join(withExa.root, '.env'), 'utf8')).toBe(`${original}EXA_API_KEY=exa-key\n`)
+    if (process.platform !== 'win32') {
+      expect((await stat(join(withExa.root, '.env'))).mode & 0o777).toBe(0o640)
+    }
     const nextRegistry = createBuiltinRegistry(withExa.profile)
     const remove = withExa.edit(nextRegistry)
     remove.configureFeature(nextRegistry.get(featureId('web')), selection('web', ['deepseek']))
@@ -767,7 +833,9 @@ describe('extension points', () => {
     expect(acpEntry?.validateConfig?.({ model: '' })).toHaveLength(1)
     const embedOption = app.options.find(option => option.id === 'embed')
     expect(embedOption?.markerConfigEntries(profile)).toEqual([])
-    expect(embedOption?.contribution(profile, {}).resources).toEqual([])
+    expect(embedOption?.contribution(profile, {}).resources.map(resource => resource.kind)).toEqual([
+      'owned-file', 'owned-file', 'package-script', 'package-script',
+    ])
     expect(embedOption?.matchesConfigEntries([
       { id: 'agent-loop', name: '@deepseek-ai/dsh-agent-loop' },
       { id: 'stdio', name: '@deepseek-ai/dsh-stdio' },

From d8f6251e3a59566493c4e7f643144b5370b20151 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 15 Jul 2026 22:18:28 +0800
Subject: [PATCH 45/48] feat: rename dsh to dsh-sdk

---
 ...sdk-project-editing-architecture.i18n.yaml |  4 +-
 ...-07-15-sdk-project-editing-architecture.md |  8 +--
 ...-15-sdk-project-editing-architecture.zh.md |  8 +--
 ...026-07-14-sdk-developer-projects.i18n.yaml |  4 +-
 .../2026-07-14-sdk-developer-projects.md      | 38 ++++++-------
 .../2026-07-14-sdk-developer-projects.zh.md   | 38 ++++++-------
 packages/sdk/README.md                        |  4 +-
 .../create-sdk/tests/built-artifacts.e2e.ts   |  4 +-
 packages/sdk/create-sdk/tests/create.spec.ts  |  8 +--
 .../create-sdk/tests/link-workspace.e2e.ts    |  4 +-
 packages/sdk/helper/README.md                 |  2 +-
 .../helper/src/templates/assets/README.md.tpl |  2 +-
 .../src/templates/assets/package.json.tpl     |  4 +-
 .../helper/src/templates/project-template.ts  |  4 +-
 packages/sdk/helper/tests/project.spec.ts     | 12 ++--
 packages/sdk/scripts/README.md                | 12 ++--
 packages/sdk/scripts/package.json             |  2 +-
 packages/sdk/scripts/src/args.ts              | 22 ++++----
 packages/sdk/scripts/src/bin.ts               |  6 +-
 packages/sdk/scripts/src/build.ts             |  2 +-
 packages/sdk/scripts/src/command.ts           | 22 ++++----
 packages/sdk/scripts/src/config.ts            |  6 +-
 .../sdk/scripts/src/config/config-workflow.ts |  4 +-
 packages/sdk/scripts/src/runtime.ts           | 12 ++--
 .../src/templates/assets/usage.txt.tpl        |  2 +-
 ...{dsh-templates.ts => dsh-sdk-templates.ts} |  8 +--
 .../__snapshots__/config.snapshot.ts.snap     |  2 +-
 packages/sdk/scripts/tests/config.snapshot.ts |  2 +-
 packages/sdk/scripts/tests/scripts.spec.ts    | 56 +++++++++----------
 29 files changed, 151 insertions(+), 151 deletions(-)
 rename packages/sdk/scripts/src/templates/{dsh-templates.ts => dsh-sdk-templates.ts} (70%)

diff --git a/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
index 036616cddb..6e301ee06a 100644
--- a/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.i18n.yaml
+++ b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.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
-2026-07-15-sdk-project-editing-architecture.md: 0a3751d9641e6d4c56d14b8d81ed578905c48c73
-2026-07-15-sdk-project-editing-architecture.zh.md: 6f6ec656bf0734cf81d6c69d9c0e163fb78a33b5
+2026-07-15-sdk-project-editing-architecture.md: 985cc22c159c68801b78262aa96c7422bdfa1318
+2026-07-15-sdk-project-editing-architecture.zh.md: 6a194e8e5f193e62bfc283fd93a5fde0367fe196
diff --git a/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
index 0a3751d964..985cc22c15 100644
--- a/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
+++ b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md
@@ -32,12 +32,12 @@ Structured files are modified through document objects, while one-shot text arti
 | Package | Responsibility | Does not own |
 |---|---|---|
 | `@deepseek-ai/dsh-helper` | Edit sessions, feature configuration, project-template rendering, package-manager adaptation, and prompt interaction adaptation | Booting Cordis applications or deciding create/config terminal workflows |
-| `@deepseek-ai/dsh-scripts` | `dsh start/dev/build/config`, process lifecycle, project entry loading, the config workflow, and its terminal-copy templates | Interpreting feature definitions directly or modifying YAML/JSON ASTs |
+| `@deepseek-ai/dsh-scripts` | `dsh-sdk start/dev/build/config`, process lifecycle, project entry loading, the config workflow, and its terminal-copy templates | Interpreting feature definitions directly or modifying YAML/JSON ASTs |
 | `@deepseek-ai/create-sdk` | Arguments, question order, initial project creation, installation finish, and terminal-copy templates for `npm create @deepseek-ai/sdk` | Becoming a generated project's runtime npm dependency or providing a library API |
 
 `@deepseek-ai/create-sdk` is the only exception to the repository's `@deepseek-ai/dsh-*` naming rule. npm's scoped-initializer convention requires that package name for `npm create @deepseek-ai/sdk`. The exception is a repository architecture fact and does not add a third developer product entrypoint.
 
-The three packages export only the narrow entrypoints consumed by adjacent layers and provide no `src/*` deep imports. The scripts library entrypoint and build-config subpath serve generated code and project build configuration, while the developer product contract remains the `dsh` commands.
+The three packages export only the narrow entrypoints consumed by adjacent layers and provide no `src/*` deep imports. The scripts library entrypoint and build-config subpath serve generated code and project build configuration, while the developer product contract remains the `dsh-sdk` commands.
 
 ## Project aggregate and edit session
 
@@ -84,7 +84,7 @@ Templates use Handlebars strict mode and `noEscape` without custom processing. F
 
 ## Command and runtime boundary
 
-Scripts supports `dsh start/dev/build/config`. Start dynamically loads a module target and calls its named entrypoint. Dev adds TypeScript and local-workspace source resolution before following the same path. Build invokes the project's installed tsdown. Config opens one edit session and commits after Review & Apply. Generated projects run `tsc -b` directly for typechecking.
+Scripts supports `dsh-sdk start/dev/build/config`. Start dynamically loads a module target and calls its named entrypoint. Dev adds TypeScript and local-workspace source resolution before following the same path. Build invokes the project's installed tsdown. Config opens one edit session and commits after Review & Apply. Generated projects run `tsc -b` directly for typechecking.
 
 HMR is an explicit Cordis config entry loaded by dev and start. Its required `node-addon-require-builtin` package is supplied transitively by the scripts package and is absent from the generated project's `package.json`.
 
@@ -117,7 +117,7 @@ Link mode preserves the ordinary project file shape. `@deepseek-ai/*` points int
 - Adding an ordinary feature, feature option, or parameter extends only its typed spec or owning behavior object, without adding a central switch to create or config workflows
 - Helper owns the feature model, npm dependency and other resource configuration, and inconsistent-state detection
 - Structured files change through `*File` document objects; one-shot files and complete product copy come from package-owned Handlebars templates, and business decisions do not enter a template DSL
-- `dsh start/dev/build/config` is the runtime product surface, typecheck uses `tsc -b` directly, HMR is not injected by command mode, and only the scripts package transitively supplies `node-addon-require-builtin`
+- `dsh-sdk start/dev/build/config` is the runtime product surface, typecheck uses `tsc -b` directly, HMR is not injected by command mode, and only the scripts package transitively supplies `node-addon-require-builtin`
 - `--link-workspace` exists only as a hidden repository-development option and preserves one module identity under npm, pnpm, and Yarn
 
 ## Risks
diff --git a/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
index 6f6ec656bf..6a194e8e5f 100644
--- a/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
+++ b/docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.zh.md
@@ -32,12 +32,12 @@ SDK 使用一个共享的面向对象工程模型。`SdkProject` 是只读快照
 | Package | 责任 | 不负责 |
 |---|---|---|
 | `@deepseek-ai/dsh-helper` | 编辑会话、功能配置、工程模板渲染、包管理适配和 prompt 交互适配 | 启动 Cordis 应用或决定 create/config 的终端流程 |
-| `@deepseek-ai/dsh-scripts` | `dsh start/dev/build/config`、进程生命周期、项目入口加载、config 流程和所属终端文案模板 | 直接解释功能定义或修改 YAML/JSON AST |
+| `@deepseek-ai/dsh-scripts` | `dsh-sdk start/dev/build/config`、进程生命周期、项目入口加载、config 流程和所属终端文案模板 | 直接解释功能定义或修改 YAML/JSON AST |
 | `@deepseek-ai/create-sdk` | `npm create @deepseek-ai/sdk` 的参数、问题顺序、首次工程创建、安装收尾和所属终端文案模板 | 成为生成工程的运行时 NPM 依赖或提供库 API |
 
 `@deepseek-ai/create-sdk` 是仓库 `@deepseek-ai/dsh-*` 命名规则的唯一例外；npm scoped initializer 约定要求 `npm create @deepseek-ai/sdk` 对应这个 package 名。该例外是仓库架构事实，不增加第三个开发者产品入口。
 
-三个 package 只导出相邻层实际使用的最小入口，不提供 `src/*` 深路径。scripts 的库入口与构建配置子路径服务生成代码和项目构建配置，但开发者产品合同仍由 `dsh` 命令承担。
+三个 package 只导出相邻层实际使用的最小入口，不提供 `src/*` 深路径。scripts 的库入口与构建配置子路径服务生成代码和项目构建配置，但开发者产品合同仍由 `dsh-sdk` 命令承担。
 
 ## 工程聚合与编辑会话
 
@@ -84,7 +84,7 @@ helper 提供通用的数据类型化 `TextTemplate` 模板渲染器，调用 pa
 
 ## 命令与运行边界
 
-scripts 支持 `dsh start/dev/build/config`。start 动态加载模块 target 并调用其命名入口；dev 在同一路径前增加 TypeScript 与本地 workspace 源码解析；build 调用工程安装的 tsdown；config 打开一个编辑会话并在 Review & Apply 后提交。typecheck 由生成工程直接执行 `tsc -b`。
+scripts 支持 `dsh-sdk start/dev/build/config`。start 动态加载模块 target 并调用其命名入口；dev 在同一路径前增加 TypeScript 与本地 workspace 源码解析；build 调用工程安装的 tsdown；config 打开一个编辑会话并在 Review & Apply 后提交。typecheck 由生成工程直接执行 `tsc -b`。
 
 HMR 作为显式 Cordis 配置项由 dev 和 start 加载；它所需的 `node-addon-require-builtin` 由 scripts package 传递提供，不写入开发者工程的 `package.json`。
 
@@ -117,7 +117,7 @@ create-sdk 保留隐藏的 `--link-workspace` 选项供 Harness 仓库开发和
 - 新增普通功能、功能选项或参数只扩展类型化 spec 或所属行为对象，create/config 流程不增加中央 switch
 - 功能模型、NPM 依赖与其他资源配置、不一致检测由 helper 统一实现
 - 结构化文件通过 `*File` 文档对象修改；一次性文件和完整产品文案通过所属 package 的 Handlebars 模板生成，业务决策不进入模板 DSL
-- `dsh start/dev/build/config` 是运行产品面，typecheck 直接使用 `tsc -b`，HMR 不通过命令隐式注入，`node-addon-require-builtin` 只由 scripts package 传递提供
+- `dsh-sdk start/dev/build/config` 是运行产品面，typecheck 直接使用 `tsc -b`，HMR 不通过命令隐式注入，`node-addon-require-builtin` 只由 scripts package 传递提供
 - `--link-workspace` 只作为隐藏的仓库开发选项存在，并对 npm、pnpm 和 Yarn 保持单一模块身份
 
 ## 风险
diff --git a/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
index 7b5a289e1e..36bb26161f 100644
--- a/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.i18n.yaml
+++ b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.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
-2026-07-14-sdk-developer-projects.md: 4650b5df5d1dc85035d8029754ec60b7d7008d4c
-2026-07-14-sdk-developer-projects.zh.md: 613da4da930591fb13516b287f408ebc3b15b2c2
+2026-07-14-sdk-developer-projects.md: 0b5fe876f92153e1ccf5bd8fe383464f5087f4b1
+2026-07-14-sdk-developer-projects.zh.md: ec08f323acba1b9dc049182937fda34bfb50d4ee
diff --git a/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md
index 4650b5df5d..0b5fe876f9 100644
--- a/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md
+++ b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.md
@@ -16,7 +16,7 @@ Initial creation and later configuration address the same builtin feature set. W
 
 The SDK creates an ordinary, explicit TypeScript/Cordis project owned by its developer. `cordis.yml` is the only runtime plugin tree; development and production read the same file. The generated `package.json`, `cordis.yml`, TypeScript entrypoint, build configuration, and `plugins/*` remain directly editable instead of being hidden behind a preset.
 
-The only developer product entrypoints are `npm create @deepseek-ai/sdk` and the `dsh` commands. The initializer performs initial creation, `dsh config` manages SDK-recognized builtin features afterward, and `dsh dev`, `dsh build`, and `dsh start` own development, build, and startup; this phase provides no `dsh create`. Create and config consume one manually authored feature definition, so each feature has one source for its feature options, npm dependencies, Cordis config entries, related files, and inspection rules. The [SDK project editing architecture](../architecture/2026-07-15-sdk-project-editing-architecture.md) defines terms such as feature and feature option.
+The only developer product entrypoints are `npm create @deepseek-ai/sdk` and the `dsh-sdk` commands. The initializer performs initial creation, `dsh-sdk config` manages SDK-recognized builtin features afterward, and `dsh-sdk dev`, `dsh-sdk build`, and `dsh-sdk start` own development, build, and startup; this phase provides no `dsh-sdk create`. Create and config consume one manually authored feature definition, so each feature has one source for its feature options, npm dependencies, Cordis config entries, related files, and inspection rules. The [SDK project editing architecture](../architecture/2026-07-15-sdk-project-editing-architecture.md) defines terms such as feature and feature option.
 
 The SDK offers interaction for feature selection and finite feature options only; it does not turn arbitrary Cordis plugin config into a generic form. A feature collects the small number of dedicated inputs required by its feature options. All other Cordis plugin config remains in `cordis.yml`, with comments documenting common edits, for direct developer control.
 
@@ -27,10 +27,10 @@ Initial creation collects information in an order where earlier answers determin
 ```sh
 npm create @deepseek-ai/sdk my-agent
 cd my-agent
-npm exec dsh dev index.ts
-npm exec dsh config
-npm exec dsh build
-npm exec dsh start index.js
+npm exec dsh-sdk dev index.ts
+npm exec dsh-sdk config
+npm exec dsh-sdk build
+npm exec dsh-sdk start index.js
 ```
 
 Create rejects every target path that already exists. After committing the project files, the CLI asks whether to install npm dependencies and build. An install or build failure preserves the generated project and prints commands that can retry the failed work.
@@ -94,31 +94,31 @@ my-agent/
 
 `.env.example` always exists, and the SDK keeps its placeholders aligned with the current feature set. A gitignored `.env` is also created when a secret is captured or the developer confirms an empty credential to fill later. The SDK only appends differently named variables that are not already present in `.env` and never updates or removes existing contents. Feature-option changes may remove obsolete `.env.example` placeholders, while old credentials remain in `.env` for the developer to manage. pnpm and Yarn projects add their required workspace files, but do not fork the runtime plugin tree or TypeScript entrypoint.
 
-Generated `package.json` provides the following scripts. `dev`, `build`, `start`, and `config` invoke `dsh`, while `typecheck` invokes TypeScript directly:
+Generated `package.json` provides the following scripts. `dev`, `build`, `start`, and `config` invoke `dsh-sdk`, while `typecheck` invokes TypeScript directly:
 
 | Script | Behavior |
 |---|---|
-| `dev` | Run `dsh dev index.ts`, registering development-time resolution for TypeScript and local workspace plugins |
-| `build` | Run `dsh build`, invoking the project's installed tsdown for the root entrypoint and `plugins/*` packages |
+| `dev` | Run `dsh-sdk dev index.ts`, registering development-time resolution for TypeScript and local workspace plugins |
+| `build` | Run `dsh-sdk build`, invoking the project's installed tsdown for the root entrypoint and `plugins/*` packages |
 | `typecheck` | Run `tsc -b` directly |
-| `start` | Run `dsh start index.js`, starting the built entrypoint without an implicit build |
-| `config` | Run `dsh config` to edit the current project's feature tree |
+| `start` | Run `dsh-sdk start index.js`, starting the built entrypoint without an implicit build |
+| `config` | Run `dsh-sdk config` to edit the current project's feature tree |
 
-`dsh start` and `dsh dev` accept a module target and forward arguments after `--` unchanged to the project entrypoint. Generic argument parsing uses Node `parseArgs()` with zero schema: valued flags use `--key=value`, bare flags become `true`, and `--no-*` becomes `false`.
+`dsh-sdk start` and `dsh-sdk dev` accept a module target and forward arguments after `--` unchanged to the project entrypoint. Generic argument parsing uses Node `parseArgs()` with zero schema: valued flags use `--key=value`, bare flags become `true`, and `--no-*` becomes `false`.
 
 - Stdio projects pass the selected model through `--model=<name>` and create or resume an agent according to optional `--resume=<session-id>`;
 - ACP uses protocol `session/load`
 - Embed uses the model written into the generated code.
 
-Each feature-owned Cordis config entry keeps its developer-editable Cordis plugin config and explanatory comments in `cordis.yml`. When `dsh config` changes other features, it preserves unknown fields, formatting on untouched nodes, and comments. HMR is an ordinary leaf config entry: when the feature is selected, dev and start load the same watcher, and the command does not change the plugin tree implicitly.
+Each feature-owned Cordis config entry keeps its developer-editable Cordis plugin config and explanatory comments in `cordis.yml`. When `dsh-sdk config` changes other features, it preserves unknown fields, formatting on untouched nodes, and comments. HMR is an ordinary leaf config entry: when the feature is selected, dev and start load the same watcher, and the command does not change the plugin tree implicitly.
 
 ## Post-creation configuration
 
-`dsh config` requires only readable root `package.json` and `cordis.yml` files in the current directory. It inspects standard features and their current feature options, expresses the final desired state through one feature tree, and shows feature changes and affected files before Review & Apply.
+`dsh-sdk config` requires only readable root `package.json` and `cordis.yml` files in the current directory. It inspects standard features and their current feature options, expresses the final desired state through one feature tree, and shows feature changes and affected files before Review & Apply.
 
-`dsh config` can install missing features, enable or disable installed features, and switch finite feature options. Required features cannot be removed. An npm dependency change runs the project package manager's install once after the file commit; installation failure does not roll back committed project files.
+`dsh-sdk config` can install missing features, enable or disable installed features, and switch finite feature options. Required features cannot be removed. An npm dependency change runs the project package manager's install once after the file commit; installation failure does not roll back committed project files.
 
-The SDK modifies only Cordis config entries, config keys, npm dependencies, `.env.example` placeholders, and owned files explicitly owned by a feature. Updating the same feature option preserves unknown config keys in its Cordis config entries. Handwritten and third-party plugins support enable and disable by stable ID only. When a known feature has been edited into an incomplete, ambiguous, or otherwise unreadable shape, `dsh config` displays diagnostics and refuses automatic changes until the developer repairs it manually.
+The SDK modifies only Cordis config entries, config keys, npm dependencies, `.env.example` placeholders, and owned files explicitly owned by a feature. Updating the same feature option preserves unknown config keys in its Cordis config entries. Handwritten and third-party plugins support enable and disable by stable ID only. When a known feature has been edited into an incomplete, ambiguous, or otherwise unreadable shape, `dsh-sdk config` displays diagnostics and refuses automatic changes until the developer repairs it manually.
 
 One config session accumulates every change in an in-memory working copy. Before Apply, it validates feature relationships, resource conflicts, and document shapes, then compares each affected existing file with the text read when the session opened. Validation failure or an external edit causes zero writes. Once physical writes begin, the SDK does not provide cross-file transactional rollback.
 
@@ -128,7 +128,7 @@ The SDK curates its builtin support set instead of exposing npm packages automat
 
 ## Future work
 
-- `dsh add [package-spec]` unifies local-plugin creation with external Cordis plugin installation: without a package or repository source it creates a local plugin/tool, while a supplied source adds the npm dependency and `cordis.yml` config entry; the source model leaves room for GitHub repositories and other extensions
+- `dsh-sdk add [package-spec]` unifies local-plugin creation with external Cordis plugin installation: without a package or repository source it creates a local plugin/tool, while a supplied source adds the npm dependency and `cordis.yml` config entry; the source model leaves room for GitHub repositories and other extensions
 - Non-interactive create/config: both workflows require a TTY in this phase and provide no complete input contract for automation
 - More feature-specific inputs: this product surface exposes only finite feature options, secrets, and a few dedicated values in this phase rather than a generic parameter interface for Cordis plugin config
 
@@ -144,7 +144,7 @@ The SDK curates its builtin support set instead of exposing npm packages automat
 
 **A private local-plugin discovery protocol.** Ordinary package-manager workspaces, root npm dependencies, TypeScript references, and Cordis config entries already express the complete relationship. Another discovery protocol would create hidden state understood only by the SDK.
 
-**A `dsh create` command for existing projects.** Create already provides one editable local-plugin skeleton, and later plugins can use ordinary workspace and Cordis mechanisms manually. A parallel command would add a second scaffolding product surface without adding composition functionality.
+**A `dsh-sdk create` command for existing projects.** Create already provides one editable local-plugin skeleton, and later plugins can use ordinary workspace and Cordis mechanisms manually. A parallel command would add a second scaffolding product surface without adding composition functionality.
 
 **Automatically expose every new Cordis plugin as a builtin.** An npm package cannot say how several plugins compose into one product feature, nor can it derive exclusivity, feature requirements, secrets, interface applicability, or security constraints. The support set requires human curation; automation is suitable only for checking whether candidates have been classified.
 
@@ -153,8 +153,8 @@ The SDK curates its builtin support set instead of exposing npm packages automat
 - `npm create @deepseek-ai/sdk` collects project identity, provider, interface, features, an optional local plugin, package manager, and installation choice in the documented order, and cancellation leaves the target path absent
 - A default npm project has the documented tree and `dev`, `build`, `typecheck`, `start`, and `config` scripts, with dev and start sharing one `cordis.yml`
 - Create offers the documented features and feature options; local and sandbox bash are exclusive with local as the default, the sandbox Cordis config entry retains the editable commented config example, and HMR is selected by default and loaded by both dev and start
-- Create's `plugin` or `tool` choice creates at most one fixed-name local plugin and atomically updates its files and root-project relationships; this phase provides no `dsh create`
-- `dsh config` reads the same support set from an existing project, installs, enables, disables, and switches supported feature options, preserves unknown config and comments, and refuses to modify inconsistent config
+- Create's `plugin` or `tool` choice creates at most one fixed-name local plugin and atomically updates its files and root-project relationships; this phase provides no `dsh-sdk create`
+- `dsh-sdk config` reads the same support set from an existing project, installs, enables, disables, and switches supported feature options, preserves unknown config and comments, and refuses to modify inconsistent config
 - `.env.example` reflects variables required by the current features; `.env` only appends missing differently named variables and never updates or removes existing contents
 - npm, pnpm, and Yarn workspaces install, build, and start; local plugins resolve from source under dev and from built output under start
 
diff --git a/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.zh.md b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
index 613da4da93..ec08f323ac 100644
--- a/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
+++ b/docs/rfc/proposed/feature/2026-07-14-sdk-developer-projects.zh.md
@@ -16,7 +16,7 @@ DeepSeek Harness 通过 Cordis 插件对功能进行组合，但从空目录开
 
 SDK 创建一个普通、显式且归开发者所有的 TypeScript/Cordis 工程。`cordis.yml` 是唯一的运行时插件树；开发和生产读取同一份文件。工程中的 `package.json`、`cordis.yml`、TypeScript 入口、构建配置和 `plugins/*` 均可直接编辑，SDK 不把它们封装成不可见的 preset。
 
-开发者产品入口只有 `npm create @deepseek-ai/sdk` 和 `dsh` 命令。前者负责首次创建，`dsh config` 在创建后管理 SDK 能识别的内置功能，`dsh dev`、`dsh build` 与 `dsh start` 负责开发、构建和启动；本期不提供 `dsh create`。create 与 config 使用同一份人工编写的功能定义，因此一项功能的功能选项、NPM 依赖、Cordis 配置项、相关文件和识别规则只有一个来源。功能、功能选项等名词由 [SDK 工程编辑架构](../architecture/2026-07-15-sdk-project-editing-architecture.md) 的术语表定义。
+开发者产品入口只有 `npm create @deepseek-ai/sdk` 和 `dsh-sdk` 命令。前者负责首次创建，`dsh-sdk config` 在创建后管理 SDK 能识别的内置功能，`dsh-sdk dev`、`dsh-sdk build` 与 `dsh-sdk start` 负责开发、构建和启动；本期不提供 `dsh-sdk create`。create 与 config 使用同一份人工编写的功能定义，因此一项功能的功能选项、NPM 依赖、Cordis 配置项、相关文件和识别规则只有一个来源。功能、功能选项等名词由 [SDK 工程编辑架构](../architecture/2026-07-15-sdk-project-editing-architecture.md) 的术语表定义。
 
 SDK 只为功能选择和有限功能选项提供交互，不尝试把任意 Cordis 插件配置变成通用表单。功能选项所需的少量专用输入由所属功能收集；其余 Cordis 插件配置留在 `cordis.yml` 中，并通过注释指明常用改法，由开发者直接修改。
 
@@ -27,10 +27,10 @@ SDK 只为功能选择和有限功能选项提供交互，不尝试把任意 Cor
 ```sh
 npm create @deepseek-ai/sdk my-agent
 cd my-agent
-npm exec dsh dev index.ts
-npm exec dsh config
-npm exec dsh build
-npm exec dsh start index.js
+npm exec dsh-sdk dev index.ts
+npm exec dsh-sdk config
+npm exec dsh-sdk build
+npm exec dsh-sdk start index.js
 ```
 
 create 拒绝任何已经存在的目标路径。工程文件提交成功后，CLI 询问是否安装 NPM 依赖并构建；安装或构建失败时保留生成结果，并打印可以重新执行的命令。
@@ -94,31 +94,31 @@ my-agent/
 
 `.env.example` 始终存在，并由 SDK 根据当前功能维护占位。收集到 secret 或开发者确认稍后填写空凭据时，同时生成 gitignored `.env`。SDK 只向 `.env` 追加尚不存在的不同名变量，绝不覆盖或删除已有内容；切换功能选项可以清理 `.env.example` 中不再需要的占位，但旧凭据仍留在 `.env` 中供开发者自行处理。pnpm 和 Yarn 工程增加各自所需的 workspace 配置文件，但运行时插件树和 TypeScript 入口不分叉。
 
-生成的 `package.json` 提供以下 scripts；其中 `dev`、`build`、`start` 与 `config` 调用 `dsh`，`typecheck` 直接调用 TypeScript：
+生成的 `package.json` 提供以下 scripts；其中 `dev`、`build`、`start` 与 `config` 调用 `dsh-sdk`，`typecheck` 直接调用 TypeScript：
 
 | script | 行为 |
 |---|---|
-| `dev` | 运行 `dsh dev index.ts`，为 TypeScript 和本地 workspace 插件注册开发期解析 |
-| `build` | 运行 `dsh build`，调用工程安装的 tsdown 构建根入口和 `plugins/*` package |
+| `dev` | 运行 `dsh-sdk dev index.ts`，为 TypeScript 和本地 workspace 插件注册开发期解析 |
+| `build` | 运行 `dsh-sdk build`，调用工程安装的 tsdown 构建根入口和 `plugins/*` package |
 | `typecheck` | 直接运行 `tsc -b` |
-| `start` | 运行 `dsh start index.js`，启动已构建入口且不隐式构建 |
-| `config` | 运行 `dsh config`，修改当前工程功能树 |
+| `start` | 运行 `dsh-sdk start index.js`，启动已构建入口且不隐式构建 |
+| `config` | 运行 `dsh-sdk config`，修改当前工程功能树 |
 
-`dsh start` 与 `dsh dev` 可以接收模块 target，并把 `--` 后的参数原样转发给工程入口。通用参数解析使用 Node `parseArgs()` 的零 schema 模式：带值 flag 采用 `--key=value`，bare flag 转换为 `true`，`--no-*` 转换为 `false`。
+`dsh-sdk start` 与 `dsh-sdk dev` 可以接收模块 target，并把 `--` 后的参数原样转发给工程入口。通用参数解析使用 Node `parseArgs()` 的零 schema 模式：带值 flag 采用 `--key=value`，bare flag 转换为 `true`，`--no-*` 转换为 `false`。
 
 - stdio 工程通过 `--model=<name>` 传入所选 model，并根据可选的 `--resume=<session-id>` 创建或恢复 agent；
 - acp 使用协议 `session/load`
 - embed 使用生成代码中的 model。
 
-每个功能拥有的 Cordis 配置项在 `cordis.yml` 中保留自己的可编辑 Cordis 插件配置和说明注释；`dsh config` 修改其他功能时必须保留未知字段、未修改节点的格式和注释。HMR（热模块替换）是普通叶子配置项：选择该功能后，dev 和 start 加载同一个 watcher，命令不隐式改变插件树。
+每个功能拥有的 Cordis 配置项在 `cordis.yml` 中保留自己的可编辑 Cordis 插件配置和说明注释；`dsh-sdk config` 修改其他功能时必须保留未知字段、未修改节点的格式和注释。HMR（热模块替换）是普通叶子配置项：选择该功能后，dev 和 start 加载同一个 watcher，命令不隐式改变插件树。
 
 ## 创建后的配置
 
-`dsh config` 只要求当前目录具有可读的根 `package.json` 与 `cordis.yml`。它检查标准功能及其当前功能选项，以一棵功能树表达最终目标状态，并在 Review & Apply 前展示功能变化和受影响文件。
+`dsh-sdk config` 只要求当前目录具有可读的根 `package.json` 与 `cordis.yml`。它检查标准功能及其当前功能选项，以一棵功能树表达最终目标状态，并在 Review & Apply 前展示功能变化和受影响文件。
 
-`dsh config` 可以安装缺失功能、启停已安装功能和切换有限功能选项。required 功能不能取消。改变 NPM 依赖后只运行一次项目包管理器安装；安装失败不回滚已经提交的工程文件。
+`dsh-sdk config` 可以安装缺失功能、启停已安装功能和切换有限功能选项。required 功能不能取消。改变 NPM 依赖后只运行一次项目包管理器安装；安装失败不回滚已经提交的工程文件。
 
-SDK 只修改功能明确拥有的 Cordis 配置项、配置键、NPM 依赖、`.env.example` 占位和独占文件。同一功能选项的更新保留 Cordis 配置项中的未知配置键；手写或第三方插件只支持按稳定 ID 启停。已知功能被手改成不完整、歧义或无法读取的形状时，`dsh config` 显示诊断并拒绝自动修改，直到开发者手工修复。
+SDK 只修改功能明确拥有的 Cordis 配置项、配置键、NPM 依赖、`.env.example` 占位和独占文件。同一功能选项的更新保留 Cordis 配置项中的未知配置键；手写或第三方插件只支持按稳定 ID 启停。已知功能被手改成不完整、歧义或无法读取的形状时，`dsh-sdk config` 显示诊断并拒绝自动修改，直到开发者手工修复。
 
 一次 config 会话在内存工作区上累计全部修改。Apply 前完成功能关系、资源冲突和文件形状校验，并比较受影响文件与会话打开时的原文；校验失败或检测到外部修改时不写盘。实际写盘开始后不提供跨文件事务回滚。
 
@@ -128,7 +128,7 @@ Builtin 支持集由 SDK 人工策划，不根据 NPM 依赖名称或目录约
 
 ## 后续工作
 
-- `dsh add [package-spec]`：统一本地插件创建与外部 Cordis 插件接入；未指定 package 或仓库来源时创建本地 plugin/tool，指定来源时增加 NPM 依赖和 `cordis.yml` 配置项，来源模型为 GitHub 仓库等扩展保留空间
+- `dsh-sdk add [package-spec]`：统一本地插件创建与外部 Cordis 插件接入；未指定 package 或仓库来源时创建本地 plugin/tool，指定来源时增加 NPM 依赖和 `cordis.yml` 配置项，来源模型为 GitHub 仓库等扩展保留空间
 - 非交互 create/config：本期两个流程都要求 TTY，不提供供自动化调用的完整输入合同
 - 更多功能专用参数输入：本期产品只展示有限功能选项、secret 和少量专用值，不为 Cordis 插件配置提供通用参数界面
 
@@ -144,7 +144,7 @@ Builtin 支持集由 SDK 人工策划，不根据 NPM 依赖名称或目录约
 
 **使用私有协议发现本地插件。** 普通 package manager workspace、根 NPM 依赖、TypeScript references 和 Cordis 配置项已能表达完整关系；额外发现协议会创造只能由 SDK 理解的隐藏状态。
 
-**在现有工程中提供 `dsh create`。** create 已能生成一种可编辑的本地插件骨架，后续插件可以沿用普通 workspace 和 Cordis 机制手工添加；再提供同构命令会增加第二条脚手架产品面，却不增加新的组合功能。
+**在现有工程中提供 `dsh-sdk create`。** create 已能生成一种可编辑的本地插件骨架，后续插件可以沿用普通 workspace 和 Cordis 机制手工添加；再提供同构命令会增加第二条脚手架产品面，却不增加新的组合功能。
 
 **把每个新 Cordis 插件自动暴露为 builtin。** package 无法说明多个插件如何组合成一项产品功能，也无法推导互斥关系、功能依赖、secret、接口适用性和安全限制；支持集需要人工策划，自动化只适合检查候选是否完成分类。
 
@@ -153,8 +153,8 @@ Builtin 支持集由 SDK 人工策划，不根据 NPM 依赖名称或目录约
 - `npm create @deepseek-ai/sdk` 按本文顺序收集项目身份、provider、interface、功能、可选本地插件、包管理器和安装选择，并在取消时保持目标路径不存在
 - 默认 npm 工程具有本文目录树和 `dev`、`build`、`typecheck`、`start`、`config` scripts，且 dev/start 使用同一份 `cordis.yml`
 - create 展示本文功能及功能选项；`bash` 的 local/sandbox 二选一且默认 local，sandbox Cordis 配置项保留可编辑的注释配置示例；HMR 默认选中并同时由 dev/start 加载
-- create 的 `plugin` 或 `tool` 选择至多生成一个固定名称的本地插件，并原子更新插件文件与根工程关系；本期不提供 `dsh create`
-- `dsh config` 从现有工程读取同一支持集，能够安装、启停和切换支持的功能选项，保留未知配置与注释，并拒绝修改不一致配置
+- create 的 `plugin` 或 `tool` 选择至多生成一个固定名称的本地插件，并原子更新插件文件与根工程关系；本期不提供 `dsh-sdk create`
+- `dsh-sdk config` 从现有工程读取同一支持集，能够安装、启停和切换支持的功能选项，保留未知配置与注释，并拒绝修改不一致配置
 - `.env.example` 反映当前功能所需变量；`.env` 只追加缺失的不同名变量，从不覆盖或清理已有内容
 - npm、pnpm 和 Yarn 生成的 workspace 能安装、构建和启动；本地插件在 dev 中使用源码，在 start 中使用构建产物
 
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index a193206a65..953d52ea76 100644
--- a/packages/sdk/README.md
+++ b/packages/sdk/README.md
@@ -7,9 +7,9 @@ The [feature RFC](../../docs/rfc/proposed/feature/2026-07-14-sdk-developer-proje
 | Package | Role |
 |---|---|
 | [`helper`](helper/README.md) | Project aggregate, edit session, builtin features, project documents, templates, package managers, and prompt abstraction |
-| [`scripts`](scripts/README.md) | The `dsh` launcher: `start`, `dev`, `build`, and interactive `config` |
+| [`scripts`](scripts/README.md) | The `dsh-sdk` launcher: `start`, `dev`, `build`, and interactive `config` |
 | [`create-sdk`](create-sdk/README.md) | The `npm create @deepseek-ai/sdk` initializer |
 
 `@deepseek-ai/create-sdk` is the one package-name exception to the repository's `@deepseek-ai/dsh-*` rule: npm's scoped initializer convention requires that name for `npm create @deepseek-ai/sdk`.
 
-Generated projects keep `cordis.yml` as the only runtime plugin tree. `dsh dev` adds TypeScript and local-workspace resolution around that same file; it does not create a development-only config.
+Generated projects keep `cordis.yml` as the only runtime plugin tree. `dsh-sdk dev` adds TypeScript and local-workspace resolution around that same file; it does not create a development-only config.
diff --git a/packages/sdk/create-sdk/tests/built-artifacts.e2e.ts b/packages/sdk/create-sdk/tests/built-artifacts.e2e.ts
index 53a2b858ba..4b2de078c7 100644
--- a/packages/sdk/create-sdk/tests/built-artifacts.e2e.ts
+++ b/packages/sdk/create-sdk/tests/built-artifacts.e2e.ts
@@ -13,9 +13,9 @@ const scriptsBin = join(repoRoot, 'packages/sdk/scripts/lib/bin.js')
 describe.skipIf(!existsSync(createBin) || !existsSync(scriptsBin))(
   'SDK built artifacts',
   () => {
-    it('runs the published dsh bin help path under plain Node', async () => {
+    it('runs the published dsh-sdk bin help path under plain Node', async () => {
       const result = await execFileAsync(process.execPath, [scriptsBin, '--help'], { encoding: 'utf8' })
-      expect(result.stdout).toContain('Usage: dsh <command>')
+      expect(result.stdout).toContain('Usage: dsh-sdk <command>')
       expect(result.stderr).toBe('')
     })
 
diff --git a/packages/sdk/create-sdk/tests/create.spec.ts b/packages/sdk/create-sdk/tests/create.spec.ts
index 8233806ac5..9d75700bb9 100644
--- a/packages/sdk/create-sdk/tests/create.spec.ts
+++ b/packages/sdk/create-sdk/tests/create.spec.ts
@@ -261,11 +261,11 @@ describe('CreateWizard and scaffolder', () => {
     const manifest = parseGeneratedPackageManifest(await readFile(join(target, 'package.json'), 'utf8'))
     expect(tsconfig.compilerOptions.types).toEqual(['node'])
     expect(manifest.scripts).toEqual({
-      dev: 'dsh dev index.ts',
-      build: 'dsh build',
+      dev: 'dsh-sdk dev index.ts',
+      build: 'dsh-sdk build',
       typecheck: 'tsc -b',
-      start: 'dsh start index.js',
-      config: 'dsh config',
+      start: 'dsh-sdk start index.js',
+      config: 'dsh-sdk config',
     })
     expect(manifest.dependencies).not.toHaveProperty('node-addon-require-builtin')
     expect(manifest.devDependencies?.['@types/node']).toBe('^22.20.0')
diff --git a/packages/sdk/create-sdk/tests/link-workspace.e2e.ts b/packages/sdk/create-sdk/tests/link-workspace.e2e.ts
index d78993995d..6e0b404dc6 100644
--- a/packages/sdk/create-sdk/tests/link-workspace.e2e.ts
+++ b/packages/sdk/create-sdk/tests/link-workspace.e2e.ts
@@ -93,8 +93,8 @@ describe.skipIf(!existsSync(builtScripts))('live-linked generated projects', ()
       })
       expect(existsSync(join(root, 'index.js'))).toBe(true)
       expect(existsSync(join(root, 'plugins/probe/lib/index.js'))).toBe(true)
-      const dsh = join(root, 'node_modules/@deepseek-ai/dsh-scripts/lib/bin.js')
-      const run = await execFileAsync(process.execPath, [dsh, 'dev', 'index.ts'], {
+      const dshSdk = join(root, 'node_modules/@deepseek-ai/dsh-scripts/lib/bin.js')
+      const run = await execFileAsync(process.execPath, [dshSdk, 'dev', 'index.ts'], {
         cwd: root,
         env: { ...commandEnvironment, DEEPSEEK_API_KEY: 'test-key' },
         encoding: 'utf8',
diff --git a/packages/sdk/helper/README.md b/packages/sdk/helper/README.md
index 3e1148e567..5b5608cdf0 100644
--- a/packages/sdk/helper/README.md
+++ b/packages/sdk/helper/README.md
@@ -1,6 +1,6 @@
 # `@deepseek-ai/dsh-helper`
 
-Shared project domain and infrastructure for `create-sdk` and `dsh config`. `SdkProject` is a read-only snapshot; `ProjectEditSession` is the only mutation and commit boundary. The [SDK architecture RFC](../../../docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md) owns the rationale.
+Shared project domain and infrastructure for `create-sdk` and `dsh-sdk config`. `SdkProject` is a read-only snapshot; `ProjectEditSession` is the only mutation and commit boundary. The [SDK architecture RFC](../../../docs/rfc/proposed/architecture/2026-07-15-sdk-project-editing-architecture.md) owns the rationale.
 
 The package owns the builtin typed-spec catalog, provider/app behavior entities, structured project file objects, helper-owned project templates, the shared typed `TextTemplate` renderer, package-manager strategies, local-plugin blueprints, typed questions, and the clack prompt adapter. It never boots a Cordis application.
 
diff --git a/packages/sdk/helper/src/templates/assets/README.md.tpl b/packages/sdk/helper/src/templates/assets/README.md.tpl
index 5d56d13a72..0033c8e0d4 100644
--- a/packages/sdk/helper/src/templates/assets/README.md.tpl
+++ b/packages/sdk/helper/src/templates/assets/README.md.tpl
@@ -30,4 +30,4 @@ Install NPM dependencies with `{{packageManager}} {{installArgs}}`, then use:
 - `start`: `{{packageManager}} start`
 - `config`: `{{packageManager}} run config`
 
-Edit `cordis.yml` to change the runtime plugin tree. Add or remove builtin features with `{{packageManager}} exec dsh config`.
+Edit `cordis.yml` to change the runtime plugin tree. Add or remove builtin features with `{{packageManager}} exec dsh-sdk config`.
diff --git a/packages/sdk/helper/src/templates/assets/package.json.tpl b/packages/sdk/helper/src/templates/assets/package.json.tpl
index 9884f0913f..b5aa0fde0d 100644
--- a/packages/sdk/helper/src/templates/assets/package.json.tpl
+++ b/packages/sdk/helper/src/templates/assets/package.json.tpl
@@ -5,9 +5,9 @@
   "description": {{description}},
   "type": "module",
   "scripts": {
-    "build": "dsh build",
+    "build": "dsh-sdk build",
     "typecheck": "tsc -b",
-    "config": "dsh config"
+    "config": "dsh-sdk config"
   },
   "dependencies": {{dependencies}},
   "devDependencies": {{devDependencies}}
diff --git a/packages/sdk/helper/src/templates/project-template.ts b/packages/sdk/helper/src/templates/project-template.ts
index 90ab46d51e..b214126b6e 100644
--- a/packages/sdk/helper/src/templates/project-template.ts
+++ b/packages/sdk/helper/src/templates/project-template.ts
@@ -107,7 +107,7 @@ export function createAppProjectArtifacts(
 export function createAppPackageScripts(context: ProjectTemplateContext): Readonly<Record<'dev' | 'start', string>> {
   const modelArg = context.isStdio ? ` -- --model=${JSON.stringify(context.model)}` : ''
   return {
-    dev: `dsh dev index.ts${modelArg}`,
-    start: `dsh start index.js${modelArg}`,
+    dev: `dsh-sdk dev index.ts${modelArg}`,
+    start: `dsh-sdk start index.js${modelArg}`,
   }
 }
diff --git a/packages/sdk/helper/tests/project.spec.ts b/packages/sdk/helper/tests/project.spec.ts
index 37c0c2f903..e888d7854f 100644
--- a/packages/sdk/helper/tests/project.spec.ts
+++ b/packages/sdk/helper/tests/project.spec.ts
@@ -167,11 +167,11 @@ describe('SdkProject and ProjectEditSession', () => {
     expect(index).toContain('agents.create')
     expect(index).toContain('boot.args.resume')
     expect(project.packageManifest().scripts).toEqual({
-      dev: 'dsh dev index.ts -- --model="deepseek-v4-flash"',
-      build: 'dsh build',
+      dev: 'dsh-sdk dev index.ts -- --model="deepseek-v4-flash"',
+      build: 'dsh-sdk build',
       typecheck: 'tsc -b',
-      start: 'dsh start index.js -- --model="deepseek-v4-flash"',
-      config: 'dsh config',
+      start: 'dsh-sdk start index.js -- --model="deepseek-v4-flash"',
+      config: 'dsh-sdk config',
     })
     expect(await readFile(join(project.root, '.env.example'), 'utf8')).toContain('EXA_API_KEY=')
     expect(project.cordis.entry('stdio')?.config).toMatchObject({ agent: 'main' })
@@ -255,8 +255,8 @@ describe('SdkProject and ProjectEditSession', () => {
     const acp = (await edit.commit()).project
     expect(acp.profile.runInterface).toBe('acp')
     expect(acp.packageManifest().scripts).toMatchObject({
-      dev: 'dsh dev index.ts',
-      start: 'dsh start index.js',
+      dev: 'dsh-sdk dev index.ts',
+      start: 'dsh-sdk start index.js',
     })
     expect(await readFile(join(acp.root, 'README.md'), 'utf8')).toContain('Run as an ACP server')
     expect(await readFile(join(acp.root, 'index.ts'), 'utf8')).not.toContain('agents.create')
diff --git a/packages/sdk/scripts/README.md b/packages/sdk/scripts/README.md
index 5b3b1908bc..e87c375a4f 100644
--- a/packages/sdk/scripts/README.md
+++ b/packages/sdk/scripts/README.md
@@ -1,17 +1,17 @@
 # `@deepseek-ai/dsh-scripts`
 
-The `dsh` launcher owns SDK project startup and configuration.
+The `dsh-sdk` launcher owns SDK project startup and configuration.
 
 | Command | Behavior |
 |---|---|
-| `dsh start [target] [-- args…]` | Import a module target and invoke `main(bootContext)`, or boot `cordis.yml` when omitted; arguments after `--` are forwarded |
-| `dsh dev [target] [-- args…]` | Register TypeScript and local-workspace source resolution, then use the start path |
-| `dsh build [args…]` | Invoke the project's installed tsdown with the project arguments |
-| `dsh config` | Open one interactive edit session, review accumulated changes, commit once, and install once when NPM dependencies changed |
+| `dsh-sdk start [target] [-- args…]` | Import a module target and invoke `main(bootContext)`, or boot `cordis.yml` when omitted; arguments after `--` are forwarded |
+| `dsh-sdk dev [target] [-- args…]` | Register TypeScript and local-workspace source resolution, then use the start path |
+| `dsh-sdk build [args…]` | Invoke the project's installed tsdown with the project arguments |
+| `dsh-sdk config` | Open one interactive edit session, review accumulated changes, commit once, and install once when NPM dependencies changed |
 
 `ProjectBuild(tsdownConfig)` and `PluginBuild(tsdownConfig)` are exported only from `@deepseek-ai/dsh-scripts/dev/tsdown-config`. Development and production read the same `cordis.yml`.
 
-Generated project scripts invoke `dsh` for dev, build, start, and config; typecheck runs `tsc -b` directly. HMR remains an explicit `cordis.yml` feature loaded by both dev and start.
+Generated project scripts invoke `dsh-sdk` for dev, build, start, and config; typecheck runs `tsc -b` directly. HMR remains an explicit `cordis.yml` feature loaded by both dev and start.
 
 The runtime library exports `startSDK(source)` to load `.env` and `cordis.yml` and return the live context, and `runSDK(target)` to import a project module and invoke its `main(bootContext)` (`runSDK()` without a target delegates to `startSDK('./cordis.yml')`). `SdkBootContext` carries the raw forwarded `argv`, generic `args`, the absolute launcher `cwd`, and the `start`/`dev` mode. The launcher declares no project options: Node `parseArgs()` runs with zero schema, so valued flags use `--key=value`, bare flags become booleans, `--no-cache` becomes `args.cache = false`, and option names retain Node's spelling (`--max-depth=3` → `args['max-depth']`).
 
diff --git a/packages/sdk/scripts/package.json b/packages/sdk/scripts/package.json
index c74ab051cc..ba441a528c 100644
--- a/packages/sdk/scripts/package.json
+++ b/packages/sdk/scripts/package.json
@@ -7,7 +7,7 @@
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
   "bin": {
-    "dsh": "lib/bin.js"
+    "dsh-sdk": "lib/bin.js"
   },
   "exports": {
     ".": {
diff --git a/packages/sdk/scripts/src/args.ts b/packages/sdk/scripts/src/args.ts
index b23fe44870..1b91269592 100644
--- a/packages/sdk/scripts/src/args.ts
+++ b/packages/sdk/scripts/src/args.ts
@@ -1,5 +1,5 @@
 /**
- * Commander adapter for the dsh subcommand surface.
+ * Commander adapter for the dsh-sdk subcommand surface.
  *
  * @module @deepseek-ai/dsh-scripts/args
  */
@@ -7,12 +7,12 @@
 import { parseArgs as parseNodeArgs } from 'node:util'
 import { Command } from 'commander'
 
-/** Commands implemented by the dsh launcher. */
-type DshCommand = 'start' | 'dev' | 'build' | 'config'
+/** Commands implemented by the dsh-sdk launcher. */
+type DshSdkCommand = 'start' | 'dev' | 'build' | 'config'
 
-/** Parsed dsh invocation. */
-export interface DshArgs {
-  command?: DshCommand
+/** Parsed dsh-sdk invocation. */
+export interface DshSdkArgs {
+  command?: DshSdkCommand
   target?: string
   forwarded: readonly string[]
   help: boolean
@@ -29,16 +29,16 @@ export function parseSdkBootArgs(argv: readonly string[]): Record<string, string
 }
 
 /** Parse one launcher invocation through real Commander subcommands. */
-export function parseDshArgs(argv: readonly string[]): DshArgs {
+export function parseDshSdkArgs(argv: readonly string[]): DshSdkArgs {
   if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
     return { forwarded: [], help: true }
   }
   const separator = argv.indexOf('--')
   const launcherArgv = separator === -1 ? argv : argv.slice(0, separator)
   const passthrough = separator === -1 ? [] : argv.slice(separator + 1)
-  let parsed: DshArgs | undefined
+  let parsed: DshSdkArgs | undefined
   const program = new Command()
-    .name('dsh')
+    .name('dsh-sdk')
     .helpOption(false)
     .showHelpAfterError(false)
     .exitOverride()
@@ -62,9 +62,9 @@ export function parseDshArgs(argv: readonly string[]): DshArgs {
   })
   program.parse([...launcherArgv], { from: 'user' })
   /* v8 ignore next -- every registered Commander action above assigns parsed or Commander throws */
-  if (!parsed) throw new Error('dsh command did not resolve')
+  if (!parsed) throw new Error('dsh-sdk command did not resolve')
   if (parsed.command === 'config' && passthrough.length > 0) {
-    throw new Error('dsh config does not accept forwarded arguments')
+    throw new Error('dsh-sdk config does not accept forwarded arguments')
   }
   return { ...parsed, forwarded: [...parsed.forwarded, ...passthrough] }
 }
diff --git a/packages/sdk/scripts/src/bin.ts b/packages/sdk/scripts/src/bin.ts
index d08b872818..f125f0f4ac 100644
--- a/packages/sdk/scripts/src/bin.ts
+++ b/packages/sdk/scripts/src/bin.ts
@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 /**
- * Self-executing dsh launcher.
+ * Self-executing dsh-sdk launcher.
  *
  * @module @deepseek-ai/dsh-scripts/bin
  */
 
-import { runDshCommand } from './command.ts'
+import { runDshSdkCommand } from './command.ts'
 
-process.exitCode = await runDshCommand()
+process.exitCode = await runDshSdkCommand()
diff --git a/packages/sdk/scripts/src/build.ts b/packages/sdk/scripts/src/build.ts
index f71832f75f..4b83a24b71 100644
--- a/packages/sdk/scripts/src/build.ts
+++ b/packages/sdk/scripts/src/build.ts
@@ -54,7 +54,7 @@ function resolveTsdownBin(cwd: string): string {
   try {
     manifestPath = require.resolve('tsdown/package.json')
   } catch (error) {
-    throw new Error(`dsh build requires tsdown in this project: ${String(error)}`)
+    throw new Error(`dsh-sdk build requires tsdown in this project: ${String(error)}`)
   }
   const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as { bin?: unknown }
   const bin = typeof manifest.bin === 'string'
diff --git a/packages/sdk/scripts/src/command.ts b/packages/sdk/scripts/src/command.ts
index 13eec41d87..9351cfa39c 100644
--- a/packages/sdk/scripts/src/command.ts
+++ b/packages/sdk/scripts/src/command.ts
@@ -1,17 +1,17 @@
 /**
- * Internal dsh command composition used by the package bin.
+ * Internal dsh-sdk command composition used by the package bin.
  *
  * @module @deepseek-ai/dsh-scripts/command
  */
 
-import { parseDshArgs } from './args.ts'
+import { parseDshSdkArgs } from './args.ts'
 import { runProjectBuild } from './build.ts'
 import { runConfigCommand, type ConfigCommandContext } from './config.ts'
 import { runSDK } from './runtime.ts'
-import { DSH_TEMPLATES } from './templates/dsh-templates.ts'
+import { DSH_SDK_TEMPLATES } from './templates/dsh-sdk-templates.ts'
 
-/** Injectable process and command boundaries used by the dsh bin. */
-export interface DshCommandContext extends ConfigCommandContext {
+/** Injectable process and command boundaries used by the dsh-sdk bin. */
+export interface DshSdkCommandContext extends ConfigCommandContext {
   cwd: string
   stdin: NodeJS.ReadStream
   stdout: NodeJS.WriteStream
@@ -21,10 +21,10 @@ export interface DshCommandContext extends ConfigCommandContext {
   config?: typeof runConfigCommand
 }
 
-/** Run one parsed dsh command and return its process exit code. */
-export async function runDshCommand(
+/** Run one parsed dsh-sdk command and return its process exit code. */
+export async function runDshSdkCommand(
   argv: readonly string[] = process.argv.slice(2),
-  context: DshCommandContext = {
+  context: DshSdkCommandContext = {
     cwd: process.cwd(),
     stdin: process.stdin,
     stdout: process.stdout,
@@ -32,9 +32,9 @@ export async function runDshCommand(
   },
 ): Promise<number> {
   try {
-    const args = parseDshArgs(argv)
+    const args = parseDshSdkArgs(argv)
     if (args.help || !args.command) {
-      context.stdout.write(DSH_TEMPLATES.usage.render({}))
+      context.stdout.write(DSH_SDK_TEMPLATES.usage.render({}))
       return 0
     }
     const run = context.run ?? runSDK
@@ -52,7 +52,7 @@ export async function runDshCommand(
     }
     return 0
   } catch (error) {
-    context.stderr.write(`dsh: ${error instanceof Error ? error.message : String(error)}\n`)
+    context.stderr.write(`dsh-sdk: ${error instanceof Error ? error.message : String(error)}\n`)
     return 1
   }
 }
diff --git a/packages/sdk/scripts/src/config.ts b/packages/sdk/scripts/src/config.ts
index bb0ab464c4..88d8cc035a 100644
--- a/packages/sdk/scripts/src/config.ts
+++ b/packages/sdk/scripts/src/config.ts
@@ -1,5 +1,5 @@
 /**
- * dsh config command composition.
+ * dsh-sdk config command composition.
  *
  * @module @deepseek-ai/dsh-scripts/config
  */
@@ -12,7 +12,7 @@ import {
 } from '@deepseek-ai/dsh-helper'
 import { ConfigWorkflow, type ConfigWorkflowResult } from './config/config-workflow.ts'
 
-/** Process stream slice required by dsh config. */
+/** Process stream slice required by dsh-sdk config. */
 export interface ConfigCommandContext {
   cwd: string
   stdin: NodeJS.ReadStream
@@ -24,7 +24,7 @@ export interface ConfigCommandContext {
 /** Open and interactively edit one existing SDK project. */
 export async function runConfigCommand(context: ConfigCommandContext): Promise<ConfigWorkflowResult> {
   if (!context.port && (!context.stdin.isTTY || !context.stdout.isTTY)) {
-    throw new Error('dsh config requires an interactive TTY')
+    throw new Error('dsh-sdk config requires an interactive TTY')
   }
   const project = await SdkProject.open(context.cwd)
   const registry = createBuiltinRegistry(project.profile)
diff --git a/packages/sdk/scripts/src/config/config-workflow.ts b/packages/sdk/scripts/src/config/config-workflow.ts
index e4e3476c3f..318ecd4ece 100644
--- a/packages/sdk/scripts/src/config/config-workflow.ts
+++ b/packages/sdk/scripts/src/config/config-workflow.ts
@@ -19,7 +19,7 @@ import {
   type PromptPort,
   type SdkProject,
 } from '@deepseek-ai/dsh-helper'
-import { DSH_TEMPLATES } from '../templates/dsh-templates.ts'
+import { DSH_SDK_TEMPLATES } from '../templates/dsh-sdk-templates.ts'
 
 /** Config result, including an install failure that happened after commit. */
 export interface ConfigWorkflowResult {
@@ -144,7 +144,7 @@ export class ConfigWorkflow {
     } catch (error) {
       const installError = error instanceof Error ? error : new Error(String(error))
       const manager = project.profile.packageManager
-      this.output.write(DSH_TEMPLATES.configInstallFailure.render({
+      this.output.write(DSH_SDK_TEMPLATES.configInstallFailure.render({
         error: installError.message,
         packageManager: manager.name,
         installArgs: manager.installCommand().join(' '),
diff --git a/packages/sdk/scripts/src/runtime.ts b/packages/sdk/scripts/src/runtime.ts
index fbd9a88726..b25563bc07 100644
--- a/packages/sdk/scripts/src/runtime.ts
+++ b/packages/sdk/scripts/src/runtime.ts
@@ -68,7 +68,7 @@ async function registerDevRuntime(cwd: string = process.cwd()): Promise<void> {
     ({ register: registerTsx } = await import('tsx/esm/api'))
   } catch (error) {
     /* v8 ignore next -- tsx is a declared project NPM dependency; missing-package behavior is defensive */
-    throw new Error(`dsh dev requires the project's tsx NPM dependency: ${String(error)}`)
+    throw new Error(`dsh-sdk dev requires the project's tsx NPM dependency: ${String(error)}`)
   }
   registerTsx()
   const mappings = await localPluginMappings(resolve(cwd))
@@ -97,9 +97,9 @@ export async function startSDK(
   }
   const requested = source instanceof URL ? fileURLToPath(source) : source
   const absolute = resolveConfigPath(requested, undefined, cwd)
-  loadEnv('dsh', dirname(absolute))
-  installFailLoud('dsh')
-  return boot('dsh', absolute)
+  loadEnv('dsh-sdk', dirname(absolute))
+  installFailLoud('dsh-sdk')
+  return boot('dsh-sdk', absolute)
 }
 
 /**
@@ -120,12 +120,12 @@ export async function runSDK(
   try {
     await access(absolute)
   } catch (error) {
-    const hint = options.dev ? '' : ' Run dsh build first if this is a TypeScript project.'
+    const hint = options.dev ? '' : ' Run dsh-sdk build first if this is a TypeScript project.'
     throw new Error(`cannot start missing target ${target}.${hint} ${String(error)}`)
   }
   const module = await import(pathToFileURL(absolute).href) as { main?: (context: SdkBootContext) => unknown }
   if (typeof module.main !== 'function') {
-    throw new Error(`dsh target ${target} must export function main()`)
+    throw new Error(`dsh-sdk target ${target} must export function main()`)
   }
   const argv = [...options.argv ?? []]
   return module.main({
diff --git a/packages/sdk/scripts/src/templates/assets/usage.txt.tpl b/packages/sdk/scripts/src/templates/assets/usage.txt.tpl
index b9680dddcf..d4122198f5 100644
--- a/packages/sdk/scripts/src/templates/assets/usage.txt.tpl
+++ b/packages/sdk/scripts/src/templates/assets/usage.txt.tpl
@@ -1,4 +1,4 @@
-Usage: dsh <command> [options]
+Usage: dsh-sdk <command> [options]
 
 Commands:
   start [target] [-- args...]  Import a built module, or boot cordis.yml
diff --git a/packages/sdk/scripts/src/templates/dsh-templates.ts b/packages/sdk/scripts/src/templates/dsh-sdk-templates.ts
similarity index 70%
rename from packages/sdk/scripts/src/templates/dsh-templates.ts
rename to packages/sdk/scripts/src/templates/dsh-sdk-templates.ts
index 136ea5940a..a7dabc3b85 100644
--- a/packages/sdk/scripts/src/templates/dsh-templates.ts
+++ b/packages/sdk/scripts/src/templates/dsh-sdk-templates.ts
@@ -1,7 +1,7 @@
 /**
- * Package-owned terminal templates for the dsh launcher.
+ * Package-owned terminal templates for the dsh-sdk launcher.
  *
- * @module @deepseek-ai/dsh-scripts/templates/dsh-templates
+ * @module @deepseek-ai/dsh-scripts/templates/dsh-sdk-templates
  */
 
 import { TextTemplate, type PackageManagerName } from '@deepseek-ai/dsh-helper'
@@ -12,8 +12,8 @@ interface ConfigInstallFailureTemplateModel {
   installArgs: string
 }
 
-/** Compiled dsh terminal templates. */
-export const DSH_TEMPLATES = {
+/** Compiled dsh-sdk terminal templates. */
+export const DSH_SDK_TEMPLATES = {
   usage: TextTemplate.fromFile<Record<string, never>>(new URL('./assets/usage.txt.tpl', import.meta.url)),
   configInstallFailure: TextTemplate.fromFile<ConfigInstallFailureTemplateModel>(
     new URL('./assets/config-install-failure.txt.tpl', import.meta.url),
diff --git a/packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap b/packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap
index bab11ec455..31e21dd8a9 100644
--- a/packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap
+++ b/packages/sdk/scripts/tests/__snapshots__/config.snapshot.ts.snap
@@ -1,6 +1,6 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`dsh config terminal contract > pins the feature tree and Review & Apply output 1`] = `
+exports[`dsh-sdk config terminal contract > pins the feature tree and Review & Apply output 1`] = `
 {
   "committed": {
     "addedFeatures": [
diff --git a/packages/sdk/scripts/tests/config.snapshot.ts b/packages/sdk/scripts/tests/config.snapshot.ts
index c6f6c64c6c..80a79a5f20 100644
--- a/packages/sdk/scripts/tests/config.snapshot.ts
+++ b/packages/sdk/scripts/tests/config.snapshot.ts
@@ -106,7 +106,7 @@ async function baseProject(): Promise<SdkProject> {
   return (await edit.commit()).project
 }
 
-describe('dsh config terminal contract', () => {
+describe('dsh-sdk config terminal contract', () => {
   it('pins the feature tree and Review & Apply output', async () => {
     const project = await baseProject()
     const registry = createBuiltinRegistry(project.profile)
diff --git a/packages/sdk/scripts/tests/scripts.spec.ts b/packages/sdk/scripts/tests/scripts.spec.ts
index 572705f8fd..0ed3fed411 100644
--- a/packages/sdk/scripts/tests/scripts.spec.ts
+++ b/packages/sdk/scripts/tests/scripts.spec.ts
@@ -25,9 +25,9 @@ import type {
   TextPromptRequest,
 } from '../../helper/src/questions/prompt-port.ts'
 import { runSDK, startSDK } from '@deepseek-ai/dsh-scripts'
-import { parseDshArgs, parseSdkBootArgs } from '../src/args.ts'
+import { parseDshSdkArgs, parseSdkBootArgs } from '../src/args.ts'
 import { PluginBuild, ProjectBuild, runProjectBuild } from '../src/build.ts'
-import { runDshCommand, type DshCommandContext } from '../src/command.ts'
+import { runDshSdkCommand, type DshSdkCommandContext } from '../src/command.ts'
 import { runConfigCommand } from '../src/config.ts'
 import { ConfigWorkflow } from '../src/config/config-workflow.ts'
 import { initialize, resolve as resolveLocalPlugin } from '../src/local-plugin-loader-hooks.ts'
@@ -62,7 +62,7 @@ function outputBuffer(): { stream: Writable; read: () => string } {
   }
 }
 
-function commandContext(cwd: string): DshCommandContext & { readStdout: () => string; readStderr: () => string } {
+function commandContext(cwd: string): DshSdkCommandContext & { readStdout: () => string; readStderr: () => string } {
   let stdout = ''
   let stderr = ''
   const stdin = Object.assign(new PassThrough(), { isTTY: true }) as unknown as NodeJS.ReadStream
@@ -117,22 +117,22 @@ async function committedProject(
 
 describe('Commander launcher arguments', () => {
   it('parses real subcommands and forwards arbitrary build options', () => {
-    expect(parseDshArgs([])).toMatchObject({ help: true })
-    expect(parseDshArgs(['start', 'index.js'])).toMatchObject({ command: 'start', target: 'index.js' })
-    expect(parseDshArgs(['dev'])).toEqual({ command: 'dev', forwarded: [], help: false })
-    expect(parseDshArgs(['build', '--watch', '--minify'])).toMatchObject({
+    expect(parseDshSdkArgs([])).toMatchObject({ help: true })
+    expect(parseDshSdkArgs(['start', 'index.js'])).toMatchObject({ command: 'start', target: 'index.js' })
+    expect(parseDshSdkArgs(['dev'])).toEqual({ command: 'dev', forwarded: [], help: false })
+    expect(parseDshSdkArgs(['build', '--watch', '--minify'])).toMatchObject({
       command: 'build', forwarded: ['--watch', '--minify'],
     })
-    expect(parseDshArgs(['start', 'index.js', '--', '--resume', 'session-1'])).toMatchObject({
+    expect(parseDshSdkArgs(['start', 'index.js', '--', '--resume', 'session-1'])).toMatchObject({
       command: 'start', target: 'index.js', forwarded: ['--resume', 'session-1'],
     })
-    expect(parseDshArgs(['config'])).toMatchObject({ command: 'config' })
-    expect(parseDshArgs(['start'])).toEqual({ command: 'start', forwarded: [], help: false })
-    expect(parseDshArgs(['dev', 'index.ts'])).toMatchObject({ command: 'dev', target: 'index.ts' })
-    expect(parseDshArgs(['-h'])).toMatchObject({ help: true })
-    expect(() => parseDshArgs(['unknown'])).toThrow()
-    expect(() => parseDshArgs(['config', 'extra'])).toThrow()
-    expect(() => parseDshArgs(['config', '--', 'extra'])).toThrow('does not accept forwarded')
+    expect(parseDshSdkArgs(['config'])).toMatchObject({ command: 'config' })
+    expect(parseDshSdkArgs(['start'])).toEqual({ command: 'start', forwarded: [], help: false })
+    expect(parseDshSdkArgs(['dev', 'index.ts'])).toMatchObject({ command: 'dev', target: 'index.ts' })
+    expect(parseDshSdkArgs(['-h'])).toMatchObject({ help: true })
+    expect(() => parseDshSdkArgs(['unknown'])).toThrow()
+    expect(() => parseDshSdkArgs(['config', 'extra'])).toThrow()
+    expect(() => parseDshSdkArgs(['config', '--', 'extra'])).toThrow('does not accept forwarded')
     expect(parseSdkBootArgs([
       '--model=mock', '--resume=session-1', '--custom=value', '--verbose', '--no-cache', '--max-depth=-1',
     ])).toEqual({
@@ -148,28 +148,28 @@ describe('Commander launcher arguments', () => {
     context.run = async (target, options) => { calls.push(['run', target, options]); return undefined }
     context.build = async (args, cwd) => { calls.push(['build', args, cwd]) }
     context.config = async () => { calls.push(['config']); return {} }
-    await expect(runDshCommand(['start', 'index.js', '--', '--resume', 'session-1'], context)).resolves.toBe(0)
-    await expect(runDshCommand(['dev', 'index.ts'], context)).resolves.toBe(0)
-    await expect(runDshCommand(['build', '--watch'], context)).resolves.toBe(0)
-    await expect(runDshCommand(['config'], context)).resolves.toBe(0)
+    await expect(runDshSdkCommand(['start', 'index.js', '--', '--resume', 'session-1'], context)).resolves.toBe(0)
+    await expect(runDshSdkCommand(['dev', 'index.ts'], context)).resolves.toBe(0)
+    await expect(runDshSdkCommand(['build', '--watch'], context)).resolves.toBe(0)
+    await expect(runDshSdkCommand(['config'], context)).resolves.toBe(0)
     expect(calls).toHaveLength(4)
     expect(calls[0]).toEqual(['run', 'index.js', { cwd: root, argv: ['--resume', 'session-1'] }])
     expect(calls[1]).toEqual(['run', 'index.ts', { cwd: root, dev: true, argv: [] }])
     context.config = async () => ({ installError: new Error('offline') })
-    await expect(runDshCommand(['config'], context)).resolves.toBe(1)
+    await expect(runDshSdkCommand(['config'], context)).resolves.toBe(1)
     context.config = async () => { throw 'broken' }
-    await expect(runDshCommand(['config'], context)).resolves.toBe(1)
+    await expect(runDshSdkCommand(['config'], context)).resolves.toBe(1)
     expect(context.readStderr()).toContain('broken')
-    await expect(runDshCommand(['unknown'], context)).resolves.toBe(1)
-    await expect(runDshCommand([], context)).resolves.toBe(0)
-    expect(context.readStdout()).toContain('Usage: dsh')
+    await expect(runDshSdkCommand(['unknown'], context)).resolves.toBe(1)
+    await expect(runDshSdkCommand([], context)).resolves.toBe(0)
+    expect(context.readStdout()).toContain('Usage: dsh-sdk')
 
     const defaults = commandContext(root)
     await writeFile(join(root, 'main.mjs'), 'export function main() { return "ok" }\n')
-    await expect(runDshCommand(['start', 'main.mjs'], defaults)).resolves.toBe(0)
-    await expect(runDshCommand(['build'], defaults)).resolves.toBe(0)
+    await expect(runDshSdkCommand(['start', 'main.mjs'], defaults)).resolves.toBe(0)
+    await expect(runDshSdkCommand(['build'], defaults)).resolves.toBe(0)
     defaults.port = new QueuePort([[]])
-    await expect(runDshCommand(['config'], defaults)).resolves.toBe(1)
+    await expect(runDshSdkCommand(['config'], defaults)).resolves.toBe(1)
   })
 })
 
@@ -260,7 +260,7 @@ describe('build profiles and invocation', () => {
     let called = false
     await runProjectBuild([], root, { run: async () => { called = true; return { exitCode: 0, signal: null } } })
     expect(called).toBe(false)
-    await expect(runSDK('index.js', { cwd: root })).rejects.toThrow('Run dsh build first')
+    await expect(runSDK('index.js', { cwd: root })).rejects.toThrow('Run dsh-sdk build first')
   })
 
   it('invokes the target module main export and rejects passive modules', async () => {

From 394706fa3c30772ef703e27ebae0326e5bf8d5da Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 15 Jul 2026 23:08:06 +0800
Subject: [PATCH 46/48] fix(sdk): address remaining tooling review findings

---
 .../helper/src/documents/cordis-yaml-file.ts  |  6 +-
 .../src/documents/pnpm-workspace-file.ts      | 94 +++++++++++--------
 .../sdk/helper/src/features/builtin/index.ts  | 10 +-
 .../sdk/helper/src/features/define-feature.ts |  3 +
 packages/sdk/helper/src/features/resources.ts |  1 +
 .../src/project/project-edit-session.ts       | 34 ++++++-
 packages/sdk/helper/tests/documents.spec.ts   | 19 +++-
 packages/sdk/helper/tests/project.spec.ts     | 29 +++++-
 packages/sdk/scripts/src/build.ts             | 17 +++-
 .../sdk/scripts/src/config/config-workflow.ts | 16 ++++
 packages/sdk/scripts/src/runtime.ts           |  2 +-
 packages/sdk/scripts/tests/scripts.spec.ts    | 57 ++++++++++-
 12 files changed, 236 insertions(+), 52 deletions(-)

diff --git a/packages/sdk/helper/src/documents/cordis-yaml-file.ts b/packages/sdk/helper/src/documents/cordis-yaml-file.ts
index 2f00db5f80..39fd8fd596 100644
--- a/packages/sdk/helper/src/documents/cordis-yaml-file.ts
+++ b/packages/sdk/helper/src/documents/cordis-yaml-file.ts
@@ -135,9 +135,11 @@ export class CordisYamlFile extends ProjectFile {
   }
 
   /** Add one new top-level entry, rejecting duplicate ids. */
-  addEntry(entry: CordisConfigEntry): void {
+  addEntry(entry: CordisConfigEntry, commentedExample?: string): void {
     if (this.entryNode(entry.id)) throw new Error(`Cordis config entry already exists: ${entry.id}`)
-    this.sequence().items.push(this.document.createNode(entry))
+    const node = this.document.createNode(entry)
+    if (commentedExample) node.comment = commentedExample.split('\n').map(line => ` ${line}`).join('\n')
+    this.sequence().items.push(node)
   }
 
   /** Remove an entry by id and report whether it existed. */
diff --git a/packages/sdk/helper/src/documents/pnpm-workspace-file.ts b/packages/sdk/helper/src/documents/pnpm-workspace-file.ts
index 6e2cb25243..b980434bad 100644
--- a/packages/sdk/helper/src/documents/pnpm-workspace-file.ts
+++ b/packages/sdk/helper/src/documents/pnpm-workspace-file.ts
@@ -4,73 +4,93 @@
  * @module @deepseek-ai/dsh-helper/documents/pnpm-workspace-file
  */
 
-import { parse, stringify } from 'yaml'
+import {
+  isMap, isScalar, isSeq, parseDocument,
+  type Document, type Scalar, type YAMLMap, type YAMLSeq,
+} from 'yaml'
 import { ProjectFile, withTrailingNewline } from './project-file.ts'
 
+function parseYaml(text: string): Document.Parsed {
+  const document = parseDocument(text, { keepSourceTokens: true, prettyErrors: true })
+  if (document.errors.length > 0) {
+    throw new Error(`invalid pnpm-workspace.yaml: ${document.errors.map(error => error.message).join('; ')}`)
+  }
+  if (!isMap(document.contents)) throw new Error('pnpm-workspace.yaml root must be an object')
+  return document
+}
+
 /** Generated pnpm-workspace.yaml model. */
 export class PnpmWorkspaceFile extends ProjectFile {
-  private readonly packages = new Set<string>()
-  private autoInstallPeers = true
+  private readonly document: Document.Parsed
 
-  private constructor(originalText?: string) {
+  private constructor(document: Document.Parsed, originalText?: string) {
     super('pnpm-workspace.yaml', originalText)
+    this.document = document
   }
 
   /** Create a pnpm workspace document. */
   static create(): PnpmWorkspaceFile {
-    return new PnpmWorkspaceFile()
-  }
-
-  /** Parse the workspace fields the SDK owns. */
-  static parse(text: string): PnpmWorkspaceFile {
-    const value: unknown = parse(text)
-    if (value === null || Array.isArray(value) || typeof value !== 'object') {
-      throw new Error('pnpm-workspace.yaml root must be an object')
-    }
-    const input = value as Record<string, unknown>
-    if (!Array.isArray(input.packages) || input.packages.some(item => typeof item !== 'string')) {
-      throw new Error('pnpm-workspace.yaml packages must be an array of strings')
-    }
-    const document = new PnpmWorkspaceFile(text)
-    for (const pattern of input.packages) document.packages.add(pattern as string)
-    if (input.autoInstallPeers !== undefined && typeof input.autoInstallPeers !== 'boolean') {
-      throw new Error('pnpm-workspace.yaml autoInstallPeers must be boolean')
-    }
-    document.autoInstallPeers = input.autoInstallPeers !== false
+    const document = new PnpmWorkspaceFile(parseYaml('{}\n'))
+    document.mapping().set('packages', document.document.createNode([]))
+    document.mapping().set('allowBuilds', document.document.createNode({ esbuild: true }))
     return document
   }
 
-  /** Clone workspace globs and peer-install policy. */
+  /** Parse the workspace fields the SDK owns while retaining all other YAML. */
+  static parse(text: string): PnpmWorkspaceFile {
+    const document = new PnpmWorkspaceFile(parseYaml(text), text)
+    document.packageSequence()
+    const autoInstallPeers = document.mapping().get('autoInstallPeers')
+    if (autoInstallPeers !== undefined && typeof autoInstallPeers !== 'boolean') {
+      throw new Error('pnpm-workspace.yaml autoInstallPeers must be boolean')
+    }
+    return document
+  }
+
+  /** Clone the complete comment-preserving workspace document. */
   override clone(): PnpmWorkspaceFile {
-    const clone = new PnpmWorkspaceFile(this.originalText)
-    for (const pattern of this.packages) clone.packages.add(pattern)
-    clone.autoInstallPeers = this.autoInstallPeers
-    return clone
+    return new PnpmWorkspaceFile(parseYaml(this.serialize()), this.originalText)
   }
 
   /** Add one package workspace glob. */
   addPackage(pattern: string): void {
-    this.packages.add(pattern)
+    const packages = this.packageSequence()
+    if (packages.items.some(item => item.value === pattern)) return
+    packages.add(this.document.createNode(pattern))
   }
 
   /** Disable registry peer auto-installation for live-link projects. */
   disableAutoInstallPeers(): void {
-    this.autoInstallPeers = false
+    this.mapping().set('autoInstallPeers', false)
   }
 
   /** Validate workspace globs. */
   override validate(): void {
-    for (const pattern of this.packages) {
+    for (const pattern of this.packageValues()) {
       if (pattern.trim().length === 0) throw new Error('pnpm workspace pattern must not be empty')
     }
   }
 
-  /** Serialize pnpm's workspace and peer policy. */
+  /** Serialize the workspace while retaining unknown settings and comments. */
   override serialize(): string {
-    return withTrailingNewline(stringify({
-      packages: [...this.packages].sort(),
-      ...this.autoInstallPeers ? {} : { autoInstallPeers: false },
-      allowBuilds: { esbuild: true },
-    }, { lineWidth: 0 }))
+    return withTrailingNewline(this.document.toString({ lineWidth: 0 }))
+  }
+
+  private mapping(): YAMLMap {
+    /* v8 ignore next -- parseYaml and create both establish a mapping root */
+    if (!isMap(this.document.contents)) throw new Error('pnpm-workspace.yaml root must be an object')
+    return this.document.contents
+  }
+
+  private packageSequence(): YAMLSeq<Scalar<string>> {
+    const packages = this.mapping().get('packages', true)
+    if (!isSeq(packages) || packages.items.some(item => !isScalar(item) || typeof item.value !== 'string')) {
+      throw new Error('pnpm-workspace.yaml packages must be an array of strings')
+    }
+    return packages as YAMLSeq<Scalar<string>>
+  }
+
+  private packageValues(): string[] {
+    return this.packageSequence().items.map(item => item.value)
   }
 }
diff --git a/packages/sdk/helper/src/features/builtin/index.ts b/packages/sdk/helper/src/features/builtin/index.ts
index abf4915f07..e8289bb971 100644
--- a/packages/sdk/helper/src/features/builtin/index.ts
+++ b/packages/sdk/helper/src/features/builtin/index.ts
@@ -55,7 +55,15 @@ export function createBuiltinRegistry(profile: ProjectProfile): FeatureRegistry
           label: 'Sandboxed executor',
           resources: [
             { kind: 'npm-cordis-config-entry', id: 'sandbox', package: '@deepseek-ai/dsh-sandbox-local' },
-            { kind: 'npm-cordis-config-entry', id: 'bash', package: '@deepseek-ai/dsh-bash-sandbox' },
+            {
+              kind: 'npm-cordis-config-entry',
+              id: 'bash',
+              package: '@deepseek-ai/dsh-bash-sandbox',
+              commentedExample: `Uncomment to allow writes under the project workspace.
+config:
+  mode: workspace-write
+  workspaceRoot: !!js process.cwd()`,
+            },
           ],
         },
       ],
diff --git a/packages/sdk/helper/src/features/define-feature.ts b/packages/sdk/helper/src/features/define-feature.ts
index 9fd6ced1d2..7c90a2853a 100644
--- a/packages/sdk/helper/src/features/define-feature.ts
+++ b/packages/sdk/helper/src/features/define-feature.ts
@@ -31,6 +31,7 @@ interface NpmCordisConfigEntrySpec {
   package: string
   config?: Readonly<Record<string, unknown>>
   ownedConfigKeys?: readonly string[]
+  commentedExample?: string
 }
 
 /** Relative or absolute file Cordis config entry with no NPM dependency. */
@@ -40,6 +41,7 @@ interface FileCordisConfigEntrySpec {
   path: string
   config?: Readonly<Record<string, unknown>>
   ownedConfigKeys?: readonly string[]
+  commentedExample?: string
 }
 
 /** Static complete file owned by one feature option. */
@@ -147,6 +149,7 @@ function resourcesFromSpec(spec: FeatureResourceSpec): ProjectResource[] {
             ...config ? { config } : {},
           },
           ownedConfigKeys: spec.ownedConfigKeys ?? Object.keys(config ?? {}),
+          ...spec.commentedExample ? { commentedExample: spec.commentedExample } : {},
           ...validateConfig ? { validateConfig } : {},
         },
       ]
diff --git a/packages/sdk/helper/src/features/resources.ts b/packages/sdk/helper/src/features/resources.ts
index 6528451e10..14b76db57a 100644
--- a/packages/sdk/helper/src/features/resources.ts
+++ b/packages/sdk/helper/src/features/resources.ts
@@ -31,6 +31,7 @@ export interface CordisConfigEntryResource {
   key: ResourceKey
   entry: CordisConfigEntry
   ownedConfigKeys: readonly string[]
+  commentedExample?: string
   validateConfig?: (config: Readonly<Record<string, unknown>>) => readonly string[]
 }
 
diff --git a/packages/sdk/helper/src/project/project-edit-session.ts b/packages/sdk/helper/src/project/project-edit-session.ts
index 4e47a5a53f..9b2c885ac5 100644
--- a/packages/sdk/helper/src/project/project-edit-session.ts
+++ b/packages/sdk/helper/src/project/project-edit-session.ts
@@ -19,7 +19,7 @@ import { EnvFile } from '../documents/env-file.ts'
 import { PackageJsonFile, type PackageManifest } from '../documents/package-json-file.ts'
 import { ProjectFile } from '../documents/project-file.ts'
 import { TsConfigFile } from '../documents/tsconfig-file.ts'
-import type { FeatureId, ResourceKey } from '../ids.ts'
+import { featureId, type FeatureId, type ResourceKey } from '../ids.ts'
 import { LinkWorkspace } from '../package-managers/link-workspace.ts'
 import type { LocalPluginBlueprint } from '../plugins/local-plugin-blueprint.ts'
 import type { FeatureSelection, ProjectProfile } from './types.ts'
@@ -390,7 +390,7 @@ export class ProjectEditSession implements FeatureProjectView {
       }
       case 'cordis-config-entry': {
         const current = this.cordis().entry(resource.entry.id)
-        if (!current) this.cordis().addEntry(resource.entry)
+        if (!current) this.cordis().addEntry(resource.entry, resource.commentedExample)
         else {
           if (current.name !== resource.entry.name) {
             throw new Error(`Cordis config entry ${resource.entry.id} is owned by ${current.name}, not ${resource.entry.name}`)
@@ -486,9 +486,17 @@ export class ProjectEditSession implements FeatureProjectView {
 
   private validateFinalState(): void {
     for (const document of this.documents.values()) document.validate()
+    const profile = this.finalProfile()
+    const view = this.projectView(profile)
     for (const feature of this.registry.all()) {
-      if (!feature.isApplicable(this.profile)) continue
-      const installation = feature.inspect(this)
+      const state = this.states.get(feature.id)
+      if (!feature.isApplicable(profile)) {
+        if (state?.state === 'enabled') {
+          throw new Error(`feature ${feature.id} is not available for ${profile.runInterface}`)
+        }
+        continue
+      }
+      const installation = feature.inspect(view)
       /* v8 ignore next 3 -- public domain commands assert feature consistency before final validation */
       if (installation.state === 'inconsistent') {
         throw new Error(`feature ${feature.id} is inconsistent: ${installation.diagnostics.join('; ')}`)
@@ -499,7 +507,7 @@ export class ProjectEditSession implements FeatureProjectView {
       }
       if (installation.state !== 'enabled' || !installation.selection) continue
       for (const requirement of feature.requirements(installation.selection)) {
-        const required = this.registry.get(requirement.id).inspect(this)
+        const required = this.registry.get(requirement.id).inspect(view)
         /* v8 ignore next 3 -- ensureRequirements establishes enabled requirements before contributions change */
         if (required.state !== 'enabled') {
           throw new Error(`feature ${feature.id} requires enabled ${requirement.id}`)
@@ -522,6 +530,22 @@ export class ProjectEditSession implements FeatureProjectView {
     }
   }
 
+  private finalProfile(): ProjectProfile {
+    const runInterface = this.states.get(featureId('app'))?.selection?.options[0]
+    if (runInterface !== 'acp' && runInterface !== 'stdio' && runInterface !== 'embed') return this.profile
+    return { ...this.profile, runInterface }
+  }
+
+  private projectView(profile: ProjectProfile): FeatureProjectView {
+    return {
+      profile,
+      cordisConfigEntries: () => this.cordisConfigEntries(),
+      packageManifest: () => this.packageManifest(),
+      hasDocument: path => this.hasDocument(path),
+      readEnvironment: (path, name) => this.readEnvironment(path, name),
+    }
+  }
+
   private async assertUnchanged(paths: readonly string[]): Promise<void> {
     for (const path of paths) {
       const source = this.source.document(path)
diff --git a/packages/sdk/helper/tests/documents.spec.ts b/packages/sdk/helper/tests/documents.spec.ts
index f71f016ab5..f5d3e13244 100644
--- a/packages/sdk/helper/tests/documents.spec.ts
+++ b/packages/sdk/helper/tests/documents.spec.ts
@@ -74,8 +74,11 @@ describe('structured project documents', () => {
 
   it('round-trips Cordis comments and !!js while editing owned fields', () => {
     const created = CordisYamlFile.create().clone()
-    created.addEntry({ id: 'created', name: 'created-package' })
+    created.addEntry({ id: 'created', name: 'created-package' }, `Uncomment this example.
+config:
+  value: true`)
     expect(created.serialize()).toMatch(/^- id: created/m)
+    expect(created.serialize()).toContain('  # Uncomment this example.\n  # config:\n  #   value: true')
     expect(created.serialize()).not.toMatch(/^\[/)
     const flow = CordisYamlFile.parse('[{ id: flow, name: flow-package, config: { root: ./flow } }]\n')
     expect(flow.serialize()).toContain('- id: flow\n  name: flow-package\n  config:\n    root: ./flow')
@@ -205,6 +208,20 @@ describe('structured project documents', () => {
     invalid.addPackage(' ')
     expect(() => { invalid.validate() }).toThrow('must not be empty')
     expect(PnpmWorkspaceFile.parse('packages: []\n').serialize()).not.toContain('autoInstallPeers')
+    const preserved = PnpmWorkspaceFile.parse(`# keep workspace settings
+packages:
+  - apps/*
+catalog:
+  react: ^19.0.0
+overrides:
+  legacy: modern
+`)
+    preserved.disableAutoInstallPeers()
+    const preservedText = preserved.clone().serialize()
+    expect(preservedText).toContain('# keep workspace settings')
+    expect(preservedText).toContain('catalog:\n  react: ^19.0.0')
+    expect(preservedText).toContain('overrides:\n  legacy: modern')
+    expect(preservedText).toContain('autoInstallPeers: false')
   })
 
   it('renders strict complete-file templates without escaping code text', () => {
diff --git a/packages/sdk/helper/tests/project.spec.ts b/packages/sdk/helper/tests/project.spec.ts
index e888d7854f..100d81d7b2 100644
--- a/packages/sdk/helper/tests/project.spec.ts
+++ b/packages/sdk/helper/tests/project.spec.ts
@@ -52,6 +52,7 @@ function request(
   extra: readonly FeatureSelection[] = [],
   plugins: readonly LocalPluginBlueprint[] = [],
   app: 'acp' | 'stdio' | 'embed' = 'stdio',
+  bash: 'local' | 'sandbox' = 'local',
 ): ProjectCreationRequest {
   return {
     name: 'test-agent',
@@ -61,7 +62,7 @@ function request(
     releaseVersion: '0.0.1',
     features: [
       selection('provider', ['deepseek'], { apiKey: 'test-key' }),
-      selection('bash', ['local']),
+      selection('bash', [bash]),
       selection('app', [app]),
       selection('persistence', ['jsonl']),
       ...extra,
@@ -203,6 +204,24 @@ describe('SdkProject and ProjectEditSession', () => {
     expect(committed.cordis.entry('stdio')).toBeUndefined()
   })
 
+  it('emits the sandbox workspace-write example as inactive Cordis config', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-sandbox-bash-'))
+    temporary.push(root)
+    const creation = request([], [], 'stdio', 'sandbox')
+    const project = SdkProject.create(root, creation)
+    const registry = createBuiltinRegistry(project.profile)
+    const edit = project.edit(registry)
+    for (const item of creation.features) edit.installFeature(registry.get(item.id), item)
+    await edit.commit()
+    const cordis = await readFile(join(root, 'cordis.yml'), 'utf8')
+    expect(cordis).toContain(`- id: bash
+  name: "@deepseek-ai/dsh-bash-sandbox"
+  # Uncomment to allow writes under the project workspace.
+  # config:
+  #   mode: workspace-write
+  #   workspaceRoot: !!js process.cwd()`)
+  })
+
   it('round-trips the custom pi-ai provider with explicit endpoint and default model', async () => {
     const root = await mkdtemp(join(tmpdir(), 'dsh-custom-provider-'))
     temporary.push(root)
@@ -285,6 +304,14 @@ describe('SdkProject and ProjectEditSession', () => {
       .toContain('missing package.json script dev')
   })
 
+  it('rejects enabled features that do not apply to the target app interface', async () => {
+    const project = await createCommitted([selection('ask-user', ['default'])])
+    const registry = createBuiltinRegistry(project.profile)
+    const edit = project.edit(registry)
+    edit.configureFeature(registry.get(featureId('app')), selection('app', ['embed']))
+    await expect(edit.commit()).rejects.toThrow('feature ask-user is not available for embed')
+  })
+
   it('supports disabled feature reconfiguration and rejects invalid state operations', async () => {
     const project = await createCommitted([selection('todo', ['default'])])
     const registry = createBuiltinRegistry(project.profile)
diff --git a/packages/sdk/scripts/src/build.ts b/packages/sdk/scripts/src/build.ts
index 4b83a24b71..025ac4b2ab 100644
--- a/packages/sdk/scripts/src/build.ts
+++ b/packages/sdk/scripts/src/build.ts
@@ -18,8 +18,23 @@ function hasLocalPluginPackages(root: string): boolean {
 }
 
 function hasTsdownConfig(root: string): boolean {
-  return ['tsdown.config.ts', 'tsdown.config.js', 'tsdown.config.mjs', 'tsdown.config.mts']
+  const hasConfigFile = [
+    'tsdown.config.ts', 'tsdown.config.mts', 'tsdown.config.cts',
+    'tsdown.config.js', 'tsdown.config.mjs', 'tsdown.config.cjs',
+    'tsdown.config.json',
+  ]
     .some(name => existsSync(resolve(root, name)))
+  if (hasConfigFile) return true
+  let manifestText: string
+  try {
+    manifestText = readFileSync(resolve(root, 'package.json'), 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+    throw error
+  }
+  const manifest: unknown = JSON.parse(manifestText)
+  return manifest !== null && !Array.isArray(manifest) && typeof manifest === 'object'
+    && Object.hasOwn(manifest, 'tsdown')
 }
 
 /**
diff --git a/packages/sdk/scripts/src/config/config-workflow.ts b/packages/sdk/scripts/src/config/config-workflow.ts
index 318ecd4ece..7d3d7ee43a 100644
--- a/packages/sdk/scripts/src/config/config-workflow.ts
+++ b/packages/sdk/scripts/src/config/config-workflow.ts
@@ -17,6 +17,7 @@ import {
   type NestedMultiSelectValue,
   type ProjectCommitResult,
   type PromptPort,
+  type RunInterface,
   type SdkProject,
 } from '@deepseek-ai/dsh-helper'
 import { DSH_SDK_TEMPLATES } from '../templates/dsh-sdk-templates.ts'
@@ -39,6 +40,14 @@ function sameOptions(left: readonly string[], right: readonly string[]): boolean
   return [...left].sort().join('\0') === [...right].sort().join('\0')
 }
 
+function targetRunInterface(
+  current: RunInterface,
+  desired: ReadonlyMap<string, NestedMultiSelectValue<string, string>>,
+): RunInterface {
+  const selected = desired.get('feature:app')?.choices[0]
+  return selected === 'acp' || selected === 'stdio' || selected === 'embed' ? selected : current
+}
+
 /** Reconcile one tree selection into domain commands, then review and commit once. */
 export class ConfigWorkflow {
   private readonly port: PromptPort
@@ -100,6 +109,13 @@ export class ConfigWorkflow {
       ],
     }))
     const desiredByTarget = new Map(desired.map(item => [item.value, item]))
+    const targetProfile = {
+      ...project.profile,
+      runInterface: targetRunInterface(project.profile.runInterface, desiredByTarget),
+    }
+    for (const feature of features) {
+      if (!feature.isApplicable(targetProfile)) desiredByTarget.delete(featureTarget(feature))
+    }
 
     for (const feature of features) {
       const installation = inspections.get(feature.id)
diff --git a/packages/sdk/scripts/src/runtime.ts b/packages/sdk/scripts/src/runtime.ts
index b25563bc07..426ac90e5b 100644
--- a/packages/sdk/scripts/src/runtime.ts
+++ b/packages/sdk/scripts/src/runtime.ts
@@ -109,7 +109,7 @@ export async function startSDK(
  * @returns target main result or live Cordis context.
  */
 export async function runSDK(
-  target: string | undefined,
+  target?: string,
   options: BootProjectOptions = {},
 ): Promise<unknown> {
   /* v8 ignore next -- the bin always supplies cwd; direct consumers normally accept process.cwd() */
diff --git a/packages/sdk/scripts/tests/scripts.spec.ts b/packages/sdk/scripts/tests/scripts.spec.ts
index 0ed3fed411..03e38b5c26 100644
--- a/packages/sdk/scripts/tests/scripts.spec.ts
+++ b/packages/sdk/scripts/tests/scripts.spec.ts
@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { PassThrough, Writable } from 'node:stream'
 import { fileURLToPath, pathToFileURL } from 'node:url'
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, expectTypeOf, it, vi } from 'vitest'
 import {
   LocalPluginBlueprint,
   NpmPackageManager,
@@ -82,6 +82,7 @@ function commandContext(cwd: string): DshSdkCommandContext & { readStdout: () =>
 function creation(
   extra: ProjectCreationRequest['features'] = [],
   localPlugins: readonly LocalPluginBlueprint[] = [],
+  app: 'acp' | 'stdio' | 'embed' = 'embed',
 ): ProjectCreationRequest {
   return {
     name: 'config-agent',
@@ -92,7 +93,7 @@ function creation(
     features: [
       { id: featureId('provider'), options: ['deepseek'], secrets: { apiKey: 'key' } },
       { id: featureId('bash'), options: ['local'] },
-      { id: featureId('app'), options: ['embed'] },
+      { id: featureId('app'), options: [app] },
       { id: featureId('persistence'), options: ['jsonl'] },
       ...extra,
     ],
@@ -103,10 +104,11 @@ function creation(
 async function committedProject(
   extra: ProjectCreationRequest['features'] = [],
   localPlugins: readonly LocalPluginBlueprint[] = [],
+  app: 'acp' | 'stdio' | 'embed' = 'embed',
 ): Promise<SdkProject> {
   const root = await mkdtemp(join(tmpdir(), 'dsh-config-workflow-'))
   temporary.push(root)
-  const request = creation(extra, localPlugins)
+  const request = creation(extra, localPlugins, app)
   const project = SdkProject.create(root, request)
   const registry = createBuiltinRegistry(project.profile)
   const edit = project.edit(registry)
@@ -219,6 +221,33 @@ describe('build profiles and invocation', () => {
     await expect(runProjectBuild([], root, killed)).rejects.toThrow('killed by SIGTERM')
   })
 
+  it('recognizes every tsdown config source', async () => {
+    const manifest = fileURLToPath(import.meta.resolve('tsdown/package.json'))
+    for (const extension of ['cts', 'cjs', 'json']) {
+      const root = await mkdtemp(join(tmpdir(), `dsh-build-${extension}-`))
+      temporary.push(root)
+      await writeFile(join(root, 'package.json'), '{"type":"module"}\n')
+      await writeFile(join(root, `tsdown.config.${extension}`), '{}\n')
+      await mkdir(join(root, 'node_modules'), { recursive: true })
+      await symlink(dirname(manifest), join(root, 'node_modules', 'tsdown'))
+      let called = false
+      await runProjectBuild([], root, {
+        run: async () => { called = true; return { exitCode: 0, signal: null } },
+      })
+      expect(called).toBe(true)
+    }
+    const root = await mkdtemp(join(tmpdir(), 'dsh-build-package-json-'))
+    temporary.push(root)
+    await writeFile(join(root, 'package.json'), '{"type":"module","tsdown":{}}\n')
+    await mkdir(join(root, 'node_modules'), { recursive: true })
+    await symlink(dirname(manifest), join(root, 'node_modules', 'tsdown'))
+    let called = false
+    await runProjectBuild([], root, {
+      run: async () => { called = true; return { exitCode: 0, signal: null } },
+    })
+    expect(called).toBe(true)
+  })
+
   it('reports missing and malformed project tsdown executables', async () => {
     const missing = await mkdtemp(join(tmpdir(), 'dsh-build-missing-'))
     temporary.push(missing)
@@ -279,6 +308,7 @@ describe('build profiles and invocation', () => {
   })
 
   it('boots empty Cordis configs and delegates targetless runs', async () => {
+    expectTypeOf(runSDK).toBeCallableWith()
     const root = await mkdtemp(join(tmpdir(), 'dsh-start-sdk-'))
     temporary.push(root)
     await writeFile(join(root, 'cordis.yml'), '[]\n')
@@ -480,4 +510,25 @@ describe('ConfigWorkflow', () => {
     expect(result.commit?.project.cordis.entry('agent-loop')).toBeDefined()
     expect(result.commit?.project.cordis.entry('agent-core')).toBeUndefined()
   })
+
+  it('disables ask-user when switching its app interface to embed', async () => {
+    const project = await committedProject([
+      { id: featureId('ask-user'), options: ['default'] },
+    ], [], 'acp')
+    const registry = createBuiltinRegistry(project.profile)
+    const output = outputBuffer()
+    const workflow = new ConfigWorkflow(new QueuePort([
+      [
+        { value: 'feature:provider', choices: ['deepseek'] },
+        { value: 'feature:app', choices: ['embed'] },
+        { value: 'feature:persistence', choices: ['jsonl'] },
+        { value: 'feature:ask-user', choices: ['default'] },
+      ],
+      true,
+    ]), output.stream, async () => {})
+    const result = await workflow.run(project, registry)
+    expect(result.commit?.project.profile.runInterface).toBe('embed')
+    expect(result.commit?.project.cordis.entry('tool-ask-user')?.disabled).toBe(true)
+    expect(output.read()).toContain('Disable feature: ask-user')
+  })
 })

From 8f9c13ffaa3af84e6b7fd05450dc1050a8776025 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 15 Jul 2026 23:26:40 +0800
Subject: [PATCH 47/48] test(sdk): restore tooling coverage

---
 packages/sdk/helper/tests/documents.spec.ts | 4 ++++
 packages/sdk/helper/tests/project.spec.ts   | 4 ++++
 packages/sdk/scripts/tests/scripts.spec.ts  | 4 ++++
 3 files changed, 12 insertions(+)

diff --git a/packages/sdk/helper/tests/documents.spec.ts b/packages/sdk/helper/tests/documents.spec.ts
index f5d3e13244..1ba8b9bd68 100644
--- a/packages/sdk/helper/tests/documents.spec.ts
+++ b/packages/sdk/helper/tests/documents.spec.ts
@@ -196,12 +196,16 @@ config:
   it('creates and parses pnpm workspace policy', () => {
     const document = PnpmWorkspaceFile.create()
     document.addPackage('plugins/*')
+    document.addPackage('plugins/*')
     document.disableAutoInstallPeers()
     document.validate()
     expect(document.serialize()).toContain('autoInstallPeers: false')
     const parsed = PnpmWorkspaceFile.parse(document.serialize())
     expect(parsed.clone().serialize()).toBe(document.serialize())
+    expect(() => PnpmWorkspaceFile.parse('packages: [')).toThrow('invalid pnpm-workspace.yaml')
     expect(() => PnpmWorkspaceFile.parse('packages: nope')).toThrow('packages must be an array')
+    expect(() => PnpmWorkspaceFile.parse('packages: [{}]')).toThrow('packages must be an array')
+    expect(() => PnpmWorkspaceFile.parse('packages: [1]')).toThrow('packages must be an array')
     expect(() => PnpmWorkspaceFile.parse('[]')).toThrow('root must be an object')
     expect(() => PnpmWorkspaceFile.parse('packages: []\nautoInstallPeers: nope')).toThrow('must be boolean')
     const invalid = PnpmWorkspaceFile.create()
diff --git a/packages/sdk/helper/tests/project.spec.ts b/packages/sdk/helper/tests/project.spec.ts
index 100d81d7b2..d55bb16be9 100644
--- a/packages/sdk/helper/tests/project.spec.ts
+++ b/packages/sdk/helper/tests/project.spec.ts
@@ -419,9 +419,11 @@ describe('SdkProject and ProjectEditSession', () => {
     const edit = project.edit(registry)
     type Internals = {
       documents: Map<string, TextProjectFile>
+      states: Map<ReturnType<typeof featureId>, unknown>
       applyResource(resource: ProjectResource, previous: ProjectResource | undefined): void
       removeResource(resource: ProjectResource): void
       replaceContribution(previous: ProjectContribution | undefined, next: ProjectContribution): void
+      finalProfile(): ProjectProfile
       manifest(): unknown
       cordis(): unknown
       environment(path: '.env' | '.env.example'): unknown
@@ -508,6 +510,8 @@ describe('SdkProject and ProjectEditSession', () => {
       override readonly options = []
     }
     expect(() => { internals.state(new Foreign()) }).toThrow('not applicable')
+    internals.states.delete(featureId('app'))
+    expect(internals.finalProfile()).toBe(project.profile)
     const sourceDocuments = (project as unknown as { documents: Map<string, TextProjectFile> }).documents
     sourceDocuments.set('.env', new TextProjectFile('.env', 'bad'))
     expect(() => project.readEnvironment('.env', 'KEY')).toThrow('not an environment document')
diff --git a/packages/sdk/scripts/tests/scripts.spec.ts b/packages/sdk/scripts/tests/scripts.spec.ts
index 03e38b5c26..8d110799ea 100644
--- a/packages/sdk/scripts/tests/scripts.spec.ts
+++ b/packages/sdk/scripts/tests/scripts.spec.ts
@@ -289,6 +289,10 @@ describe('build profiles and invocation', () => {
     let called = false
     await runProjectBuild([], root, { run: async () => { called = true; return { exitCode: 0, signal: null } } })
     expect(called).toBe(false)
+    const unreadableManifest = await mkdtemp(join(tmpdir(), 'dsh-build-unreadable-manifest-'))
+    temporary.push(unreadableManifest)
+    await mkdir(join(unreadableManifest, 'package.json'))
+    await expect(runProjectBuild([], unreadableManifest)).rejects.toThrow()
     await expect(runSDK('index.js', { cwd: root })).rejects.toThrow('Run dsh-sdk build first')
   })
 

From 7250aaea7eabbe4de1a32075f4f785870d38e5c2 Mon Sep 17 00:00:00 2001
From: Hypatia May <hypatiamay@outlook.com>
Date: Thu, 16 Jul 2026 10:07:11 +0800
Subject: [PATCH 48/48] fix(sdk): compose token meter for compact projects

---
 docs/architecture.md             |  6 +++---
 packages/sdk/helper/package.json |  1 -
 pnpm-lock.yaml                   | 32 +++++++++++++++-----------------
 3 files changed, 18 insertions(+), 21 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index b5dc852a6b..63a5f07a61 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -24,7 +24,7 @@ A harness is one [Cordis](cordis-primer.md) context. Packages contribute service
 | ctx key | Package family | Role |
 |---|---|---|
 | `ctx.llm` | [`llm/`](../packages/llm/README.md) | adapter registry and streaming model calls |
-| `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | replay-aware per-model request and surface pressure |
+| `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | replay-aware request/surface pressure per model |
 | `ctx.bash` | [`bash/`](../packages/bash/README.md) | foreground/background command execution |
 | `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | same-world process confinement (argv wrapping, per-call policy) |
 | `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | model-written program execution |
@@ -82,7 +82,7 @@ forever:
       agent/request (config only) -> log request/header -> llm/stream (frozen)
         'assistant/chunk'
       agent/step-result
-      'assistant/message' (transformed content, or an empty successful-call anchor if step-result rejects)
+      'assistant/message' (transformed content or empty success anchor after step-result rejection)
       each tool call:
         'tool/call'
         tools/pre-execute -> monotonic guards -> tools/execute -> tools/post-execute -> tools/result
@@ -126,7 +126,7 @@ Durability is a plugin concern. Persistence backends buffer synchronous `session
 
 ### Model Content
 
-Messages are arrays of typed content blocks (`text`, `reasoning`, `tool-call`, `tool-result`). The union derives from the merge-extensible `ContentBlockMap`; the same pattern types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New block types are coordinated across adapters, UI bridges, token metering, and persistence, so block types remain a repo-wide contract. Replay measurement types are cataloged in [token-meter.md](core-data-structures/token-meter.md).
+Messages are arrays of typed content blocks (`text`, `reasoning`, `tool-call`, `tool-result`). The union derives from the merge-extensible `ContentBlockMap`; the same pattern types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New block types require coordinated adapter, UI, token-meter, and persistence changes; replay measurement types live in [token-meter.md](core-data-structures/token-meter.md).
 
 Streaming is a raw chunk protocol (`block-start` through `finish`) with `BlockAssembler` as the shared chunk-to-block assembler. The loop logs raw chunks while assembling them for dispatch. `LlmAdapter` is the provider seam: subclass, implement `stream()`, and register with `ctx.llm.registerAdapter(models, adapter)`. StreamChunk conventions live in [llm-streaming.md](core-data-structures/llm-streaming.md).
 
diff --git a/packages/sdk/helper/package.json b/packages/sdk/helper/package.json
index 1452a1dbee..8d95dafe66 100644
--- a/packages/sdk/helper/package.json
+++ b/packages/sdk/helper/package.json
@@ -33,7 +33,6 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
-    "@deepseek-ai/dsh-compact-basic": "workspace:^",
     "@deepseek-ai/dsh-hooks-claude": "workspace:^",
     "@deepseek-ai/dsh-hooks-codex": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0440d83eb0..334a95346d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -832,7 +832,7 @@ importers:
     dependencies:
       '@earendil-works/pi-ai':
         specifier: ^0.79.1
-        version: 0.79.3(ws@8.21.0)(zod@4.4.3)
+        version: 0.79.3(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.21.0)(zod@4.4.3)
       schemastery:
         specifier: ^3.18.0
         version: 3.18.0
@@ -953,9 +953,6 @@ importers:
       '@deepseek-ai/dsh-brand':
         specifier: workspace:^
         version: link:../../util/brand
-      '@deepseek-ai/dsh-compact-basic':
-        specifier: workspace:^
-        version: link:../../compact/compact-basic
       '@deepseek-ai/dsh-hooks-claude':
         specifier: workspace:^
         version: link:../../hooks/hooks-claude
@@ -3091,6 +3088,10 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@pkgjs/parseargs@0.11.0':
+    resolution: {integrity: sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==}
+    engines: {node: '>=14'}
+
   '@protobufjs/aspromise@1.1.2':
     resolution: {integrity: sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==}
 
@@ -5557,11 +5558,6 @@ packages:
     engines: {node: '>=14.17'}
     hasBin: true
 
-  uglify-js@3.19.3:
-    resolution: {integrity: sha512-v3Xu+yuwBXisp6QYTcH4UbH+xYJXqnq2m/LtQVWKWzYc1iehYnLixoQDN9FH6/j9/oybfd6W9Ghwkl8+UMKTKQ==}
-    engines: {node: '>=0.8.0'}
-    hasBin: true
-
   unbash@3.0.0:
     resolution: {integrity: sha512-FeFPZ/WFT0mbRCuydiZzpPFlrYN8ZUpphQKoq4EeElVIYjYyGzPMxQR/simUwCOJIyVhpFk4RbtyO7RuMpMnHA==}
     engines: {node: '>=14'}
@@ -6169,11 +6165,11 @@ snapshots:
 
   '@csstools/css-tokenizer@4.0.0': {}
 
-  '@earendil-works/pi-ai@0.79.3(ws@8.21.0)(zod@4.4.3)':
+  '@earendil-works/pi-ai@0.79.3(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(ws@8.21.0)(zod@4.4.3)':
     dependencies:
       '@anthropic-ai/sdk': 0.91.1(zod@4.4.3)
       '@aws-sdk/client-bedrock-runtime': 3.1048.0
-      '@google/genai': 1.52.0
+      '@google/genai': 1.52.0(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))
       '@mistralai/mistralai': 2.2.1
       '@smithy/node-http-handler': 4.7.3
       http-proxy-agent: 7.0.2
@@ -6331,12 +6327,14 @@ snapshots:
 
   '@exodus/bytes@1.15.1': {}
 
-  '@google/genai@1.52.0':
+  '@google/genai@1.52.0(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))':
     dependencies:
       google-auth-library: 10.7.0
       p-retry: 4.6.2
       protobufjs: 7.6.4
       ws: 8.21.0
+    optionalDependencies:
+      '@modelcontextprotocol/sdk': 1.29.0(zod@4.4.3)
     transitivePeerDependencies:
       - bufferutil
       - supports-color
@@ -6595,6 +6593,9 @@ snapshots:
   '@oxc-resolver/binding-win32-x64-msvc@11.20.0':
     optional: true
 
+  '@pkgjs/parseargs@0.11.0':
+    optional: true
+
   '@protobufjs/aspromise@1.1.2': {}
 
   '@protobufjs/base64@1.1.2': {}
@@ -7959,8 +7960,6 @@ snapshots:
       neo-async: 2.6.2
       source-map: 0.6.1
       wordwrap: 1.0.0
-    optionalDependencies:
-      uglify-js: 3.19.3
 
   has-flag@4.0.0: {}
 
@@ -8066,6 +8065,8 @@ snapshots:
   jackspeak@3.4.3:
     dependencies:
       '@isaacs/cliui': 8.0.2
+    optionalDependencies:
+      '@pkgjs/parseargs': 0.11.0
 
   jiti@2.7.0: {}
 
@@ -9306,9 +9307,6 @@ snapshots:
 
   typescript@6.0.3: {}
 
-  uglify-js@3.19.3:
-    optional: true
-
   unbash@3.0.0: {}
 
   unconfig-core@7.5.0: