Merge remote-tracking branch 'origin/master' into codex/agent-session-jsonl-location

# Conflicts: # docs/architecture.md # docs/capability-seams.md # docs/config-catalog.md # docs/cordis-catalog/services.md # docs/core-data-structures/bash.md # docs/module-graph.md # docs/tool-catalog.md # examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md # examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json # examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.golden.md # examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.golden.json # examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.golden.md # examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.golden.json # examples/acp-agent/tests/snapshots/skill-load/tool-schemas.golden.json # examples/acp-agent/tests/snapshots/text-turn/tool-schemas.golden.json # examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.golden.json # packages/bash/bash-local/README.md # packages/bash/bash-local/src/index.ts # packages/bash/bash-local/tests/executor.spec.ts # packages/bash/bash/README.md # packages/bash/bash/src/index.ts # packages/bash/bash/src/types.ts # packages/bash/tool-bash/README.md # packages/bash/tool-bash/package.json # packages/bash/tool-bash/src/index.ts # packages/bash/tool-bash/tests/tools.spec.ts # packages/bash/tool-bash/tsconfig.json # packages/cordis/tool-cordis/src/api-catalog.ts # packages/examples/agent-spine-demo/README.md # packages/examples/agent-spine-demo/src/index.ts # packages/examples/agent-spine-demo/tests/agent-core.spec.ts # pnpm-lock.yaml
2026-07-16 16:45:52 +08:00
parent 1094748bec 4139e093dd
commit 027af418a2
243 changed files with 17079 additions and 2872 deletions
--- a/packages/bash/bash-local/README.md
+++ b/packages/bash/bash-local/README.md
@@ -23,13 +23,12 @@ Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi;

 - **Spawn per call, no shell state** — every call is a fresh non-login `bash -c` (deterministic; no rc files). All four surveyed tools spawn per call. `XXX(stateful-shell)` in `src/run.ts` records the two proven stateful designs (Claude Code's cwd-only persistence; Codex's PTY exec sessions) for when real workflows demand them.
 - **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 environment** — ambient credentials and all `DSH_*` names are removed before noninteractive terminal defaults and ordinary caller `env` are applied. Ordinary `env` rejects `DSH_*`; managed `dshEnv` rejects other names and merges last, preventing stale nested-harness identity. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment RFC](../../../docs/rfc/implemented/feature/2026-07-10-agent-session-identity-and-log-location.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.
+- **Model-friendly env + credential scrub** — `process.env` minus credential-shaped vars (`*KEY*`/`*SECRET*`/`*TOKEN*`) and all ambient `DSH_*` names, then `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` (Codex's hardcoded set) so pagers and ANSI color don't garble results. A spec's ordinary `env` is merged after the scrub but rejects `DSH_*`; managed `dshEnv` rejects ordinary names and merges last, preventing stale nested-harness identity. Supplied stdin is written and closed; otherwise fd 0 is `/dev/null`. See the [stdin/env RFC](../../../docs/rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment RFC](../../../docs/rfc/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
+- **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.

 ## Model Experience

-Indirectly, through `dsh-tool-bash`, which renders this executor's bounded stdout/stderr tails, background-task deltas and state, spill-file path, exact `Error: unknown bash task "<taskId>"` and `Error: aborted before spawn: <reason>` failures, and retains each resulting tool message until compaction.
+Indirectly, through `dsh-tool-bash`, which renders this executor's bounded stdout/stderr tails, background-process deltas, spill-file paths, and infrastructure failures.

 ## Known Limitations and Deferred Work

@@ -38,6 +37,5 @@ Indirectly, through `dsh-tool-bash`, which renders this executor's bounded stdou
 - **POSIX-only** — the `bash` binary, detached process groups, group kills, and SIGTERM→SIGKILL escalation are hardcoded; Windows is unsupported.
 - **The credential scrub is a name heuristic** — `*KEY*`/`*SECRET*`/`*TOKEN*` only; differently-named secrets (e.g. `*PASSWORD*`) pass through, and a whitelist for over-scrubbed vars is noted future work.
 - **Spill files are never deleted** — full-output recovery files (and the private per-process spill dir) accumulate under the OS tmpdir until something external cleans them.
- **Finished background tasks are never evicted** — they stay in the task map, retaining their in-memory output tails, until executor disposal.

 The raw process handling lives in `src/run.ts`; `src/index.ts` is the service wiring.
--- a/packages/bash/bash-local/src/index.ts
+++ b/packages/bash/bash-local/src/index.ts
@@ -1,15 +1,14 @@
 /**
- * Local-subprocess implementation of the bash seam. Each call runs in its own
- * process group, background tasks are tracked, and disposal kills and awaits
- * them. Execution policy belongs in `tools/pre-execute` or a sandboxing
- * executor, not this local process layer.
+ * 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
 */

 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 { clampTimeout, deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
 import { DEFAULT_GRACE_MS, runBash } from './run.ts'
 import type { RunInternals, RunningBash } from './run.ts'
@@ -37,20 +36,9 @@ 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
- * 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,8 +49,8 @@ export class LocalBashExecutor extends BashExecutor {
    graceMs: z.number().default(DEFAULT_GRACE_MS),
  })

-  private tasks = new Map<BashTaskId, TrackedTask>()
-  private nextTaskId = 1
+  /** 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 = {}

@@ -71,26 +59,21 @@ 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 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')
  }
@@ -119,9 +102,6 @@ export class LocalBashExecutor extends BashExecutor {
      ...request.stdin !== undefined ? { stdin: request.stdin } : {},
      ...request.env !== undefined ? { env: request.env } : {},
      ...request.dshEnv !== undefined ? { dshEnv: request.dshEnv } : {},
-      // 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,
      // Carry a sandbox-mode override through verbatim: this executor never
      // confines, so the field is inert here (the seam contract) — a
      // sandboxing subclass overrides resolve() to stamp its default instead.
@@ -130,9 +110,7 @@ export class LocalBashExecutor extends BashExecutor {
  }

  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,
@@ -144,18 +122,14 @@ export class LocalBashExecutor extends BashExecutor {
      env: spec.env,
      dshEnv: spec.dshEnv,
    }, 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): 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).
+  start(spec: BashExecSpec): BashProcess {
+    // Background runs ignore timeoutMs; callers stop them through kill() or spec.signal.
    const running = runBash({
      command: spec.command,
      cwd: spec.workdir,
@@ -167,93 +141,66 @@ export class LocalBashExecutor extends BashExecutor {
      dshEnv: spec.dshEnv,
    }, this.internals)

-    const id = BashTaskId(`bash-${this.nextTaskId++}`)
-    const task: TrackedTask = {
-      id,
+    let stdoutOffset = 0
+    let stderrOffset = 0
+    const proc: BashProcess = {
      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. Background runs
-        // forward only the upstream signal (no timeout), so its aborted state
-        // is the authoritative "was this cancelled" signal.
-        if (task.status === 'running') task.status = spec.signal?.aborted === true ? 'killed' : 'completed'
-        task.exitCode = outcome.exitCode
-        task.signal = outcome.signal
-        this.notifyTaskDone(task)
+        // 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'
+        }
+        proc.exitCode = outcome.exitCode
+        proc.signal = outcome.signal
+        this.onProcessDone(proc, running.stderr.readFrom(0).text)
+        this.live.delete(proc)
      }, (error: unknown) => {
-        // Spawn-level failure (bad workdir, …): the task never ran. String()
-        // suffices — runBash only rejects with Error instances.
-        task.status = 'killed'
-        task.running.stderr.push(Buffer.from(`spawn failed: ${String(error)}`))
-        this.notifyTaskDone(task)
+        // 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)
+        this.live.delete(proc)
      }),
-    }
-    this.tasks.set(id, task)
-    return task
-  }
+      readOutput: (): BashProcessRead => {
+        const out = running.stdout.readFrom(stdoutOffset)
+        const err = running.stderr.readFrom(stderrOffset)
+        stdoutOffset = out.nextOffset
+        stderrOffset = err.nextOffset

-  get(id: BashTaskId): BashTask | undefined {
-    return this.tasks.get(id)
+        // 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.live.set(proc, running)
+    return proc
  }

  /**
-   * Full collected stderr of a tracked task from stream start (bounded by the
-   * in-memory cap; bytes only in the spill file are not re-read). A protected
-   * seam for subclasses that classify a settled task's outcome — reading here
-   * does NOT advance the consumer's {@link readOutput} cursor. An unknown id
-   * (a task already dropped by disposal) reads as empty.
+   * Settlement hook for subclasses that attach execution facts to a process.
+   * 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 _stderr - the process's retained stderr tail used by subclasses for settlement classification.
   */
-  protected collectedStderr(id: BashTaskId): string {
-    const task = this.tasks.get(id)
-    return task === undefined ? '' : task.running.stderr.readFrom(0).text
-  }
-
-  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
-  }
+  protected onProcessDone(_proc: BashProcess, _stderr: string): void {}
 }

 export default LocalBashExecutor
--- 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,36 +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
-  let delta = ''
-  while (Date.now() < deadline) {
-    last = bash.readOutput(id)
-    delta += last.delta
-    if (delta.includes(expected)) return { ...last, delta }
-    await new Promise(resolve => setTimeout(resolve, 20))
-  }
-  throw new Error(`task ${id} output did not include ${JSON.stringify(expected)}; output was ${JSON.stringify(delta)}, 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', () => {
@@ -90,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; echo ready; while :; do sleep 60 & wait $!; done' }))
-    await readUntil(bash, task.id, 'ready\n')
-    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 }))
@@ -161,230 +135,184 @@ 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.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, ordinary env, and managed 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 "[$BG_VAR][$DSH_BG_VAR]"',
      stdin: 'bg-stdin\n',
      env: { BG_VAR: 'bg-env' },
      dshEnv: { DSH_BG_VAR: 'bg-dsh-env' },
    }))
-    const read = await readUntil(bash, task.id, '[bg-env][bg-dsh-env]')
-    expect(read.delta).toContain('bg-stdin')
-    await task.done
-    expect(task.exitCode).toBe(0)
+    const output = await readUntil(proc, '[bg-env][bg-dsh-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 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' }))
+    // 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('executor cancellation, callback, and disposal contracts', () => {
-  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')
  })
 })