@deepseek-ai/dsh-pwsh-local 0.1.6-alpha.2 → 0.1.7-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/pwsh-local/README.md
-README.md: 1dbc90835cb95a0e171a33b10c7409a181dd98cf
-README.zh.md: f87c7d435cccb600d123cf80264e027657ef1835
+README.md: f4001263ba06d02a4b4c3b801d9a518488a97327
+README.zh.md: e9e1c3246bef62f55c965d4974202646b5fc2096

package/README.md

@@ -57,21 +57,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 descriptively, and only infrastructure failures reject. The command string rides as one argument to `-Command`: PowerShell parses the text itself and no intermediate shell exists, so there is no shell-quoting layer to escape and native Win32 paths pass through unchanged. Every command pins UTF-8 output first, so non-ASCII output is not garbled even on the Windows PowerShell 5.1 fallback. The environment is model-friendly: `NO_COLOR=1 PAGER=cat GIT_PAGER=cat` (no `TERM=dumb` — a POSIX concept), with explicit caller-provided entries still winning.
+Run a command by awaiting the execution's `result()` projection; a nonzero exit, a timeout, or a cancellation resolves descriptively, and only infrastructure failures reject. The command string rides as one argument to `-Command`: PowerShell parses the text itself and no intermediate shell exists, so there is no shell-quoting layer to escape and native Win32 paths pass through unchanged. Every command pins UTF-8 output first, so non-ASCII output is not garbled even on the Windows PowerShell 5.1 fallback. The environment is model-friendly: `NO_COLOR=1 PAGER=cat GIT_PAGER=cat` (no `TERM=dumb` — a POSIX concept), with explicit caller-provided entries still winning.
 
 ```text
-const result = await ctx.shell.run(ctx.shell.resolve({ command: 'Get-ChildItem' }))
+const execution = await ctx.shell.execute(ctx.shell.resolve({ command: 'Get-ChildItem' }))
+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 — the same one the POSIX family uses, because a host composes exactly one provider of `ctx.shell` — so a user section in `settings.yaml` layers over the composition entry 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.
+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.
 
 -----
 
@@ -145,7 +146,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 a sandboxing executor or policy instead.
 - **No persistent shell or PTY** — every call starts a fresh `pwsh -Command`.
 - **The command string is PowerShell text** — the `-Command` domain has no shell-quoting layer, but a model-facing command is parsed by PowerShell itself, so PowerShell syntax errors are command failures, not launch failures.
-- **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`.
 - **Windows termination reports no signal** — a force-killed process settles as exit 1 with `signal: null`, so signal-based status classification does not apply on Windows; `kill()`-initiated stops still stamp `killed` directly.
 - **The encoding preamble precedes the command** — PowerShell requires `param(...)`, `#requires`, and `using` statements at the very top of a script, so a command whose first statement is one of those cannot run under the UTF-8 output preamble; wrap a `param(...)` script in `& { … }`, and run `using`/`#requires` scripts from a file instead.
 - **Non-ASCII stdin under Windows PowerShell 5.1 may be mis-decoded** — the preamble pins output encoding only; `[Console]::InputEncoding` stays at the host default because setting it under redirected stdin throws; pwsh 7 defaults to UTF-8 and is unaffected.

package/README.zh.md

@@ -57,21 +57,22 @@ kind: "package-reference"
 
 ### 运行命令
 
-用 `run` 运行命令并从结果读取输出；非零退出、超时或取消都会返回描述性结果，只有基础设施失败才会导致调用被拒绝。命令字符串作为单个参数传给 `-Command`：由 PowerShell 自己解析文本，不存在中间 shell，因此没有需要转义的 shell 引号层，原生 Win32 路径也原样通过。每条命令都先固定 UTF-8 输出，因此即使在 Windows PowerShell 5.1 兜底上，非 ASCII 输出也不会乱码。环境默认面向模型：`NO_COLOR=1 PAGER=cat GIT_PAGER=cat`（没有 `TERM=dumb`——那是 POSIX 概念），调用方显式提供的条目仍然优先。
+通过等待执行句柄的 `result()` 投影来运行命令；非零退出、超时或取消都会返回描述性结果，只有基础设施失败才会导致调用被拒绝。命令字符串作为单个参数传给 `-Command`：由 PowerShell 自己解析文本，不存在中间 shell，因此没有需要转义的 shell 引号层，原生 Win32 路径也原样通过。每条命令都先固定 UTF-8 输出，因此即使在 Windows PowerShell 5.1 兜底上，非 ASCII 输出也不会乱码。环境默认面向模型：`NO_COLOR=1 PAGER=cat GIT_PAGER=cat`（没有 `TERM=dumb`——那是 POSIX 概念），调用方显式提供的条目仍然优先。
 
 ```text
-const result = await ctx.shell.run(ctx.shell.resolve({ command: 'Get-ChildItem' }))
+const execution = await ctx.shell.execute(ctx.shell.resolve({ command: 'Get-ChildItem' }))
+const result = await execution.result()
 if (result.timedOut) console.log('timed out after', result.timeoutMs)
 ```
 
 ### 后台进程
 
-等待 `start` 即可在后台运行命令；它完成准备后返回进程句柄，且不应用执行超时。取消或准备失败会在发布句柄前拒绝调用。`readOutput()` 把流增量合并为一次消费式读取，并在 `[stderr]` 分段下标记 stderr；`kill()` 终止由提供方管理的 range；`done` 在 direct command 关闭时结算且绝不 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>
 ### 运行时调整预算
 
-当组合了设置提供方时，本执行器注册该能力共享的 `shell` 设置命名空间——与 POSIX 家族共用同一个，因为一个宿主只组装一个 `ctx.shell` 提供方——因此 `settings.yaml` 中的用户段会叠加在组合条目之上，下一条命令即按新预算运行。schema 无法判定的值——正有限数字与 `graceMs` 的定时器上界——会在写入时被拒绝，运行中的执行器保持它最后一份可用的段。
+执行预算是解析每条命令时读取的 volatile Config 字段。插件页面编辑当前执行器的 profile 条目。完整 Config 验证在表单写入磁盘前拒绝无效数字和定时器上限。
 
 -----
 
@@ -145,7 +146,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 - **自身不提供隔离**——命令以 harness 进程的权限运行；需要隔离的部署组合沙箱执行器或策略。
 - **没有持久 shell 或 PTY**——每次调用都启动全新的 `pwsh -Command`。
 - **命令字符串是 PowerShell 文本**——`-Command` 域没有 shell 引号层，但面向模型的命令由 PowerShell 自己解析，因此 PowerShell 语法错误是命令失败，而非启动失败。
-- **后台提供方失败提示只投递一次**——`SubprocessHandle.done` 可能在目标开始执行前或后被拒绝，因此执行器会将不指明失败阶段的 `subprocess failed before reporting an outcome: …` 注入且仅注入一个 `readOutput()` 增量；丢弃该增量的读取方无法恢复它。
+- **后台提供方失败提示就是整条 stderr 流**——`SubprocessHandle.done` 可能在目标命令开始执行前或后被拒绝，而 subprocess 服务不会为从未上报结果的目标命令 缓冲任何输出，因此执行器把不声明失败阶段的 `subprocess failed before reporting an outcome: …` 作为观测到的 stderr 流提供（偏移读取方按各自偏移重读），并只折入恰好一个 `readOutput()` 增量；丢弃了该增量的消耗式读取方只能经 `observed.stderr` 恢复它。
 - **Windows 终止不报告信号**——被强制终止的进程以退出码 1、`signal: null` 结算，因此基于信号的状态分类在 Windows 上不适用；`kill()` 发起的停止仍会直接标记为 `killed`。
 - **编码 preamble 位于命令之前**——PowerShell 要求 `param(...)`、`#requires` 与 `using` 语句位于脚本最顶部，因此以其中一种开头的命令无法在 UTF-8 输出 preamble 下运行；`param(...)` 脚本请包进 `& { … }`，`using`/`#requires` 脚本请改从文件运行。
 - **Windows PowerShell 5.1 下的非 ASCII stdin 可能被错误解码**——preamble 只固定输出编码；`[Console]::InputEncoding` 保持主机默认，因为在重定向 stdin 下设置它会抛出异常；pwsh 7 默认 UTF-8，不受影响。

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";
 import { lstatSync } from "node:fs";
 import { join } from "node:path";
@@ -79,64 +79,6 @@ function resolvePwshPath(configured, env = process.env, platform = process.platf
 *
 * @module @deepseek-ai/dsh-pwsh-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 for PowerShell: disable colors and
 * pagers that would garble tool output. `TERM=dumb` is a POSIX concept and is
@@ -175,19 +117,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 assertServiceablePwshConfig(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(`pwsh-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(`pwsh-local: graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`);
 }
 /**
 * Local PowerShell executor over `ctx.subprocess`. Bounded output, spill
@@ -195,51 +135,35 @@ function assertServiceablePwshConfig(config) {
 * this executor supplies their configured budgets per spawn.
 */
 var PwshLocalExecutor = class PwshLocalExecutor 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),
-		pwshPath: z.string()
+		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(),
+		pwshPath: z.string().volatile()
 	});
-	/** The currently authoritative config: the settings section, or the composition entry. */
-	source;
 	/** The declared executable the current {@link pwshPath} was resolved from. */
 	declaredPwshPath;
 	/** The pwsh executable resolved from the current config. */
 	resolvedPwshPath;
-	/** Validated config (schemastery applied the defaults before construction). */
-	get config() {
-		return this.source();
-	}
-	/** The pwsh executable every command runs through. */
+	/** The pwsh executable every command runs through; a changed declared path is probed again on the next read. */
 	get pwshPath() {
+		const declared = this.config.pwshPath.get();
+		if (declared !== this.declaredPwshPath) {
+			this.resolvedPwshPath = resolvePwshPath(declared);
+			this.declaredPwshPath = declared;
+		}
 		return this.resolvedPwshPath;
 	}
 	constructor(ctx, config) {
 		super(ctx);
-		const entry = config;
-		assertServiceablePwshConfig(entry);
-		this.source = () => entry;
-		this.declaredPwshPath = entry.pwshPath;
-		this.resolvedPwshPath = resolvePwshPath(entry.pwshPath);
-		ctx.inject(["settings"], (settingsCtx) => {
-			settingsCtx.settings.installSection(ctx, SHELL_SETTINGS_NAMESPACE, PwshLocalExecutor.Config, entry, {
-				validate: assertServiceablePwshConfig,
-				setSource: (current) => {
-					this.source = current;
-				},
-				onChange: () => {
-					const declared = this.source().pwshPath;
-					if (declared === this.declaredPwshPath) return;
-					this.declaredPwshPath = declared;
-					this.resolvedPwshPath = resolvePwshPath(declared);
-				}
-			});
-		});
+		this.config = config;
+		this.declaredPwshPath = config.pwshPath.get();
+		this.resolvedPwshPath = resolvePwshPath(this.declaredPwshPath);
 	}
 	/**
 	* Resolve a request into a fully-specified spec: fill `workdir` from
@@ -247,13 +171,15 @@ var PwshLocalExecutor = class PwshLocalExecutor extends ShellExecutor {
 	* `config.timeoutMs`, capped at `config.maxTimeoutMs`.
 	*/
 	resolve(request) {
-		const timeoutMs = clampTimeout(request.timeoutMs, this.config.timeoutMs, this.config.maxTimeoutMs, "pwsh-local: request.timeoutMs");
-		const stdoutMaxBytes = request.stdoutMaxBytes ?? this.config.maxOutputBytes;
+		assertServiceablePwshConfig(this.config);
+		const timeoutMs = clampTimeout(request.timeoutMs, this.config.timeoutMs.get(), this.config.maxTimeoutMs.get(), "pwsh-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 } : {},
@@ -265,7 +191,7 @@ var PwshLocalExecutor = class PwshLocalExecutor extends ShellExecutor {
 	/**
 	* The pwsh invocation argv for one resolved spec — the argv-level seam a
 	* confining subclass wraps through `ctx.sandbox.confine` (the pwsh twin of
-	* `dsh-bash-local`'s `runArgv`/`startArgv` hooks; see
+	* `dsh-bash-local`'s `executeArgv` hook; see
 	* `@deepseek-ai/dsh-pwsh-sandbox`).
 	*/
 	argv(spec) {
@@ -282,7 +208,7 @@ var PwshLocalExecutor = class PwshLocalExecutor extends ShellExecutor {
 	spawnSpec(spec, stdoutMaxBytes, signal, argv) {
 		const collect = (maxBytes) => ({
 			maxBytes,
-			spill: { maxBytes: this.config.maxSpillBytes }
+			spill: { maxBytes: this.config.maxSpillBytes.get() }
 		});
 		return {
 			argv: [...argv],
@@ -290,9 +216,9 @@ var PwshLocalExecutor = class PwshLocalExecutor 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,
@@ -312,116 +238,140 @@ var PwshLocalExecutor = class PwshLocalExecutor extends ShellExecutor {
 			stderr
 		};
 	}
-	async run(spec) {
-		return (await this.runArgv(spec, this.argv(spec))).result;
+	async execute(spec) {
+		return this.executeArgv(spec, this.argv(spec));
 	}
 	/**
-	* Run argv preparation and execution under one foreground deadline.
+	* 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, spec.stdoutMaxBytes, d.signal, argv));
-			const outcome = await handle.done;
-			const collected = PwshLocalExecutor.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
+				};
 			};
-		} catch (e_1) {
-			env_1.error = e_1;
-			env_1.hasError = true;
-		} finally {
-			__disposeResources(env_1);
+			disarm = () => {
+				d[Symbol.dispose]();
+			};
+		} else {
+			spawnSignal = spec.signal;
+			classify = () => ({
+				timedOut: false,
+				aborted: spec.signal?.aborted === true
+			});
 		}
-	}
-	async start(spec) {
-		return Promise.resolve(this.startArgv(spec, this.argv(spec)));
-	}
-	/** Background start of an exact argv (the confining subclass re-wraps it). */
-	startArgv(spec, argv) {
-		spec.signal?.throwIfAborted();
-		const running = this.ctx.subprocess.spawn(this.spawnSpec(spec, this.config.maxOutputBytes, spec.signal, argv));
-		const collected = PwshLocalExecutor.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, spec.stdoutMaxBytes, spawnSignal, argv));
+		} catch (error) {
+			syncSpawnError = { error };
+		}
+		const emptyReader = { readFrom: () => ({
+			text: "",
+			lossy: false,
+			nextOffset: 0
+		}) };
+		const collected = running !== void 0 ? PwshLocalExecutor.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);
@@ -442,10 +392,25 @@ var PwshLocalExecutor = class PwshLocalExecutor 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

@@ -12,10 +12,11 @@
  *
  * @module @deepseek-ai/dsh-pwsh-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 for PowerShell: disable colors and
  * pagers that would garble tool output. `TERM=dumb` is a POSIX concept and is
@@ -35,37 +36,34 @@ export declare const ENV_OVERRIDES: {
  * numbers stay accurate.
  */
 export declare const ENCODING_PREAMBLE = "[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false); $OutputEncoding = [System.Text.UTF8Encoding]::new($false); ";
-/** 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>;
     /**
      * Explicit pwsh executable. When omitted, well-known Windows install
      * locations and PATH entries are probed in order (PowerShell 7 install,
      * PATH entries such as the Microsoft Store install, then Windows
      * PowerShell 5.1), falling back to a bare `pwsh` resolved through PATH.
      */
-    pwshPath?: string;
+    pwshPath: Volatile<string | undefined>;
 }
-/** The shape after schemastery applied the defaults (cwd/pwshPath have none). */
-type ResolvedConfig = Required<Omit<Config, 'cwd' | 'pwshPath'>> & Pick<Config, 'cwd' | 'pwshPath'>;
 export { candidatePwshPaths, resolvePwshPath } from './resolve.ts';
 /**
  * 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 assertServiceablePwshConfig(config: Config): void;
@@ -75,17 +73,30 @@ export declare function assertServiceablePwshConfig(config: Config): void;
  * this executor supplies their configured budgets per spawn.
  */
 export declare class PwshLocalExecutor 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;
+    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">;
+        pwshPath: z<string, string, "volatile">;
+    }>>, 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">;
+        pwshPath: z<string, string, "volatile">;
+    }>>, "plain">;
     /** The declared executable the current {@link pwshPath} was resolved from. */
     private declaredPwshPath;
     /** The pwsh executable resolved from the current config. */
     private resolvedPwshPath;
-    /** Validated config (schemastery applied the defaults before construction). */
-    get config(): ResolvedConfig;
-    /** The pwsh executable every command runs through. */
+    /** The pwsh executable every command runs through; a changed declared path is probed again on the next read. */
     get pwshPath(): string;
     constructor(ctx: Context, config: Config);
     /**
@@ -97,7 +108,7 @@ export declare class PwshLocalExecutor extends ShellExecutor {
     /**
      * The pwsh invocation argv for one resolved spec — the argv-level seam a
      * confining subclass wraps through `ctx.sandbox.confine` (the pwsh twin of
-     * `dsh-bash-local`'s `runArgv`/`startArgv` hooks; see
+     * `dsh-bash-local`'s `executeArgv` hook; see
      * `@deepseek-ai/dsh-pwsh-sandbox`).
      */
     protected argv(spec: ShellExecSpec): string[];
@@ -105,20 +116,18 @@ export declare class PwshLocalExecutor extends ShellExecutor {
     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 argv preparation and execution under one foreground deadline.
+     * 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>;
-    /** Background start of an exact argv (the confining subclass re-wraps it). */
-    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.
      * The base implementation is intentionally empty. Mirrored from

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-pwsh-local",
   "description": "Local PowerShell implementation of the DeepSeek Harness bash executor seam",
-  "version": "0.1.6-alpha.2",
+  "version": "0.1.7-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,21 +27,19 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-shell": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-settings": "^0.1.6-alpha.2"
+    "@deepseek-ai/dsh-shell": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-timeout": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "0.1.7-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/schemastery": "~3.18.4"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-shell": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-subprocess": "^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/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-settings": "^0.1.6-alpha.2"
+    "@deepseek-ai/dsh-shell": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-timeout": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-subprocess-local": "0.1.7-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.4"
   }
 }