@deepseek-ai/dsh-bash-sandbox 0.1.6-alpha.1 → 0.1.7-alpha.1

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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/shell/bash-sandbox/README.md
-README.md: d9dbc85252a202dc7800eb727abd7700f5989fae
-README.zh.md: 23ca4b5c59da2998b2b0aa546954591bf62da546
+README.md: fea09e4ce13b0e7bd2841ff069c2aa61b30731bd
+README.zh.md: 5daed6969cf1e66cff2241423d010aa0b860beb5

package/README.md

@@ -81,14 +81,14 @@ The executor is the sandboxing Service Provider for the `ctx.shell` seam: it inh
 
 | File | Role |
 |---|---|
-| [`src/index.ts`](src/index.ts) | Plugin entry: `SandboxBashExecutor`, per-process fact retention, run/start wrapping |
+| [`src/index.ts`](src/index.ts) | Plugin entry: `SandboxBashExecutor`, per-process fact retention, execution preparation |
 | [`src/helpers.ts`](src/helpers.ts) | Denial, runner-failure, and runner-spawn-failure classification |
 | — | No runtime invariant companion is published; classification is observable in results, and this package exposes no independent event sequence or mutable data relation beyond contracts enforced at its owning seam. |
 | `tests/` | Exercised behavior across the bwrap, Landlock, and Seatbelt runners |
 
 ### Main flow
 
-For a confined mode, `resolve()` stamps the per-call policy (the session's mode override, or the deployment fallback); `run` and `start` wrap the bash argv through the provider and hand the confined argv to the inherited subprocess path. At settlement the executor classifies the outcome: a runner failure outranks a denial because the command never ran, a failed run whose stderr carries the backend's denial dialect is reported `denied: true`, and every confined run carries its mode and enforcement facts. `danger-full-access` bypasses the provider entirely and stamps `denied: false`.
+For a confined mode, `resolve()` stamps the per-call policy (the session's mode override, or the deployment fallback); `execute` awaits preparation of the bash argv through the provider and hands the confined argv to the inherited subprocess path. At settlement the executor classifies the outcome: a runner failure outranks a denial because the command never ran, a failed run whose stderr carries the backend's denial dialect is reported `denied: true`, and every confined run carries its mode and enforcement facts. `danger-full-access` bypasses the provider entirely and stamps `denied: false`.
 
 ### Invariants
 
@@ -170,7 +170,7 @@ These limits define when this executor is not a general security boundary. They
 
 - **Confinement covers file effects only** — network restriction and a uniform process-visibility guarantee are absent, 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 `job_output`; a synchronous subprocess throw that names the runner path rejects `start()` before a handle is published.
+- **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 `job_output`; a synchronous subprocess throw is contained into the same settled-killed handle, with the runner-attributed failure carried by the `result()` rejection.
 - **`danger-full-access` deliberately bypasses `ctx.sandbox`** — it is an explicit unconfined mode, not a wider sandbox profile.
 
 <a id="dev-note"></a>

package/README.zh.md

@@ -81,14 +81,14 @@ kind: "package-reference"
 
 | 文件 | 职责 |
 |---|---|
-| [`src/index.ts`](src/index.ts) | 插件入口：`SandboxBashExecutor`、按进程保留事实、run/start 包装 |
+| [`src/index.ts`](src/index.ts) | 插件入口：`SandboxBashExecutor`、按进程保留事实、execute 包装 |
 | [`src/helpers.ts`](src/helpers.ts) | 拒绝、runner 失败与 runner spawn 失败分类 |
 | — | 不发布运行时不变式伴生入口；分类可在结果中观察，且除归属 seam 所强制执行的约定外，本包不公开独立事件序列或可变数据关系。 |
 | `tests/` | 跨 bwrap、Landlock 与 Seatbelt runner 演练的行为 |
 
 ### 主要流程
 
-对受限模式，`resolve()` 标记每次调用的策略（会话的模式覆盖值，或部署回退）；`run` 与 `start` 把 bash argv 经提供方包装，再把受限 argv 交给继承的 subprocess 路径。结算时执行器对结果分类：runner 失败优先于拒绝（命令从未运行），stderr 携带后端拒绝方言的失败运行报告 `denied: true`，每次受限运行都携带模式与强制执行事实。`danger-full-access` 完全绕过提供方，并标记 `denied: false`。
+对受限模式，`resolve()` 标记每次调用的策略（会话的模式覆盖值，或部署回退）；`execute` 把 bash argv 经提供方包装，再把受限 argv 交给继承的 subprocess 路径。结算时执行器对结果分类：runner 失败优先于拒绝（命令从未运行），stderr 携带后端拒绝方言的失败运行报告 `denied: true`，每次受限运行都携带模式与强制执行事实。`danger-full-access` 完全绕过提供方，并标记 `denied: false`。
 
 ### 不变式
 
@@ -170,7 +170,7 @@ kind: "package-reference"
 
 - **限制只覆盖文件影响**——不提供网络限制和统一的进程可见性保证，因此这些模式不是通用安全沙箱。
 - **拒绝从失败命令的 stderr 推断**——后端特征使该推断可跨平台使用，但包含相同特征的应用错误可能被分类为拒绝，也可能遗漏未出现在保留尾部中的拒绝。
-- **异步观测到的后台 runner 失败没有即时错误通道**——它记录在已结算进程上，并在调用方用 `job_output` 读取通用任务时呈现；同步 subprocess throw 若指明 runner 路径，则会在发布句柄前拒绝 `start()`。
+- **异步观测到的后台 runner 失败没有即时错误通道**——它记录在已结算进程上，并在调用方用 `job_output` 读取通用任务时呈现；同步的子进程抛错被收容为同样的已结算 killed 句柄，可归因于 runner 的失败由 `result()` 的 rejection 携带。
 - **`danger-full-access` 有意绕过 `ctx.sandbox`**——它是显式无约束模式，不是更宽的沙箱 profile。
 
 <a id="dev-note"></a>

package/lib/index.js

@@ -29,7 +29,7 @@ function classifyDenial(result, signatures) {
 * calls fall back to deployment policy. `result.sandbox` reports the mode and
 * enforcement actually used.
 */
-var SandboxBashExecutor = class extends LocalBashExecutor {
+var SandboxBashExecutor = class SandboxBashExecutor extends LocalBashExecutor {
 	static inject = [
 		"subprocess",
 		"sandbox",
@@ -62,79 +62,74 @@ var SandboxBashExecutor = class extends LocalBashExecutor {
 			sandboxPolicy: request.sandboxPolicy ?? this.ctx.sandboxPolicy.resolve()
 		};
 	}
-	async run(spec) {
+	async execute(spec) {
 		const policy = spec.sandboxPolicy;
 		const { mode } = policy;
-		if (mode === "danger-full-access") return {
-			...await super.run(spec),
+		if (mode === "danger-full-access") return SandboxBashExecutor.decorateResult(await super.execute(spec), (result) => ({
+			...result,
 			sandbox: {
 				mode,
 				denied: false
 			}
-		};
+		}));
 		let confined;
-		let result;
-		let spawnRequested;
-		try {
-			({result, spawnRequested} = await this.runArgv(spec, async (signal) => {
-				const prepared = await this.confine(spec.command, {
-					...policy,
-					mode
-				}, signal);
-				signal.throwIfAborted();
-				confined = prepared;
-				return prepared.argv;
-			}));
-		} catch (error) {
+		const ex = await this.executeArgv(spec, async (signal) => {
+			const prepared = await this.confine(spec.command, {
+				...policy,
+				mode
+			}, signal);
+			signal.throwIfAborted();
+			confined = prepared;
+			return prepared.argv;
+		}, (process) => {
+			const facts = confined;
+			this.processFacts.set(process, {
+				mode,
+				enforcement: facts.enforcement,
+				denialSignatures: facts.denialSignatures,
+				runnerFailureRules: facts.runnerFailureRules,
+				runnerProgram: facts.argv[0],
+				workdir: spec.workdir
+			});
+		});
+		return SandboxBashExecutor.decorateResult(ex, (result) => {
+			if (confined === void 0) return {
+				...result,
+				sandbox: {
+					mode,
+					denied: false
+				}
+			};
+			const { enforcement, denialSignatures, runnerFailureRules } = confined;
+			const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, runnerFailureRules);
+			if (runnerFailure !== void 0) throw new SandboxUnavailableError(mode, runnerFailure.detail);
+			return {
+				...result,
+				sandbox: {
+					mode,
+					denied: classifyDenial(result, denialSignatures),
+					enforcement
+				}
+			};
+		}, (error) => {
 			if (spec.signal?.aborted === true) spec.signal.throwIfAborted();
 			if (confined !== void 0 && isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) throw new SandboxUnavailableError(mode, String(error));
 			throw error;
-		}
-		if (!spawnRequested) return {
-			...result,
-			sandbox: {
-				mode,
-				denied: false
-			}
-		};
-		const facts = confined;
-		const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, facts.runnerFailureRules);
-		if (runnerFailure !== void 0) throw new SandboxUnavailableError(mode, runnerFailure.detail);
-		return {
-			...result,
-			sandbox: {
-				mode,
-				denied: classifyDenial(result, facts.denialSignatures),
-				enforcement: facts.enforcement
-			}
-		};
-	}
-	async start(spec) {
-		const policy = spec.sandboxPolicy;
-		const { mode } = policy;
-		if (mode === "danger-full-access") return super.start(spec);
-		const confined = await this.confine(spec.command, {
-			...policy,
-			mode
-		}, spec.signal);
-		spec.signal?.throwIfAborted();
-		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;
+	}
+	/**
+	* Decorate the handle's foreground projection in place, memoized once. The
+	* handle keeps its identity (never wrapped in a second object) because the
+	* per-process facts and `onProcessDone` key on the exact instance.
+	*/
+	static decorateResult(ex, map, mapError) {
+		const base = ex.result.bind(ex);
+		let decorated;
+		ex.result = () => {
+			decorated ??= base().then(map, mapError);
+			return decorated;
+		};
+		return ex;
 	}
 	/**
 	* Stamp per-process sandbox facts before `done` settles. Full-access processes

package/lib/types/index.d.ts

@@ -9,7 +9,7 @@
  * @module @deepseek-ai/dsh-bash-sandbox
  */
 import { Context } from '@deepseek-ai/cordis';
-import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellRunResult } from '@deepseek-ai/dsh-shell';
+import type { ShellExecRequest, ShellExecSpec, ShellExecution, ShellProcess } from '@deepseek-ai/dsh-shell';
 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';
@@ -47,8 +47,13 @@ export declare class SandboxBashExecutor extends LocalBashExecutor {
      * the deployment policy.
      */
     resolve(request: ShellExecRequest): ShellExecSpec;
-    run(spec: ShellExecSpec): Promise<ShellRunResult>;
-    start(spec: ShellExecSpec): Promise<ShellProcess>;
+    execute(spec: ShellExecSpec): Promise<ShellExecution>;
+    /**
+     * Decorate the handle's foreground projection in place, memoized once. The
+     * handle keeps its identity (never wrapped in a second object) because the
+     * per-process facts and `onProcessDone` key on the exact instance.
+     */
+    private static decorateResult;
     /**
      * Stamp per-process sandbox facts before `done` settles. Full-access processes
      * have no facts; signal deaths are not denials.

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.1.6-alpha.1",
+  "version": "0.1.7-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,21 +27,21 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-shell": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-bash-local": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-shell": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-bash-local": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.7-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.3"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-shell": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-bash-local": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-subprocess-local": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-sandbox-local": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-shell": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-bash-local": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox-local": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.7-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.3",
     "@deepseek-ai/node-addon-system": "^0.1.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.6-alpha.1"
+    "@deepseek-ai/dsh-session-projection": "^0.1.7-alpha.1"
   }
 }