@deepseek-ai/dsh-bash-local 0.1.6-alpha.2 → 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-local/README.md
-README.md: 2cd69993b454a462bcbfa43175ff7dc7dba72e01
-README.zh.md: 81436511992d93a2bb81c4f3e242dd2046ec11e8
+README.md: 578e5284e22d6ec6dda1590848734ac63d2399fc
+README.zh.md: 4bac3b6cceced30935108ffd14665df51a0c23ce

package/README.md

@@ -52,21 +52,22 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
 
 ### Running commands
 
-Run a command with `run` and read its output from the result. A nonzero exit, a timeout, or a cancellation resolves with a descriptive result — only infrastructure failures reject. Per-call `timeoutMs` overrides are capped by the configuration, while `workdir` falls back to the configured default when unset; a trusted foreground caller can also raise the stdout capture budget for one call, while stderr and background runs keep `maxOutputBytes`. The environment is model-friendly by default: `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` keep pagers and ANSI colors from garbling output, and an explicit caller-provided entry still wins.
+Run a command by awaiting the execution's `result()` projection. A nonzero exit, a timeout, or a cancellation resolves with a descriptive result — only infrastructure failures reject. Per-call `timeoutMs` overrides are capped by the configuration, while `workdir` falls back to the configured default when unset; a trusted caller can also raise the per-call stdout capture budget, while stderr keeps `maxOutputBytes`. The environment is model-friendly by default: `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` keep pagers and ANSI colors from garbling output, and an explicit caller-provided entry still wins.
 
 ```text
-const result = await ctx.shell.run(ctx.shell.resolve({ command: 'ls -la' }))
+const execution = await ctx.shell.execute(ctx.shell.resolve({ command: 'ls -la' }))
+const result = await execution.result()
 if (result.timedOut) console.log('timed out after', result.timeoutMs)
 ```
 
 ### Background processes
 
-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.
+Resolve with `onExpiry: 'none'` and await `execute` to run a command in the background; no deadline is armed. 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
 
-When a settings provider is composed, this executor registers the capability's shared `shell` settings namespace with the composition entry as its base, so a user section in `settings.yaml` layers over it and the next command runs with the new budgets. Values the schema cannot judge — positive and finite numbers, and the `graceMs` timer bound — are refused at the write, leaving the running executor on its last good section; without a provider, the composition entry is what runs.
+Execution budgets are volatile Config fields sampled when resolving each command. The Plugins page edits the active executor’s profile entry. Complete Config validation rejects invalid numbers and timer limits before a form write reaches disk.
 
 -----
 
@@ -93,7 +94,7 @@ The executor is a Service Provider for the `ctx.shell` seam built on the subproc
 
 ### Main flow
 
-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.
+A call runs through three steps: `resolve()` fills `workdir`/`timeoutMs`/`onExpiry`/`stdoutMaxBytes` from config and the request (capping per-call overrides); `execute` wires the deadline per expiry policy — `'kill'` fuses the clamped timeout with the caller's abort signal, `'none'` arms nothing — and spawns `['bash', '-c', command]` through `ctx.subprocess` with explicit byte caps and the `graceMs`; the settled outcome is classified first-cause — only the executor's own timeout reports `timedOut`, an upstream cancel reports `aborted`, a self-signaled command reports neither — and `result()` projects it 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.
 
@@ -139,7 +140,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 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 background provider-failure note is the whole stderr stream** — `SubprocessHandle.done` can reject before or after target execution begins, and the subprocess service buffers no output for a target that never reported, so the executor serves the stage-neutral `subprocess failed before reporting an outcome: …` as the observed stderr stream (offset readers re-read it at their own offsets) and folds it into exactly one `readOutput()` delta; a consuming reader that discards that delta recovers it only through `observed.stderr`.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -52,21 +52,22 @@ kind: "package-reference"
 
 ### 运行命令
 
-用 `run` 运行命令并从结果读取输出。非零退出、超时或取消都会 resolve 为描述性结果——只有基础设施失败才 reject。每次调用的 `timeoutMs` 覆盖值受配置上限约束，`workdir` 未设置时则回退到配置的默认值；受信任的前台调用方还可以为单次调用提高 stdout 捕获预算，而 stderr 与后台运行仍使用 `maxOutputBytes`。环境默认面向模型：`NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` 可防止分页器与 ANSI 颜色破坏输出，调用方显式提供的条目仍然优先。
+通过等待 execution 的 `result()` 投影来运行命令。非零退出、超时或取消都会 resolve 为描述性结果——只有基础设施失败才 reject。每次调用的 `timeoutMs` 覆盖值受配置上限约束，`workdir` 未设置时则回退到配置的默认值；受信任的调用方还可以为单次调用提高 stdout 捕获预算，而 stderr 仍使用 `maxOutputBytes`。环境默认面向模型：`NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` 可防止分页器与 ANSI 颜色破坏输出，调用方显式提供的条目仍然优先。
 
 ```text
-const result = await ctx.shell.run(ctx.shell.resolve({ command: 'ls -la' }))
+const execution = await ctx.shell.execute(ctx.shell.resolve({ command: 'ls -la' }))
+const result = await execution.result()
 if (result.timedOut) console.log('timed out after', result.timeoutMs)
 ```
 
 ### 后台进程
 
-等待 `start` 即可在后台运行命令；它完成准备后返回进程句柄，且不应用执行超时。取消或准备失败会在发布句柄前拒绝调用。`readOutput()` 把流增量合并为一次消费式读取，并在 `[stderr]` 分段下标记 stderr；`kill()` 终止提供方管理的 range；`done` 在直接命令关闭时结算且绝不 reject。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。
+以 `onExpiry: 'none'` 解析并等待 `execute` 返回句柄即可在后台运行命令；不布置任何 deadline。取消或准备失败会在发布句柄前拒绝调用。`readOutput()` 把流增量合并为一次消费式读取，并在 `[stderr]` 分段下标记 stderr；`kill()` 终止提供方管理的 range；`done` 在直接命令关闭时结算且绝不 reject。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。
 
 <a id="adjusting-budgets-at-runtime"></a>
 ### 运行时调整预算
 
-当组合了设置提供方时，本执行器以组合条目为 base 注册该能力共享的 `shell` 设置命名空间，因此 `settings.yaml` 中的用户段会叠加其上，下一条命令即按新预算运行。schema 无法判定的值——正有限数字与 `graceMs` 的定时器上界——会在写入时被拒绝，运行中的执行器保持它最后一份可用的段；没有提供方时，运行的就是组合条目。
+执行预算是解析每条命令时读取的 volatile Config 字段。插件页面编辑当前执行器的 profile 条目。完整 Config 验证在表单写入磁盘前拒绝无效数字和定时器上限。
 
 -----
 
@@ -93,7 +94,7 @@ 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`。
+一次调用分三步：`resolve()` 从配置与请求填充 `workdir`/`timeoutMs`/`onExpiry`/`stdoutMaxBytes`（并限制每次调用的覆盖值）；`execute` 按到期策略布置 deadline——`'kill'` 把钳位后的超时与调用方的中止信号融合为一个 deadline，`'none'` 不布置任何 deadline——再以显式字节上限与 `graceMs` 通过 `ctx.subprocess` spawn `['bash', '-c', command]`；结算的 subprocess 结果被分类——只有执行器自身的超时报告 `timedOut`，上游取消报告 `aborted`，自身因信号终止的命令两者皆不报告——并投影为带收集输出的 `ShellRunResult`。
 
 前台 deadline 从 argv 准备开始，并在准备与执行之间保持同一信号和剩余预算。准备阶段超时返回空输出、`timedOut: true`，且 `exitCode` 和 `signal` 均为 `null`；调用方在发布进程前取消仍会拒绝调用。准备晚到的成功或失败不会触发 spawn。
 
@@ -139,7 +140,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。
-- **后台提供方失败提示只交付一次**——`SubprocessHandle.done` 可能在目标命令开始执行前或后被拒绝，因此执行器把不声明失败阶段的 `subprocess failed before reporting an outcome: …` 注入恰好一个 `readOutput()` 增量；丢弃了该增量的读取方无法再恢复它。
+- **后台提供方失败提示就是整条 stderr 流**——`SubprocessHandle.done` 可能在目标命令开始执行前或后被拒绝，而 subprocess 服务不会为从未上报结果的目标命令 缓冲任何输出，因此执行器把不声明失败阶段的 `subprocess failed before reporting an outcome: …` 作为观测到的 stderr 流提供（偏移读取方按各自偏移重读），并只折入恰好一个 `readOutput()` 增量；丢弃了该增量的消耗式读取方只能经 `observed.stderr` 恢复它。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -1,5 +1,5 @@
 import z from "@deepseek-ai/schemastery";
-import { SHELL_SETTINGS_NAMESPACE, ShellExecutor } from "@deepseek-ai/dsh-shell";
+import { ShellExecutor } from "@deepseek-ai/dsh-shell";
 import { MAX_TIMER_DELAY_MS, clampTimeout, deadline, timeoutOf } from "@deepseek-ai/dsh-timeout";
 //#region lib/types/index.js
 /**
@@ -12,64 +12,6 @@ import { MAX_TIMER_DELAY_MS, clampTimeout, deadline, timeoutOf } from "@deepseek
 * `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
@@ -102,19 +44,17 @@ function assertPositiveFinite(name, value) {
 /**
 * Reject a resolved section this executor could not run with. The schema
 * expresses neither "positive and finite" nor the timer bound `graceMs` has to
-* fit, so a stored value is refused where it is written instead of failing at
-* the next command.
-* @param config - the resolved section, schema-valid by construction.
+* fit, so a stored value that cannot be used fails at the next command.
+* @param config - the live configuration, schema-valid by construction.
 * @throws Error naming the field that cannot be used.
 */
 function assertServiceableBashConfig(config) {
-	const resolved = config;
-	assertPositiveFinite("timeoutMs", resolved.timeoutMs);
-	assertPositiveFinite("maxTimeoutMs", resolved.maxTimeoutMs);
-	assertPositiveFinite("maxOutputBytes", resolved.maxOutputBytes);
-	assertPositiveFinite("maxSpillBytes", resolved.maxSpillBytes);
-	assertPositiveFinite("graceMs", resolved.graceMs);
-	if (resolved.graceMs > MAX_TIMER_DELAY_MS) throw new Error(`bash-local: graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`);
+	assertPositiveFinite("timeoutMs", config.timeoutMs.get());
+	assertPositiveFinite("maxTimeoutMs", config.maxTimeoutMs.get());
+	assertPositiveFinite("maxOutputBytes", config.maxOutputBytes.get());
+	assertPositiveFinite("maxSpillBytes", config.maxSpillBytes.get());
+	assertPositiveFinite("graceMs", config.graceMs.get());
+	if (config.graceMs.get() > 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,
@@ -124,51 +64,37 @@ function assertServiceableBashConfig(config) {
 * composition teardown) even across an executor reload.
 */
 var LocalBashExecutor = class LocalBashExecutor extends ShellExecutor {
+	config;
 	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)
+		cwd: z.string().volatile(),
+		timeoutMs: z.number().default(12e4).volatile(),
+		maxTimeoutMs: z.number().default(6e5).volatile(),
+		maxOutputBytes: z.number().default(64e3).volatile(),
+		maxSpillBytes: z.number().default(DEFAULT_MAX_SPILL_BYTES).volatile(),
+		graceMs: z.number().default(DEFAULT_GRACE_MS).volatile()
 	});
-	/** The currently authoritative config: the settings section, or the composition entry. */
-	source;
-	/** Validated config (schemastery applied the defaults before construction). */
-	get config() {
-		return this.source();
-	}
 	constructor(ctx, config) {
 		super(ctx);
-		const entry = config;
-		assertServiceableBashConfig(entry);
-		this.source = () => entry;
-		ctx.inject(["settings"], (settingsCtx) => {
-			settingsCtx.settings.installSection(ctx, SHELL_SETTINGS_NAMESPACE, LocalBashExecutor.Config, entry, {
-				validate: assertServiceableBashConfig,
-				setSource: (current) => {
-					this.source = current;
-				},
-				onChange: () => {}
-			});
-		});
+		this.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.
+	* this before {@link execute}, so it receives explicit values and never
+	* re-defaults.
 	*/
 	resolve(request) {
-		const timeoutMs = clampTimeout(request.timeoutMs, this.config.timeoutMs, this.config.maxTimeoutMs, "bash-local: request.timeoutMs");
-		const stdoutMaxBytes = request.stdoutMaxBytes ?? this.config.maxOutputBytes;
+		assertServiceableBashConfig(this.config);
+		const timeoutMs = clampTimeout(request.timeoutMs, this.config.timeoutMs.get(), this.config.maxTimeoutMs.get(), "bash-local: request.timeoutMs");
+		const stdoutMaxBytes = request.stdoutMaxBytes ?? this.config.maxOutputBytes.get();
 		assertPositiveFinite("request.stdoutMaxBytes", stdoutMaxBytes);
 		return {
 			command: request.command,
-			workdir: request.workdir ?? this.config.cwd ?? process.cwd(),
+			workdir: request.workdir ?? this.config.cwd.get() ?? process.cwd(),
 			timeoutMs,
+			onExpiry: request.onExpiry ?? "kill",
 			stdoutMaxBytes,
 			...request.signal ? { signal: request.signal } : {},
 			...request.stdin !== void 0 ? { stdin: request.stdin } : {},
@@ -181,7 +107,7 @@ var LocalBashExecutor = class LocalBashExecutor extends ShellExecutor {
 	spawnSpec(spec, argv, stdoutMaxBytes, signal) {
 		const collect = (maxBytes) => ({
 			maxBytes,
-			spill: { maxBytes: this.config.maxSpillBytes }
+			spill: { maxBytes: this.config.maxSpillBytes.get() }
 		});
 		return {
 			argv,
@@ -189,9 +115,9 @@ var LocalBashExecutor = class LocalBashExecutor extends ShellExecutor {
 			stdio: {
 				stdin: spec.stdin !== void 0 ? { data: spec.stdin } : "ignore",
 				stdout: collect(stdoutMaxBytes),
-				stderr: collect(this.config.maxOutputBytes)
+				stderr: collect(this.config.maxOutputBytes.get())
 			},
-			graceMs: this.config.graceMs,
+			graceMs: this.config.graceMs.get(),
 			signal,
 			env: {
 				...ENV_OVERRIDES,
@@ -211,134 +137,144 @@ var LocalBashExecutor = class LocalBashExecutor extends ShellExecutor {
 			stderr
 		};
 	}
-	async run(spec) {
-		return (await this.runArgv(spec, [
+	async execute(spec) {
+		return this.executeArgv(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
+	* Execute an explicit argv with the lifecycle, environment, output,
+	* deadline, 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 argvOrPrepare - exact argv, or preparation cancelled by the same deadline as execution.
-	* @returns the foreground result and whether argv reached the subprocess provider.
+	* @param argvOrPrepare - exact argv, or preparation using the execution cancellation signal.
+	* @param onStarted - installs provider facts synchronously before the handle can settle.
+	* @returns the live execution handle; spawn rejection settles the handle as
+	*   killed while `result()` carries the same failure as its rejection.
 	*/
-	async runArgv(spec, argvOrPrepare) {
-		const env_1 = {
-			stack: [],
-			error: void 0,
-			hasError: false
-		};
-		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 {
-				spawnRequested: true,
-				result: {
-					...outcome,
+	async executeArgv(spec, argvOrPrepare, onStarted) {
+		let spawnSignal;
+		let classify;
+		let disarm = () => {};
+		if (spec.onExpiry === "kill") {
+			const d = deadline(spec.signal, spec.timeoutMs, "BASH_TIMEOUT");
+			spawnSignal = d.signal;
+			classify = () => {
+				const timedOut = timeoutOf(d.signal, "BASH_TIMEOUT") !== void 0;
+				return {
 					timedOut,
-					aborted,
-					timeoutMs: spec.timeoutMs,
-					stdout: finalOutput(collected.stdout),
-					stderr: finalOutput(collected.stderr)
-				}
+					aborted: d.signal.aborted && !timedOut
+				};
+			};
+			disarm = () => {
+				d[Symbol.dispose]();
 			};
-		} catch (e_1) {
-			env_1.error = e_1;
-			env_1.hasError = true;
-		} finally {
-			__disposeResources(env_1);
+		} else {
+			spawnSignal = spec.signal;
+			classify = () => ({
+				timedOut: false,
+				aborted: spec.signal?.aborted === true
+			});
 		}
-	}
-	async start(spec) {
-		return Promise.resolve(this.startArgv(spec, [
-			"bash",
-			"-c",
-			spec.command
-		]));
-	}
-	/**
-	* Start an explicit argv with the background lifecycle, environment, output,
-	* 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; 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;
+		let argv = [];
+		let preparationTimedOut = false;
+		if (typeof argvOrPrepare === "function") {
+			const signal = spawnSignal ?? new AbortController().signal;
+			const cancelled = Promise.withResolvers();
+			const abort = () => {
+				cancelled.reject(signal.reason);
+			};
+			signal.addEventListener("abort", abort, { once: true });
+			try {
+				argv = await Promise.race([Promise.resolve().then(() => {
+					signal.throwIfAborted();
+					return argvOrPrepare(signal);
+				}), cancelled.promise]);
+				signal.throwIfAborted();
+			} catch (error) {
+				if (!classify().timedOut) {
+					disarm();
+					throw error;
+				}
+				preparationTimedOut = true;
+			} finally {
+				signal.removeEventListener("abort", abort);
+			}
+		} else argv = argvOrPrepare;
+		let running;
+		let syncSpawnError;
+		try {
+			if (!preparationTimedOut) running = this.ctx.subprocess.spawn(this.spawnSpec(spec, argv, spec.stdoutMaxBytes, spawnSignal));
+		} catch (error) {
+			syncSpawnError = { error };
+		}
+		const emptyReader = { readFrom: () => ({
+			text: "",
+			lossy: false,
+			nextOffset: 0
+		}) };
+		const collected = running !== void 0 ? LocalBashExecutor.collected(running) : {
+			stdout: emptyReader,
+			stderr: emptyReader
+		};
+		const spawnThrow = () => syncSpawnError.error;
+		const spawned = preparationTimedOut ? Promise.resolve({
+			exitCode: null,
+			signal: null
+		}) : running !== void 0 ? running.done : Promise.reject(spawnThrow());
+		let providerFailure;
+		let providerFailureReported = false;
 		const consumeProviderFailure = () => {
-			const note = providerFailureNote ?? "";
-			providerFailureNote = void 0;
-			return note;
+			if (providerFailure === void 0 || providerFailureReported) return "";
+			providerFailureReported = true;
+			return providerFailure.note;
 		};
+		const observedStderr = { readFrom: (fromByte) => {
+			if (providerFailure === void 0) return collected.stderr.readFrom(fromByte);
+			const note = Buffer.from(providerFailure.note, "utf8");
+			return {
+				text: note.subarray(Math.min(fromByte, note.length)).toString("utf8"),
+				nextOffset: note.length,
+				lossy: false
+			};
+		} };
 		let stdoutOffset = 0;
 		let stderrOffset = 0;
+		let resultPromise;
 		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";
+			observed: {
+				stdout: collected.stdout,
+				stderr: observedStderr
+			},
+			done: spawned.then((outcome) => {
+				if (proc.status === "running") proc.status = spawnSignal?.aborted === true || outcome.signal !== null ? "killed" : "completed";
 				proc.exitCode = outcome.exitCode;
 				proc.signal = outcome.signal;
 				this.onProcessDone(proc, collected.stderr.readFrom(0).text, false);
+				disarm();
 			}, (error) => {
+				if (running !== void 0 && (proc.status === "killed" || spawnSignal?.aborted === true)) {
+					proc.status = "killed";
+					this.onProcessDone(proc, collected.stderr.readFrom(0).text, false);
+					disarm();
+					return;
+				}
 				proc.status = "killed";
 				let detail = "unprintable provider failure";
 				try {
 					detail = String(error);
 				} catch {}
-				providerFailureNote = `subprocess failed before reporting an outcome: ${detail}`;
-				this.onProcessDone(proc, providerFailureNote, true, error);
+				providerFailure = {
+					error,
+					note: `subprocess failed before reporting an outcome: ${detail}`
+				};
+				this.onProcessDone(proc, providerFailure.note, true, error);
+				disarm();
 			}),
 			readOutput: () => {
 				const out = collected.stdout.readFrom(stdoutOffset);
@@ -359,10 +295,25 @@ var LocalBashExecutor = class LocalBashExecutor extends ShellExecutor {
 			kill: () => {
 				if (proc.status !== "running") return false;
 				proc.status = "killed";
-				running.terminate();
+				running?.terminate();
 				return true;
+			},
+			result: () => {
+				resultPromise ??= proc.done.then(() => {
+					if (providerFailure !== void 0) throw providerFailure.error;
+					return {
+						exitCode: proc.exitCode,
+						signal: proc.signal,
+						...classify(),
+						timeoutMs: spec.timeoutMs,
+						stdout: finalOutput(collected.stdout),
+						stderr: finalOutput(collected.stderr)
+					};
+				});
+				return resultPromise;
 			}
 		};
+		if (!preparationTimedOut) onStarted?.(proc);
 		return proc;
 	}
 	/**

package/lib/types/index.d.ts

@@ -8,10 +8,11 @@
  * `tools/pre-execute` or a sandboxing executor.
  * @module @deepseek-ai/dsh-bash-local
  */
+import type { Volatile } from '@deepseek-ai/cordis';
 import { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { ShellExecutor } from '@deepseek-ai/dsh-shell';
-import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellRunResult } from '@deepseek-ai/dsh-shell';
+import type { ShellExecRequest, ShellExecSpec, ShellExecution, ShellProcess } from '@deepseek-ai/dsh-shell';
 /**
  * Model-friendly environment overrides: disable colors, pagers, and
  * interactive terminal features that would garble tool output (the same set
@@ -25,29 +26,26 @@ export declare const ENV_OVERRIDES: {
     readonly PAGER: "cat";
     readonly GIT_PAGER: "cat";
 };
-/** Plugin config (all optional — `static Config` supplies the defaults). */
+/** Validated plugin configuration with live command budgets. */
 export interface Config {
     /** Default working directory for commands (default: process.cwd()). */
-    cwd?: string;
+    cwd: Volatile<string | undefined>;
     /** Default foreground timeout in milliseconds. */
-    timeoutMs?: number;
+    timeoutMs: Volatile<number>;
     /** Upper bound for per-call timeout overrides. */
-    maxTimeoutMs?: number;
+    maxTimeoutMs: Volatile<number>;
     /** Per-stream in-memory output cap; overflow spills to a temp file. */
-    maxOutputBytes?: number;
+    maxOutputBytes: Volatile<number>;
     /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */
-    maxSpillBytes?: number;
+    maxSpillBytes: Volatile<number>;
     /** Grace period for kill escalation and inherited pipes; at most `MAX_TIMER_DELAY_MS`. */
-    graceMs?: number;
+    graceMs: Volatile<number>;
 }
-/** The shape after schemastery applied the defaults (cwd has none). */
-type ResolvedConfig = Required<Omit<Config, 'cwd'>> & Pick<Config, 'cwd'>;
 /**
  * Reject a resolved section this executor could not run with. The schema
  * expresses neither "positive and finite" nor the timer bound `graceMs` has to
- * fit, so a stored value is refused where it is written instead of failing at
- * the next command.
- * @param config - the resolved section, schema-valid by construction.
+ * fit, so a stored value that cannot be used fails at the next command.
+ * @param config - the live configuration, schema-valid by construction.
  * @throws Error naming the field that cannot be used.
  */
 export declare function assertServiceableBashConfig(config: Config): void;
@@ -59,49 +57,48 @@ export declare function assertServiceableBashConfig(config: Config): void;
  * composition teardown) even across an executor reload.
  */
 export declare class LocalBashExecutor extends ShellExecutor {
+    readonly config: Config;
     static inject: string[];
-    static Config: z<Config>;
-    /** The currently authoritative config: the settings section, or the composition entry. */
-    private source;
-    /** Validated config (schemastery applied the defaults before construction). */
-    get config(): ResolvedConfig;
+    static Config: z<Schemastery.ObjectS<NoInfer<{
+        cwd: z<string, string, "volatile">;
+        timeoutMs: z<number, number, "volatile-defined">;
+        maxTimeoutMs: z<number, number, "volatile-defined">;
+        maxOutputBytes: z<number, number, "volatile-defined">;
+        maxSpillBytes: z<number, number, "volatile-defined">;
+        graceMs: z<number, number, "volatile-defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        cwd: z<string, string, "volatile">;
+        timeoutMs: z<number, number, "volatile-defined">;
+        maxTimeoutMs: z<number, number, "volatile-defined">;
+        maxOutputBytes: z<number, number, "volatile-defined">;
+        maxSpillBytes: z<number, number, "volatile-defined">;
+        graceMs: z<number, number, "volatile-defined">;
+    }>>, "plain">;
     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.
+     * this before {@link execute}, so it receives explicit values and never
+     * re-defaults.
      */
     resolve(request: ShellExecRequest): ShellExecSpec;
     /** 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: ShellExecSpec): Promise<ShellRunResult>;
+    execute(spec: ShellExecSpec): Promise<ShellExecution>;
     /**
-     * Run an explicit argv with the foreground lifecycle, environment, output,
-     * timeout, and cancellation semantics of this executor. Subclasses use this
+     * Execute an explicit argv with the lifecycle, environment, output,
+     * deadline, 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 argvOrPrepare - exact argv, or preparation cancelled by the same deadline as execution.
-     * @returns the foreground result and whether argv reached the subprocess provider.
+     * @param argvOrPrepare - exact argv, or preparation using the execution cancellation signal.
+     * @param onStarted - installs provider facts synchronously before the handle can settle.
+     * @returns the live execution handle; spawn rejection settles the handle as
+     *   killed while `result()` carries the same failure as its rejection.
      */
-    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.
-     * 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; provider rejection settles it as killed.
-     */
-    protected startArgv(spec: ShellExecSpec, argv: readonly string[]): ShellProcess;
+    protected executeArgv(spec: ShellExecSpec, argvOrPrepare: readonly string[] | ((signal: AbortSignal) => Promise<readonly string[]>), onStarted?: (process: ShellExecution) => void): Promise<ShellExecution>;
     /**
      * Settlement hook for subclasses that attach execution facts to a process.
      * Called after exit facts or provider-failure output are stamped and before

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