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.

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

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