@deepseek-ai/dsh-pwsh-local 0.1.2-alpha.5 → 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/pwsh-local/README.md
-README.md: d9ad46b84f78a2a8ed373420039646e710b79710
-README.zh.md: ef4f7e376dbad2ad1878b45dae156b6afb312783
+README.md: 1d6872ec6b342f415b1632f87be5a485c4dfa270
+README.zh.md: 2594ecc1623fec9ea8022f92d1c38941f643d979

package/README.md

@@ -66,7 +66,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 tree; `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
@@ -85,7 +85,7 @@ This section explains the design of the executor and points at the code that rea
 
 ### Design concept
 
-The executor is the PowerShell Service Provider for the `ctx.shell` seam built on the subprocess capability: it owns everything pwsh-shaped — executable resolution, command defaulting and caps, deadline fusion and cause classification, UTF-8 output pinning, the model-friendly terminal environment, and the background read merge — while process-tree mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) belong to the subprocess service. Every call spawns a fresh non-interactive `pwsh -Command` with `-NoLogo -NoProfile -NonInteractive`, so commands are deterministic and profile state never leaks between calls.
+The executor is the PowerShell Service Provider for the `ctx.shell` seam built on the subprocess capability: it owns everything pwsh-shaped — executable resolution, command defaulting and caps, deadline fusion and cause classification, UTF-8 output pinning, 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-interactive `pwsh -Command` with `-NoLogo -NoProfile -NonInteractive`, so commands are deterministic and profile state never leaks between calls.
 
 ### Source map
 
@@ -143,7 +143,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 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.
 - **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

@@ -66,7 +66,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` 在 direct command 关闭时结算且绝不 reject。job id、所有权、轮询与通知属于通用 `ctx.jobs` 运行时，工具层会把句柄注册进去。
 
 <a id="adjusting-budgets-at-runtime"></a>
 ### 运行时调整预算
@@ -85,7 +85,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 
 ### 设计概念
 
-本执行器是基于 subprocess 能力的 `ctx.shell` seam 的 PowerShell Service Provider：它负责所有 pwsh 层职责——可执行文件解析、命令默认化与上限、deadline 融合与原因分类、UTF-8 输出固定、面向模型的终端环境，以及后台读取合并——而进程树机制（有界 spill 输出、凭据清除、终止升级、dispose（资源释放））属于 subprocess 服务。每次调用都 spawn 全新的非交互 `pwsh -Command`，并带 `-NoLogo -NoProfile -NonInteractive`，因此命令是确定性的，profile 状态绝不会在调用之间泄漏。
+本执行器是基于 subprocess 能力的 `ctx.shell` seam 的 PowerShell Service Provider：它负责所有 pwsh 层职责——可执行文件解析、命令默认化与上限、deadline 融合与原因分类、UTF-8 输出固定、面向模型的终端环境，以及后台读取合并——而 managed-range 机制（有界 spill 输出、凭据清除、终止升级、完全停稳与 dispose（资源释放））属于 subprocess 服务。每次调用都 spawn 全新的非交互 `pwsh -Command`，并带 `-NoLogo -NoProfile -NonInteractive`，因此命令是确定性的，profile 状态绝不会在调用之间泄漏。
 
 ### 源码地图
 
@@ -143,7 +143,7 @@ if (result.timedOut) console.log('timed out after', result.timeoutMs)
 - **自身不提供隔离**——命令以 harness 进程的权限运行；需要隔离的部署组合沙箱执行器或策略。
 - **没有持久 shell 或 PTY**——每次调用都启动全新的 `pwsh -Command`。
 - **命令字符串是 PowerShell 文本**——`-Command` 域没有 shell 引号层，但面向模型的命令由 PowerShell 自己解析，因此 PowerShell 语法错误是命令失败，而非启动失败。
-- **后台 spawn 失败提示只交付一次**——subprocess 服务不会为从未真正运行的进程缓冲任何输出，因此执行器把 `spawn failed: …` 注入恰好一个 `readOutput()` 增量；丢弃了该增量的读取方无法再恢复它。
+- **后台 provider failure 提示只交付一次**——`SubprocessHandle.done` 可能在 target 开始执行前或后 reject，因此执行器把不声明失败阶段的 `subprocess failed before reporting an outcome: …` 注入恰好一个 `readOutput()` 增量；丢弃了该增量的读取方无法再恢复它。
 - **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

@@ -191,7 +191,7 @@ function assertServiceablePwshConfig(config) {
 }
 /**
 * Local PowerShell executor over `ctx.subprocess`. Bounded output, spill
-* files, and process-tree termination are the subprocess service's mechanics;
+* files, and managed-range termination are the subprocess service's mechanics;
 * this executor supplies their configured budgets per spawn.
 */
 var PwshLocalExecutor = class PwshLocalExecutor extends ShellExecutor {
@@ -351,10 +351,10 @@ var PwshLocalExecutor = class PwshLocalExecutor extends ShellExecutor {
 	startArgv(spec, argv) {
 		const running = this.ctx.subprocess.spawn(this.spawnSpec(spec, this.config.maxOutputBytes, spec.signal, argv));
 		const collected = PwshLocalExecutor.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;
@@ -370,15 +370,21 @@ var PwshLocalExecutor = class PwshLocalExecutor 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}` : ""),
@@ -403,10 +409,10 @@ var PwshLocalExecutor = class PwshLocalExecutor extends ShellExecutor {
 	* pwsh-confining consumer is `@deepseek-ai/dsh-pwsh-sandbox`.
 	* @param _proc - the settled process handle.
 	* @param _stderr - the process's retained stderr tail used by subclasses for settlement classification.
-	* @param _spawnFailed - whether the spawn rejected before any process existed.
-	* @param _spawnError - the spawn rejection, when `_spawnFailed`.
+	* @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 { ENCODING_PREAMBLE, ENV_OVERRIDES, PwshLocalExecutor, PwshLocalExecutor as default, assertServiceablePwshConfig, candidatePwshPaths, resolvePwshPath };

package/lib/types/index.d.ts

@@ -71,7 +71,7 @@ export { candidatePwshPaths, resolvePwshPath } from './resolve.ts';
 export declare function assertServiceablePwshConfig(config: Config): void;
 /**
  * Local PowerShell executor over `ctx.subprocess`. Bounded output, spill
- * files, and process-tree termination are the subprocess service's mechanics;
+ * files, and managed-range termination are the subprocess service's mechanics;
  * this executor supplies their configured budgets per spawn.
  */
 export declare class PwshLocalExecutor extends ShellExecutor {
@@ -118,10 +118,10 @@ export declare class PwshLocalExecutor extends ShellExecutor {
      * pwsh-confining consumer is `@deepseek-ai/dsh-pwsh-sandbox`.
      * @param _proc - the settled process handle.
      * @param _stderr - the process's retained stderr tail used by subclasses for settlement classification.
-     * @param _spawnFailed - whether the spawn rejected before any process existed.
-     * @param _spawnError - the spawn rejection, when `_spawnFailed`.
+     * @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 PwshLocalExecutor;
 //# sourceMappingURL=index.d.ts.map

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