@deepseek-ai/dsh-pwsh-local 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/bash/pwsh-local/README.md
+README.md: eb3365b009e3595230e5fb0f616079bd73c55840
+README.zh.md: d79201c756a26bbc343e2b284a803b0cf9aee69b

package/README.md

@@ -0,0 +1,56 @@
+# @deepseek-ai/dsh-pwsh-local
+
+English | [中文](README.zh.md)
+
+Local PowerShell Service provider for the `@deepseek-ai/dsh-bash` executor seam over the [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) service: `PwshLocalExecutor` spawns `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>` per call as a managed process through `ctx.subprocess`, and owns everything PowerShell-shaped — executable resolution, command defaulting and caps, timeout/cancel classification, the model-friendly terminal environment, and the model-facing stdout/stderr merge for background reads. Group mechanics (bounded spill-backed output, credential scrub, kill escalation, disposal) are the subprocess service's.
+
+The command string rides as ONE argv element to `-Command`: PowerShell itself parses the text, and no intermediate shell exists, so there is no shell-quoting layer to escape (the `bash -c` string domain has no equivalent here). Native Win32 paths (`C:\...`) pass through unchanged.
+
+The package root exports the default and named `PwshLocalExecutor` plugin, its `Config`, the pure `resolvePwshPath`/`candidatePwshPaths` helpers, and the `ENV_OVERRIDES`/`ENCODING_PREAMBLE` constants the executor injects into every spawn.
+
+## Config
+
+```yaml
+- id: bash
+  name: '@deepseek-ai/dsh-pwsh-local'
+  config:
+    cwd: C:\path\to\workspace   # default: process.cwd()
+    timeoutMs: 120000           # default foreground timeout
+    maxTimeoutMs: 600000        # cap for per-call overrides
+    maxOutputBytes: 64000       # per-stream in-memory cap; overflow spills to disk
+    maxSpillBytes: 67108864     # per-stream full-output spill cap
+    graceMs: 3000               # kill escalation and post-exit pipe-drain grace
+    pwshPath: C:\Program Files\PowerShell\7\pwsh.exe  # explicit executable; else well-known locations, then PATH
+```
+
+## Behavior
+
+The Windows counterpart of `dsh-bash-local`, deliberately mirroring its semantics call-for-call:
+
+- **Spawn per call, no shell state** — every call is a fresh non-interactive `pwsh -Command` (deterministic; no profile files). The `-NoLogo -NoProfile -NonInteractive` flags disable startup banners, profile loading, and prompts that would garble tool output.
+- **UTF-8 output pinned** — every command runs with `[Console]::OutputEncoding` and `$OutputEncoding` set to UTF-8 first, so the Windows PowerShell 5.1 fallback (or any host whose console code page is not UTF-8) cannot garble non-ASCII output: the subprocess collector decodes bytes as UTF-8. Input encoding is left at the host default; pwsh 7 defaults to UTF-8 and is unaffected.
+- **Executable resolution** — `resolvePwshPath` prefers an explicit `pwshPath`, then on Windows probes PowerShell 7's install location, every PATH entry (Microsoft Store installs; surrounding quotes stripped), and Windows PowerShell 5.1 as a legacy last resort, checking `existsSync` on each; elsewhere it falls back to a bare `pwsh` resolved through PATH. Resolution is a pure function of `(configured, env, platform)` and happens once at construction.
+- **Configured budgets over managed groups** — `resolve()` fills `workdir`/`timeoutMs`/`stdoutMaxBytes` from config, and every spawn hands the service explicit byte caps, spill cap, and `graceMs`. The grace must be positive, finite, and no greater than [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md), so Node can represent it with one timer. Tree termination (taskkill on Windows, process-group signals on POSIX), the post-exit pipe-drain grace, tail-keep truncation, and bounded spill files are [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) mechanics. A foreground `BashExecRequest.stdoutMaxBytes` can raise stdout's capture budget for one trusted caller; stderr and background runs still use `maxOutputBytes`.
+- **Timeout and cancel classification** — `run()` fuses its config-clamped timeout with the caller's signal through one deadline; only the executor's own timeout reports `timedOut`, an upstream cancel reports `aborted`, and a self-terminated command reports neither ([timeout-library Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)). Windows reports forced termination as exit 1 without a signal, so signal-stamped facts (`signal`, `killed` status) are POSIX-only there; the timeout/abort classification is platform-independent.
+- **Model-friendly terminal env** — `NO_COLOR=1 PAGER=cat GIT_PAGER=cat` (no `TERM=dumb`: that is a POSIX concept; `NO_COLOR` is honored by modern PowerShell renderers) merged as ordinary env under the service's credential scrub and `DSH_*` channel rules; an explicit caller entry still wins.
+- **Background processes** — `start()` returns a live `BashProcess` handle immediately, no timeout applies, and the handle's `readOutput()` merges the service's offset-based stdout/stderr reads into one marked-section delta with a consuming cursor. A still-running process belongs to the subprocess service, so it survives executor reloads and dies (killed and joined) with the service's disposal. Everything task-shaped (ids, ownership, polling, notices) lives in the generic [`ctx.tasks` runtime](../../tasks/tasks/README.md), which the tool layer registers the handle with — this executor never sees a session or a registry.
+
+## Model Experience
+
+Indirectly, through `dsh-tool-pwsh`, which renders this executor's bounded stdout/stderr tails, background-process deltas (through the generic task runtime), spill-file paths, and infrastructure failures.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Unconfined by itself** — this executor always runs commands with the harness process's authority; deployments needing confinement compose a sandboxing bash 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.
+- **Windows termination reports no signal** — a force-killed process settles as exit 1 with `signal: null`, so signal-based status classification (POSIX `killed`) does not apply on Windows; `kill()`-initiated stops still stamp `killed` directly.
+- **The encoding preamble precedes the command** — PowerShell requires `param(...)`, `#requires`, and `using namespace`/`using assembly` 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 `& { … }` (a param block legally heads a script block); `using` statements and `#requires` have no in-command workaround (`#requires` is inert inside `-Command` regardless of position) — run such 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.
+
+Scrub-heuristic and spill-retention caveats live with [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md), which owns those mechanics.

package/README.zh.md

@@ -0,0 +1,56 @@
+# @deepseek-ai/dsh-pwsh-local
+
+[English](README.md) | 中文
+
+`@deepseek-ai/dsh-bash` 执行器 seam 的本地 PowerShell Service provider，基于 [`@deepseek-ai/dsh-subprocess`](../../subprocess/subprocess/README.md) 服务：`PwshLocalExecutor` 每次调用以受管进程的方式通过 `ctx.subprocess` spawn `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>`，并拥有所有 PowerShell 形状的职责——可执行文件解析、命令默认化与上限、超时/取消分类、面向模型的终端环境，以及后台读取的 stdout/stderr 合并。进程组机制（有界 spill 输出、凭据清理、终止升级、销毁）属于 subprocess 服务。
+
+命令字符串作为 ONE argv 元素传给 `-Command`：由 PowerShell 自己解析文本，不存在中间 shell，因此没有需要转义的 shell 引号层（这里不存在与 `bash -c` 字符串域对应的层）。原生 Win32 路径（`C:\...`）原样通过。
+
+包根导出默认与具名 `PwshLocalExecutor` 插件、其 `Config`、纯函数 `resolvePwshPath`/`candidatePwshPaths` 辅助函数，以及执行器注入每次 spawn 的 `ENV_OVERRIDES`/`ENCODING_PREAMBLE` 常量。
+
+## 配置
+
+```yaml
+- id: bash
+  name: '@deepseek-ai/dsh-pwsh-local'
+  config:
+    cwd: C:\path\to\workspace   # default: process.cwd()
+    timeoutMs: 120000           # default foreground timeout
+    maxTimeoutMs: 600000        # cap for per-call overrides
+    maxOutputBytes: 64000       # per-stream in-memory cap; overflow spills to disk
+    maxSpillBytes: 67108864     # per-stream full-output spill cap
+    graceMs: 3000               # kill escalation and post-exit pipe-drain grace
+    pwshPath: C:\Program Files\PowerShell\7\pwsh.exe  # explicit executable; else well-known locations, then PATH
+```
+
+## 行为
+
+作为 `dsh-bash-local` 的 Windows 对应物，逐调用地镜像其语义：
+
+- **每次调用新建进程，无 shell 状态**——每次调用都是全新的非交互 `pwsh -Command`（确定性；不加载 profile 文件）。`-NoLogo -NoProfile -NonInteractive` 关闭启动横幅、profile 加载与会干扰工具输出的提示符。
+- **UTF-8 输出固定**——每条命令都先以 UTF-8 设置 `[Console]::OutputEncoding` 与 `$OutputEncoding`，因此 Windows PowerShell 5.1 兜底（或任何控制台代码页非 UTF-8 的主机）不会破坏非 ASCII 输出：subprocess collector 以 UTF-8 解码字节。输入编码保持宿主默认；pwsh 7 默认为 UTF-8，不受影响。
+- **可执行文件解析**——`resolvePwshPath` 优先显式 `pwshPath`，然后在 Windows 上依次探测 PowerShell 7 安装位置、每个 PATH 条目（Microsoft Store 安装；剥离两端引号）以及作为遗留兜底的 Windows PowerShell 5.1，逐一检查 `existsSync`；其他平台回退为通过 PATH 解析的裸 `pwsh`。解析是 `(configured, env, platform)` 的纯函数，在构造时执行一次。
+- **受管进程组之上的配置预算**——`resolve()` 从配置填充 `workdir`/`timeoutMs`/`stdoutMaxBytes`，每次 spawn 都向服务提供显式字节上限、spill 上限与 `graceMs`。该宽限期须为正有限值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)，这样 Node 就能用一个定时器表示它。进程树终止（Windows 用 taskkill，POSIX 用进程组信号）、退出后管道排空宽限、保尾截断与有界 spill 文件是 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 的机制。前台 `BashExecRequest.stdoutMaxBytes` 可为单个受信调用方提高 stdout 捕获预算；stderr 与后台运行仍使用 `maxOutputBytes`。
+- **超时与取消分类**——`run()` 通过一个 deadline 融合按配置上限截取的超时与调用方信号；只有执行器自身超时报告 `timedOut`，上游取消报告 `aborted`，自我终止的命令两者都不报告（见 [timeout 库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)）。Windows 将强制终止报告为退出码 1 且无信号，因此带信号标记的事实（`signal`、`killed` 状态）在那里仅限 POSIX；超时/取消分类与平台无关。
+- **面向模型的终端环境**——`NO_COLOR=1 PAGER=cat GIT_PAGER=cat`（没有 `TERM=dumb`：那是 POSIX 概念；现代 PowerShell 渲染器遵循 `NO_COLOR`），作为普通 env 在服务的凭据清理与 `DSH_*` 通道规则之下合并；显式调用方条目仍然优先。
+- **后台进程**——`start()` 立即返回存活的 `BashProcess` 句柄，不设超时；句柄的 `readOutput()` 把服务基于偏移的 stdout/stderr 读取合并为带标记分段的增量与消费游标。仍在运行的进程属于 subprocess 服务，因此它跨执行器重载存活，并随服务销毁（被终止并 join）。一切任务形状的职责（id、所有权、轮询、通知）都在通用 [`ctx.tasks` 运行时](../../tasks/tasks/README.md) 中，由工具层把句柄注册进去——本执行器从不接触会话或注册表。
+
+## 模型体验
+
+间接地，经由 `dsh-tool-pwsh` 呈现本执行器的有界 stdout/stderr 尾部、后台进程增量（经通用任务运行时）、spill 文件路径与基础设施失败。
+
+#### KV Cache 影响
+
+无直接失效；具名消费方拥有请求前缀的任何变更。
+
+## 已知局限与延期工作
+
+- **自身不设沙箱**——本执行器始终以 harness 进程的权限运行命令；需要约束的部署应组合沙箱化 bash 执行器或策略。
+- **无持久 shell 或 PTY**——每次调用都是全新的 `pwsh -Command`。
+- **命令字符串是 PowerShell 文本**——`-Command` 域没有 shell 引号层，但面向模型的命令由 PowerShell 自己解析，因此 PowerShell 语法错误是命令失败，而非启动失败。
+- **后台 spawn 失败提示只投递一次**——subprocess 服务不会为从未运行的进程缓冲输出，因此执行器只把 `spawn failed: …` 注入一次 `readOutput()` 增量；丢弃该增量的读取方无法恢复它。
+- **Windows 终止不报告信号**——被强制终止的进程以退出码 1、`signal: null` 结束，因此基于信号的状态分类（POSIX `killed`）在 Windows 上不适用；`kill()` 发起的停止仍会直接盖上 `killed`。
+- **编码 preamble 位于命令之前**——PowerShell 要求 `param(...)`、`#requires` 与 `using namespace`/`using assembly` 语句位于脚本最顶部，因此以其中一种开头的命令无法在 UTF-8 输出 preamble 下运行。`param(...)` 脚本可包进 `& { … }`（param 块可以合法地位于脚本块开头）；`using` 语句与 `#requires` 在命令内没有变通办法（`#requires` 在 `-Command` 中无论位置如何都不生效）——此类脚本请改从文件运行。
+- **Windows PowerShell 5.1 下的非 ASCII stdin 可能被错误解码**——preamble 只固定输出编码；`[Console]::InputEncoding` 保持主机默认，因为在重定向 stdin 下设置它会抛出异常。pwsh 7 默认 UTF-8，不受影响。
+
+清理启发式与 spill 保留的注意事项由 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 持有，它拥有这些机制。

package/lib/index.js

@@ -0,0 +1,359 @@
+import z from "@deepseek-ai/schemastery";
+import { BashExecutor } from "@deepseek-ai/dsh-bash";
+import { MAX_TIMER_DELAY_MS, clampTimeout, deadline, timeoutOf } from "@deepseek-ai/dsh-timeout";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+//#region lib/types/resolve.js
+/**
+* PowerShell executable resolution, dependency-free so non-package consumers
+* (the repository's coverage-gate probe in `vitest.config.ts`) can share the
+* ONE resolution definition with the executor and its suites — a probe that
+* resolved differently from the code under test could exempt a file whose
+* suites actually run.
+*
+* @module @deepseek-ai/dsh-pwsh-local/resolve
+*/
+/**
+* Well-known Windows PowerShell install locations plus PATH entries, newest
+* first. Explicitly parameterized (env) so resolution is a pure function of
+* its inputs on every platform.
+* @param env - the environment to probe; defaults to the process environment.
+* @returns candidate `pwsh` executable paths in resolution order.
+*/
+function candidatePwshPaths(env = process.env) {
+	const programFiles = env.ProgramFiles ?? "C:\\Program Files";
+	const systemRoot = env.SystemRoot ?? "C:\\Windows";
+	const candidates = [join(programFiles, "PowerShell", "7", "pwsh.exe")];
+	for (const entry of (env.PATH ?? "").split(";")) {
+		const trimmed = entry.trim().replace(/^"|"$/g, "");
+		if (trimmed.length === 0) continue;
+		candidates.push(join(trimmed, "pwsh.exe"));
+	}
+	candidates.push(join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"));
+	return candidates;
+}
+/**
+* Resolve the pwsh executable this executor spawns.
+* @param configured - an explicit `pwshPath` config value, trusted as-is.
+* @param env - the environment to probe on Windows; defaults to the process environment.
+* @param platform - the platform to resolve for; defaults to the process platform.
+* @returns the first existing well-known location on Windows (PowerShell 7
+*   install, a PATH entry such as the Microsoft Store install, then Windows
+*   PowerShell 5.1), else `pwsh` for PATH resolution.
+*/
+function resolvePwshPath(configured, env = process.env, platform = process.platform) {
+	if (configured !== void 0 && configured.length > 0) return configured;
+	if (platform === "win32") {
+		for (const candidate of candidatePwshPaths(env)) if (existsSync(candidate)) return candidate;
+	}
+	return "pwsh";
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Local PowerShell Service provider for the bash capability seam. Each command runs
+* as `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>` in a managed
+* process spawned through `ctx.subprocess`; the executor owns command
+* defaulting, deadlines and cause classification, the model-friendly terminal
+* environment, and the model-facing stdout/stderr merge for background reads.
+*
+* The command string is passed as ONE argv element to `-Command`: PowerShell
+* itself parses the text, and no intermediate shell exists, so there is no
+* shell-quoting layer to escape (the `bash -c` string domain has no
+* equivalent here). Native Win32 paths (`C:\...`) pass through unchanged.
+*
+* @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
+* deliberately absent; `NO_COLOR` is honored by modern pwsh renderers.
+*/
+const ENV_OVERRIDES = {
+	NO_COLOR: "1",
+	PAGER: "cat",
+	GIT_PAGER: "cat"
+};
+/**
+* UTF-8 output pinning prepended to every command. The subprocess collector
+* decodes output bytes as UTF-8, but Windows PowerShell 5.1 (the last-resort
+* executable fallback) writes the console/OEM code page by default, which
+* garbles non-ASCII output; pwsh 7 defaults to UTF-8 and is unaffected. The
+* statements ride on line 1 after `; ` separators so PowerShell error line
+* numbers stay accurate.
+*/
+const ENCODING_PREAMBLE = "[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false); $OutputEncoding = [System.Text.UTF8Encoding]::new($false); ";
+/** Default SIGTERM→SIGKILL grace period (the `graceMs` config). */
+const DEFAULT_GRACE_MS = 3e3;
+/** Default per-stream spill cap (the `maxSpillBytes` config). */
+const DEFAULT_MAX_SPILL_BYTES = 64 * 1024 * 1024;
+/** Project a settled collect-mode reader into the final CollectedOutput shape. */
+function finalOutput(reader) {
+	const read = reader.readFrom(0);
+	return {
+		text: read.text,
+		truncated: read.lossy,
+		...read.spillPath !== void 0 ? { spillPath: read.spillPath } : {}
+	};
+}
+function assertPositiveFinite(name, value) {
+	if (!Number.isFinite(value) || value <= 0) throw new Error(`pwsh-local: ${name} must be a positive finite number`);
+}
+/**
+* Local PowerShell executor over `ctx.subprocess`. Bounded output, spill
+* files, and process-tree termination are the subprocess service's mechanics;
+* this executor supplies their configured budgets per spawn.
+*/
+var PwshLocalExecutor = class PwshLocalExecutor extends BashExecutor {
+	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()
+	});
+	/** Validated config (schemastery applied the defaults before construction). */
+	config;
+	/** The pwsh executable resolved once at construction. */
+	pwshPath;
+	constructor(ctx, config) {
+		super(ctx);
+		this.config = config;
+		assertPositiveFinite("timeoutMs", this.config.timeoutMs);
+		assertPositiveFinite("maxTimeoutMs", this.config.maxTimeoutMs);
+		assertPositiveFinite("maxOutputBytes", this.config.maxOutputBytes);
+		assertPositiveFinite("maxSpillBytes", this.config.maxSpillBytes);
+		assertPositiveFinite("graceMs", this.config.graceMs);
+		if (this.config.graceMs > MAX_TIMER_DELAY_MS) throw new Error(`pwsh-local: graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`);
+		this.pwshPath = resolvePwshPath(this.config.pwshPath);
+	}
+	/**
+	* 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`.
+	*/
+	resolve(request) {
+		const timeoutMs = clampTimeout(request.timeoutMs, this.config.timeoutMs, this.config.maxTimeoutMs, "pwsh-local: request.timeoutMs");
+		const stdoutMaxBytes = request.stdoutMaxBytes ?? this.config.maxOutputBytes;
+		assertPositiveFinite("request.stdoutMaxBytes", stdoutMaxBytes);
+		return {
+			command: request.command,
+			workdir: request.workdir ?? this.config.cwd ?? process.cwd(),
+			timeoutMs,
+			stdoutMaxBytes,
+			...request.signal ? { signal: request.signal } : {},
+			...request.stdin !== void 0 ? { stdin: request.stdin } : {},
+			...request.env !== void 0 ? { env: request.env } : {},
+			...request.dshEnv !== void 0 ? { dshEnv: request.dshEnv } : {},
+			sandboxPolicy: request.sandboxPolicy
+		};
+	}
+	/**
+	* 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
+	* `@deepseek-ai/dsh-pwsh-sandbox`).
+	*/
+	argv(spec) {
+		return [
+			this.pwshPath,
+			"-NoLogo",
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			`${ENCODING_PREAMBLE}${spec.command}`
+		];
+	}
+	/** Map one resolved spec plus its argv onto a fully-specified subprocess spawn. */
+	spawnSpec(spec, stdoutMaxBytes, signal, argv) {
+		const collect = (maxBytes) => ({
+			maxBytes,
+			spill: { maxBytes: this.config.maxSpillBytes }
+		});
+		return {
+			argv: [...argv],
+			cwd: spec.workdir,
+			stdio: {
+				stdin: spec.stdin !== void 0 ? { data: spec.stdin } : "ignore",
+				stdout: collect(stdoutMaxBytes),
+				stderr: collect(this.config.maxOutputBytes)
+			},
+			graceMs: this.config.graceMs,
+			signal,
+			env: {
+				...ENV_OVERRIDES,
+				...spec.env,
+				...spec.dshEnv
+			}
+		};
+	}
+	/** The collect-mode readers the executor itself requested (present by construction). */
+	static collected(handle) {
+		const { stdout, stderr } = handle.collected;
+		/* v8 ignore start -- collect dispositions expose both readers by the seam contract; defensive. */
+		if (stdout === void 0 || stderr === void 0) throw new Error("pwsh-local: subprocess implementation dropped a requested collect stream");
+		/* v8 ignore stop */
+		return {
+			stdout,
+			stderr
+		};
+	}
+	async run(spec) {
+		return this.runArgv(spec, this.argv(spec));
+	}
+	/** Foreground run of an exact argv (the confining subclass re-wraps it). */
+	async runArgv(spec, argv) {
+		const env_1 = {
+			stack: [],
+			error: void 0,
+			hasError: false
+		};
+		try {
+			const d = __addDisposableResource(env_1, deadline(spec.signal, spec.timeoutMs, "BASH_TIMEOUT"), false);
+			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 {
+				...outcome,
+				timedOut,
+				aborted,
+				timeoutMs: spec.timeoutMs,
+				stdout: finalOutput(collected.stdout),
+				stderr: finalOutput(collected.stderr)
+			};
+		} catch (e_1) {
+			env_1.error = e_1;
+			env_1.hasError = true;
+		} finally {
+			__disposeResources(env_1);
+		}
+	}
+	start(spec) {
+		return this.startArgv(spec, this.argv(spec));
+	}
+	/** Background start of an exact argv (the confining subclass re-wraps it). */
+	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;
+			return note;
+		};
+		let stdoutOffset = 0;
+		let stderrOffset = 0;
+		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";
+				proc.exitCode = outcome.exitCode;
+				proc.signal = outcome.signal;
+				this.onProcessDone(proc, collected.stderr.readFrom(0).text, false);
+			}, (error) => {
+				proc.status = "killed";
+				spawnFailureNote = `spawn failed: ${String(error)}`;
+				this.onProcessDone(proc, spawnFailureNote, 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 separator = out.text.length > 0 && !out.text.endsWith("\n") ? "\n" : "";
+				return {
+					delta: out.text + (errText.length > 0 ? `${separator}[stderr]\n${errText}` : ""),
+					lossy: out.lossy || err.lossy,
+					...out.spillPath !== void 0 ? { stdoutSpillPath: out.spillPath } : {},
+					...err.spillPath !== void 0 ? { stderrSpillPath: err.spillPath } : {}
+				};
+			},
+			kill: () => {
+				if (proc.status !== "running") return false;
+				proc.status = "killed";
+				running.terminate();
+				return true;
+			}
+		};
+		return proc;
+	}
+	/**
+	* Settlement hook for subclasses that attach execution facts to a process.
+	* The base implementation is intentionally empty. Mirrored from
+	* `dsh-bash-local` (whose sandboxing subclass consumes the same hook); the
+	* 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`.
+	*/
+	onProcessDone(_proc, _stderr, _spawnFailed, _spawnError) {}
+};
+//#endregion
+export { ENCODING_PREAMBLE, ENV_OVERRIDES, PwshLocalExecutor, PwshLocalExecutor as default, candidatePwshPaths, resolvePwshPath };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-pwsh-local`.
+* @module @deepseek-ai/dsh-pwsh-local/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-pwsh-local";
+/** Cordis companion plugin name. */
+const name = "pwsh-local-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Local PowerShell Service provider for the bash capability seam. Each command runs
+ * as `pwsh -NoLogo -NoProfile -NonInteractive -Command <command>` in a managed
+ * process spawned through `ctx.subprocess`; the executor owns command
+ * defaulting, deadlines and cause classification, the model-friendly terminal
+ * environment, and the model-facing stdout/stderr merge for background reads.
+ *
+ * The command string is passed as ONE argv element to `-Command`: PowerShell
+ * itself parses the text, and no intermediate shell exists, so there is no
+ * shell-quoting layer to escape (the `bash -c` string domain has no
+ * equivalent here). Native Win32 paths (`C:\...`) pass through unchanged.
+ *
+ * @module @deepseek-ai/dsh-pwsh-local
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { BashExecutor } from '@deepseek-ai/dsh-bash';
+import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash';
+/**
+ * Model-friendly environment overrides for PowerShell: disable colors and
+ * pagers that would garble tool output. `TERM=dumb` is a POSIX concept and is
+ * deliberately absent; `NO_COLOR` is honored by modern pwsh renderers.
+ */
+export declare const ENV_OVERRIDES: {
+    readonly NO_COLOR: "1";
+    readonly PAGER: "cat";
+    readonly GIT_PAGER: "cat";
+};
+/**
+ * UTF-8 output pinning prepended to every command. The subprocess collector
+ * decodes output bytes as UTF-8, but Windows PowerShell 5.1 (the last-resort
+ * executable fallback) writes the console/OEM code page by default, which
+ * garbles non-ASCII output; pwsh 7 defaults to UTF-8 and is unaffected. The
+ * statements ride on line 1 after `; ` separators so PowerShell error line
+ * 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). */
+export interface Config {
+    /** Default working directory for commands (default: process.cwd()). */
+    cwd?: string;
+    /** Default foreground timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Upper bound for per-call timeout overrides. */
+    maxTimeoutMs?: number;
+    /** Per-stream in-memory output cap; overflow spills to a temp file. */
+    maxOutputBytes?: number;
+    /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */
+    maxSpillBytes?: number;
+    /** Grace period for kill escalation and inherited pipes; at most `MAX_TIMER_DELAY_MS`. */
+    graceMs?: 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;
+}
+/** 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';
+/**
+ * Local PowerShell executor over `ctx.subprocess`. Bounded output, spill
+ * files, and process-tree termination are the subprocess service's mechanics;
+ * this executor supplies their configured budgets per spawn.
+ */
+export declare class PwshLocalExecutor extends BashExecutor {
+    static inject: string[];
+    static Config: z<Config>;
+    /** Validated config (schemastery applied the defaults before construction). */
+    readonly config: ResolvedConfig;
+    /** The pwsh executable resolved once at construction. */
+    readonly pwshPath: string;
+    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`.
+     */
+    resolve(request: BashExecRequest): BashExecSpec;
+    /**
+     * 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
+     * `@deepseek-ai/dsh-pwsh-sandbox`).
+     */
+    protected argv(spec: BashExecSpec): string[];
+    /** Map one resolved spec plus its 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: BashExecSpec): Promise<BashRunResult>;
+    /** Foreground run of an exact argv (the confining subclass re-wraps it). */
+    protected runArgv(spec: BashExecSpec, argv: readonly string[]): Promise<BashRunResult>;
+    start(spec: BashExecSpec): BashProcess;
+    /** Background start of an exact argv (the confining subclass re-wraps it). */
+    protected startArgv(spec: BashExecSpec, argv: readonly string[]): BashProcess;
+    /**
+     * Settlement hook for subclasses that attach execution facts to a process.
+     * The base implementation is intentionally empty. Mirrored from
+     * `dsh-bash-local` (whose sandboxing subclass consumes the same hook); the
+     * 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`.
+     */
+    protected onProcessDone(_proc: BashProcess, _stderr: string, _spawnFailed: boolean, _spawnError?: unknown): void;
+}
+export default PwshLocalExecutor;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-pwsh-local`.
+ * @module @deepseek-ai/dsh-pwsh-local/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "pwsh-local-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/resolve.d.ts

@@ -0,0 +1,28 @@
+/**
+ * PowerShell executable resolution, dependency-free so non-package consumers
+ * (the repository's coverage-gate probe in `vitest.config.ts`) can share the
+ * ONE resolution definition with the executor and its suites — a probe that
+ * resolved differently from the code under test could exempt a file whose
+ * suites actually run.
+ *
+ * @module @deepseek-ai/dsh-pwsh-local/resolve
+ */
+/**
+ * Well-known Windows PowerShell install locations plus PATH entries, newest
+ * first. Explicitly parameterized (env) so resolution is a pure function of
+ * its inputs on every platform.
+ * @param env - the environment to probe; defaults to the process environment.
+ * @returns candidate `pwsh` executable paths in resolution order.
+ */
+export declare function candidatePwshPaths(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Resolve the pwsh executable this executor spawns.
+ * @param configured - an explicit `pwshPath` config value, trusted as-is.
+ * @param env - the environment to probe on Windows; defaults to the process environment.
+ * @param platform - the platform to resolve for; defaults to the process platform.
+ * @returns the first existing well-known location on Windows (PowerShell 7
+ *   install, a PATH entry such as the Microsoft Store install, then Windows
+ *   PowerShell 5.1), else `pwsh` for PATH resolution.
+ */
+export declare function resolvePwshPath(configured?: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
+//# sourceMappingURL=resolve.d.ts.map

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@deepseek-ai/dsh-pwsh-local",
+  "description": "Local PowerShell implementation of the DeepSeek Harness bash executor seam",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/bash/pwsh-local"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-bash": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-bash": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subprocess-local": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}