@bo-agent/pwsh-local 0.0.2

package/lib/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 @bo-agent/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/lib/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,EAAE,CAgBjF;AAqBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,UAAU,CAAC,EAAE,MAAM,EACnB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,MAAM,CAQR"}

package/lib/resolve.js

@@ -0,0 +1,76 @@
+/**
+ * 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 @bo-agent/pwsh-local/resolve
+ */
+import { lstatSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * 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 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'),
+    ];
+    // Microsoft Store installs (and any user-added location) live on PATH;
+    // entries may carry surrounding quotes from `setx`-style definitions.
+    for (const entry of (env.PATH ?? '').split(';')) {
+        const trimmed = entry.trim().replace(/^"|"$/g, '');
+        if (trimmed.length === 0)
+            continue;
+        candidates.push(join(trimmed, 'pwsh.exe'));
+    }
+    // Windows PowerShell 5.1 remains the last-resort fallback on legacy hosts.
+    candidates.push(join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'));
+    return candidates;
+}
+/**
+ * Whether a candidate can be spawned. lstat opens the entry itself instead of
+ * following reparse points, so it sees the Store app execution alias where
+ * stat hits the target's ACL (EACCES); Node reports that alias as a symlink
+ * on current releases and as a plain file on older ones, and CreateProcess
+ * resolves either shape. A real directory never matches.
+ */
+function candidateExists(candidate) {
+    try {
+        const stat = lstatSync(candidate);
+        return stat.isFile() || stat.isSymbolicLink();
+    }
+    catch {
+        // ENOENT (the candidate vanished between listing and probing) is the only
+        // expected failure; any other error names an unspawnable path, so false
+        // is the safe answer for it too.
+        return false;
+    }
+}
+/**
+ * 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 function resolvePwshPath(configured, env = process.env, platform = process.platform) {
+    if (configured !== undefined && configured.length > 0)
+        return configured;
+    if (platform === 'win32') {
+        for (const candidate of candidatePwshPaths(env)) {
+            if (candidateExists(candidate))
+                return candidate;
+        }
+    }
+    return 'pwsh';
+}
+//# sourceMappingURL=resolve.js.map

package/lib/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACrE,MAAM,YAAY,GAAG,GAAG,CAAC,YAAY,IAAI,mBAAmB,CAAA;IAC5D,MAAM,UAAU,GAAG,GAAG,CAAC,UAAU,IAAI,aAAa,CAAA;IAClD,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,YAAY,EAAE,YAAY,EAAE,GAAG,EAAE,UAAU,CAAC;KAClD,CAAA;IACD,uEAAuE;IACvE,sEAAsE;IACtE,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;QAClD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAQ;QAClC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAA;IAC5C,CAAC;IACD,2EAA2E;IAC3E,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAA;IAC5F,OAAO,UAAU,CAAA;AACnB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,SAAiB;IACxC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,CAAA;QACjC,OAAO,IAAI,CAAC,MAAM,EAAE,IAAI,IAAI,CAAC,cAAc,EAAE,CAAA;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;QAC1E,wEAAwE;QACxE,iCAAiC;QACjC,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,UAAmB,EACnB,MAAyB,OAAO,CAAC,GAAG,EACpC,WAA4B,OAAO,CAAC,QAAQ;IAE5C,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,UAAU,CAAA;IACxE,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,KAAK,MAAM,SAAS,IAAI,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;YAChD,IAAI,eAAe,CAAC,SAAS,CAAC;gBAAE,OAAO,SAAS,CAAA;QAClD,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/lib/timeout.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Minimal timeout + deadline primitives used by the pwsh-local executor.
+ * Inlined here (rather than imported from a separate `@bo-agent/timeout`
+ * package) to keep the dependency surface small — same pattern as
+ * `@bo-agent/bash-local`.
+ *
+ * @module @bo-agent/pwsh-local/timeout
+ */
+/**
+ * Largest value `setTimeout` can express as a 32-bit signed milliseconds
+ * delay. Anything larger would wrap to a near-immediate fire. Inlined to
+ * mirror Node's `TIMEOUT_MAX` and to keep the dependency surface small.
+ */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/**
+ * Clamp a per-call value against a configured range. The default applies
+ * first; the maximum caps any explicit caller-supplied value.
+ * @param value - the requested value (may be undefined).
+ * @param defaultValue - the value used when none is requested.
+ * @param maxValue - the upper bound for explicit values.
+ * @param name - label prefixed to thrown errors.
+ * @returns a positive finite value within [1, maxValue].
+ * @throws Error when neither default nor requested value is a positive finite
+ *   number, or when maxValue itself is invalid.
+ */
+export declare function clampTimeout(value: number | undefined, defaultValue: number, maxValue: number, name: string): number;
+/** A symbol tagged on the AbortSignal's reason so the timeout reason is identifiable. */
+export declare const TIMEOUT_REASON: unique symbol;
+/**
+ * Combine a caller's optional AbortSignal with a millisecond timeout into a
+ * single controller. Either side aborts the controller; disposal clears the
+ * timer and removes the upstream listener, so the result is safe to discard
+ * at end of scope via the `using` declaration.
+ */
+export interface DeadlineHandle {
+    readonly signal: AbortSignal;
+    [Symbol.dispose](): void;
+}
+/**
+ * Build a deadline fused from the caller's signal and the executor's
+ * timeout. The returned controller aborts on whichever fires first; a
+ * successful command observes `signal.aborted === false`. The timeout
+ * reason is tagged so callers can tell timeout apart from upstream
+ * cancellation.
+ * @param signal - caller's upstream signal; may be undefined.
+ * @param timeoutMs - milliseconds until the timeout branch aborts.
+ * @param reason - human-readable label for the timeout reason; only used
+ *   for tagging, never surfaced to the user.
+ */
+export declare function deadline(signal: AbortSignal | undefined, timeoutMs: number, reason: string): DeadlineHandle;
+/**
+ * Return the tagged reason if the controller aborted because of the timeout
+ * branch (or upstream cancellation that mirrored it). Other abort reasons
+ * resolve as the caller's own cancellation; undefined means the controller
+ * is still live.
+ * @param signal - a controller's signal after a wait.
+ * @param expected - the label passed to {@link deadline}; matched against
+ *   the symbol tag, so the timeout reason identifies itself.
+ */
+export declare function timeoutOf(signal: AbortSignal, _expected: string): symbol | undefined;
+//# sourceMappingURL=timeout.d.ts.map

package/lib/timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../src/timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,aAAgB,CAAA;AAE/C;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,CASR;AAED,yFAAyF;AACzF,eAAO,MAAM,cAAc,eAAoD,CAAA;AAE/E;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAA;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,cAAc,CAwBhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIpF"}

package/lib/timeout.js

@@ -0,0 +1,92 @@
+/**
+ * Minimal timeout + deadline primitives used by the pwsh-local executor.
+ * Inlined here (rather than imported from a separate `@bo-agent/timeout`
+ * package) to keep the dependency surface small — same pattern as
+ * `@bo-agent/bash-local`.
+ *
+ * @module @bo-agent/pwsh-local/timeout
+ */
+/**
+ * Largest value `setTimeout` can express as a 32-bit signed milliseconds
+ * delay. Anything larger would wrap to a near-immediate fire. Inlined to
+ * mirror Node's `TIMEOUT_MAX` and to keep the dependency surface small.
+ */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/**
+ * Clamp a per-call value against a configured range. The default applies
+ * first; the maximum caps any explicit caller-supplied value.
+ * @param value - the requested value (may be undefined).
+ * @param defaultValue - the value used when none is requested.
+ * @param maxValue - the upper bound for explicit values.
+ * @param name - label prefixed to thrown errors.
+ * @returns a positive finite value within [1, maxValue].
+ * @throws Error when neither default nor requested value is a positive finite
+ *   number, or when maxValue itself is invalid.
+ */
+export function clampTimeout(value, defaultValue, maxValue, name) {
+    if (!Number.isFinite(maxValue) || maxValue <= 0) {
+        throw new Error(`${name}: maxValue must be a positive finite number`);
+    }
+    const candidate = value ?? defaultValue;
+    if (!Number.isFinite(candidate) || candidate <= 0) {
+        throw new Error(`${name}: value must be a positive finite number`);
+    }
+    return Math.min(candidate, maxValue);
+}
+/** A symbol tagged on the AbortSignal's reason so the timeout reason is identifiable. */
+export const TIMEOUT_REASON = Symbol.for('@bo-agent/pwsh-local/TIMEOUT_REASON');
+/**
+ * Build a deadline fused from the caller's signal and the executor's
+ * timeout. The returned controller aborts on whichever fires first; a
+ * successful command observes `signal.aborted === false`. The timeout
+ * reason is tagged so callers can tell timeout apart from upstream
+ * cancellation.
+ * @param signal - caller's upstream signal; may be undefined.
+ * @param timeoutMs - milliseconds until the timeout branch aborts.
+ * @param reason - human-readable label for the timeout reason; only used
+ *   for tagging, never surfaced to the user.
+ */
+export function deadline(signal, timeoutMs, reason) {
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(signal?.reason);
+    if (signal !== undefined) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+        }
+        else {
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    }
+    // `setTimeout` cannot express delays above MAX_TIMER_DELAY_MS without
+    // wrapping; cap the request so the timeout branch actually fires when
+    // promised.
+    const safeTimeout = Math.min(timeoutMs, MAX_TIMER_DELAY_MS);
+    const timer = setTimeout(() => {
+        controller.abort(TIMEOUT_REASON);
+    }, safeTimeout);
+    return {
+        signal: controller.signal,
+        [Symbol.dispose]() {
+            clearTimeout(timer);
+            if (signal !== undefined)
+                signal.removeEventListener('abort', onAbort);
+        },
+    };
+}
+/**
+ * Return the tagged reason if the controller aborted because of the timeout
+ * branch (or upstream cancellation that mirrored it). Other abort reasons
+ * resolve as the caller's own cancellation; undefined means the controller
+ * is still live.
+ * @param signal - a controller's signal after a wait.
+ * @param expected - the label passed to {@link deadline}; matched against
+ *   the symbol tag, so the timeout reason identifies itself.
+ */
+export function timeoutOf(signal, _expected) {
+    if (!signal.aborted)
+        return undefined;
+    if (signal.reason === TIMEOUT_REASON)
+        return TIMEOUT_REASON;
+    return undefined;
+}
+//# sourceMappingURL=timeout.js.map

package/lib/timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.js","sourceRoot":"","sources":["../src/timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAAA;AAE/C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAyB,EACzB,YAAoB,EACpB,QAAgB,EAChB,IAAY;IAEZ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,6CAA6C,CAAC,CAAA;IACvE,CAAC;IACD,MAAM,SAAS,GAAG,KAAK,IAAI,YAAY,CAAA;IACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,0CAA0C,CAAC,CAAA;IACpE,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;AACtC,CAAC;AAED,yFAAyF;AACzF,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,qCAAqC,CAAC,CAAA;AAa/E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ,CACtB,MAA+B,EAC/B,SAAiB,EACjB,MAAc;IAEd,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;IACxC,MAAM,OAAO,GAAG,GAAS,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5D,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACjC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;QAC3D,CAAC;IACH,CAAC;IACD,sEAAsE;IACtE,sEAAsE;IACtE,YAAY;IACZ,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAA;IAC3D,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC5B,UAAU,CAAC,KAAK,CAAC,cAAc,CAAC,CAAA;IAClC,CAAC,EAAE,WAAW,CAAC,CAAA;IACf,OAAO;QACL,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,CAAC,MAAM,CAAC,OAAO,CAAC;YACd,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,IAAI,MAAM,KAAK,SAAS;gBAAE,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACxE,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,MAAmB,EAAE,SAAiB;IAC9D,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,SAAS,CAAA;IACrC,IAAI,MAAM,CAAC,MAAM,KAAK,cAAc;QAAE,OAAO,cAAc,CAAA;IAC3D,OAAO,SAAS,CAAA;AAClB,CAAC"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@bo-agent/pwsh-local",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./resolve": {
+      "types": "./lib/resolve.d.ts",
+      "import": "./lib/resolve.js"
+    }
+  },
+  "dependencies": {
+    "cordis": "4.0.0-rc.10",
+    "schemastery": "3.18.0",
+    "@bo-agent/inline": "0.0.2",
+    "@bo-agent/shell": "0.0.2",
+    "@bo-agent/subprocess": "0.0.2"
+  },
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,351 @@
+/**
+ * Local PowerShell Service Provider for the pwsh 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 @bo-agent/pwsh-local
+ */
+
+/* jscpd:ignore-start -- this executor mirrors bash-local call-for-call by
+   design (see upstream README), so the two import the same seam surface */
+import { Context } from 'cordis'
+import z from 'schemastery'
+import { ShellExecutor } from '@bo-agent/shell'
+import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellProcessRead, ShellRunResult, CollectedOutput } from '@bo-agent/shell'
+import type { SubprocessCollect, SubprocessHandle, SubprocessOutputReader, SubprocessSpawnSpec } from '@bo-agent/subprocess'
+import { clampTimeout, deadline, MAX_TIMER_DELAY_MS, timeoutOf } from './timeout.ts'
+/* jscpd:ignore-end */
+import { resolvePwshPath } from './resolve.ts'
+
+/* jscpd:ignore-start -- deliberate call-for-call mirror of bash-local (pwsh-tool-and-executor). */
+/**
+ * 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 const ENV_OVERRIDES = {
+  NO_COLOR: '1',
+  PAGER: 'cat',
+  GIT_PAGER: 'cat',
+} as const
+
+/**
+ * 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.
+ *
+ * The type-creation (`[System.Text.UTF8Encoding]::new(...)`) is restricted in
+ * PowerShell's Constrained Language mode (Windows AppLocker / restricted
+ * token). When this executor runs under a Windows ACL restricted token,
+ * that mode is active and the construct errors; the `LanguageMode` check
+ * gates the assignment so the rest of the user's command still runs. Full
+ * LanguageMode runs hit the assignment unchanged.
+ */
+export const ENCODING_PREAMBLE =
+  "if ($ExecutionContext.SessionState.LanguageMode -ne 'ConstrainedLanguage') { [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 = 3_000
+
+/** Default per-stream spill cap (the `maxSpillBytes` config). */
+const DEFAULT_MAX_SPILL_BYTES = 64 * 1024 * 1024
+
+/** 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 get defaults). */
+type ResolvedConfig = Required<Omit<Config, 'cwd' | 'pwshPath'>> & Pick<Config, 'cwd' | 'pwshPath'>
+
+// Resolution lives in its own dependency-free module so callers and the
+// executor share one definition of which executable the package will use.
+export { candidatePwshPaths, resolvePwshPath } from './resolve.ts'
+
+/** Project a settled collect-mode reader into the final CollectedOutput shape. */
+function finalOutput(reader: SubprocessOutputReader): CollectedOutput {
+  const read = reader.readFrom(0)
+  return {
+    text: read.text,
+    truncated: read.lossy,
+    ...read.spillPath !== undefined ? { spillPath: read.spillPath } : {},
+  }
+}
+
+function assertPositiveFinite(name: string, value: number): void {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`pwsh-local: ${name} must be a positive finite number`)
+  }
+}
+
+/**
+ * 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.
+ * @throws Error naming the field that cannot be used.
+ */
+export function assertServiceablePwshConfig(config: Config): void {
+  const resolved = config as ResolvedConfig
+  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}`)
+  }
+}
+
+/**
+ * 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 class PwshLocalExecutor extends ShellExecutor {
+  static inject = ['subprocess']
+
+  static Config: z<Config> = z.object({
+    cwd: z.string().default(process.cwd()),
+    timeoutMs: z.number().default(120_000),
+    maxTimeoutMs: z.number().default(600_000),
+    maxOutputBytes: z.number().default(64_000),
+    maxSpillBytes: z.number().default(DEFAULT_MAX_SPILL_BYTES),
+    graceMs: z.number().default(DEFAULT_GRACE_MS),
+    pwshPath: z.string().default(''),
+  })
+
+  /** Validated config (schemastery applied the defaults before construction). */
+  private readonly config: ResolvedConfig
+
+  /** The pwsh executable resolved from the current config. */
+  private readonly resolvedPwshPath: string
+
+  /** The pwsh executable every command runs through. */
+  get pwshPath(): string {
+    return this.resolvedPwshPath
+  }
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx)
+    // Schemastery fills these fields before construction; the type does not encode that step.
+    const entry = config as ResolvedConfig
+    assertServiceablePwshConfig(entry)
+    this.config = entry
+    // Default pwshPath to platform resolution: probe well-known Windows
+    // installs, then fall back to a bare `pwsh` resolved through PATH.
+    this.resolvedPwshPath = resolvePwshPath(entry.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: ShellExecRequest): ShellExecSpec {
+    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 !== undefined ? { stdin: request.stdin } : {},
+      ...request.env !== undefined ? { env: request.env } : {},
+      ...request.dshEnv !== undefined ? { dshEnv: request.dshEnv } : {},
+      // Carry a sandbox policy through verbatim: this executor never
+      // confines, so the field is inert here (the seam contract) — a
+      // sandboxing subclass overrides resolve() to stamp its default instead.
+      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
+   * bash-local's `runArgv`/`startArgv` hooks; see `@bo-agent/pwsh-sandbox`).
+   */
+  protected argv(spec: ShellExecSpec): string[] {
+    return [this.pwshPath, '-NoLogo', '-NoProfile', '-NonInteractive', '-Command', `${ENCODING_PREAMBLE}${spec.command}`]
+  }
+
+  /** Map one resolved spec plus its argv onto a fully-specified subprocess spawn. */
+  private spawnSpec(
+    spec: ShellExecSpec,
+    stdoutMaxBytes: number,
+    signal: AbortSignal | undefined,
+    argv: readonly string[],
+  ): SubprocessSpawnSpec {
+    const collect = (maxBytes: number): SubprocessCollect =>
+      ({ maxBytes, spill: { maxBytes: this.config.maxSpillBytes } })
+    return {
+      argv: [...argv],
+      cwd: spec.workdir,
+      stdio: {
+        stdin: spec.stdin !== undefined ? { 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). */
+  private static collected(handle: SubprocessHandle): { stdout: SubprocessOutputReader; stderr: SubprocessOutputReader } {
+    const { stdout, stderr } = handle.collected
+    /* v8 ignore start -- collect dispositions expose both readers by the seam contract; defensive. */
+    if (stdout === undefined || stderr === undefined) {
+      throw new Error('pwsh-local: subprocess implementation dropped a requested collect stream')
+    }
+    /* v8 ignore stop */
+    return { stdout, stderr }
+  }
+
+  async run(spec: ShellExecSpec): Promise<ShellRunResult> {
+    return this.runArgv(spec, this.argv(spec))
+  }
+
+  /** Foreground run of an exact argv (the confining subclass re-wraps it). */
+  protected async runArgv(spec: ShellExecSpec, argv: readonly string[]): Promise<ShellRunResult> {
+    // One deadline combines timeout and upstream cancellation; disposal clears its timer.
+    using d = deadline(spec.signal, spec.timeoutMs, 'PWSH_TIMEOUT')
+    const handle = this.ctx.subprocess.spawn(this.spawnSpec(spec, spec.stdoutMaxBytes, d.signal, argv))
+    const outcome = await handle.done
+    const collected = PwshLocalExecutor.collected(handle)
+    // Only this executor's timeout reason counts as timedOut; outer deadlines count as aborts.
+    const timedOut = timeoutOf(d.signal, 'PWSH_TIMEOUT') !== undefined
+    const aborted = d.signal.aborted && !timedOut
+    return {
+      ...outcome,
+      timedOut,
+      aborted,
+      timeoutMs: spec.timeoutMs,
+      stdout: finalOutput(collected.stdout),
+      stderr: finalOutput(collected.stderr),
+    }
+  }
+
+  start(spec: ShellExecSpec): ShellProcess {
+    return this.startArgv(spec, this.argv(spec))
+  }
+
+  /** Background start of an exact argv (the confining subclass re-wraps it). */
+  protected startArgv(spec: ShellExecSpec, argv: readonly string[]): ShellProcess {
+    // Background runs ignore timeoutMs; callers stop them through kill() or spec.signal.
+    const running = this.ctx.subprocess.spawn(this.spawnSpec(spec, this.config.maxOutputBytes, spec.signal, argv))
+    const collected = PwshLocalExecutor.collected(running)
+
+    // A spawn failure produces no process output, so the subprocess service has nothing
+    // to buffer; the note is delivered exactly once through the read path.
+    let spawnFailureNote: string | undefined
+    const consumeSpawnFailure = (): string => {
+      const note = spawnFailureNote ?? ''
+      spawnFailureNote = undefined
+      return note
+    }
+
+    let stdoutOffset = 0
+    let stderrOffset = 0
+    const proc: ShellProcess = {
+      status: 'running',
+      exitCode: null,
+      signal: null,
+      done: running.done.then((outcome) => {
+        // Any signal termination is killed, including a command signaling itself.
+        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: unknown) => {
+        // Background spawn failures settle as killed and surface through the read path.
+        proc.status = 'killed'
+        spawnFailureNote = `spawn failed: ${String(error)}`
+        this.onProcessDone(proc, spawnFailureNote, true, error)
+      }),
+      readOutput: (): ShellProcessRead => {
+        const out = collected.stdout.readFrom(stdoutOffset)
+        const err = collected.stderr.readFrom(stderrOffset)
+        stdoutOffset = out.nextOffset
+        stderrOffset = err.nextOffset
+
+        // A failed spawn never produced process output, so the note and real
+        // stderr text are mutually exclusive.
+        const errText = err.text.length > 0 ? err.text : consumeSpawnFailure()
+        // Single newline between sections: stdout chunks usually end with one
+        // already; add it only when missing.
+        const separator = out.text.length > 0 && !out.text.endsWith('\n') ? '\n' : ''
+        const delta = out.text
+          + (errText.length > 0 ? `${separator}[stderr]\n${errText}` : '')
+        return {
+          delta,
+          lossy: out.lossy || err.lossy,
+          ...out.spillPath !== undefined ? { stdoutSpillPath: out.spillPath } : {},
+          ...err.spillPath !== undefined ? { stderrSpillPath: err.spillPath } : {},
+        }
+      },
+      kill: (): boolean => {
+        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
+   * `bash-local` (whose sandboxing subclass consumes the same hook); the
+   * pwsh-confining consumer is `@bo-agent/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: ShellProcess, _stderr: string, _spawnFailed: boolean, _spawnError?: unknown): void {}
+}
+/* jscpd:ignore-end */
+
+export default PwshLocalExecutor