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

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

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

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

packages/bash/bash/tsconfig.json

@@ -13,9 +13,6 @@
     },
     {
       "path": "../../../vendor/cordis"
-    },
-    {
-      "path": "../../util/brand"
     }
   ]
 }