@deepseek-ai/dsh-bash-local 0.1.2-rc.1 → 0.1.3-alpha.2

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: df9248651c94b26df3a16a19a360056a5a9199e1
-README.zh.md: ad5ba2143f0b0eff46264de2be48bd1bb1067edf
+README.md: 462054d435433067355a91103aa0d606cea6521b
+README.zh.md: 6127c6265079d522b5a58d8b1fd019c1bd909262

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()` stops the process group; `done` settles when the process 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.
+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.
 
 <a id="adjusting-budgets-at-runtime"></a>
 ### Adjusting budgets at runtime
@@ -80,7 +80,7 @@ This section explains the design of the executor and points at the code that rea
 
 ### Design concept
 
-The executor is a Service Provider for the `ctx.shell` seam built on the subprocess capability: it owns everything bash-shaped — command defaulting and caps, deadline fusion and cause classification, the model-friendly terminal environment, and the background read merge — while process-group mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) belong to the subprocess service. Every call spawns a fresh non-login `bash -c` with no rc files, so commands are deterministic and shell state never leaks between calls.
+The executor is a Service Provider for the `ctx.shell` seam built on the subprocess capability: it owns everything bash-shaped — command defaulting and caps, deadline fusion and cause classification, the model-friendly terminal environment, and the background read merge — while managed-range mechanics (bounded spill-backed output, credential scrub, termination escalation, quiescence, and disposal) belong to the subprocess service. Every call spawns a fresh non-login `bash -c` with no rc files, so commands are deterministic and shell state never leaks between calls.
 
 ### Source map
 
@@ -114,7 +114,7 @@ Read these pages when the executor contract is not enough. They move from the se
 - [bash-sandbox](../bash-sandbox/README.md) — the confining executor to compose instead when commands need the sandbox capability.
 - [tool-bash](../tool-bash/README.md) — the model-facing `bash` tool over this executor.
 - [Bash executor subsystem](../../../docs/subsystems/shell.md) — request/spec vocabulary, results, and the service contract in full.
-- [subprocess-local](../../subprocess/subprocess-local/README.md) — the process-group mechanics behind this executor.
+- [subprocess-local](../../subprocess/subprocess-local/README.md) — the managed-range mechanics behind this executor.
 
 -----
 
@@ -137,7 +137,7 @@ These limits define when this executor is a poor fit. They are current package c
 - **Unconfined by itself** — commands run with the harness process's authority; deployments needing confinement compose `dsh-bash-sandbox`, while per-call allow/deny/ask policy belongs on the tools' `pre-execute` waterfall.
 - **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.
+- **A background provider-failure note is single-delivery** — `SubprocessHandle.done` can reject before or after target execution begins, so the executor injects the stage-neutral `subprocess failed before reporting an outcome: …` into exactly one `readOutput()` delta; a reader that discards that delta cannot recover it.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -61,7 +61,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 
 ### 后台进程
 
-调用 `start` 即可在后台运行命令；它立即返回句柄，且不应用任何超时。`readOutput()` 把流增量合并为一次消费式读取，并在 `[stderr]` 分段下标记 stderr；`kill()` 停止进程组；`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>
 ### 运行时调整预算
@@ -80,7 +80,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 
 ### 设计概念
 
-本执行器是基于 subprocess 能力的 `ctx.shell` seam 的 Service Provider：它负责所有 bash 层职责——命令默认化与上限、deadline 融合与原因分类、面向模型的终端环境，以及后台读取合并——而进程组机制（有界 spill 输出、凭据清除、终止升级、dispose（资源释放））属于 subprocess 服务。每次调用都 spawn 全新的非登录 `bash -c`，不读取 rc 文件，因此命令是确定性的，shell 状态绝不会在调用之间泄漏。
+本执行器是基于 subprocess 能力的 `ctx.shell` seam 的 Service Provider：它负责所有 bash 层职责——命令默认化与上限、deadline 融合与原因分类、面向模型的终端环境，以及后台读取合并——而 managed-range 机制（有界 spill 输出、凭据清除、终止升级、完全停稳与 dispose（资源释放））属于 subprocess 服务。每次调用都 spawn 全新的非登录 `bash -c`，不读取 rc 文件，因此命令是确定性的，shell 状态绝不会在调用之间泄漏。
 
 ### 源码地图
 
@@ -114,7 +114,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 - [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) —— 本执行器背后的进程组机制。
+- [subprocess-local](../../subprocess/subprocess-local/README.zh.md) —— 本执行器背后的 managed-range 机制。
 
 -----
 
@@ -137,7 +137,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 - **自身不提供隔离**——命令以 harness 进程的权限运行；需要隔离的部署组合 `dsh-bash-sandbox`，每次调用的 allow/deny/ask 策略则属于工具的 `pre-execute` waterfall。
 - **没有持久 shell 或 PTY**——每次调用都启动全新的非登录 `bash -c`；仅持久化 cwd 与交互式终端会话均继续延期，直到真实工作流需要它们。
 - **仅支持 POSIX**——`bash` 二进制已硬编码，底层服务的进程组语义也是 POSIX 的；不支持 Windows。
-- **后台 spawn 失败提示只交付一次**——subprocess 服务不会为从未真正运行的进程缓冲任何输出，因此执行器把 `spawn failed: …` 注入恰好一个 `readOutput()` 增量；丢弃了该增量的读取方无法再恢复它。
+- **后台 provider failure 提示只交付一次**——`SubprocessHandle.done` 可能在 target 开始执行前或后 reject，因此执行器把不声明失败阶段的 `subprocess failed before reporting an outcome: …` 注入恰好一个 `readOutput()` 增量；丢弃了该增量的读取方无法再恢复它。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -4,7 +4,7 @@ import { MAX_TIMER_DELAY_MS, clampTimeout, deadline, timeoutOf } from "@deepseek
 //#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
+* capability seam. Public commands run as `bash -c` in a provider-managed range
 * 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
@@ -117,9 +117,9 @@ function assertServiceableBashConfig(config) {
 	if (resolved.graceMs > MAX_TIMER_DELAY_MS) throw new Error(`bash-local: graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`);
 }
 /**
-* 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
+* Local bash executor over `ctx.subprocess`. Bounded output, spill files,
+* managed-range SIGTERM→SIGKILL escalation, and quiescence 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.
 */
@@ -263,20 +263,20 @@ var LocalBashExecutor = class LocalBashExecutor extends ShellExecutor {
 	}
 	/**
 	* Start an explicit argv with the background lifecycle, environment, output,
-	* cancellation, and process-tree ownership semantics of this executor.
+	* cancellation, and managed-range 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.
+	* @returns the live background handle; provider 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;
+		let providerFailureNote;
+		const consumeProviderFailure = () => {
+			const note = providerFailureNote ?? "";
+			providerFailureNote = void 0;
 			return note;
 		};
 		let stdoutOffset = 0;
@@ -292,15 +292,21 @@ var LocalBashExecutor = class LocalBashExecutor extends ShellExecutor {
 				this.onProcessDone(proc, collected.stderr.readFrom(0).text, false);
 			}, (error) => {
 				proc.status = "killed";
-				spawnFailureNote = `spawn failed: ${String(error)}`;
-				this.onProcessDone(proc, spawnFailureNote, true, error);
+				let detail = "unprintable provider failure";
+				try {
+					detail = String(error);
+				} catch {}
+				providerFailureNote = `subprocess failed before reporting an outcome: ${detail}`;
+				this.onProcessDone(proc, providerFailureNote, 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 providerFailure = consumeProviderFailure();
+				const failureSeparator = err.text.length > 0 && !err.text.endsWith("\n") ? "\n" : "";
+				const errText = err.text + (providerFailure.length > 0 ? `${failureSeparator}${providerFailure}` : "");
 				const separator = out.text.length > 0 && !out.text.endsWith("\n") ? "\n" : "";
 				return {
 					delta: out.text + (errText.length > 0 ? `${separator}[stderr]\n${errText}` : ""),
@@ -320,15 +326,15 @@ var LocalBashExecutor = class LocalBashExecutor extends ShellExecutor {
 	}
 	/**
 	* Settlement hook for subclasses that attach execution facts to a process.
-	* Called after exit facts or spawn-failure output are stamped and before
+	* Called after exit facts or provider-failure output are stamped and before
 	* {@link ShellProcess.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.
+	* @param _providerRejected - whether the subprocess promise rejected without a direct outcome.
+	* @param _providerError - the provider rejection reason, which may itself be undefined.
 	*/
-	onProcessDone(_proc, _stderr, _spawnFailed, _spawnError) {}
+	onProcessDone(_proc, _stderr, _providerRejected, _providerError) {}
 };
 //#endregion
 export { ENV_OVERRIDES, LocalBashExecutor, LocalBashExecutor as default, assertServiceableBashConfig };

package/lib/types/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * 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
+ * capability seam. Public commands run as `bash -c` in a provider-managed range
  * 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
@@ -52,9 +52,9 @@ type ResolvedConfig = Required<Omit<Config, 'cwd'>> & Pick<Config, 'cwd'>;
  */
 export declare function assertServiceableBashConfig(config: Config): void;
 /**
- * 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
+ * Local bash executor over `ctx.subprocess`. Bounded output, spill files,
+ * managed-range SIGTERM→SIGKILL escalation, and quiescence 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.
  */
@@ -91,25 +91,25 @@ export declare class LocalBashExecutor extends ShellExecutor {
     start(spec: ShellExecSpec): ShellProcess;
     /**
      * Start an explicit argv with the background lifecycle, environment, output,
-     * cancellation, and process-tree ownership semantics of this executor.
+     * cancellation, and managed-range 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.
+     * @returns the live background handle; provider rejection settles it as killed.
      */
     protected startArgv(spec: ShellExecSpec, argv: readonly string[]): ShellProcess;
     /**
      * Settlement hook for subclasses that attach execution facts to a process.
-     * Called after exit facts or spawn-failure output are stamped and before
+     * Called after exit facts or provider-failure output are stamped and before
      * {@link ShellProcess.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.
+     * @param _providerRejected - whether the subprocess promise rejected without a direct outcome.
+     * @param _providerError - the provider rejection reason, which may itself be undefined.
      */
-    protected onProcessDone(_proc: ShellProcess, _stderr: string, _spawnFailed: boolean, _spawnError?: unknown): void;
+    protected onProcessDone(_proc: ShellProcess, _stderr: string, _providerRejected: boolean, _providerError?: unknown): void;
 }
 export default LocalBashExecutor;
 //# sourceMappingURL=index.d.ts.map

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.2-rc.1",
+  "version": "0.1.3-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,21 +27,21 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-shell": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-shell": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.3-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-settings": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-subprocess": "^0.1.2-rc.1"
+    "@deepseek-ai/dsh-settings": "^0.1.3-alpha.2"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-shell": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-subprocess": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-subprocess-local": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.1.2-rc.1",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-settings": "^0.1.2-rc.1"
+    "@deepseek-ai/dsh-shell": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-settings": "^0.1.3-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   }
 }