@deepseek-ai/dsh-bash-sandbox 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-sandbox/README.md
+README.md: 44321d7ef26e9e4399438f61b3fdfbfa2e4d8c11
+README.zh.md: f3e110c049871a5a6121716307aaa3d1d1f3eedb

package/README.md

@@ -0,0 +1,88 @@
+# @deepseek-ai/dsh-bash-sandbox
+
+English | [中文](README.zh.md)
+
+Sandbox-consuming Service provider for the [`@deepseek-ai/dsh-bash`](../bash/) executor seam. Load it **instead of** `@deepseek-ai/dsh-bash-local`, together with a [`ctx.sandbox`](../../sandbox/sandbox/) provider (e.g. [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)) and a [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) (which owns the default mode + workspace root, shared with the sandboxed filesystem) — no alternate tool plugin is needed; `dsh-tool-bash` detects the executor's `sandboxMode` capability and adds the escalation fields.
+
+The package root exports the default and named `SandboxBashExecutor` plugin plus its `Config`; result-classification helpers stay internal.
+
+Every command is confined by handing the provider the exact `['bash', '-c', command]` argv this executor is about to spawn and spawning the returned argv directly. With the shipped native runners, the inner Bash retains shell semantics and evaluates `BASH_ENV` only after the runner establishes confinement. WHICH platform runner confines it — and whether one is usable at all (fail closed with a structured `SANDBOX_UNAVAILABLE` error, never a silent unconfined run) — is the provider's concern; this package owns the bash side only.
+
+| Mode | File effects |
+|---|---|
+| `read-only` (default) | No writes anywhere (of `/dev`, only the `/dev/null` node is writable, so `>/dev/null` keeps working) |
+| `workspace-write` | Writes only under `workspaceRoot` + `/tmp` (ephemeral under bwrap, the host `/tmp` under Landlock, `/private/tmp` plus the per-user temp dir under Seatbelt) |
+| `danger-full-access` | No confinement; the provider is never consulted. Foreground results carry `sandbox: { mode, denied: false }`; background process handles carry no sandbox facts. |
+
+Semantics:
+
+- **Denials are result facts.** A failed run whose stderr carries the selected backend's own denial dialect — the signatures the provider stamps on every wrap (EROFS text under bwrap, EACCES under Landlock, EPERM under Seatbelt) — is reported as `BashRunResult.sandbox.denied: true` (conservative classification, read from the collected stderr tail); every CONFINED run also carries the mode it executed under (`result.sandbox.mode`) and the provider's enforcement completeness (`result.sandbox.enforcement`: `full`, or `partial` on an older Landlock ABI).
+- **The runner path or syscall must match.** Before a process starts, a rejection is attributed to the runner only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` with either an `error.path` equal to provider argv[0] or, when `error.path` is absent, an exact `syscall: 'spawn <runner>'`. A present path also requires `syscall: 'spawn'` or the exact `spawn <runner>`. This covers a missing runner, a non-executable runner, or an executable script whose shebang interpreter is unavailable. A bare `syscall: 'spawn'` without an exact error path, any other code, an invalid or unusable workdir, a resource failure, an unrelated syscall, or an unstructured rejection retains the local executor's command-start failure semantics. Foreground execution throws `SANDBOX_UNAVAILABLE` with the original spawn detail, while asynchronous background settlement stamps `runnerFailed: true` and `denied: false`. If a `SubprocessService` synchronously throws the same runner-identifying `ENOENT`/`EACCES` shape, background start throws `SANDBOX_UNAVAILABLE`; other synchronous errors propagate unchanged. After a process starts, a rule's optional exit-code check and a remaining fatal stderr line must both match after exact informational-line exclusions. A match takes priority over denial; foreground execution throws `SANDBOX_UNAVAILABLE` with the matched fatal line, while a settled background process stamps `process.sandbox.runnerFailed`, which the bash producer renders through generic `task_output`. Confined background handles retain their mode/enforcement facts and release per-process accounting in either path.
+- **Deployment fallback, per-call policy.** [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) resolves a complete `SandboxExecutionPolicy` for every tool call: the calling session supplies its mode override and immutable cwd root, while deployment config supplies the fallbacks for agentless calls. An approved escalation changes only that policy's mode; its session root stays attached. `resolve()` carries the policy onto the spec, so overlapping commands from different projects run, classify, and report under their own roots and modes. The capability fact `ctx.bash.sandboxMode` reports the configured default so the tool layer advertises escalation only when this executor is mounted; the static bash tool description separately owns denial and escalation guidance.
+- **File effects only.** Network and process visibility are deliberately not restricted — the mode vocabulary does not pretend to cover what the backend does not enforce.
+- Process mechanics (spawn, process-group kills, output collection/spill, background handles, credential scrub) are inherited from [`dsh-bash-local`](../bash-local/); runner selection lives in [`dsh-sandbox-local`](../../sandbox/sandbox-local/).
+
+Deny-only at the seam: a denial is a reported fact, and this executor never negotiates permissions itself — the approval question lives in the tool layer (`dsh-tool-bash`), which drives the override this package honors.
+
+```yaml
+- id: sandbox
+  name: '@deepseek-ai/dsh-sandbox-local'
+- id: sandbox-policy
+  name: '@deepseek-ai/dsh-sandbox-policy'
+  config:
+    mode: read-only
+    workspaceRoot: !!js process.cwd() # fallback for calls without a session cwd
+- id: bash
+  name: '@deepseek-ai/dsh-bash-sandbox'
+```
+
+## Model Experience
+
+### Bash tool schema, indirectly
+
+#### What the model sees
+
+The generated [`dsh-tool-bash` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash) are the baseline. By advertising a confining `sandboxMode`, this backend augments `bash` with `sandbox_permissions` using enum `workspace-write` | `danger-full-access` and with `justification`. The policy owner separately contributes the current capability-neutral `sandbox:policy` context.
+
+#### Token effect
+
+Small fixed schema increment on requests where `bash` is visible, plus the current-policy clause owned by `dsh-sandbox-policy`.
+
+#### KV Cache effect
+
+A standing-policy change appends a complete owner-rendered context snapshot after retained history, preserving the existing system/history prefix byte-for-byte. Changing executor capabilities alters the `bash` schema.
+
+### Bash tool result, indirectly
+
+#### What the model sees
+
+After ordinary bounded output, a denied call appends exactly `[sandbox: file access denied under <mode> mode]`. When escalation is available it next appends `[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]`. A settled background runner failure instead appends `[sandbox: the sandbox runner itself failed under <mode> mode — the command did not run; this is a sandbox problem, not a command failure]`.
+
+#### Token effect
+
+Zero additional tokens on an unremarkable allowed run beyond ordinary output. Denial or failure adds the quoted conditional marker, retained until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Bash tool error, indirectly
+
+#### What the model sees
+
+If no runner can enforce a confined mode, the foreground call propagates the [`SANDBOX_UNAVAILABLE` error owned by `dsh-sandbox`](../../sandbox/sandbox/README.md#confinement-error-indirectly). A runner-attributable spawn failure supplies the original spawn error as detail; a rejection without `ENOENT`/`EACCES` path or syscall evidence that names argv[0] remains an ordinary command-start error. A settled runner failure supplies the matched fatal stderr line and preserves the original stderr collection. When present, the appended `Runner failure: <detail>` is the authoritative diagnosis; the preceding backend-install text is the generic `SANDBOX_UNAVAILABLE` prefix.
+
+#### Token effect
+
+Conditional error text is visible for that call and retained in history until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **Confinement covers file effects only** — network access and process visibility are unchanged, so the modes are not a general-purpose security sandbox.
+- **Denials are inferred from failed-command stderr** — backend signatures make the inference portable, but a matching application error can be classified as a denial and a denial omitted from the retained tail can be missed.
+- **An asynchronously observed background runner failure has no immediate error channel** — it is recorded on the settled process and surfaces when the caller reads the generic task with `task_output`; a synchronous `SubprocessService` throw that names the runner path instead fails `start()` immediately.
+- **`danger-full-access` deliberately bypasses `ctx.sandbox`** — it is an explicit unconfined mode, not a wider sandbox profile.

package/README.zh.md

@@ -0,0 +1,88 @@
+# @deepseek-ai/dsh-bash-sandbox
+
+[English](README.md) | 中文
+
+这是使用沙箱能力的 [`@deepseek-ai/dsh-bash`](../bash/) 执行器 seam Service provider。加载它时，应**用它替代** `@deepseek-ai/dsh-bash-local`，并同时加载 [`ctx.sandbox`](../../sandbox/sandbox/) 提供方（例如 [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)）及 [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/)；默认模式和工作区根目录由后者负责，并与受沙箱约束的文件系统共享这些设置。无需使用替代工具插件；`dsh-tool-bash` 会检测执行器的 `sandboxMode` 能力并添加升权字段。
+
+包根目录导出默认与具名的 `SandboxBashExecutor` 插件及其 `Config`；结果分类 helper 保留在内部。
+
+每条命令的限制方式都是：把本执行器即将 spawn 的精确 `['bash', '-c', command]` argv 交给提供方，并直接 spawn 返回的 argv。使用随附的原生 runner 时，内层 Bash 保留 shell 语义，并且只在 runner 建立约束后才求值 `BASH_ENV`。由哪种平台 runner 执行限制，以及是否有 runner 可用，属于提供方职责；若无可用 runner，则按失败关闭原则拒绝执行并返回结构化 `SANDBOX_UNAVAILABLE` 错误，绝不能静默地无约束运行。本包只负责 bash 侧。
+
+| 模式 | 文件影响 |
+|---|---|
+| `read-only`（默认） | 任何位置都不可写（在 `/dev` 中只有 `/dev/null` 节点可写，因此 `>/dev/null` 仍可正常工作） |
+| `workspace-write` | 只能写入 `workspaceRoot` + `/tmp`（在 bwrap 下为临时目录，在 Landlock 下为宿主 `/tmp`，在 Seatbelt 下为 `/private/tmp` 加每用户临时目录） |
+| `danger-full-access` | 不作限制；绝不咨询提供方。前台结果携带 `sandbox: { mode, denied: false }`；后台进程句柄不携带沙箱事实。 |
+
+语义：
+
+- **拒绝是结果事实。** 如果一次失败运行的 stderr 包含所选后端自身的拒绝方言，即提供方在每次包装时加上的特征（bwrap 下的 EROFS 文本、Landlock 下的 EACCES、Seatbelt 下的 EPERM），则结果报告 `BashRunResult.sandbox.denied: true`（从已收集的 stderr 尾部进行保守分类）。每次受限制运行还会携带执行时模式（`result.sandbox.mode`）与提供方强制执行完整性（`result.sandbox.enforcement`：`full`，或在较旧 Landlock ABI 上为 `partial`）。
+- **Runner 路径或 syscall 必须匹配。** 进程启动前，调用方拥有的 workdir 必须经独立验证可用，Node 必须报告 `ENOENT` 或 `EACCES`，并且错误必须符合以下一种形态：`error.path` 等于提供方返回的 `argv[0]`，同时 `syscall` 为 `'spawn'` 或精确的 `'spawn <runner>'`；或者 `error.path` 不存在，同时 `syscall` 为精确的 `'spawn <runner>'`。这样可以识别缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本。没有精确错误路径的裸 `syscall: 'spawn'`、任何其他错误码、无效或不可用的 workdir、资源失败、无关 syscall 或无结构拒绝仍保留本地执行器的命令启动失败语义。前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带原始 spawn 错误详情，异步后台结算则会标记 `runnerFailed: true` 和 `denied: false`。如果 `SubprocessService` 同步抛出同样能指明 runner 的 `ENOENT`／`EACCES` 形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，先按整行精确匹配排除信息性行，随后规则的可选退出码检查和余下 stderr 中的一行致命诊断必须同时匹配。匹配结果优先于拒绝；前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带匹配到的致命行，已结算的后台进程则会标记 `process.sandbox.runnerFailed`，Bash 结果生成方通过通用 `task_output` 渲染它。无论走哪条路径，受限制的后台句柄都会保留自身的模式／强制执行事实，并释放每进程计数。
+- **部署回退，每次调用策略。** [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) 为每次工具调用解析完整的 `SandboxExecutionPolicy`：调用会话提供自身的模式覆盖与不可变 cwd 根目录，部署配置则为无 agent（智能体）调用提供回退。已批准的升权只更改该策略的模式，会话根目录仍然附着其上。`resolve()` 把策略带入 spec，因此来自不同项目的重叠命令会在各自的根目录与模式下运行、分类和报告。能力事实 `ctx.bash.sandboxMode` 报告已配置的默认值，因此工具层只在装载该执行器时才公布升权；静态 bash 工具描述则单独负责拒绝与升权引导。
+- **只限制文件影响。** 设计上不限制网络与进程可见性：模式词汇不会声称覆盖后端未强制执行的范围。
+- 进程机制（spawn、进程组终止、输出收集／spill、后台句柄、凭证清理）继承自 [`dsh-bash-local`](../bash-local/)；runner 选择位于 [`dsh-sandbox-local`](../../sandbox/sandbox-local/)。
+
+该 seam 只报告拒绝：拒绝是一项结果事实，本执行器绝不自行协商权限。批准问题位于工具层（`dsh-tool-bash`），由它设置本包所遵守的模式覆盖值。
+
+```yaml
+- id: sandbox
+  name: '@deepseek-ai/dsh-sandbox-local'
+- id: sandbox-policy
+  name: '@deepseek-ai/dsh-sandbox-policy'
+  config:
+    mode: read-only
+    workspaceRoot: !!js process.cwd() # fallback for calls without a session cwd
+- id: bash
+  name: '@deepseek-ai/dsh-bash-sandbox'
+```
+
+## 模型体验
+
+### 间接的 Bash 工具 schema
+
+#### 模型看到的内容
+
+基线是生成的 [`dsh-tool-bash` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-bash)。通过公布表明启用隔离的 `sandboxMode` 能力，此后端会为 `bash` 增加 `sandbox_permissions`，其 enum 为 `workspace-write` | `danger-full-access`，并增加 `justification`。策略归属方会另行贡献当前且不区分具体能力的 `sandbox:policy` 上下文。
+
+#### Token 影响
+
+在 `bash` 可见的请求上，schema 固定增加少量内容，另有一条由 `dsh-sandbox-policy` 负责的当前策略子句。
+
+#### KV Cache 影响
+
+常驻策略变化会在保留的历史之后追加一份由归属方渲染的完整上下文快照，并使既有 system/history 前缀保持逐字节不变。更改执行器能力会改变 `bash` schema。
+
+### 间接的 Bash 工具结果
+
+#### 模型看到的内容
+
+在普通有界输出之后，被拒绝的调用会精确追加 `[sandbox: file access denied under <mode> mode]`。当升权可用时，接下来精确追加 `[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]`。已结算的后台 runner 失败则追加 `[sandbox: the sandbox runner itself failed under <mode> mode — the command did not run; this is a sandbox problem, not a command failure]`。
+
+#### Token 影响
+
+除普通输出外，正常允许的运行不会增加 token。拒绝或失败会增加上述有条件标记，并保留到上下文压缩（context compaction）。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+
+### 间接的 Bash 工具错误
+
+#### 模型看到的内容
+
+如果没有 runner 能强制执行受限模式，前台调用会传播 [`SANDBOX_UNAVAILABLE` 错误](../../sandbox/sandbox/README.md#confinement-error-indirectly)；该错误由 `dsh-sandbox` 定义。判定为 runner 失败的 spawn 错误会以原始 spawn 错误作为详细信息；如果拒绝没有通过 `ENOENT`／`EACCES` 的 `path` 或 `syscall` 证据指明 `argv[0]`，它仍是普通的命令启动错误。已结算的 runner 失败则以匹配到的致命 stderr 行作为详细信息，并保留原始 stderr 收集结果。如果追加了 `Runner failure: <detail>`，它就是权威诊断；前面的后端安装文本只是通用的 `SANDBOX_UNAVAILABLE` 前缀。
+
+#### Token 影响
+
+该次调用会在相应条件下显示错误文本，该文本会保留在历史记录中直到上下文压缩。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **限制只覆盖文件影响**：网络访问与进程可见性不变，因此这些模式不是通用安全沙箱。
+- **拒绝从失败命令的 stderr 推断**：后端特征使该推断可跨平台使用，但包含相同后端特征的应用错误可能被分类为拒绝，也可能遗漏未出现在保留尾部中的拒绝。
+- **异步观测到的后台 runner 失败没有即时错误通道**：它记录在已结算进程上，并在调用方使用 `task_output` 读取通用任务时呈现；`SubprocessService` 同步抛出的错误包含 runner 路径时，则会使 `start()` 立即失败。
+- **`danger-full-access` 有意绕过 `ctx.sandbox`**：它是显式无约束模式，不是更宽的沙箱 profile。

package/lib/index.js

@@ -0,0 +1,237 @@
+import { SandboxUnavailableError } from "@deepseek-ai/dsh-sandbox";
+import { LocalBashExecutor } from "@deepseek-ai/dsh-bash-local";
+import { accessSync, constants, statSync } from "node:fs";
+//#region lib/types/helpers.js
+/**
+* Internal sandbox-result classification helpers.
+*
+* @module @deepseek-ai/dsh-bash-sandbox/helpers
+*/
+/** Node-local spawn codes proven to identify executable resolution or permission failure. */
+const EXECUTABLE_SPAWN_CODES = new Set(["EACCES", "ENOENT"]);
+/** Whether the caller-owned spawn cwd can be entered. */
+function isUsableWorkdir(path) {
+	try {
+		if (!statSync(path).isDirectory()) return false;
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Attribute only Node ENOENT/EACCES failures whose error path equals argv[0]
+* after independently ruling out the caller-owned cwd. A supplied error path
+* must exactly identify the runner; without one, the syscall must. With a
+* usable cwd, these codes describe resolution or execute permission for that
+* argv[0] or its shebang interpreter.
+* The workdir is checked at classification time, not atomically with spawn;
+* concurrent path replacement may change attribution but cannot permit an
+* unconfined execution.
+* @param error - the original spawn rejection.
+* @param runnerProgram - provider argv[0], the executable that establishes confinement.
+* @param workdir - the caller-owned spawn cwd, checked independently for usability.
+* @returns whether the rejection has executable-specific runner evidence.
+*/
+function isRunnerSpawnFailure(error, runnerProgram, workdir) {
+	if (runnerProgram === void 0 || !isUsableWorkdir(workdir)) return false;
+	if (typeof error !== "object" || error === null) return false;
+	const { code, path, syscall } = error;
+	if (typeof code !== "string" || !EXECUTABLE_SPAWN_CODES.has(code)) return false;
+	if (typeof syscall !== "string") return false;
+	const exactSyscall = `spawn ${runnerProgram}`;
+	if (path === void 0) return syscall === exactSyscall;
+	if (typeof path !== "string" || path.length === 0 || path !== runnerProgram) return false;
+	return syscall === "spawn" || syscall === exactSyscall;
+}
+/**
+* Classify a failed run against the selected backend's denial dialect.
+* @param result - settled foreground run.
+* @param signatures - case-insensitive denial substrings from the active wrap.
+* @returns whether the failed run matches that denial dialect.
+*/
+function classifyDenial(result, signatures) {
+	return matchesSignature(result.exitCode, result.stderr.text, signatures);
+}
+/**
+* Classify one settled process against the selected backend's structured
+* runner-failure rules. Each rule requires a nonzero exit, its optional
+* exit-code gate, and a fatal signature on one stderr line after exact
+* informational lines are excluded.
+* @param exitCode - process exit code; null means signal termination.
+* @param stderr - collected stderr text, left unchanged.
+* @param rules - structured runner-failure rules from the active wrap.
+* @returns the first matching fatal line, or undefined when evidence is insufficient.
+*/
+function classifyRunnerFailure(exitCode, stderr, rules) {
+	if (exitCode === null || exitCode === 0) return void 0;
+	const lines = stderr.split(/\r?\n/);
+	for (const rule of rules) {
+		if (rule.allowedExitCodes !== void 0 && !rule.allowedExitCodes.includes(exitCode)) continue;
+		const informationalLines = new Set((rule.informationalLines ?? []).map((line) => line.toLowerCase()));
+		const fatalSignatures = rule.fatalSignatures.filter((signature) => signature.trim().length > 0).map((signature) => signature.toLowerCase());
+		for (const line of lines) {
+			const lowered = line.toLowerCase();
+			if (informationalLines.has(lowered)) continue;
+			if (fatalSignatures.some((signature) => lowered.includes(signature))) return { detail: line };
+		}
+	}
+}
+/**
+* Match a non-zero exit against case-insensitive stderr signatures.
+* @param exitCode - process exit code; null means signal termination.
+* @param stderr - collected stderr text.
+* @param signatures - substrings identifying the selected backend's dialect.
+* @returns whether this is a non-zero exit whose stderr matches a signature.
+*/
+function matchesSignature(exitCode, stderr, signatures) {
+	if (exitCode === null || exitCode === 0) return false;
+	const lowered = stderr.toLowerCase();
+	return signatures.some((signature) => lowered.includes(signature.toLowerCase()));
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Sandbox-consuming bash executor. It wraps the exact local bash argv through
+* `ctx.sandbox`, inherits local process mechanics, and reports the selected
+* mode, enforcement, and denial facts. Positive runner-launch evidence means
+* the command never ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while
+* background processes carry `runnerFailed`; other spawn rejections retain
+* local-executor semantics. The tool owns approval and passes a complete per-call policy.
+* @module @deepseek-ai/dsh-bash-sandbox
+*/
+/**
+* Registers as `ctx.bash` in place of the local executor and requires a
+* `ctx.sandbox` provider plus `ctx.sandboxPolicy`; the tool layer is
+* unchanged. Tool calls pass the calling session's resolved policy; direct
+* calls fall back to deployment policy. `result.sandbox` reports the mode and
+* enforcement actually used.
+*/
+var SandboxBashExecutor = class extends LocalBashExecutor {
+	static inject = [
+		"subprocess",
+		"sandbox",
+		"sandboxPolicy"
+	];
+	mode;
+	/**
+	* Per-process confinement facts retained until settlement. Providers may
+	* vary enforcement and diagnostic dialect between overlapping calls, so a
+	* shared latest-wrap value would classify a process against the wrong facts.
+	* Unconfined processes have no entry.
+	*/
+	processFacts = /* @__PURE__ */ new Map();
+	constructor(ctx, config) {
+		super(ctx, config);
+		this.mode = ctx.sandboxPolicy.defaultMode;
+	}
+	/** The configured default mode — the capability fact the tool layer reads. */
+	get sandboxMode() {
+		return this.mode;
+	}
+	/**
+	* Stamp a complete per-call policy onto the spec. Tool calls supply the
+	* calling session's resolved mode and root; lower-level callers fall back to
+	* the deployment policy.
+	*/
+	resolve(request) {
+		return {
+			...super.resolve(request),
+			sandboxPolicy: request.sandboxPolicy ?? this.ctx.sandboxPolicy.resolve()
+		};
+	}
+	async run(spec) {
+		const policy = spec.sandboxPolicy;
+		const { mode } = policy;
+		if (mode === "danger-full-access") return {
+			...await super.run(spec),
+			sandbox: {
+				mode,
+				denied: false
+			}
+		};
+		const confined = this.confine(spec.command, {
+			...policy,
+			mode
+		});
+		let result;
+		try {
+			result = await this.runArgv(spec, confined.argv);
+		} catch (error) {
+			if (spec.signal?.aborted === true) spec.signal.throwIfAborted();
+			if (isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) throw new SandboxUnavailableError(mode, String(error));
+			throw error;
+		}
+		const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, confined.runnerFailureRules);
+		if (runnerFailure !== void 0) throw new SandboxUnavailableError(mode, runnerFailure.detail);
+		return {
+			...result,
+			sandbox: {
+				mode,
+				denied: classifyDenial(result, confined.denialSignatures),
+				enforcement: confined.enforcement
+			}
+		};
+	}
+	start(spec) {
+		const policy = spec.sandboxPolicy;
+		const { mode } = policy;
+		if (mode === "danger-full-access") return super.start(spec);
+		const confined = this.confine(spec.command, {
+			...policy,
+			mode
+		});
+		let proc;
+		try {
+			proc = this.startArgv(spec, confined.argv);
+		} catch (error) {
+			if (isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) throw new SandboxUnavailableError(mode, String(error));
+			throw error;
+		}
+		const { enforcement, denialSignatures, runnerFailureRules } = confined;
+		this.processFacts.set(proc, {
+			mode,
+			enforcement,
+			denialSignatures,
+			runnerFailureRules,
+			runnerProgram: confined.argv[0],
+			workdir: spec.workdir
+		});
+		return proc;
+	}
+	/**
+	* Stamp per-process sandbox facts before `done` settles. Full-access processes
+	* have no facts; signal deaths are not denials.
+	*/
+	onProcessDone(proc, stderr, spawnFailed, spawnError) {
+		const facts = this.processFacts.get(proc);
+		if (facts !== void 0) {
+			this.processFacts.delete(proc);
+			const runnerFailed = spawnFailed ? isRunnerSpawnFailure(spawnError, facts.runnerProgram, facts.workdir) : classifyRunnerFailure(proc.exitCode, stderr, facts.runnerFailureRules) !== void 0;
+			proc.sandbox = {
+				mode: facts.mode,
+				denied: !runnerFailed && matchesSignature(proc.exitCode, stderr, facts.denialSignatures),
+				enforcement: facts.enforcement,
+				...runnerFailed ? { runnerFailed } : {}
+			};
+		}
+		super.onProcessDone(proc, stderr, spawnFailed, spawnError);
+	}
+	/**
+	* Wrap one shell command via the `ctx.sandbox` provider. Provider errors
+	* propagate unchanged; the returned argv is handed directly to the local
+	* executor's subprocess path.
+	* @param command - shell source for the confined inner `bash -c`.
+	* @param policy - resolved confined execution policy.
+	* @returns the provider's exact argv and settlement-classification facts.
+	*/
+	confine(command, policy) {
+		return this.ctx.sandbox.confine([
+			"bash",
+			"-c",
+			command
+		], policy);
+	}
+};
+//#endregion
+export { SandboxBashExecutor, SandboxBashExecutor as default };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-bash-sandbox`.
+* @module @deepseek-ai/dsh-bash-sandbox/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-bash-sandbox";
+/** Cordis companion plugin name. */
+const name = "bash-sandbox-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/helpers.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Internal sandbox-result classification helpers.
+ *
+ * @module @deepseek-ai/dsh-bash-sandbox/helpers
+ */
+import type { BashRunResult } from '@deepseek-ai/dsh-bash';
+import type { RunnerFailureRule } from '@deepseek-ai/dsh-sandbox';
+/**
+ * Attribute only Node ENOENT/EACCES failures whose error path equals argv[0]
+ * after independently ruling out the caller-owned cwd. A supplied error path
+ * must exactly identify the runner; without one, the syscall must. With a
+ * usable cwd, these codes describe resolution or execute permission for that
+ * argv[0] or its shebang interpreter.
+ * The workdir is checked at classification time, not atomically with spawn;
+ * concurrent path replacement may change attribution but cannot permit an
+ * unconfined execution.
+ * @param error - the original spawn rejection.
+ * @param runnerProgram - provider argv[0], the executable that establishes confinement.
+ * @param workdir - the caller-owned spawn cwd, checked independently for usability.
+ * @returns whether the rejection has executable-specific runner evidence.
+ */
+export declare function isRunnerSpawnFailure(error: unknown, runnerProgram: string | undefined, workdir: string): boolean;
+/** Fatal runner evidence retained for infrastructure-error detail. */
+interface RunnerFailureMatch {
+    /** The original stderr line that matched a fatal signature. */
+    detail: string;
+}
+/**
+ * Classify a failed run against the selected backend's denial dialect.
+ * @param result - settled foreground run.
+ * @param signatures - case-insensitive denial substrings from the active wrap.
+ * @returns whether the failed run matches that denial dialect.
+ */
+export declare function classifyDenial(result: BashRunResult, signatures: readonly string[]): boolean;
+/**
+ * Classify one settled process against the selected backend's structured
+ * runner-failure rules. Each rule requires a nonzero exit, its optional
+ * exit-code gate, and a fatal signature on one stderr line after exact
+ * informational lines are excluded.
+ * @param exitCode - process exit code; null means signal termination.
+ * @param stderr - collected stderr text, left unchanged.
+ * @param rules - structured runner-failure rules from the active wrap.
+ * @returns the first matching fatal line, or undefined when evidence is insufficient.
+ */
+export declare function classifyRunnerFailure(exitCode: number | null, stderr: string, rules: readonly RunnerFailureRule[]): RunnerFailureMatch | undefined;
+/**
+ * Match a non-zero exit against case-insensitive stderr signatures.
+ * @param exitCode - process exit code; null means signal termination.
+ * @param stderr - collected stderr text.
+ * @param signatures - substrings identifying the selected backend's dialect.
+ * @returns whether this is a non-zero exit whose stderr matches a signature.
+ */
+export declare function matchesSignature(exitCode: number | null, stderr: string, signatures: readonly string[]): boolean;
+export {};
+//# sourceMappingURL=helpers.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Sandbox-consuming bash executor. It wraps the exact local bash argv through
+ * `ctx.sandbox`, inherits local process mechanics, and reports the selected
+ * mode, enforcement, and denial facts. Positive runner-launch evidence means
+ * the command never ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while
+ * background processes carry `runnerFailed`; other spawn rejections retain
+ * local-executor semantics. The tool owns approval and passes a complete per-call policy.
+ * @module @deepseek-ai/dsh-bash-sandbox
+ */
+import { Context } from '@deepseek-ai/cordis';
+import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash';
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local';
+import type { Config as LocalConfig } from '@deepseek-ai/dsh-bash-local';
+/**
+ * Plugin config: the local executor's knobs, verbatim. The sandbox policy —
+ * the default mode and fallback `workspace-write` root — is NOT here: it lives
+ * on `ctx.sandboxPolicy` (`@deepseek-ai/dsh-sandbox-policy`), which resolves
+ * each calling session's mode and cwd for every enforcing capability. The runner
+ * choice is likewise the `ctx.sandbox` provider's config, not this executor's.
+ */
+export type Config = LocalConfig;
+/**
+ * Registers as `ctx.bash` in place of the local executor and requires a
+ * `ctx.sandbox` provider plus `ctx.sandboxPolicy`; the tool layer is
+ * unchanged. Tool calls pass the calling session's resolved policy; direct
+ * calls fall back to deployment policy. `result.sandbox` reports the mode and
+ * enforcement actually used.
+ */
+export declare class SandboxBashExecutor extends LocalBashExecutor {
+    static inject: string[];
+    private readonly mode;
+    /**
+     * Per-process confinement facts retained until settlement. Providers may
+     * vary enforcement and diagnostic dialect between overlapping calls, so a
+     * shared latest-wrap value would classify a process against the wrong facts.
+     * Unconfined processes have no entry.
+     */
+    private readonly processFacts;
+    constructor(ctx: Context, config: Config);
+    /** The configured default mode — the capability fact the tool layer reads. */
+    get sandboxMode(): SandboxMode;
+    /**
+     * Stamp a complete per-call policy onto the spec. Tool calls supply the
+     * calling session's resolved mode and root; lower-level callers fall back to
+     * the deployment policy.
+     */
+    resolve(request: BashExecRequest): BashExecSpec;
+    run(spec: BashExecSpec): Promise<BashRunResult>;
+    start(spec: BashExecSpec): BashProcess;
+    /**
+     * Stamp per-process sandbox facts before `done` settles. Full-access processes
+     * have no facts; signal deaths are not denials.
+     */
+    protected onProcessDone(proc: BashProcess, stderr: string, spawnFailed: boolean, spawnError?: unknown): void;
+    /**
+     * Wrap one shell command via the `ctx.sandbox` provider. Provider errors
+     * propagate unchanged; the returned argv is handed directly to the local
+     * executor's subprocess path.
+     * @param command - shell source for the confined inner `bash -c`.
+     * @param policy - resolved confined execution policy.
+     * @returns the provider's exact argv and settlement-classification facts.
+     */
+    private confine;
+}
+export default SandboxBashExecutor;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-bash-sandbox`.
+ * @module @deepseek-ai/dsh-bash-sandbox/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "bash-sandbox-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,53 @@
+{
+  "name": "@deepseek-ai/dsh-bash-sandbox",
+  "description": "Sandbox-consuming implementation of the DeepSeek Harness bash executor seam (confines every command via ctx.sandbox, reports denial/enforcement result facts)",
+  "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-sandbox"
+  },
+  "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-bash-local": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sandbox": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-bash": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-bash-local": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess-local": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sandbox": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sandbox-local": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/node-addon-landlock-run": "0.0.1"
+  }
+}