refactor(process): split the process manager out of the bash executor

New process/ capability family: @deepseek-ai/dsh-process owns ctx.processes —
abstract ProcessManager.spawn(spec) over a fully-explicit ProcessSpawnSpec —
plus the shared DSH_* managed-environment and CollectedOutput vocabulary;
@deepseek-ai/dsh-process-local carries the former bash-local run.ts plumbing
(detached groups, tail-keep spill-backed output, credential scrub, kill
escalation, kill-and-join disposal) with no config of its own.

dsh-bash-local becomes a consumer: it keeps command defaulting, the fused
deadline timedOut/aborted classification, the model-friendly terminal env
(now merged through the ordinary env channel), and the [stderr]-marked
background read merge, and spawns through ctx.processes. Background-process
lifetime moves to the manager, so an executor reload no longer kills live
background work; a background spawn failure is injected once into the read
path instead of being buffered as fake stderr. dsh-bash re-exports the moved
vocabulary so bash consumers keep one import root; dsh-bash-sandbox only
redeclares the inherited inject.

Every composition loading a bash executor now loads dsh-process-local (CLI,
examples, python bundled runtime, create-sdk bash feature, inline test
configs).

packages/bash/bash-local/README.md

@@ -1,8 +1,8 @@
 # @deepseek-ai/dsh-bash-local
 
-Local-subprocess implementation of the `@deepseek-ai/dsh-bash` executor seam: `LocalBashExecutor` spawns `bash -c <command>` per call in its own process group, collects bounded output with size-limited full-stream spill files, and escalates kills SIGTERM→SIGKILL across the whole group.
+Local implementation of the `@deepseek-ai/dsh-bash` executor seam over the [`@deepseek-ai/dsh-process`](../../process/process/README.md) manager: `LocalBashExecutor` spawns `bash -c <command>` per call as a managed process group through `ctx.processes`, and owns everything bash-shaped — command defaulting and caps, timeout/cancel classification, the model-friendly terminal environment, and the model-facing stdout/stderr merge for background reads. Group mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) are the process manager's.
 
-The package root exports the default and named `LocalBashExecutor` plugin plus its `Config`; subprocess plumbing stays internal to the implementation package.
+The package root exports the default and named `LocalBashExecutor` plugin plus its `Config`.
 
 ## Config
 
@@ -22,11 +22,11 @@ The package root exports the default and named `LocalBashExecutor` plugin plus i
 
 Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi; the notable choices:
 
-- **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). After the main shell exits, inherited stdout/stderr pipes receive the same bounded drain grace so a surviving descendant cannot hold the command open indefinitely. ESRCH is tolerated; daemons that re-parent away from the group can still survive — same caveat as the surveyed tools.
-- **Tail-keep truncation + bounded 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. A foreground `BashExecRequest.stdoutMaxBytes` can raise stdout's capture budget for one trusted caller; stderr and background tasks still use `maxOutputBytes`. A stream larger than `maxSpillBytes` discards its now-incomplete spill and returns only the marked truncated tail. If the final spill close reports a delayed writeback failure, the executor likewise withholds the path rather than advertising an incomplete file.
-- **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 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/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.
+- **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/index.ts` records the two proven stateful designs (Claude Code's cwd-only persistence; Codex's PTY exec sessions) for when real workflows demand them.
+- **Configured budgets over managed groups** — `resolve()` fills `workdir`/`timeoutMs`/`stdoutMaxBytes` from config, and every spawn hands the manager explicit byte caps, spill cap, and `graceMs` (default 3s — OpenCode's escalation). Process-group kills, the post-exit pipe-drain grace, tail-keep truncation, and bounded spill files are [`dsh-process-local`](../../process/process-local/README.md) mechanics. A foreground `BashExecRequest.stdoutMaxBytes` can raise stdout's capture budget for one trusted caller; stderr and background runs still use `maxOutputBytes`.
+- **Timeout and cancel classification** — `run()` fuses its config-clamped timeout with the caller's signal through one deadline; only the executor's own timeout reports `timedOut`, an upstream cancel reports `aborted`, and a self-signaled command reports neither ([timeout-library Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
+- **Model-friendly terminal env** — `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` (Codex's hardcoded set) so pagers and ANSI color don't garble results, merged as ordinary env under the manager's credential scrub and `DSH_*` channel rules; an explicit caller entry still wins. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/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), and the handle's `readOutput()` merges the manager's offset-based stdout/stderr reads into one marked-section delta with a consuming cursor. A still-running process belongs to the manager, so it survives executor reloads and dies (killed and joined) with the manager's disposal. 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
 
@@ -40,8 +40,7 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 - **Unconfined by itself** — this executor always runs commands with the harness process's authority; deployments needing confinement compose [`dsh-bash-sandbox`](../bash-sandbox/README.md), while per-call allow/deny/ask policy belongs on `tools/pre-execute`.
 - **No persistent shell or PTY** — every call starts a fresh non-login `bash -c`; cwd-only persistence and interactive terminal sessions remain deferred until a real workflow requires them.
-- **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.
-- **Completed spill files are not deleted** — bounded full-output recovery files (and the private per-process spill dir) accumulate under the OS tmpdir until something external cleans them; oversize incomplete spills are discarded and deletion is attempted immediately, but a cleanup failure can leave a bounded file behind.
+- **POSIX-only** — the `bash` binary is hardcoded, and the underlying manager's group semantics are POSIX; Windows is unsupported.
+- **A background spawn-failure note is single-delivery** — the manager buffers no output for a process that never ran, so the executor injects `spawn failed: …` into exactly one `readOutput()` delta; a reader that discards that delta cannot recover it.
 
-The raw process handling lives in `src/run.ts`; `src/index.ts` is the service wiring.
+Scrub-heuristic and spill-retention caveats live with [`dsh-process-local`](../../process/process-local/README.md), which owns those mechanics.

packages/bash/bash-local/package.json

@@ -29,6 +29,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-bash": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-process": "^0.0.1",
     "@deepseek-ai/dsh-timeout": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
@@ -38,6 +39,8 @@
   "devDependencies": {
     "@deepseek-ai/dsh-bash": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-process": "workspace:^",
+    "@deepseek-ai/dsh-process-local": "workspace:^",
     "@deepseek-ai/dsh-timeout": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }

packages/bash/bash-local/src/index.ts

@@ -1,7 +1,10 @@
 /**
- * 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.
+ * Local implementation of the bash executor seam over the process-manager
+ * seam. Each command runs as `bash -c` in a managed process group spawned
+ * through `ctx.processes`; this executor owns command defaulting, deadlines
+ * and cause classification, the model-friendly terminal environment, and the
+ * model-facing stdout/stderr merge for background reads. Execution policy
+ * belongs in `tools/pre-execute` or a sandboxing executor.
  * @module @deepseek-ai/dsh-bash-local
  */
 
@@ -9,9 +12,28 @@ import { Context } from 'cordis'
 import z from 'schemastery'
 import { BashExecutor } from '@deepseek-ai/dsh-bash'
 import type { BashExecRequest, BashExecSpec, BashProcess, BashProcessRead, BashRunResult } from '@deepseek-ai/dsh-bash'
+import type { ProcessSpawnSpec } from '@deepseek-ai/dsh-process'
 import { clampTimeout, deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
-import { DEFAULT_GRACE_MS, DEFAULT_MAX_SPILL_BYTES, runBash } from './run.ts'
-import type { RunInternals, RunningBash } from './run.ts'
+
+/**
+ * Model-friendly environment overrides: disable colors, pagers, and
+ * interactive terminal features that would garble tool output (the same set
+ * Codex hardcodes; Claude Code achieves it via TERM=dumb). Bash-tool policy —
+ * merged into the ordinary env channel, so a trusted caller's own entry still
+ * wins; the process manager applies its credential scrub independently.
+ */
+export const ENV_OVERRIDES = {
+  NO_COLOR: '1',
+  TERM: 'dumb',
+  PAGER: 'cat',
+  GIT_PAGER: 'cat',
+} as const
+
+/** Default SIGTERM→SIGKILL grace period (the `graceMs` config; matches OpenCode's 3s). */
+const DEFAULT_GRACE_MS = 3_000
+
+/** Default per-stream spill cap (the `maxSpillBytes` config). */
+const DEFAULT_MAX_SPILL_BYTES = 64 * 1024 * 1024
 
 /** Plugin config (all optional — `static Config` supplies the defaults). */
 export interface Config {
@@ -39,10 +61,15 @@ function assertPositiveFinite(name: string, value: number): void {
 }
 
 /**
- * Local bash executor with bounded output, spill files, and process-group
- * `SIGTERM` to `SIGKILL` escalation.
+ * Local bash executor over `ctx.processes`. Bounded output, spill files, and
+ * process-group SIGTERM→SIGKILL escalation are the process manager's
+ * mechanics; this executor supplies their configured budgets per spawn, so a
+ * still-running background process stays managed (killed and joined at
+ * composition teardown) even across an executor reload.
  */
 export class LocalBashExecutor extends BashExecutor {
+  static inject = ['processes']
+
   static Config: z<Config> = z.object({
     cwd: z.string(),
     timeoutMs: z.number().default(120_000),
@@ -52,11 +79,6 @@ export class LocalBashExecutor extends BashExecutor {
     graceMs: z.number().default(DEFAULT_GRACE_MS),
   })
 
-  /** 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 = {}
-
   /** Validated config (schemastery applied the defaults before construction). */
   readonly config: ResolvedConfig
 
@@ -69,17 +91,6 @@ export class LocalBashExecutor extends BashExecutor {
     assertPositiveFinite('maxOutputBytes', this.config.maxOutputBytes)
     assertPositiveFinite('maxSpillBytes', this.config.maxSpillBytes)
     assertPositiveFinite('graceMs', this.config.graceMs)
-    ctx.effect(() => async () => {
-      // Await closure so even a TERM-trapping child cannot outlive the fiber.
-      const pending: Promise<void>[] = []
-      for (const [proc, running] of this.live) {
-        proc.status = 'killed'
-        running.kill()
-        pending.push(proc.done)
-      }
-      this.live.clear()
-      await Promise.all(pending)
-    }, 'local bash teardown')
   }
 
   /**
@@ -105,7 +116,7 @@ export class LocalBashExecutor extends BashExecutor {
       stdoutMaxBytes,
       ...request.signal ? { signal: request.signal } : {},
       // Carry stdin/ordinary env/trusted dshEnv through verbatim — optional,
-      // no config default. run.ts owns the scrub and merge order.
+      // no config default. The process manager owns the scrub and merge order.
       ...request.stdin !== undefined ? { stdin: request.stdin } : {},
       ...request.env !== undefined ? { env: request.env } : {},
       ...request.dshEnv !== undefined ? { dshEnv: request.dshEnv } : {},
@@ -116,21 +127,27 @@ export class LocalBashExecutor extends BashExecutor {
     }
   }
 
-  async run(spec: BashExecSpec): Promise<BashRunResult> {
-    // 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,
+  /** Map one resolved bash spec onto a fully-specified process spawn. */
+  // XXX(stateful-shell): evaluate persistent cwd or PTY sessions when workflows require shell state.
+  private spawnSpec(spec: BashExecSpec, stdoutMaxBytes: number, signal: AbortSignal | undefined): ProcessSpawnSpec {
+    return {
+      argv: ['bash', '-c', spec.command],
       cwd: spec.workdir,
-      stdoutMaxBytes: spec.stdoutMaxBytes,
+      stdoutMaxBytes,
       stderrMaxBytes: this.config.maxOutputBytes,
       maxSpillBytes: this.config.maxSpillBytes,
       graceMs: this.config.graceMs,
-      signal: d.signal,
+      signal,
       stdin: spec.stdin,
-      env: spec.env,
+      env: { ...ENV_OVERRIDES, ...spec.env },
       dshEnv: spec.dshEnv,
-    }, this.internals).done
+    }
+  }
+
+  async run(spec: BashExecSpec): Promise<BashRunResult> {
+    // One deadline combines timeout and upstream cancellation; disposal clears its timer.
+    using d = deadline(spec.signal, spec.timeoutMs, 'BASH_TIMEOUT')
+    const outcome = await this.ctx.processes.spawn(this.spawnSpec(spec, spec.stdoutMaxBytes, d.signal)).done
     // 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
@@ -139,18 +156,16 @@ export class LocalBashExecutor extends BashExecutor {
 
   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,
-      stdoutMaxBytes: this.config.maxOutputBytes,
-      stderrMaxBytes: this.config.maxOutputBytes,
-      maxSpillBytes: this.config.maxSpillBytes,
-      graceMs: this.config.graceMs,
-      signal: spec.signal,
-      stdin: spec.stdin,
-      env: spec.env,
-      dshEnv: spec.dshEnv,
-    }, this.internals)
+    const running = this.ctx.processes.spawn(this.spawnSpec(spec, this.config.maxOutputBytes, spec.signal))
+
+    // A spawn failure produces no process output, so the manager has nothing
+    // to buffer; the note is delivered exactly once through the read path.
+    let spawnFailureNote: string | undefined
+    const consumeSpawnFailure = (): string => {
+      const note = spawnFailureNote ?? ''
+      spawnFailureNote = undefined
+      return note
+    }
 
     let stdoutOffset = 0
     let stderrOffset = 0
@@ -166,13 +181,11 @@ export class LocalBashExecutor extends BashExecutor {
         proc.exitCode = outcome.exitCode
         proc.signal = outcome.signal
         this.onProcessDone(proc, running.stderr.readFrom(0).text)
-        this.live.delete(proc)
       }, (error: unknown) => {
         // 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)
+        spawnFailureNote = `spawn failed: ${String(error)}`
+        this.onProcessDone(proc, spawnFailureNote)
       }),
       readOutput: (): BashProcessRead => {
         const out = running.stdout.readFrom(stdoutOffset)
@@ -180,11 +193,14 @@ export class LocalBashExecutor extends BashExecutor {
         stdoutOffset = out.nextOffset
         stderrOffset = err.nextOffset
 
+        // A failed spawn never produced process output, so the note and real
+        // stderr text are mutually exclusive.
+        const errText = err.text.length > 0 ? err.text : consumeSpawnFailure()
         // 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}` : '')
+          + (errText.length > 0 ? `${separator}[stderr]\n${errText}` : '')
         return {
           delta,
           lossy: out.lossy || err.lossy,
@@ -199,7 +215,6 @@ export class LocalBashExecutor extends BashExecutor {
         return true
       },
     }
-    this.live.set(proc, running)
     return proc
   }
 

packages/bash/bash-local/src/run.ts

@@ -1,399 +0,0 @@
-/**
- * Process plumbing for the local bash executor: detached process-group spawn,
- * tail-keep output with spill files, and SIGTERM→SIGKILL escalation. This layer
- * reacts to an abort signal; the executor owns deadlines and classifies causes.
- * @module dsh-bash-local/run
- */
-
-import { type ChildProcessByStdio, spawn } from 'node:child_process'
-import type { Readable, Writable } from 'node:stream'
-import { randomBytes } from 'node:crypto'
-import { closeSync, mkdtempSync, openSync, unlinkSync, writeSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-bash'
-import type { CollectedOutput, DshEnvironment } from '@deepseek-ai/dsh-bash'
-
-/**
- * Model-friendly environment overrides: disable colors, pagers, and
- * interactive terminal features that would garble tool output (the same set
- * Codex hardcodes; Claude Code achieves it via TERM=dumb).
- */
-export const ENV_OVERRIDES = {
-  NO_COLOR: '1',
-  TERM: 'dumb',
-  PAGER: 'cat',
-  GIT_PAGER: 'cat',
-} as const
-
-/**
- * Credential-shaped env vars are NOT forwarded to commands (the harness's
- * own DEEPSEEK_API_KEY must not leak into `env` output, tool results, or
- * spill files). Same default pattern as Codex's env policy; a future config
- * can whitelist specific vars when a workflow genuinely needs one.
- */
-export const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i
-
-/**
- * Build a child environment from scrubbed ambient values, terminal overrides,
- * ordinary caller entries, and a managed `DSH_*` snapshot. Ambient managed
- * names are removed; ordinary and managed entries reject the other channel's
- * namespace before `dshEnv` merges last.
- * @param extra - caller entries; `DSH_*` names are rejected.
- * @param dshEnv - managed entries; non-`DSH_*` names are rejected.
- * @returns the environment to hand to `spawn` for the child process.
- */
-export function childEnv(
-  extra?: Readonly<Record<string, string>>,
-  dshEnv?: DshEnvironment,
-): NodeJS.ProcessEnv {
-  const env: NodeJS.ProcessEnv = {}
-  for (const [key, value] of Object.entries(process.env)) {
-    if (!SENSITIVE_ENV_PATTERN.test(key) && !key.startsWith(DSH_ENV_PREFIX)) env[key] = value
-  }
-  for (const key of Object.keys(extra ?? {})) {
-    if (key.startsWith(DSH_ENV_PREFIX)) {
-      throw new Error(`ordinary bash env cannot set reserved variable "${key}"; use dshEnv`)
-    }
-  }
-  for (const key of Object.keys(dshEnv ?? {})) {
-    if (!key.startsWith(DSH_ENV_PREFIX)) {
-      throw new Error(`managed bash env cannot set ordinary variable "${key}"; use env`)
-    }
-  }
-  return { ...env, ...ENV_OVERRIDES, ...extra, ...dshEnv }
-}
-
-/** What to run and under which limits (resolved — no defaults in here). */
-export interface SpawnSpec {
-  command: string
-  cwd: string
-  /** Stdout in-memory cap; overflow spills to disk (tail kept in memory). */
-  stdoutMaxBytes: number
-  /** Stderr in-memory cap; overflow spills to disk (tail kept in memory). */
-  stderrMaxBytes: number
-  /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */
-  maxSpillBytes: number
-  /** Grace period for kill escalation and for inherited pipes after shell exit. */
-  graceMs: number
-  /**
-   * Abort signal — kills the process group when it fires. The executor owns
-   * timing: `run()` passes a fused timeout/cancel deadline signal (see
-   * `@deepseek-ai/dsh-timeout`), `start()` passes the bare upstream signal.
-   * runBash only listens and kills; it does NOT classify why (the executor
-   * reads the signal's reason afterward).
-   */
-  signal?: AbortSignal | undefined
-  /**
-   * Bytes to write to the child's stdin, then close it. Absent (or empty)
-   * leaves stdin closed/empty. Set by in-process plugins (the hooks bridges);
-   * the model-facing `dsh-tool-bash` tool does not thread model input here.
-   */
-  stdin?: string | undefined
-  /**
-   * Ordinary environment entries merged after the credential scrub and
-   * terminal overrides. `DSH_*` names are rejected and belong in `dshEnv`.
-   */
-  env?: Record<string, string> | undefined
-  /** Harness-owned entries; non-`DSH_*` names are rejected before spawn. */
-  dshEnv?: DshEnvironment | undefined
-}
-
-/**
- * Raw outcome of one closed process (before result shaping). Deliberately
- * carries NO timeout/cancel classification: runBash kills on abort but does not
- * decide why — the executor's `run()`/`start()` reads the deadline signal it
- * owns to classify `timedOut`/`aborted` (see the package README).
- */
-export interface SpawnOutcome {
-  exitCode: number | null
-  signal: NodeJS.Signals | null
-  stdout: CollectedOutput
-  stderr: CollectedOutput
-}
-
-/** Injectable knobs so tests can exercise spill behavior without the OS tmpdir. */
-export interface RunInternals {
-  /** Directory for spill files (defaults to the OS temp dir). */
-  spillDir?: string
-}
-
-/** Default SIGTERM→SIGKILL grace period (the `graceMs` config; matches OpenCode's 3s). */
-export const DEFAULT_GRACE_MS = 3_000
-
-/** Default per-stream spill cap (the `maxSpillBytes` config). */
-export const DEFAULT_MAX_SPILL_BYTES = 64 * 1024 * 1024
-
-let spillCounter = 0
-let defaultSpillDir: string | undefined
-
-/**
- * The default spill location: a private (0700) per-process directory under
- * the OS tmpdir, created lazily. Predictable world-readable paths would let
- * other local users read command output or pre-create symlinks.
- */
-function privateSpillDir(): string {
-  defaultSpillDir ??= mkdtempSync(join(tmpdir(), 'dsh-bash-'))
-  return defaultSpillDir
-}
-
-/**
- * Collects one stream with a bounded in-memory tail. On first overflow a
- * spill file is created and every chunk (including those already collected)
- * is appended there while the full stream remains within `maxSpillBytes`.
- *
- * Tail-keep rationale (pi/OpenCode): errors and final results cluster at the
- * end of command output; the spill file covers the head.
- */
-export class OutputCollector {
-  private chunks: Buffer[] = []
-  private bytes = 0
-  private dropped = false
-  private spillFd: number | undefined
-  private spillFile: string | undefined
-  private spillDisabled = false
-  /** Total bytes ever pushed (not just retained). */
-  private total = 0
-
-  constructor(
-    private readonly maxBytes: number,
-    private readonly maxSpillBytes: number,
-    private readonly label: string,
-    private readonly spillDir: string,
-  ) {}
-
-  /**
-   * Ingest one stream chunk, counting it toward the whole-stream total. On
-   * first overflow of the in-memory cap a spill file is opened and every chunk
-   * (already-collected ones included) is appended there from then on; the
-   * in-memory tail then drops whole chunks from its head (or the head of a
-   * single over-cap chunk) until it fits the cap again.
-   * @param chunk - the raw bytes from one stream 'data' event.
-   */
-  push(chunk: Buffer): void {
-    this.total += chunk.length
-    const overflows = this.bytes + chunk.length > this.maxBytes
-    if (!this.spillDisabled && (overflows || this.spillFd !== undefined)) this.spillAll(chunk)
-    this.chunks.push(chunk)
-    this.bytes += chunk.length
-    while (this.bytes > this.maxBytes && this.chunks.length > 1) {
-      // Drop whole chunks from the head; pipe chunks are small (≤64KiB), so
-      // the retained tail tracks the cap closely enough for a model-facing
-      // truncation boundary. (length > 1 was just checked — shift() returns.)
-      const head = this.chunks.shift() as Buffer
-      this.bytes -= head.length
-      this.dropped = true
-    }
-    if (this.bytes > this.maxBytes && this.chunks.length === 1) {
-      // A single chunk larger than the cap: keep its tail.
-      const only = this.chunks[0] as Buffer
-      this.chunks[0] = only.subarray(only.length - this.maxBytes)
-      this.bytes = this.maxBytes
-      this.dropped = true
-    }
-  }
-
-  /** Open the spill file lazily and append `chunk` (and any prior chunks once). */
-  private spillAll(chunk: Buffer): void {
-    if (this.total > this.maxSpillBytes) {
-      this.discardSpill()
-      return
-    }
-    if (this.spillFd === undefined) {
-      // Random suffix + O_EXCL + no-follow-equivalent ('wx' fails on any
-      // existing path, symlink or not) + owner-only mode: defeats spill-path
-      // prediction and symlink planting in shared tmp dirs.
-      this.spillFile = join(
-        this.spillDir,
-        `dsh-bash-${process.pid}-${++spillCounter}-${randomBytes(6).toString('hex')}-${this.label}.log`,
-      )
-      this.spillFd = openSync(this.spillFile, 'wx', 0o600)
-      for (const prior of this.chunks) writeSync(this.spillFd, prior)
-    }
-    writeSync(this.spillFd, chunk)
-  }
-
-  /** Stop spilling and remove the file once it can no longer hold the complete stream. */
-  private discardSpill(): void {
-    const fd = this.spillFd
-    const file = this.spillFile
-    this.spillFd = undefined
-    this.spillFile = undefined
-    this.spillDisabled = true
-    if (fd !== undefined) {
-      try {
-        closeSync(fd)
-      } catch {
-        // Retain the descriptor so finalize can retry the failed close.
-        this.spillFd = fd
-      }
-    }
-    if (file !== undefined) {
-      try {
-        unlinkSync(file)
-      } catch {
-        // A failed unlink leaves at most maxSpillBytes behind, never an unbounded file.
-      }
-    }
-  }
-
-  /**
-   * Incremental read in whole-stream byte coordinates: returns everything
-   * pushed since `fromByte`. When `fromByte` has already slid out of the
-   * in-memory tail window, the read is `lossy` — it returns the whole
-   * retained tail and the gap is only recoverable from the spill file.
-   * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 for the first read).
-   * @returns the delta text, the offset for the next read, the `lossy` flag, and the spill path when one was created.
-   */
-  readFrom(fromByte: number): { text: string; nextOffset: number; lossy: boolean; spillPath?: string } {
-    const windowStart = this.total - this.bytes
-    const buffer = Buffer.concat(this.chunks)
-    const lossy = fromByte < windowStart
-    const slice = lossy ? buffer : buffer.subarray(fromByte - windowStart)
-    return {
-      text: slice.toString('utf8'),
-      nextOffset: this.total,
-      lossy,
-      ...this.spillFile !== undefined ? { spillPath: this.spillFile } : {},
-    }
-  }
-
-  /**
-   * Close the spill file (if any) and return the final output. A failed close
-   * (delayed writeback fault) stops advertising the spill path — the file may
-   * be missing its tail — but still returns the in-memory result.
-   * @returns the final collected output: tail text, truncation flag, and the spill path when intact.
-   */
-  finalize(): CollectedOutput {
-    if (this.spillFd !== undefined) {
-      try {
-        closeSync(this.spillFd)
-      } catch {
-        // A delayed writeback failure makes the spill unreliable; keep finalize
-        // total but stop advertising that file.
-        this.spillFile = undefined
-      }
-      this.spillFd = undefined
-    }
-    return {
-      text: Buffer.concat(this.chunks).toString('utf8'),
-      truncated: this.dropped,
-      ...this.spillFile !== undefined ? { spillPath: this.spillFile } : {},
-    }
-  }
-}
-
-/**
- * Send `sig` to a detached process group. Never throws: delivery races process
- * exit and may run in a timer callback, so failures are contained and a
- * non-positive pid is a no-op.
- * @param pid - the group leader's pid; non-positive means the spawn failed and the call is a no-op.
- * @param sig - the signal to deliver to the whole group.
- */
-export function killGroup(pid: number, sig: NodeJS.Signals): void {
-  if (pid <= 0) return
-  try {
-    process.kill(-pid, sig)
-  } catch {
-    // Swallow: see contract above.
-  }
-}
-
-/**
- * A live bash child process: the promise resolves when the process closes;
- * `kill()` starts the SIGTERM→grace→SIGKILL escalation on its group.
- */
-export interface RunningBash {
-  /** Process id (group leader); -1 when the spawn itself failed. */
-  readonly pid: number
-  /** stdout/stderr collectors (live — background polling reads incrementally). */
-  readonly stdout: OutputCollector
-  readonly stderr: OutputCollector
-  /** Resolves when the process closes; rejects only for spawn-level failures. */
-  readonly done: Promise<SpawnOutcome>
-  /** Begin SIGTERM→grace→SIGKILL on the process group. Idempotent. */
-  kill(): void
-}
-
-/**
- * Spawn one isolated `bash -c` process group and collect its output.
- * Runtime exits resolve as {@link SpawnOutcome}; only spawn failures reject.
- * @param spec - fully resolved command, cwd, limits, and cancellation.
- * @param internals - test-only process and spill-directory overrides.
- * @returns live process handle and outcome promise.
- */
-// XXX(stateful-shell): evaluate persistent cwd or PTY sessions when workflows require shell state.
-export function runBash(spec: SpawnSpec, internals: RunInternals = {}): RunningBash {
-  const spillDir = internals.spillDir ?? privateSpillDir()
-
-  if (spec.signal?.aborted) {
-    throw new Error(`aborted before spawn: ${String(spec.signal.reason ?? 'aborted')}`)
-  }
-
-  // Keep absent stdin as /dev/null; literal tuples preserve non-null output types.
-  const env = childEnv(spec.env, spec.dshEnv)
-  const child: ChildProcessByStdio<Writable | null, Readable, Readable> = spec.stdin !== undefined
-    ? spawn('bash', ['-c', spec.command], { cwd: spec.cwd, env, stdio: ['pipe', 'pipe', 'pipe'], detached: true })
-    : spawn('bash', ['-c', spec.command], { cwd: spec.cwd, env, stdio: ['ignore', 'pipe', 'pipe'], detached: true })
-
-  const stdout = new OutputCollector(spec.stdoutMaxBytes, spec.maxSpillBytes, 'stdout', spillDir)
-  const stderr = new OutputCollector(spec.stderrMaxBytes, spec.maxSpillBytes, 'stderr', spillDir)
-  child.stdout.on('data', (chunk: Buffer) => { stdout.push(chunk) })
-  child.stderr.on('data', (chunk: Buffer) => { stderr.push(chunk) })
-
-  let graceTimer: NodeJS.Timeout | undefined
-
-  // Failed spawns use pid -1 so kill remains a no-op.
-  const pid = child.pid ?? -1
-
-  const kill = (): void => {
-    if (graceTimer !== undefined) return // escalation already in flight
-    killGroup(pid, 'SIGTERM')
-    graceTimer = setTimeout(() => { killGroup(pid, 'SIGKILL') }, spec.graceMs)
-  }
-
-  // The executor owns timeout classification; this layer only reacts to abort.
-  const onAbort = (): void => { kill() }
-  spec.signal?.addEventListener('abort', onAbort, { once: true })
-
-  // Stdin writes are best-effort; process exit and captured output remain authoritative.
-  if (child.stdin !== null) {
-    child.stdin.on('error', () => { /* stdin write is best-effort; outcome rides on exit/output. */ })
-    child.stdin.end(spec.stdin)
-  }
-
-  const done = new Promise<SpawnOutcome>((resolve, reject) => {
-    let settled = false
-    let pipeDrainTimer: NodeJS.Timeout | undefined
-    const settle = (exitCode: number | null, signal: NodeJS.Signals | null): void => {
-      if (settled) return
-      settled = true
-      child.stdout.destroy()
-      child.stderr.destroy()
-      cleanup()
-      resolve({
-        exitCode,
-        signal,
-        stdout: stdout.finalize(),
-        stderr: stderr.finalize(),
-      })
-    }
-    child.on('error', (error) => {
-      // No meaningful close outcome follows a spawn failure.
-      settled = true
-      cleanup()
-      reject(error)
-    })
-    child.on('exit', (exitCode, signal) => {
-      pipeDrainTimer = setTimeout(() => { settle(exitCode, signal) }, spec.graceMs)
-    })
-    child.on('close', settle)
-    function cleanup(): void {
-      if (graceTimer !== undefined) clearTimeout(graceTimer)
-      if (pipeDrainTimer !== undefined) clearTimeout(pipeDrainTimer)
-      spec.signal?.removeEventListener('abort', onAbort)
-    }
-  })
-
-  return { pid, stdout, stderr, done, kill }
-}

packages/bash/bash-local/tests/executor.spec.ts

@@ -4,16 +4,18 @@ import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import LocalProcessManager from '@deepseek-ai/dsh-process-local'
 import type { BashProcess } from '@deepseek-ai/dsh-bash'
 
 const spillDir = mkdtempSync(join(tmpdir(), 'dsh-bash-exec-spec-'))
 
 async function setup(config: ConstructorParameters<typeof LocalBashExecutor>[1] = {}) {
   const ctx = new Context()
+  await ctx.plugin(LocalProcessManager)
+  ;(ctx.processes as LocalProcessManager).internals = { spillDir }
   // A short kill grace via the REAL config path, so escalation tests stay fast.
   await ctx.plugin(LocalBashExecutor, { graceMs: 200, ...config })
   const bash = ctx.bash as LocalBashExecutor
-  bash.internals = { spillDir }
   return { ctx, bash }
 }
 
@@ -293,44 +295,52 @@ describe('LocalBashExecutor.start (background process handles)', () => {
   })
 })
 
-describe('LocalBashExecutor disposal', () => {
-  it('disposing the fiber kills running processes and AWAITS their exit (no orphans, SIGKILL escalation included)', async () => {
+describe('process lifecycle ownership (the manager, not the executor)', () => {
+  it('a background process survives executor-fiber disposal and dies with the process manager', async () => {
     const ctx = new Context()
-    const fiber = await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
+    const managerFiber = await ctx.plugin(LocalProcessManager)
+    ;(ctx.processes as LocalProcessManager).internals = { spillDir }
+    const executorFiber = await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
     const bash = ctx.bash as LocalBashExecutor
-    bash.internals = { spillDir }
 
     // 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 proc = bash.start(bash.resolve({ command: '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.
+    // Reloading/disposing the executor no longer kills backend work — the
+    // handle stays live and readable, mirroring the task runtime's
+    // registrations-outlive-producer-fibers contract.
+    await executorFiber.dispose()
+    expect(proc.status).toBe('running')
+    expect(() => process.kill(pid, 0)).not.toThrow()
+
+    // Manager disposal kills the group and AWAITS its exit (no orphans).
+    await managerFiber.dispose()
     expect(() => process.kill(pid, 0)).toThrow()
-    expect(proc.status).toBe('killed')
     await proc.done
+    expect(proc.status).toBe('killed')
   })
 
-  it('settled processes already left the live map: dispose does not touch them', async () => {
+  it('manager disposal escalates to SIGKILL for TERM-trapping children and settles handles', async () => {
     const ctx = new Context()
-    const fiber = await ctx.plugin(LocalBashExecutor, { graceMs: 200 })
+    const managerFiber = await ctx.plugin(LocalProcessManager)
+    ;(ctx.processes as LocalProcessManager).internals = { spillDir }
+    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' }))
+    const trapping = bash.start(bash.resolve({ command: 'trap \'\' TERM; echo armed; sleep 60' }))
+    await readUntil(trapping, 'armed')
 
-    await fiber.dispose()
-    // The teardown marks every LIVE entry killed; a settled process had
-    // already left the map, so its status stays completed.
+    await managerFiber.dispose()
+    // A settled process was untouched; the live one died by escalation.
     expect(finished.status).toBe('completed')
-    expect(running.status).toBe('killed')
-    await running.done
-    expect(running.signal).toBe('SIGTERM')
+    await trapping.done
+    expect(trapping.status).toBe('killed')
+    expect(trapping.signal).toBe('SIGKILL')
   })
 })

packages/bash/bash-local/tests/run.spec.ts

@@ -1,510 +0,0 @@
-import { mkdtempSync, readFileSync, statSync, unlinkSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
-import { describe, expect, it, vi } from 'vitest'
-import type { DshEnvironment } from '@deepseek-ai/dsh-bash'
-import { killGroup, OutputCollector, runBash } from '../src/run.ts'
-import type { RunningBash } from '../src/run.ts'
-
-const { failNextClose, failNextUnlink } = vi.hoisted(() => ({
-  failNextClose: { value: false },
-  failNextUnlink: { value: false },
-}))
-vi.mock('node:fs', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('node:fs')>()
-  return {
-    ...actual,
-    closeSync(fd: number): void {
-      if (failNextClose.value) {
-        failNextClose.value = false
-        throw Object.assign(new Error('simulated EIO on close'), { code: 'EIO' })
-      }
-      actual.closeSync(fd)
-    },
-    unlinkSync(path: Parameters<typeof actual.unlinkSync>[0]): void {
-      if (failNextUnlink.value) {
-        failNextUnlink.value = false
-        throw Object.assign(new Error('simulated EIO on unlink'), { code: 'EIO' })
-      }
-      actual.unlinkSync(path)
-    },
-  }
-})
-
-const spillDir = mkdtempSync(join(tmpdir(), 'dsh-bash-spec-'))
-
-function spec(command: string, overrides: Partial<Parameters<typeof runBash>[0]> = {}) {
-  return {
-    command,
-    cwd: process.cwd(),
-    stdoutMaxBytes: 64_000,
-    stderrMaxBytes: 64_000,
-    maxSpillBytes: 64 * 1024 * 1024,
-    graceMs: 3_000,
-    ...overrides,
-  }
-}
-
-/** Poll until a pid no longer exists (kill(pid, 0) throws ESRCH). */
-async function waitGone(pid: number, timeoutMs = 5_000): Promise<void> {
-  const deadline = Date.now() + timeoutMs
-  while (Date.now() < deadline) {
-    try {
-      process.kill(pid, 0)
-    } catch {
-      return
-    }
-    await new Promise(resolve => setTimeout(resolve, 20))
-  }
-  throw new Error(`pid ${pid} still alive after ${timeoutMs}ms`)
-}
-
-async function waitForStdout(running: RunningBash, expected: string, timeoutMs = 5_000): Promise<void> {
-  const deadline = Date.now() + timeoutMs
-  while (Date.now() < deadline) {
-    if (running.stdout.readFrom(0).text.includes(expected)) return
-    await new Promise(resolve => setTimeout(resolve, 20))
-  }
-  throw new Error(`stdout did not include ${JSON.stringify(expected)} after ${timeoutMs}ms`)
-}
-
-async function waitForPidFile(path: string, timeoutMs = 5_000): Promise<number> {
-  const deadline = Date.now() + timeoutMs
-  while (Date.now() < deadline) {
-    try {
-      const pid = Number(readFileSync(path, 'utf8').trim())
-      if (Number.isSafeInteger(pid) && pid > 0) return pid
-    } catch {
-      // The child shell has not written the pid file yet.
-    }
-    await new Promise(resolve => setTimeout(resolve, 20))
-  }
-  throw new Error(`pid file ${path} was not written after ${timeoutMs}ms`)
-}
-
-describe('runBash', () => {
-  it('captures stdout on success', async () => {
-    const result = await runBash(spec('echo hello')).done
-    expect(result.exitCode).toBe(0)
-    expect(result.signal).toBeNull()
-    expect(result.stdout.text).toBe('hello\n')
-    expect(result.stdout.truncated).toBe(false)
-    expect(result.stderr.text).toBe('')
-  })
-
-  it('captures stderr separately', async () => {
-    const result = await runBash(spec('echo oops >&2')).done
-    expect(result.exitCode).toBe(0)
-    expect(result.stdout.text).toBe('')
-    expect(result.stderr.text).toBe('oops\n')
-  })
-
-  it('captures both streams', async () => {
-    const result = await runBash(spec('echo out; echo err >&2')).done
-    expect(result.stdout.text).toBe('out\n')
-    expect(result.stderr.text).toBe('err\n')
-  })
-
-  it('reports non-zero exit codes', async () => {
-    const result = await runBash(spec('exit 42')).done
-    expect(result.exitCode).toBe(42)
-    expect(result.signal).toBeNull()
-  })
-
-  it('applies model-friendly env overrides', async () => {
-    const result = await runBash(spec('echo "$NO_COLOR/$TERM/$PAGER"')).done
-    expect(result.stdout.text).toBe('1/dumb/cat\n')
-  })
-
-  it('runs in the requested cwd', async () => {
-    const result = await runBash(spec('pwd', { cwd: '/tmp' })).done
-    expect(result.stdout.text.trim()).toMatch(/\/tmp$/)
-  })
-
-  it('kills the process group with SIGTERM when the signal fires', async () => {
-    // runBash owns no timer: it kills on abort. The executor drives the timeout
-    // by firing this signal via a deadline (see executor.spec.ts); here we
-    // assert the kill itself lands as SIGTERM.
-    const controller = new AbortController()
-    const start = Date.now()
-    const running = runBash(spec('sleep 60', { signal: controller.signal }))
-    setTimeout(() => { controller.abort('deadline') }, 100)
-    const result = await running.done
-    expect(Date.now() - start).toBeLessThan(5_000)
-    expect(result.signal).toBe('SIGTERM')
-    expect(result.exitCode).toBeNull()
-  })
-
-  it('escalates to SIGKILL when SIGTERM is trapped', async () => {
-    const running = runBash(spec('trap \'\' TERM; echo ready; while :; do sleep 60 & wait $!; done', { graceMs: 200 }))
-    await waitForStdout(running, 'ready\n')
-    running.kill()
-    const result = await running.done
-    expect(result.signal).toBe('SIGKILL')
-  })
-
-  it('kills the whole process group (grandchildren die too)', async () => {
-    // The subshell writes the sleep's pid then waits on it; killing the
-    // group must take the sleep down with bash.
-    const pidFile = join(spillDir, `grandchild-${Date.now()}.pid`)
-    const running = runBash(spec(`sleep 60 & echo $! > ${pidFile}; wait`))
-    const grandchild = await waitForPidFile(pidFile)
-    expect(grandchild).toBeGreaterThan(0)
-
-    running.kill()
-    const result = await running.done
-    expect(result.signal).toBe('SIGTERM')
-    await waitGone(grandchild)
-  })
-
-  it('aborts via AbortSignal mid-run', async () => {
-    const controller = new AbortController()
-    const running = runBash(spec('sleep 60', { signal: controller.signal }))
-    setTimeout(() => { controller.abort('user cancelled') }, 50)
-    const result = await running.done
-    expect(result.signal).toBe('SIGTERM')
-  })
-
-  it('throws when the signal is already aborted before spawn', () => {
-    const controller = new AbortController()
-    controller.abort('too late')
-    expect(() => runBash(spec('echo hi', { signal: controller.signal })))
-      .toThrow(/aborted before spawn: too late/)
-  })
-
-  it('rejects with a spawn error for a nonexistent cwd', async () => {
-    await expect(runBash(spec('echo hi', { cwd: '/nonexistent-dir-dsh-test' })).done)
-      .rejects.toThrow(/ENOENT/)
-  })
-
-  it('kill() is idempotent (second call does not restart escalation)', async () => {
-    const running = runBash(spec('sleep 60'))
-    running.kill()
-    running.kill()
-    const result = await running.done
-    expect(result.signal).toBe('SIGTERM')
-  })
-
-  it('bounds inherited-pipe draining after the shell exits', async () => {
-    const pidFile = join(spillDir, `pipe-holder-${Date.now()}.pid`)
-    const started = Date.now()
-    const running = runBash(spec(`sleep 60 & echo $! > ${pidFile}; echo shell-done`, { graceMs: 100 }))
-    const descendant = await waitForPidFile(pidFile)
-    try {
-      const result = await running.done
-      expect(Date.now() - started).toBeLessThan(1_000)
-      expect(result.exitCode).toBe(0)
-      expect(result.stdout.text).toBe('shell-done\n')
-    } finally {
-      process.kill(descendant, 'SIGKILL')
-      await waitGone(descendant)
-    }
-  })
-})
-
-describe('stdin and extra env (set by in-process plugins)', () => {
-  it('writes stdin to the command and closes it', async () => {
-    const result = await runBash(spec('cat', { stdin: 'hello from stdin\n' })).done
-    expect(result.exitCode).toBe(0)
-    expect(result.stdout.text).toBe('hello from stdin\n')
-  })
-
-  it('a command that reads stdin sees EOF when none is supplied', async () => {
-    // No stdin → fd 0 is /dev/null, so `cat` reads EOF and exits 0 with no
-    // output (it does NOT block).
-    const result = await runBash(spec('cat')).done
-    expect(result.exitCode).toBe(0)
-    expect(result.stdout.text).toBe('')
-  })
-
-  it('gives fd 0 the exact pre-seam type: /dev/null when no stdin, a pipe when supplied', async () => {
-    // With no bytes, fd 0 remains the pre-seam `ignore` default (/dev/null, a character device).
-    // Supplied bytes use Node's spawn pipe, which is an AF_UNIX socket rather than a FIFO.
-    const none = await runBash(spec('test -c /dev/stdin && echo char || echo other')).done
-    expect(none.stdout.text).toBe('char\n')
-    const piped = await runBash(spec('test -S /dev/stdin && echo socket || echo other', { stdin: 'x' })).done
-    expect(piped.stdout.text).toBe('socket\n')
-  })
-
-  it('merges ordinary extra env entries onto the scrubbed environment', async () => {
-    const result = await runBash(spec('echo "$EXTRA_ONE/$EXTRA_TWO"', {
-      env: { EXTRA_ONE: 'alpha', EXTRA_TWO: 'beta' },
-    })).done
-    expect(result.stdout.text).toBe('alpha/beta\n')
-  })
-
-  it('an explicit extra env entry overrides the model-friendly override and the scrub', async () => {
-    // TERM is a model-friendly OVERRIDE (dumb); an explicit extra entry wins.
-    // EXPLICIT_OVERRIDE_KEY matches the credential scrub pattern, yet an explicit
-    // entry is still honored — the scrub only drops AMBIENT process.env creds.
-    const result = await runBash(spec('echo "$TERM/$EXPLICIT_OVERRIDE_KEY"', {
-      env: { TERM: 'xterm-256color', EXPLICIT_OVERRIDE_KEY: 'explicit-wins' },
-    })).done
-    expect(result.stdout.text).toBe('xterm-256color/explicit-wins\n')
-  })
-
-  it('does not crash or reject when the child ignores a large stdin (EPIPE)', async () => {
-    // The child exits without reading, so closing a stdin pipe holding ~1 MiB triggers EPIPE.
-    // The handler swallows that write error and `done` reports the child's real exit.
-    const big = 'x'.repeat(1024 * 1024)
-    const result = await runBash(spec('exit 7', { stdin: big })).done
-    expect(result.exitCode).toBe(7)
-  })
-})
-
-describe('output truncation and spill', () => {
-  it('applies stdout and stderr caps independently', async () => {
-    const result = await runBash(
-      spec('printf "%.0sx" $(seq 1 500); printf "%.0se" $(seq 1 500) >&2', {
-        stdoutMaxBytes: 500,
-        stderrMaxBytes: 100,
-      }),
-      { spillDir },
-    ).done
-    expect(result.stdout.truncated).toBe(false)
-    expect(result.stdout.text).toBe('x'.repeat(500))
-    expect(result.stderr.truncated).toBe(true)
-    expect(result.stderr.text.length).toBeLessThanOrEqual(100)
-  })
-
-  it('keeps the tail and spills the full stream to disk', async () => {
-    // 200 numbered lines of ~10 bytes; cap at 500 bytes keeps a late tail.
-    const result = await runBash(
-      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
-      { spillDir },
-    ).done
-    expect(result.stdout.truncated).toBe(true)
-    expect(result.stdout.text.length).toBeLessThanOrEqual(500)
-    expect(result.stdout.text).toContain('line-0200')
-    expect(result.stdout.text).not.toContain('line-0001')
-    expect(result.stdout.spillPath).toBeDefined()
-    const full = readFileSync(result.stdout.spillPath!, 'utf8')
-    expect(full).toContain('line-0001')
-    expect(full).toContain('line-0200')
-  })
-
-  it('does not truncate output exactly at the cap', async () => {
-    const result = await runBash(
-      spec('printf "%.0sx" $(seq 1 500)', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
-      { spillDir },
-    ).done
-    expect(result.stdout.truncated).toBe(false)
-    expect(result.stdout.text.length).toBe(500)
-    expect(result.stdout.spillPath).toBeUndefined()
-  })
-
-  it('settles with the tail and no spill path when final spill close fails', async () => {
-    failNextClose.value = true
-    const result = await runBash(
-      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
-      { spillDir },
-    ).done
-    expect(failNextClose.value).toBe(false)
-    expect(result.exitCode).toBe(0)
-    expect(result.stdout.truncated).toBe(true)
-    expect(result.stdout.text).toContain('line-0200')
-    expect(result.stdout.spillPath).toBeUndefined()
-  })
-})
-
-describe('OutputCollector', () => {
-  it('keeps the tail of a single oversized chunk', () => {
-    const collector = new OutputCollector(10, 100, 'test', spillDir)
-    collector.push(Buffer.from('0123456789abcdef'))
-    const out = collector.finalize()
-    expect(out.text).toBe('6789abcdef')
-    expect(out.truncated).toBe(true)
-    expect(readFileSync(out.spillPath!, 'utf8')).toBe('0123456789abcdef')
-  })
-
-  it('readFrom returns increments and flags lossy reads', () => {
-    const collector = new OutputCollector(10, 100, 'test', spillDir)
-    collector.push(Buffer.from('aaaaa'))
-    const first = collector.readFrom(0)
-    expect(first.text).toBe('aaaaa')
-    expect(first.lossy).toBe(false)
-    expect(first.nextOffset).toBe(5)
-
-    collector.push(Buffer.from('bbbbb'))
-    const second = collector.readFrom(first.nextOffset)
-    expect(second.text).toBe('bbbbb')
-    expect(second.lossy).toBe(false)
-
-    // Push enough to slide the window past the last offset.
-    collector.push(Buffer.from('c'.repeat(20)))
-    const third = collector.readFrom(second.nextOffset)
-    expect(third.lossy).toBe(true)
-    expect(third.text).toBe('c'.repeat(10))
-    expect(third.spillPath).toBeDefined()
-  })
-
-  it('contains close failures and drops the spill path', () => {
-    const collector = new OutputCollector(4, 100, 'closefail', spillDir)
-    collector.push(Buffer.from('aaaa'))
-    collector.push(Buffer.from('bbbb'))
-    expect(collector.readFrom(0).spillPath).toBeDefined()
-
-    failNextClose.value = true
-    let out: ReturnType<typeof collector.finalize>
-    expect(() => { out = collector.finalize() }).not.toThrow()
-
-    expect(failNextClose.value).toBe(false)
-    expect(out!.text).toBe('bbbb')
-    expect(out!.truncated).toBe(true)
-    expect(out!.spillPath).toBeUndefined()
-  })
-
-  it('discards a spill that exceeds its configured cap', () => {
-    const collector = new OutputCollector(4, 8, 'bounded', spillDir)
-    collector.push(Buffer.from('aaaa'))
-    collector.push(Buffer.from('bbbb'))
-    const spillPath = collector.readFrom(0).spillPath!
-    expect(readFileSync(spillPath, 'utf8')).toBe('aaaabbbb')
-
-    collector.push(Buffer.from('c'))
-    collector.push(Buffer.from('dddd'))
-    const out = collector.finalize()
-    expect(out.text).toBe('dddd')
-    expect(out.truncated).toBe(true)
-    expect(out.spillPath).toBeUndefined()
-    expect(() => readFileSync(spillPath)).toThrow()
-  })
-
-  it('does not create a spill when the first overflowing chunk exceeds the cap', () => {
-    const collector = new OutputCollector(4, 4, 'no-spill', spillDir)
-    collector.push(Buffer.from('abcdefgh'))
-    const out = collector.finalize()
-    expect(out.text).toBe('efgh')
-    expect(out.truncated).toBe(true)
-    expect(out.spillPath).toBeUndefined()
-  })
-
-  it('contains cleanup failures while disabling an oversize spill', () => {
-    const collector = new OutputCollector(4, 8, 'cleanup-fail', spillDir)
-    collector.push(Buffer.from('aaaa'))
-    collector.push(Buffer.from('bbbb'))
-    const spillPath = collector.readFrom(0).spillPath!
-
-    failNextClose.value = true
-    failNextUnlink.value = true
-    expect(() => { collector.push(Buffer.from('c')) }).not.toThrow()
-    expect(failNextClose.value).toBe(false)
-    expect(failNextUnlink.value).toBe(false)
-    expect(collector.finalize().spillPath).toBeUndefined()
-    unlinkSync(spillPath)
-  })
-})
-
-describe('killGroup', () => {
-  it('ignores non-positive pids', () => {
-    expect(() => { killGroup(-1, 'SIGTERM') }).not.toThrow()
-    expect(() => { killGroup(0, 'SIGTERM') }).not.toThrow()
-  })
-
-  it('swallows ESRCH for vanished groups', async () => {
-    const running = runBash(spec('true'))
-    await running.done
-    expect(() => { killGroup(running.pid, 'SIGTERM') }).not.toThrow()
-  })
-})
-
-describe('abort edge cases', () => {
-  it('reports a fallback reason for reason-less pre-aborted signals', () => {
-    // Real AbortControllers always set a DOMException reason; signal-like
-    // objects from other libraries may not — the fallback covers them.
-    const bare = {
-      aborted: true,
-      reason: undefined,
-      addEventListener() {},
-      removeEventListener() {},
-    } as unknown as AbortSignal
-    expect(() => runBash(spec('echo hi', { signal: bare })))
-      .toThrow(/aborted before spawn: aborted/)
-  })
-
-  it('reports the terminating signal of an externally self-killed command', async () => {
-    // runBash reports the raw signal; whether it counts as timeout/cancel is the
-    // executor's classification (a self-kill is neither) — see executor.spec.ts.
-    const result = await runBash(spec('kill -TERM $$')).done
-    expect(result.signal).toBe('SIGTERM')
-  })
-})
-
-describe('environment and spill-file hardening', () => {
-  it('scrubs credential-shaped and ambient DSH env vars from child processes', async () => {
-    process.env.DSH_TEST_API_KEY = 'super-secret'
-    process.env.DSH_TEST_TOKEN = 'also-secret'
-    process.env.DSH_TEST_PLAIN = 'visible'
-    try {
-      const result = await runBash(spec('echo "[${DSH_TEST_API_KEY:-absent}|${DSH_TEST_TOKEN:-absent}|${DSH_TEST_PLAIN:-absent}]"')).done
-      expect(result.stdout.text.trim()).toBe('[absent|absent|absent]')
-    } finally {
-      delete process.env.DSH_TEST_API_KEY
-      delete process.env.DSH_TEST_TOKEN
-      delete process.env.DSH_TEST_PLAIN
-    }
-  })
-
-  it('injects only the current trusted DSH environment after scrubbing ambient values', async () => {
-    process.env.DSH_STALE = 'old-value'
-    try {
-      const result = await runBash(spec('echo "[${DSH_STALE:-absent}|$DSH_SHELL|$DSH_SESSION_ID]"', {
-        dshEnv: { DSH_SHELL: '1', DSH_SESSION_ID: 'current-session' },
-      })).done
-      expect(result.stdout.text.trim()).toBe('[absent|1|current-session]')
-    } finally {
-      delete process.env.DSH_STALE
-    }
-  })
-
-  it('rejects DSH variables on the ordinary env channel', () => {
-    expect(() => runBash(spec('true', { env: { DSH_WRONG_CHANNEL: 'bad' } })))
-      .toThrow(/DSH_WRONG_CHANNEL.*dshEnv/)
-  })
-
-  it('rejects ordinary variables on the managed env channel', () => {
-    const invalid = { PATH: '/wrong-channel' } as unknown as DshEnvironment
-    expect(() => runBash(spec('true', { dshEnv: invalid })))
-      .toThrow(/managed bash env.*PATH.*use env/)
-  })
-
-  it('creates spill files with owner-only permissions and random names', async () => {
-    const result = await runBash(
-      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
-      { spillDir },
-    ).done
-    const path = result.stdout.spillPath!
-    expect(path).toMatch(/dsh-bash-\d+-\d+-[0-9a-f]{12}-stdout\.log$/)
-    const mode = statSync(path).mode & 0o777
-    expect(mode).toBe(0o600)
-  })
-
-  it('defaults spills into a private per-process directory', async () => {
-    const result = await runBash(
-      spec('for i in $(seq 1 200); do printf "line-%04d\\n" $i; done', { stdoutMaxBytes: 500, stderrMaxBytes: 500 }),
-    ).done
-    const dir = dirname(result.stdout.spillPath!)
-    expect(dir).toMatch(/dsh-bash-/)
-    const mode = statSync(dir).mode & 0o777
-    expect(mode).toBe(0o700)
-  })
-
-  it('killGroup never throws, even for EPERM-style failures', () => {
-    const spy = vi.spyOn(process, 'kill').mockImplementation(() => {
-      throw Object.assign(new Error('EPERM'), { code: 'EPERM' })
-    })
-    try {
-      expect(() => { killGroup(12345, 'SIGTERM') }).not.toThrow()
-    } finally {
-      spy.mockRestore()
-    }
-  })
-
-  it('honors AbortSignal on background-style runs (no timeout)', async () => {
-    const controller = new AbortController()
-    const running = runBash(spec('sleep 60', { signal: controller.signal }))
-    setTimeout(() => { controller.abort() }, 50)
-    const result = await running.done
-    expect(result.signal).toBe('SIGTERM')
-  })
-})

packages/bash/bash-local/tsconfig.json

@@ -26,6 +26,9 @@
     {
       "path": "../../bash/bash"
     },
+    {
+      "path": "../../process/process"
+    },
     {
       "path": "../../support/invariants"
     }