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.

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

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