@deepseek-ai/dsh-bash-local 0.1.5-rc.1 → 0.1.6-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-local/README.md
-README.md: 462054d435433067355a91103aa0d606cea6521b
-README.zh.md: 6127c6265079d522b5a58d8b1fd019c1bd909262
+README.md: 2cd69993b454a462bcbfa43175ff7dc7dba72e01
+README.zh.md: 81436511992d93a2bb81c4f3e242dd2046ec11e8

package/README.md

@@ -61,7 +61,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 
 ### Background processes
 
-Call `start` to run a command in the background; it returns a handle immediately and no timeout applies. `readOutput()` merges the stream deltas into one consuming read, marking stderr under a `[stderr]` section; `kill()` terminates the provider-managed range; `done` settles when the direct command closes and never rejects. Job ids, ownership, polling, and notices belong to the generic `ctx.jobs` runtime, which the tool layer registers the handle with.
+Await `start` to run a command in the background; it resolves with the prepared process handle and no execution timeout applies. Cancellation or preparation failure rejects before a handle is published. `readOutput()` merges the stream deltas into one consuming read, marking stderr under a `[stderr]` section; `kill()` terminates the provider-managed range; `done` settles when the direct command closes and never rejects. Job ids, ownership, polling, and notices belong to the generic `ctx.jobs` runtime, which the tool layer registers the handle with.
 
 <a id="adjusting-budgets-at-runtime"></a>
 ### Adjusting budgets at runtime
@@ -95,6 +95,8 @@ The executor is a Service Provider for the `ctx.shell` seam built on the subproc
 
 A call runs through three steps: `resolve()` fills `workdir`/`timeoutMs`/`stdoutMaxBytes` from config (capping per-call overrides); `run` fuses the config-clamped timeout with the caller's abort signal into one deadline and spawns `['bash', '-c', command]` through `ctx.subprocess` with explicit byte caps and the `graceMs`; the settled subprocess outcome is classified — only the executor's own timeout reports `timedOut`, an upstream cancel reports `aborted`, a self-signaled command reports neither — and projected into a `ShellRunResult` with collected output.
 
+The foreground deadline starts before argv preparation and retains the same signal and remaining budget through execution. Preparation timeout returns empty output, `timedOut: true`, and null `exitCode` and `signal`; caller cancellation before process publication still rejects. Late preparation success or failure cannot trigger a spawn.
+
 ### Invariants and ownership
 
 - The `graceMs` budget must be positive, finite, and no greater than `MAX_TIMER_DELAY_MS` so Node can represent it with one timer; invalid values are refused where they are written.

package/README.zh.md

@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-当组合需要在 POSIX 上执行 Bash 命令且不需要隔离时，挂载此执行器。它注册为 `ctx.shell`，面向模型的 `bash` 工具会立即基于它工作：agent 调用工具，命令即以全新 `bash -c` 进程按下面的预算运行。
+当组合需要在 POSIX 上执行 Bash 命令且不需要隔离时，挂载此执行器。它注册为 `ctx.shell`，面向模型的 `bash` 工具会立即基于它工作：agent（智能体）调用工具，命令即以全新 `bash -c` 进程按下面的预算运行。
 
 ### 最小配置
 
@@ -61,7 +61,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 
 ### 后台进程
 
-调用 `start` 即可在后台运行命令；它立即返回句柄，且不应用任何超时。`readOutput()` 把流增量合并为一次消费式读取，并在 `[stderr]` 分段下标记 stderr；`kill()` 终止提供方管理的 range；`done` 在直接命令关闭时结算且绝不 reject。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。
+等待 `start` 即可在后台运行命令；它完成准备后返回进程句柄，且不应用执行超时。取消或准备失败会在发布句柄前拒绝调用。`readOutput()` 把流增量合并为一次消费式读取，并在 `[stderr]` 分段下标记 stderr；`kill()` 终止提供方管理的 range；`done` 在直接命令关闭时结算且绝不 reject。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。
 
 <a id="adjusting-budgets-at-runtime"></a>
 ### 运行时调整预算
@@ -87,7 +87,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 | 文件 | 职责 |
 |---|---|
 | [`src/index.ts`](src/index.ts) | 插件入口：`LocalBashExecutor`、`Config`、设置段接线 |
-| — | 不发布运行时不变式伴生入口；约定在所属 seam 处执行。 |
+| — | 不发布运行时不变式伴生入口；除由所属 seam 强制执行的约定外，本包不公开独立的事件序列或可变数据关系。 |
 | `tests/executor.spec.ts` | 已演练的行为：预算、分类、后台句柄、归属 |
 | `tests/settings.spec.ts` | 设置段叠加在组合条目之上 |
 
@@ -95,11 +95,13 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 
 一次调用分三步：`resolve()` 从配置填充 `workdir`/`timeoutMs`/`stdoutMaxBytes`（并限制每次调用的覆盖值）；`run` 把按配置钳位的超时与调用方的中止信号融合为一个 deadline，再以显式字节上限与 `graceMs` 通过 `ctx.subprocess` spawn `['bash', '-c', command]`；结算的 subprocess 结果被分类——只有执行器自身的超时报告 `timedOut`，上游取消报告 `aborted`，自身因信号终止的命令两者皆不报告——并投影为带收集输出的 `ShellRunResult`。
 
+前台 deadline 从 argv 准备开始，并在准备与执行之间保持同一信号和剩余预算。准备阶段超时返回空输出、`timedOut: true`，且 `exitCode` 和 `signal` 均为 `null`；调用方在发布进程前取消仍会拒绝调用。准备晚到的成功或失败不会触发 spawn。
+
 ### 不变式与归属
 
 - `graceMs` 预算必须为正有限值且不大于 `MAX_TIMER_DELAY_MS`，这样 Node 就能用一个定时器表示它；无效值在写入处被拒绝。
 - 环境分层固定：先是终端覆盖值，然后是调用方的 `env`，最后才是受信任的 `dshEnv` 快照；subprocess 服务独立清除环境中的凭据与继承的 `DSH_*` 名称。
-- 后台进程属于 subprocess 服务：它能在仅重载执行器后存活，并在服务 dispose 时被终止并 join。
+- 后台进程属于 subprocess 服务：它能在仅重载执行器后存活，并在服务 dispose 时被终止且等待退出。
 
 </details>
 
@@ -108,10 +110,10 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 <a id="further-exploration"></a>
 ## 进一步探索
 
-当执行器约定不够用时阅读以下页面。它们从 seam 进入受限的兄弟包及其底层机制。
+当执行器约定不够用时阅读以下页面。这些页面从 seam 讲到提供隔离的同级包及其底层机制。
 
 - [shell seam](../shell/README.zh.md) —— 本提供方实现的执行器约定，包括请求/spec 拆分。
-- [bash-sandbox](../bash-sandbox/README.zh.md) —— 需要沙箱能力时替换组合的受限执行器。
+- [bash-sandbox](../bash-sandbox/README.zh.md) —— 需要沙箱能力时，应改为组合此隔离执行器。
 - [tool-bash](../tool-bash/README.zh.md) —— 基于本执行器的面向模型 `bash` 工具。
 - [Bash 执行器子系统](../../../docs/subsystems/shell.zh.md) —— 请求/spec 词汇、结果与完整的服务约定。
 - [subprocess-local](../../subprocess/subprocess-local/README.zh.md) —— 本执行器背后的 managed-range 机制。
@@ -134,10 +136,10 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 
 这些限制说明本执行器何时不合适。它们是当前包约束，不是路线图。
 
-- **自身不提供隔离**——命令以 harness 进程的权限运行；需要隔离的部署组合 `dsh-bash-sandbox`，每次调用的 allow/deny/ask 策略则属于工具的 `pre-execute` waterfall。
+- **自身不提供隔离**——命令以 harness 进程的权限运行；需要隔离的部署组合 `dsh-bash-sandbox`，每次调用的 allow/deny/ask 策略则属于工具的 `pre-execute` waterfall（瀑布式事件）。
 - **没有持久 shell 或 PTY**——每次调用都启动全新的非登录 `bash -c`；仅持久化 cwd 与交互式终端会话均继续延期，直到真实工作流需要它们。
 - **仅支持 POSIX**——`bash` 二进制已硬编码，底层服务的进程组语义也是 POSIX 的；不支持 Windows。
-- **后台 provider failure 提示只交付一次**——`SubprocessHandle.done` 可能在 target 开始执行前或后 reject，因此执行器把不声明失败阶段的 `subprocess failed before reporting an outcome: …` 注入恰好一个 `readOutput()` 增量；丢弃了该增量的读取方无法再恢复它。
+- **后台提供方失败提示只交付一次**——`SubprocessHandle.done` 可能在目标命令开始执行前或后被拒绝，因此执行器把不声明失败阶段的 `subprocess failed before reporting an outcome: …` 注入恰好一个 `readOutput()` 增量；丢弃了该增量的读取方无法再恢复它。
 
 <a id="dev-note"></a>
 ### 开发备注
@@ -145,6 +147,6 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 <details>
 <summary>维护者的工作上下文——点击展开</summary>
 
-None.
+无。
 
 </details>

package/lib/index.js

@@ -212,21 +212,21 @@ var LocalBashExecutor = class LocalBashExecutor extends ShellExecutor {
 		};
 	}
 	async run(spec) {
-		return this.runArgv(spec, [
+		return (await this.runArgv(spec, [
 			"bash",
 			"-c",
 			spec.command
-		]);
+		])).result;
 	}
 	/**
 	* 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.
+	* @param argvOrPrepare - exact argv, or preparation cancelled by the same deadline as execution.
+	* @returns the foreground result and whether argv reached the subprocess provider.
 	*/
-	async runArgv(spec, argv) {
+	async runArgv(spec, argvOrPrepare) {
 		const env_1 = {
 			stack: [],
 			error: void 0,
@@ -234,18 +234,58 @@ var LocalBashExecutor = class LocalBashExecutor extends ShellExecutor {
 		};
 		try {
 			const d = __addDisposableResource(env_1, deadline(spec.signal, spec.timeoutMs, "BASH_TIMEOUT"), false);
+			let argv;
+			if (typeof argvOrPrepare === "function") {
+				const cancelled = Promise.withResolvers();
+				const abort = () => {
+					cancelled.reject(d.signal.reason);
+				};
+				d.signal.addEventListener("abort", abort, { once: true });
+				try {
+					argv = await Promise.race([Promise.resolve().then(() => {
+						d.signal.throwIfAborted();
+						return argvOrPrepare(d.signal);
+					}), cancelled.promise]);
+					d.signal.throwIfAborted();
+				} catch (error) {
+					if (timeoutOf(d.signal, "BASH_TIMEOUT") === void 0) throw error;
+					return {
+						spawnRequested: false,
+						result: {
+							exitCode: null,
+							signal: null,
+							timedOut: true,
+							aborted: false,
+							timeoutMs: spec.timeoutMs,
+							stdout: {
+								text: "",
+								truncated: false
+							},
+							stderr: {
+								text: "",
+								truncated: false
+							}
+						}
+					};
+				} finally {
+					d.signal.removeEventListener("abort", abort);
+				}
+			} else argv = argvOrPrepare;
 			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)
+				spawnRequested: true,
+				result: {
+					...outcome,
+					timedOut,
+					aborted,
+					timeoutMs: spec.timeoutMs,
+					stdout: finalOutput(collected.stdout),
+					stderr: finalOutput(collected.stderr)
+				}
 			};
 		} catch (e_1) {
 			env_1.error = e_1;
@@ -254,12 +294,12 @@ var LocalBashExecutor = class LocalBashExecutor extends ShellExecutor {
 			__disposeResources(env_1);
 		}
 	}
-	start(spec) {
-		return this.startArgv(spec, [
+	async start(spec) {
+		return Promise.resolve(this.startArgv(spec, [
 			"bash",
 			"-c",
 			spec.command
-		]);
+		]));
 	}
 	/**
 	* Start an explicit argv with the background lifecycle, environment, output,
@@ -271,6 +311,7 @@ var LocalBashExecutor = class LocalBashExecutor extends ShellExecutor {
 	* @returns the live background handle; provider rejection settles it as killed.
 	*/
 	startArgv(spec, argv) {
+		spec.signal?.throwIfAborted();
 		const running = this.ctx.subprocess.spawn(this.spawnSpec(spec, argv, this.config.maxOutputBytes, spec.signal));
 		const collected = LocalBashExecutor.collected(running);
 		let providerFailureNote;

package/lib/types/index.d.ts

@@ -84,11 +84,14 @@ export declare class LocalBashExecutor extends ShellExecutor {
      * 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.
+     * @param argvOrPrepare - exact argv, or preparation cancelled by the same deadline as execution.
+     * @returns the foreground result and whether argv reached the subprocess provider.
      */
-    protected runArgv(spec: ShellExecSpec, argv: readonly string[]): Promise<ShellRunResult>;
-    start(spec: ShellExecSpec): ShellProcess;
+    protected runArgv(spec: ShellExecSpec, argvOrPrepare: readonly string[] | ((signal: AbortSignal) => Promise<readonly string[]>)): Promise<{
+        result: ShellRunResult;
+        spawnRequested: boolean;
+    }>;
+    start(spec: ShellExecSpec): Promise<ShellProcess>;
     /**
      * Start an explicit argv with the background lifecycle, environment, output,
      * cancellation, and managed-range ownership semantics of this executor.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-bash-local",
   "description": "Local-subprocess implementation of the DeepSeek Harness bash executor seam",
-  "version": "0.1.5-rc.1",
+  "version": "0.1.6-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,21 +27,21 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-shell": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-subprocess": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-shell": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-timeout": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.1",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-settings": "^0.1.5-rc.1"
+    "@deepseek-ai/dsh-settings": "^0.1.6-alpha.1"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-shell": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-subprocess": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-subprocess-local": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-shell": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-timeout": "^0.1.6-alpha.1",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-settings": "^0.1.5-rc.1"
+    "@deepseek-ai/dsh-settings": "^0.1.6-alpha.1"
   }
 }