@deepseek-ai/dsh-bash-local 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/bash/bash-local/README.md
+README.md: cb8e7f0ae766d9b1c5f1678e77d35992085d3d52
+README.zh.md: 20af9c18998c6f3f0403c50f3a8ac599607dc094

package/README.md

@@ -0,0 +1,46 @@
+# @deepseek-ai/dsh-bash-local
+
+English | [中文](README.zh.md)
+
+Local Service provider for the `@deepseek-ai/dsh-bash` executor seam over the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) service: `LocalBashExecutor` spawns `bash -c <command>` per call as a managed process group through `ctx.subprocess`, 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 subprocess service's.
+
+The package root exports the default and named `LocalBashExecutor` plugin plus its `Config`.
+
+## Config
+
+```yaml
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+  config:
+    cwd: /path/to/workspace   # default: process.cwd()
+    timeoutMs: 120000          # default foreground timeout
+    maxTimeoutMs: 600000       # cap for per-call overrides
+    maxOutputBytes: 64000      # per-stream in-memory cap; overflow spills to disk
+    maxSpillBytes: 67108864    # per-stream full-output spill cap
+    graceMs: 3000              # kill escalation and post-exit pipe-drain grace
+```
+
+## Behavior
+
+- **Spawn per call, no shell state** — every call is a fresh non-login `bash -c` with no rc files.
+- **Configured budgets over managed groups** — `resolve()` fills `workdir`/`timeoutMs`/`stdoutMaxBytes` from config, and every spawn hands the service explicit byte caps, spill cap, and `graceMs`. The grace must be positive, finite, and no greater than [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md), so Node can represent it with one timer. Process-group kills, post-exit pipe draining, tail retention, and bounded spill files are [`dsh-subprocess-local`](../../subprocess/subprocess-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` prevents pagers and ANSI color from garbling results. These values merge as ordinary env under the service'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 with no timeout, and `readOutput()` merges offset-based stdout/stderr reads into one consuming delta, placing stderr under a `[stderr]` marker when present. A running process belongs to the subprocess service, survives executor reloads, and is killed and joined on service disposal. Task ids, ownership, polling, and notices belong to the generic [`ctx.tasks` runtime](../../tasks/tasks/README.md), which the tool layer registers the handle with.
+
+## Model Experience
+
+Indirectly, through `dsh-tool-bash`, which renders this executor's bounded stdout/stderr tails, background-process deltas, spill-file paths, and infrastructure failures.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **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 is hardcoded, and the underlying service's group semantics are POSIX; Windows is unsupported.
+- **A background spawn-failure note is single-delivery** — the subprocess service 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.
+
+Scrub-heuristic and spill-retention caveats live with [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md), which owns those mechanics.

package/README.zh.md

@@ -0,0 +1,46 @@
+# @deepseek-ai/dsh-bash-local
+
+[English](README.md) | 中文
+
+`@deepseek-ai/dsh-bash` 执行器 seam 的本地 Service provider，构建在 [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) 服务之上：`LocalBashExecutor` 每次调用都通过 `ctx.subprocess` 把 `bash -c <command>` 作为受管进程组 spawn，并负责所有 Bash 层职责（命令默认值补全与上限、超时与取消分类、适合模型的终端环境，以及后台读取时面向模型的 stdout/stderr 合并）。以 spill 文件兜底的有界输出、凭据清除、kill 升级和 dispose（资源释放）等进程组机制则由 subprocess 服务负责。
+
+包根目录导出默认与具名的 `LocalBashExecutor` 插件及其 `Config`。
+
+## 配置
+
+```yaml
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+  config:
+    cwd: /path/to/workspace   # default: process.cwd()
+    timeoutMs: 120000          # default foreground timeout
+    maxTimeoutMs: 600000       # cap for per-call overrides
+    maxOutputBytes: 64000      # per-stream in-memory cap; overflow spills to disk
+    maxSpillBytes: 67108864    # per-stream full-output spill cap
+    graceMs: 3000              # kill escalation and post-exit pipe-drain grace
+```
+
+## 行为
+
+- **每次调用都 spawn，不保留 shell 状态**：每次调用都启动新的非登录 `bash -c`，且不读取 rc 文件。
+- **在受管进程组之上应用配置预算**：`resolve()` 从配置补全 `workdir`／`timeoutMs`／`stdoutMaxBytes`，每次 spawn 都向服务传入显式的字节上限、spill 上限与 `graceMs`。该宽限期须为正有限值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)，这样 Node 就能用一个定时器表示它。进程组终止、退出后管道排空、尾部保留与有界 spill 文件是 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 的机制。前台 `BashExecRequest.stdoutMaxBytes` 可为某个受信任调用方提高单次 stdout 捕获预算；stderr 和后台运行仍使用 `maxOutputBytes`。
+- **超时与取消分类**：`run()` 通过同一个 deadline 把经配置钳位的超时与调用方的信号融合；只有执行器自身的超时报告 `timedOut`，上游取消报告 `aborted`，自身因信号终止的命令两者皆不报告（见[超时库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)）。
+- **适合模型的终端环境**：`NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` 防止分页器与 ANSI 颜色破坏结果。这些值作为普通 env 合并，遵循服务的凭据清除与 `DSH_*` 通道规则；调用方的显式条目依旧优先。详见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
+- **后台进程**：`start()` 会立即返回活动的 `BashProcess` 句柄且不应用超时；`readOutput()` 把基于偏移量的 stdout/stderr 读取合并为一条消费式增量，并在存在 stderr 时将其置于 `[stderr]` 标记下。运行中的进程属于 subprocess 服务，可在执行器重载后存活，并在服务 dispose 时被终止且等待退出。task id、所有权、轮询和通知属于通用 [`ctx.tasks` 运行时](../../tasks/tasks/README.md)，工具层会在其中注册该句柄。
+
+## 模型体验
+
+通过 `dsh-tool-bash` 间接影响；该工具会渲染此执行器有界的 stdout/stderr 尾部、后台进程增量、spill 文件路径与基础设施失败。
+
+#### KV Cache 影响
+
+不会直接导致 KV Cache 失效；请求前缀变更由具名消费方负责。
+
+## 已知限制与暂缓事项
+
+- **自身不提供隔离**：此执行器始终以 harness 进程的权限运行命令；需要限制的部署可以组合 [`dsh-bash-sandbox`](../bash-sandbox/README.md)，每次调用的 allow/deny/ask 策略则属于 `tools/pre-execute`。
+- **没有持久 shell 或 PTY**：每次调用都启动新的非登录 `bash -c`；仅持久化 cwd 与交互式终端会话均继续暂缓，直到真实工作流需要它们。
+- **仅支持 POSIX**：`bash` 二进制已硬编码，底层服务的进程组语义也是 POSIX 的；不支持 Windows。
+- **后台 spawn 失败提示只交付一次**：进程管理器不会为从未真正运行的进程缓冲任何输出，因此执行器把 `spawn failed: …` 注入恰好一个 `readOutput()` 增量；丢弃了该增量的读取方无法再恢复它。
+
+凭据清除启发式规则与 spill 保留的注意事项随 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 记录；这些机制归它所有。

package/lib/index.js

@@ -0,0 +1,308 @@
+import z from "@deepseek-ai/schemastery";
+import { BashExecutor } from "@deepseek-ai/dsh-bash";
+import { MAX_TIMER_DELAY_MS, clampTimeout, deadline, timeoutOf } from "@deepseek-ai/dsh-timeout";
+//#region lib/types/index.js
+/**
+* Local Service provider for the bash capability seam over the subprocess
+* capability seam. Public commands run as `bash -c` in a managed process group spawned
+* through `ctx.subprocess`; subclasses may reuse the same mechanics with an
+* explicit argv. 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
+*/
+var __addDisposableResource = function(env, value, async) {
+	if (value !== null && value !== void 0) {
+		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+		var dispose, inner;
+		if (async) {
+			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+			dispose = value[Symbol.asyncDispose];
+		}
+		if (dispose === void 0) {
+			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+			dispose = value[Symbol.dispose];
+			if (async) inner = dispose;
+		}
+		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+		if (inner) dispose = function() {
+			try {
+				inner.call(this);
+			} catch (e) {
+				return Promise.reject(e);
+			}
+		};
+		env.stack.push({
+			value,
+			dispose,
+			async
+		});
+	} else if (async) env.stack.push({ async: true });
+	return value;
+};
+var __disposeResources = (function(SuppressedError) {
+	return function(env) {
+		function fail(e) {
+			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+			env.hasError = true;
+		}
+		var r, s = 0;
+		function next() {
+			while (r = env.stack.pop()) try {
+				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+				if (r.dispose) {
+					var result = r.dispose.call(r.value);
+					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
+						fail(e);
+						return next();
+					});
+				} else s |= 1;
+			} catch (e) {
+				fail(e);
+			}
+			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+			if (env.hasError) throw env.error;
+		}
+		return next();
+	};
+})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+	var e = new Error(message);
+	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/**
+* 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 first into the spawn's explicit env, so a trusted caller's own entry
+* still wins; the subprocess service applies its credential scrub independently.
+*/
+const ENV_OVERRIDES = {
+	NO_COLOR: "1",
+	TERM: "dumb",
+	PAGER: "cat",
+	GIT_PAGER: "cat"
+};
+/** Default SIGTERM→SIGKILL grace period (the `graceMs` config; matches OpenCode's 3s). */
+const DEFAULT_GRACE_MS = 3e3;
+/** Default per-stream spill cap (the `maxSpillBytes` config). */
+const DEFAULT_MAX_SPILL_BYTES = 64 * 1024 * 1024;
+/** Project a settled collect-mode reader into the final CollectedOutput shape. */
+function finalOutput(reader) {
+	const read = reader.readFrom(0);
+	return {
+		text: read.text,
+		truncated: read.lossy,
+		...read.spillPath !== void 0 ? { spillPath: read.spillPath } : {}
+	};
+}
+function assertPositiveFinite(name, value) {
+	if (!Number.isFinite(value) || value <= 0) throw new Error(`bash-local: ${name} must be a positive finite number`);
+}
+/**
+* Local bash executor over `ctx.subprocess`. Bounded output, spill files, and
+* process-group SIGTERM→SIGKILL escalation are the subprocess service'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.
+*/
+var LocalBashExecutor = class LocalBashExecutor extends BashExecutor {
+	static inject = ["subprocess"];
+	static Config = z.object({
+		cwd: z.string(),
+		timeoutMs: z.number().default(12e4),
+		maxTimeoutMs: z.number().default(6e5),
+		maxOutputBytes: z.number().default(64e3),
+		maxSpillBytes: z.number().default(DEFAULT_MAX_SPILL_BYTES),
+		graceMs: z.number().default(DEFAULT_GRACE_MS)
+	});
+	/** Validated config (schemastery applied the defaults before construction). */
+	config;
+	constructor(ctx, config) {
+		super(ctx);
+		this.config = config;
+		assertPositiveFinite("timeoutMs", this.config.timeoutMs);
+		assertPositiveFinite("maxTimeoutMs", this.config.maxTimeoutMs);
+		assertPositiveFinite("maxOutputBytes", this.config.maxOutputBytes);
+		assertPositiveFinite("maxSpillBytes", this.config.maxSpillBytes);
+		assertPositiveFinite("graceMs", this.config.graceMs);
+		if (this.config.graceMs > MAX_TIMER_DELAY_MS) throw new Error(`bash-local: graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`);
+	}
+	/**
+	* Resolve a request into a fully-specified spec: fill `workdir` from
+	* `config.cwd` (else `process.cwd()`), and `timeoutMs` from
+	* `config.timeoutMs`, capped at `config.maxTimeoutMs`. The tool layer calls
+	* this before {@link run}/{@link start}, so those methods receive explicit
+	* values and never re-default.
+	*/
+	resolve(request) {
+		const timeoutMs = clampTimeout(request.timeoutMs, this.config.timeoutMs, this.config.maxTimeoutMs, "bash-local: request.timeoutMs");
+		const stdoutMaxBytes = request.stdoutMaxBytes ?? this.config.maxOutputBytes;
+		assertPositiveFinite("request.stdoutMaxBytes", stdoutMaxBytes);
+		return {
+			command: request.command,
+			workdir: request.workdir ?? this.config.cwd ?? process.cwd(),
+			timeoutMs,
+			stdoutMaxBytes,
+			...request.signal ? { signal: request.signal } : {},
+			...request.stdin !== void 0 ? { stdin: request.stdin } : {},
+			...request.env !== void 0 ? { env: request.env } : {},
+			...request.dshEnv !== void 0 ? { dshEnv: request.dshEnv } : {},
+			sandboxPolicy: request.sandboxPolicy
+		};
+	}
+	/** Map one resolved bash spec and explicit argv onto a fully-specified subprocess spawn. */
+	spawnSpec(spec, argv, stdoutMaxBytes, signal) {
+		const collect = (maxBytes) => ({
+			maxBytes,
+			spill: { maxBytes: this.config.maxSpillBytes }
+		});
+		return {
+			argv,
+			cwd: spec.workdir,
+			stdio: {
+				stdin: spec.stdin !== void 0 ? { data: spec.stdin } : "ignore",
+				stdout: collect(stdoutMaxBytes),
+				stderr: collect(this.config.maxOutputBytes)
+			},
+			graceMs: this.config.graceMs,
+			signal,
+			env: {
+				...ENV_OVERRIDES,
+				...spec.env,
+				...spec.dshEnv
+			}
+		};
+	}
+	/** The collect-mode readers the executor itself requested (present by construction). */
+	static collected(handle) {
+		const { stdout, stderr } = handle.collected;
+		/* v8 ignore start -- collect dispositions expose both readers by the seam contract; defensive. */
+		if (stdout === void 0 || stderr === void 0) throw new Error("bash-local: subprocess implementation dropped a requested collect stream");
+		/* v8 ignore stop */
+		return {
+			stdout,
+			stderr
+		};
+	}
+	async run(spec) {
+		return this.runArgv(spec, [
+			"bash",
+			"-c",
+			spec.command
+		]);
+	}
+	/**
+	* Run an explicit argv with the foreground lifecycle, environment, output,
+	* timeout, and cancellation semantics of this executor. Subclasses use this
+	* after replacing the public command's shell argv at an execution boundary.
+	* @param spec - resolved execution settings and caller-owned command metadata.
+	* @param argv - exact executable and arguments to hand to `ctx.subprocess`.
+	* @returns the settled foreground result with collected output and cause facts.
+	*/
+	async runArgv(spec, argv) {
+		const env_1 = {
+			stack: [],
+			error: void 0,
+			hasError: false
+		};
+		try {
+			const d = __addDisposableResource(env_1, deadline(spec.signal, spec.timeoutMs, "BASH_TIMEOUT"), false);
+			const handle = this.ctx.subprocess.spawn(this.spawnSpec(spec, argv, spec.stdoutMaxBytes, d.signal));
+			const outcome = await handle.done;
+			const collected = LocalBashExecutor.collected(handle);
+			const timedOut = timeoutOf(d.signal, "BASH_TIMEOUT") !== void 0;
+			const aborted = d.signal.aborted && !timedOut;
+			return {
+				...outcome,
+				timedOut,
+				aborted,
+				timeoutMs: spec.timeoutMs,
+				stdout: finalOutput(collected.stdout),
+				stderr: finalOutput(collected.stderr)
+			};
+		} catch (e_1) {
+			env_1.error = e_1;
+			env_1.hasError = true;
+		} finally {
+			__disposeResources(env_1);
+		}
+	}
+	start(spec) {
+		return this.startArgv(spec, [
+			"bash",
+			"-c",
+			spec.command
+		]);
+	}
+	/**
+	* Start an explicit argv with the background lifecycle, environment, output,
+	* cancellation, and process-tree ownership semantics of this executor.
+	* Subclasses use this after replacing the public command's shell argv at an
+	* execution boundary.
+	* @param spec - resolved execution settings and caller-owned command metadata.
+	* @param argv - exact executable and arguments to hand to `ctx.subprocess`.
+	* @returns the live background handle; spawn rejection settles it as killed.
+	*/
+	startArgv(spec, argv) {
+		const running = this.ctx.subprocess.spawn(this.spawnSpec(spec, argv, this.config.maxOutputBytes, spec.signal));
+		const collected = LocalBashExecutor.collected(running);
+		let spawnFailureNote;
+		const consumeSpawnFailure = () => {
+			const note = spawnFailureNote ?? "";
+			spawnFailureNote = void 0;
+			return note;
+		};
+		let stdoutOffset = 0;
+		let stderrOffset = 0;
+		const proc = {
+			status: "running",
+			exitCode: null,
+			signal: null,
+			done: running.done.then((outcome) => {
+				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, collected.stderr.readFrom(0).text, false);
+			}, (error) => {
+				proc.status = "killed";
+				spawnFailureNote = `spawn failed: ${String(error)}`;
+				this.onProcessDone(proc, spawnFailureNote, true, error);
+			}),
+			readOutput: () => {
+				const out = collected.stdout.readFrom(stdoutOffset);
+				const err = collected.stderr.readFrom(stderrOffset);
+				stdoutOffset = out.nextOffset;
+				stderrOffset = err.nextOffset;
+				const errText = err.text.length > 0 ? err.text : consumeSpawnFailure();
+				const separator = out.text.length > 0 && !out.text.endsWith("\n") ? "\n" : "";
+				return {
+					delta: out.text + (errText.length > 0 ? `${separator}[stderr]\n${errText}` : ""),
+					lossy: out.lossy || err.lossy,
+					...out.spillPath !== void 0 ? { stdoutSpillPath: out.spillPath } : {},
+					...err.spillPath !== void 0 ? { stderrSpillPath: err.spillPath } : {}
+				};
+			},
+			kill: () => {
+				if (proc.status !== "running") return false;
+				proc.status = "killed";
+				running.terminate();
+				return true;
+			}
+		};
+		return proc;
+	}
+	/**
+	* 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.
+	* @param _spawnFailed - whether the subprocess promise rejected before a process started.
+	* @param _spawnError - the original spawn rejection reason, which may itself be undefined.
+	*/
+	onProcessDone(_proc, _stderr, _spawnFailed, _spawnError) {}
+};
+//#endregion
+export { ENV_OVERRIDES, LocalBashExecutor, LocalBashExecutor as default };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-bash-local`.
+* @module @deepseek-ai/dsh-bash-local/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-bash-local";
+/** Cordis companion plugin name. */
+const name = "bash-local-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Local Service provider for the bash capability seam over the subprocess
+ * capability seam. Public commands run as `bash -c` in a managed process group spawned
+ * through `ctx.subprocess`; subclasses may reuse the same mechanics with an
+ * explicit argv. 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
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { BashExecutor } from '@deepseek-ai/dsh-bash';
+import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } 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). Bash-tool policy —
+ * merged first into the spawn's explicit env, so a trusted caller's own entry
+ * still wins; the subprocess service applies its credential scrub independently.
+ */
+export declare const ENV_OVERRIDES: {
+    readonly NO_COLOR: "1";
+    readonly TERM: "dumb";
+    readonly PAGER: "cat";
+    readonly GIT_PAGER: "cat";
+};
+/** Plugin config (all optional — `static Config` supplies the defaults). */
+export interface Config {
+    /** Default working directory for commands (default: process.cwd()). */
+    cwd?: string;
+    /** Default foreground timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Upper bound for per-call timeout overrides. */
+    maxTimeoutMs?: number;
+    /** Per-stream in-memory output cap; overflow spills to a temp file. */
+    maxOutputBytes?: number;
+    /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */
+    maxSpillBytes?: number;
+    /** Grace period for kill escalation and inherited pipes; at most `MAX_TIMER_DELAY_MS`. */
+    graceMs?: number;
+}
+/** The shape after schemastery applied the defaults (cwd has none). */
+type ResolvedConfig = Required<Omit<Config, 'cwd'>> & Pick<Config, 'cwd'>;
+/**
+ * Local bash executor over `ctx.subprocess`. Bounded output, spill files, and
+ * process-group SIGTERM→SIGKILL escalation are the subprocess service'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 declare class LocalBashExecutor extends BashExecutor {
+    static inject: string[];
+    static Config: z<Config>;
+    /** Validated config (schemastery applied the defaults before construction). */
+    readonly config: ResolvedConfig;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Resolve a request into a fully-specified spec: fill `workdir` from
+     * `config.cwd` (else `process.cwd()`), and `timeoutMs` from
+     * `config.timeoutMs`, capped at `config.maxTimeoutMs`. The tool layer calls
+     * this before {@link run}/{@link start}, so those methods receive explicit
+     * values and never re-default.
+     */
+    resolve(request: BashExecRequest): BashExecSpec;
+    /** Map one resolved bash spec and explicit argv onto a fully-specified subprocess spawn. */
+    private spawnSpec;
+    /** The collect-mode readers the executor itself requested (present by construction). */
+    private static collected;
+    run(spec: BashExecSpec): Promise<BashRunResult>;
+    /**
+     * Run an explicit argv with the foreground lifecycle, environment, output,
+     * timeout, and cancellation semantics of this executor. Subclasses use this
+     * after replacing the public command's shell argv at an execution boundary.
+     * @param spec - resolved execution settings and caller-owned command metadata.
+     * @param argv - exact executable and arguments to hand to `ctx.subprocess`.
+     * @returns the settled foreground result with collected output and cause facts.
+     */
+    protected runArgv(spec: BashExecSpec, argv: readonly string[]): Promise<BashRunResult>;
+    start(spec: BashExecSpec): BashProcess;
+    /**
+     * Start an explicit argv with the background lifecycle, environment, output,
+     * cancellation, and process-tree ownership semantics of this executor.
+     * Subclasses use this after replacing the public command's shell argv at an
+     * execution boundary.
+     * @param spec - resolved execution settings and caller-owned command metadata.
+     * @param argv - exact executable and arguments to hand to `ctx.subprocess`.
+     * @returns the live background handle; spawn rejection settles it as killed.
+     */
+    protected startArgv(spec: BashExecSpec, argv: readonly string[]): BashProcess;
+    /**
+     * 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.
+     * @param _spawnFailed - whether the subprocess promise rejected before a process started.
+     * @param _spawnError - the original spawn rejection reason, which may itself be undefined.
+     */
+    protected onProcessDone(_proc: BashProcess, _stderr: string, _spawnFailed: boolean, _spawnError?: unknown): void;
+}
+export default LocalBashExecutor;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-bash-local`.
+ * @module @deepseek-ai/dsh-bash-local/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "bash-local-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@deepseek-ai/dsh-bash-local",
+  "description": "Local-subprocess implementation of the DeepSeek Harness bash executor seam",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/bash/bash-local"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-bash": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-bash": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess-local": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}