feat(pwsh): add the pwsh-local executor and the pwsh tool

Windows-native execution foundation: PwshLocalExecutor implements the bash
executor seam over ctx.subprocess (pwsh -NoLogo -NoProfile -NonInteractive
-Command, one argv element, no quoting layer; resolvePwshPath probes
PowerShell 7 / PATH / Windows PowerShell 5.1 as a pure function), and
tool-pwsh is the minimal PowerShell-dialect model-facing tool over ctx.bash
(foreground only, managed DSH_* env, timeout/signal/exit markers, terminal
and generic presenters). Both packages carry full suites (real pwsh,
self-skipping without it) at per-file 100% coverage; vitest's Windows
exclusion narrows from packages/bash/* to the bash-requiring packages so the
pwsh suites run natively on Windows too. The CLI gains the workspace deps
and tsconfig projects without mounting either plugin; the Windows-default
roadmap is recorded as a proposed Agent Note.

packages/bash/pwsh-local/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: a97612ab4e11bf4a3fcfb77daf0624a894b02ad4
+README.zh.md: d6751dac6df789eec9727c1380f1a4c91da60728

packages/bash/pwsh-local/README.md

@@ -0,0 +1,53 @@
+# @deepseek-ai/dsh-pwsh-local
+
+English | [中文](README.zh.md)
+
+Local PowerShell implementation of 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`, and the pure `resolvePwshPath`/`candidatePwshPaths` helpers.
+
+## 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 (and where it came from)
+
+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.
+- **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`. 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, 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`; interactive terminal sessions remain deferred until the roadmap's pwsh TUI/GUI rendering work lands.
+- **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.
+
+Scrub-heuristic and spill-retention caveats live with [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md), which owns those mechanics.

packages/bash/pwsh-local/README.zh.md

@@ -0,0 +1,53 @@
+# @deepseek-ai/dsh-pwsh-local
+
+[English](README.md) | 中文
+
+`@deepseek-ai/dsh-bash` 执行器 seam 的本地 PowerShell 实现，基于 [`@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` 辅助函数。
+
+## 配置
+
+```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 加载与会干扰工具输出的提示符。
+- **可执行文件解析**——`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`。进程树终止（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`；交互式终端会话在路线图的 pwsh TUI/GUI 渲染工作落地之前保持延期。
+- **命令字符串是 PowerShell 文本**——`-Command` 域没有 shell 引号层，但面向模型的命令由 PowerShell 自己解析，因此 PowerShell 语法错误是命令失败，而非启动失败。
+- **后台 spawn 失败提示只投递一次**——subprocess 服务不会为从未运行的进程缓冲输出，因此执行器只把 `spawn failed: …` 注入一次 `readOutput()` 增量；丢弃该增量的读取方无法恢复它。
+- **Windows 终止不报告信号**——被强制终止的进程以退出码 1、`signal: null` 结束，因此基于信号的状态分类（POSIX `killed`）在 Windows 上不适用；`kill()` 发起的停止仍会直接盖上 `killed`。
+
+清理启发式与 spill 保留的注意事项由 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 持有，它拥有这些机制。

packages/bash/pwsh-local/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@deepseek-ai/dsh-pwsh-local",
+  "description": "Local PowerShell implementation of the DeepSeek Harness bash executor seam",
+  "version": "0.0.1",
+  "private": true,
+  "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",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-bash": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-bash": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/bash/pwsh-local/src/index.ts

@@ -0,0 +1,316 @@
+/**
+ * Local PowerShell implementation of the bash executor 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 { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { Context } from 'cordis'
+import z from 'schemastery'
+import { BashExecutor } from '@deepseek-ai/dsh-bash'
+import type { BashExecRequest, BashExecSpec, BashProcess, BashProcessRead, BashRunResult, CollectedOutput } from '@deepseek-ai/dsh-bash'
+import type { SubprocessCollect, SubprocessHandle, SubprocessOutputReader, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import { clampTimeout, deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
+
+/**
+ * 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
+
+/** 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 for inherited pipes after shell exit. */
+  graceMs?: number
+  /**
+   * Explicit pwsh executable. When omitted, well-known Windows install
+   * locations are probed first (PowerShell 7, 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'>
+
+/**
+ * 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: NodeJS.ProcessEnv = process.env): string[] {
+  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
+}
+
+/**
+ * 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?: string,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  if (configured !== undefined && configured.length > 0) return configured
+  if (platform === 'win32') {
+    for (const candidate of candidatePwshPaths(env)) {
+      if (existsSync(candidate)) return candidate
+    }
+  }
+  return 'pwsh'
+}
+
+/** 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`)
+  }
+}
+
+/**
+ * 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 BashExecutor {
+  static inject = ['subprocess']
+
+  static Config: z<Config> = z.object({
+    cwd: z.string(),
+    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(),
+  })
+
+  /** 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) {
+    super(ctx)
+    // Schemastery fills these fields before construction; the type does not encode that step.
+    this.config = config as ResolvedConfig
+    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)
+    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: BashExecRequest): BashExecSpec {
+    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 } : {},
+      sandboxPolicy: request.sandboxPolicy,
+    }
+  }
+
+  /** Map one resolved bash spec onto a fully-specified subprocess spawn. */
+  private spawnSpec(spec: BashExecSpec, stdoutMaxBytes: number, signal: AbortSignal | undefined): SubprocessSpawnSpec {
+    const collect = (maxBytes: number): SubprocessCollect =>
+      ({ maxBytes, spill: { maxBytes: this.config.maxSpillBytes } })
+    return {
+      argv: [this.pwshPath, '-NoLogo', '-NoProfile', '-NonInteractive', '-Command', spec.command],
+      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: BashExecSpec): Promise<BashRunResult> {
+    // One deadline combines timeout and upstream cancellation; disposal clears its timer.
+    using d = deadline(spec.signal, spec.timeoutMs, 'BASH_TIMEOUT')
+    const handle = this.ctx.subprocess.spawn(this.spawnSpec(spec, spec.stdoutMaxBytes, d.signal))
+    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, 'BASH_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: BashExecSpec): BashProcess {
+    // 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))
+    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: BashProcess = {
+      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)
+      }, (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)
+      }),
+      readOutput: (): BashProcessRead => {
+        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.
+   * @param _proc - the settled process handle.
+   * @param _stderr - the process's retained stderr tail used by subclasses for settlement classification.
+   */
+  protected onProcessDone(_proc: BashProcess, _stderr: string): void {}
+}
+
+export default PwshLocalExecutor

packages/bash/pwsh-local/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-pwsh-local`.
+ * @module @deepseek-ai/dsh-pwsh-local/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-pwsh-local'
+
+/** Cordis companion plugin name. */
+export const name = 'pwsh-local-invariant'
+/** Service required before the companion can reserve package ownership. */
+export 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: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/bash/pwsh-local/tests/executor.spec.ts

@@ -0,0 +1,412 @@
+/**
+ * Real-process tests for `@deepseek-ai/dsh-pwsh-local`: the LOCAL subprocess
+ * service plus a REAL pwsh executable, exercised through the executor seam
+ * (`resolve` → `run`/`start`). These verify the world — actual PowerShell
+ * runs, output capture, truncation and spill, deadlines, kill escalation, and
+ * the background-handle contract. The suite self-skips when no `pwsh` is on
+ * PATH (a CI accommodation for hosts without PowerShell); the pure unit tests
+ * (config validation, executable resolution) run on every platform. PowerShell
+ * writes CRLF on Windows, so exact text assertions normalize line endings.
+ */
+
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { PwshLocalExecutor, candidatePwshPaths, resolvePwshPath } from '@deepseek-ai/dsh-pwsh-local'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import type { BashProcess } from '@deepseek-ai/dsh-bash'
+
+const spillDir = mkdtempSync(join(tmpdir(), 'dsh-pwsh-exec-spec-'))
+
+const hasPwsh = spawnSync('pwsh', ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', '$true'], { encoding: 'utf8' }).status === 0
+
+/** Normalize PowerShell's platform line endings (CRLF on Windows, LF elsewhere). */
+const lf = (text: string): string => text.replace(/\r\n/g, '\n')
+
+/** Case-insensitive path equality on Windows (Get-Location may re-case the drive). */
+function samePath(actual: string, expected: string): boolean {
+  const norm = (value: string) => (process.platform === 'win32' ? value.toLowerCase() : value)
+  return norm(actual) === norm(expected)
+}
+
+async function setup(config: ConstructorParameters<typeof PwshLocalExecutor>[1] = {}) {
+  const ctx = new Context()
+  await ctx.plugin(LocalSubprocessService)
+  ;(ctx.subprocess as LocalSubprocessService).internals = { spillDir }
+  // A short kill grace via the REAL config path, so escalation tests stay fast.
+  await ctx.plugin(PwshLocalExecutor, { graceMs: 200, ...config })
+  const bash = ctx.bash as PwshLocalExecutor
+  return { ctx, bash }
+}
+
+/**
+ * Poll a handle's consuming readOutput until the ACCUMULATED delta contains
+ * `expected`; returns the accumulation (reads never re-deliver, so the caller
+ * gets everything produced up to the match).
+ */
+async function readUntil(proc: BashProcess, expected: string, timeoutMs = 5_000): Promise<string> {
+  const deadline = Date.now() + timeoutMs
+  let all = ''
+  while (Date.now() < deadline) {
+    all += proc.readOutput().delta
+    if (lf(all).includes(expected)) return lf(all)
+    await new Promise(resolve => setTimeout(resolve, 20))
+  }
+  throw new Error(`process output did not include ${JSON.stringify(expected)}; accumulated ${JSON.stringify(lf(all))}`)
+}
+
+describe('resolvePwshPath and candidatePwshPaths (pure, every platform)', () => {
+  it('trusts an explicit configured path verbatim', () => {
+    expect(resolvePwshPath('C:\\custom\\pwsh.exe')).toBe('C:\\custom\\pwsh.exe')
+    expect(resolvePwshPath('pwsh')).toBe('pwsh')
+  })
+
+  it('falls through an empty configured path to platform resolution', () => {
+    // SystemRoot points at a non-existent tree so the Windows PowerShell 5.1
+    // fallback candidate cannot exist either.
+    expect(resolvePwshPath('', { PATH: 'P:\\Store', SystemRoot: 'S:\\no-windows' }, 'win32')).toBe('pwsh')
+  })
+
+  it('returns pwsh on non-Windows platforms regardless of the environment', () => {
+    expect(resolvePwshPath(undefined, { ProgramFiles: 'P:\\Program Files' }, 'linux')).toBe('pwsh')
+    expect(resolvePwshPath(undefined, { PATH: 'P:\\Store' }, 'darwin')).toBe('pwsh')
+  })
+
+  it('lists PowerShell 7, PATH entries (quotes stripped), then Windows PowerShell 5.1 on win32', () => {
+    const candidates = candidatePwshPaths({
+      ProgramFiles: 'P:\\Program Files',
+      SystemRoot: 'S:\\Windows',
+      PATH: ';"Q:\\quoted store";' + ';',
+    })
+    expect(candidates).toEqual([
+      join('P:\\Program Files', 'PowerShell', '7', 'pwsh.exe'),
+      join('Q:\\quoted store', 'pwsh.exe'),
+      join('S:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
+    ])
+    // A missing PATH contributes no entries (the empty-string fallback).
+    expect(candidatePwshPaths({ ProgramFiles: 'P:\\Program Files', SystemRoot: 'S:\\Windows' }))
+      .toEqual([
+        join('P:\\Program Files', 'PowerShell', '7', 'pwsh.exe'),
+        join('S:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
+      ])
+  })
+
+  it('returns the first EXISTING win32 candidate, else pwsh', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-pwsh-resolve-'))
+    const store = join(dir, 'store')
+    mkdirSync(store, { recursive: true })
+    writeFileSync(join(store, 'pwsh.exe'), '')
+    // The existing PATH entry wins over the non-existent Program Files install.
+    expect(resolvePwshPath(undefined, { ProgramFiles: join(dir, 'missing'), PATH: store }, 'win32'))
+      .toBe(join(store, 'pwsh.exe'))
+    // No candidate exists anywhere (SystemRoot points at a non-existent tree,
+    // so even the Windows PowerShell 5.1 fallback cannot exist) → the
+    // PATH-resolution fallback.
+    expect(resolvePwshPath(undefined, { ProgramFiles: join(dir, 'missing'), PATH: join(dir, 'empty'), SystemRoot: join(dir, 'no-windows') }, 'win32'))
+      .toBe('pwsh')
+  })
+})
+
+describe.skipIf(!hasPwsh)('PwshLocalExecutor.run', () => {
+  it('resolves with output and the effective timeout', async () => {
+    const { bash } = await setup({ timeoutMs: 5_000 })
+    const result = await bash.run(bash.resolve({ command: 'Write-Output hi' }))
+    expect(result.exitCode).toBe(0)
+    expect(lf(result.stdout.text)).toBe('hi\n')
+    expect(result.timeoutMs).toBe(5_000)
+  })
+
+  it('uses config cwd, overridable per call', async () => {
+    const first = mkdtempSync(join(tmpdir(), 'dsh-pwsh-cwd-a-'))
+    const second = mkdtempSync(join(tmpdir(), 'dsh-pwsh-cwd-b-'))
+    const { bash } = await setup({ cwd: first })
+    const fromConfig = await bash.run(bash.resolve({ command: '(Get-Location).Path' }))
+    expect(samePath(fromConfig.stdout.text.trim(), first)).toBe(true)
+    const fromCall = await bash.run(bash.resolve({ command: '(Get-Location).Path', workdir: second }))
+    expect(samePath(fromCall.stdout.text.trim(), second)).toBe(true)
+  })
+
+  it('defaults cwd to process.cwd()', async () => {
+    const { bash } = await setup()
+    const result = await bash.run(bash.resolve({ command: '(Get-Location).Path' }))
+    expect(samePath(result.stdout.text.trim(), process.cwd())).toBe(true)
+  })
+
+  it('caps per-call timeouts at maxTimeoutMs', async () => {
+    const { bash } = await setup({ timeoutMs: 1_000, maxTimeoutMs: 2_000 })
+    const result = await bash.run(bash.resolve({ command: 'Write-Output ok', timeoutMs: 99_999 }))
+    expect(result.timeoutMs).toBe(2_000)
+  })
+
+  it('rejects invalid numeric config and timeout overrides', async () => {
+    await expect(setup({ timeoutMs: Number.NaN })).rejects.toThrow(/timeoutMs/)
+    await expect(setup({ maxTimeoutMs: 0 })).rejects.toThrow(/maxTimeoutMs/)
+    await expect(setup({ maxOutputBytes: -1 })).rejects.toThrow(/maxOutputBytes/)
+    await expect(setup({ maxSpillBytes: 0 })).rejects.toThrow(/maxSpillBytes/)
+    await expect(setup({ graceMs: 0 })).rejects.toThrow(/graceMs/)
+
+    const { bash } = await setup()
+    expect(() => bash.resolve({ command: 'Write-Output ok', timeoutMs: Number.NaN })).toThrow(/request\.timeoutMs/)
+    expect(() => bash.resolve({ command: 'Write-Output ok', timeoutMs: -1 })).toThrow(/request\.timeoutMs/)
+    expect(() => bash.resolve({ command: 'Write-Output ok', stdoutMaxBytes: Number.NaN })).toThrow(/request\.stdoutMaxBytes/)
+    expect(() => bash.resolve({ command: 'Write-Output ok', stdoutMaxBytes: -1 })).toThrow(/request\.stdoutMaxBytes/)
+  })
+
+  it('defaults stdoutMaxBytes to maxOutputBytes and lets foreground callers raise stdout only', async () => {
+    const { bash } = await setup({ maxOutputBytes: 100 })
+    expect(bash.resolve({ command: 'Write-Output ok' }).stdoutMaxBytes).toBe(100)
+
+    // Raw Console writes avoid PowerShell's own line-ending and formatting
+    // layers, so the byte counts are exact on every platform.
+    const result = await bash.run(bash.resolve({
+      command: '[Console]::Out.Write("x" * 500); [Console]::Error.WriteLine("e" * 500)',
+      stdoutMaxBytes: 500,
+    }))
+
+    expect(result.stdout.text).toBe('x'.repeat(500))
+    expect(result.stdout.truncated).toBe(false)
+    expect(result.stderr.truncated).toBe(true)
+    expect(result.stderr.text.length).toBeLessThanOrEqual(100)
+  })
+
+  it('per-call timeout takes precedence under the cap and kills on expiry', async () => {
+    const { bash } = await setup({ timeoutMs: 60_000 })
+    const result = await bash.run(bash.resolve({ command: 'Start-Sleep -Seconds 60', timeoutMs: 100 }))
+    expect(result.timedOut).toBe(true)
+    // Mutually exclusive: a timeout classifies as timedOut, never also aborted.
+    expect(result.aborted).toBe(false)
+    expect(result.timeoutMs).toBe(100)
+  })
+
+  it('propagates abort signals', async () => {
+    const { bash } = await setup()
+    const controller = new AbortController()
+    const pending = bash.run(bash.resolve({ command: 'Start-Sleep -Seconds 60', signal: controller.signal }))
+    setTimeout(() => { controller.abort() }, 50)
+    const result = await pending
+    expect(result.aborted).toBe(true)
+    // Mutually exclusive: an upstream cancel classifies as aborted, never also timedOut.
+    expect(result.timedOut).toBe(false)
+  })
+
+  it('classifies a self-killed command as neither timed out nor aborted', async () => {
+    const { bash } = await setup({ timeoutMs: 60_000 })
+    const result = await bash.run(bash.resolve({ command: 'Stop-Process -Id $PID' }))
+    expect(result.timedOut).toBe(false)
+    expect(result.aborted).toBe(false)
+    // Windows reports a forced termination without a signal; POSIX reports SIGTERM.
+    if (process.platform === 'win32') {
+      expect(result.signal).toBeNull()
+    } else {
+      expect(result.signal).toBe('SIGTERM')
+    }
+  })
+
+  it('rejects on spawn failure (bad workdir)', async () => {
+    const { bash } = await setup()
+    await expect(bash.run(bash.resolve({ command: 'Write-Output ok', workdir: '/nonexistent-dsh' }))).rejects.toThrow(/ENOENT/)
+  })
+
+  it('resolve() carries stdin/env/dshEnv onto the spec, and run() threads them to the command', async () => {
+    const { bash } = await setup()
+    const spec = bash.resolve({
+      command: '$s = ([Console]::In.ReadToEnd()).TrimEnd(); Write-Output $s; Write-Output "[$env:SEAM_VAR][$env:DSH_SEAM_VAR]"',
+      stdin: 'piped\n',
+      env: { SEAM_VAR: 'env-ok' },
+      dshEnv: { DSH_SEAM_VAR: 'dsh-ok' },
+    })
+    // resolve() keeps the optional input/environment fields verbatim.
+    expect(spec.stdin).toBe('piped\n')
+    expect(spec.env).toEqual({ SEAM_VAR: 'env-ok' })
+    expect(spec.dshEnv).toEqual({ DSH_SEAM_VAR: 'dsh-ok' })
+    const result = await bash.run(spec)
+    expect(lf(result.stdout.text)).toBe('piped\n[env-ok][dsh-ok]\n')
+  })
+
+  it('resolve() omits stdin/env/dshEnv when the request supplies none', async () => {
+    const { bash } = await setup()
+    const spec = bash.resolve({ command: 'Write-Output ok' })
+    expect('stdin' in spec).toBe(false)
+    expect('env' in spec).toBe(false)
+    expect('dshEnv' in spec).toBe(false)
+  })
+})
+
+describe.skipIf(!hasPwsh)('PwshLocalExecutor.start (background process handles)', () => {
+  it('start returns immediately with a running handle that settles as completed', async () => {
+    const { bash } = await setup()
+    const before = Date.now()
+    const proc = bash.start(bash.resolve({ command: 'Start-Sleep -Milliseconds 200; Write-Output done' }))
+    expect(Date.now() - before).toBeLessThan(150)
+    expect(proc.status).toBe('running')
+    await proc.done
+    expect(proc.status).toBe('completed')
+    expect(proc.exitCode).toBe(0)
+  })
+
+  it('threads stdin and extra env into a background process', async () => {
+    const { bash } = await setup()
+    const proc = bash.start(bash.resolve({
+      command: '$s = ([Console]::In.ReadToEnd()).TrimEnd(); Write-Output $s; Write-Output "[$env:BG_VAR][$env:DSH_BG_VAR]"',
+      stdin: 'bg-stdin\n',
+      env: { BG_VAR: 'bg-env' },
+      dshEnv: { DSH_BG_VAR: 'bg-dsh-env' },
+    }))
+    const output = await readUntil(proc, '[bg-env][bg-dsh-env]')
+    expect(output).toBe('bg-stdin\n[bg-env][bg-dsh-env]\n')
+    await proc.done
+    expect(proc.exitCode).toBe(0)
+  })
+
+  it('readOutput is consuming: increments are never re-delivered, and reads stay valid after exit', async () => {
+    const { bash } = await setup()
+    const proc = bash.start(bash.resolve({ command: 'Write-Output first; Start-Sleep -Seconds 1; Write-Output second' }))
+    const first = await readUntil(proc, 'first\n')
+    expect(lf(first)).toBe('first\n')
+    await proc.done
+    // Read-after-exit returns the remaining buffered output — once.
+    const second = proc.readOutput()
+    expect(lf(second.delta)).toBe('second\n')
+    expect(second.lossy).toBe(false)
+    expect(proc.readOutput().delta).toBe('')
+  })
+
+  it('readOutput marks stderr sections', async () => {
+    const { bash } = await setup()
+    const proc = bash.start(bash.resolve({ command: 'Write-Output out; [Console]::Error.WriteLine("err")' }))
+    await proc.done
+    expect(lf(proc.readOutput().delta)).toBe('out\n[stderr]\nerr\n')
+  })
+
+  it('readOutput reports stderr-only deltas without a leading newline', async () => {
+    const { bash } = await setup()
+    const proc = bash.start(bash.resolve({ command: '[Console]::Error.WriteLine("err")' }))
+    await proc.done
+    expect(lf(proc.readOutput().delta)).toBe('[stderr]\nerr\n')
+  })
+
+  it('readOutput adds a separator only when stdout lacks a trailing newline', async () => {
+    const { bash } = await setup()
+    const proc = bash.start(bash.resolve({ command: '[Console]::Out.Write("out"); [Console]::Error.WriteLine("err")' }))
+    await proc.done
+    expect(lf(proc.readOutput().delta)).toBe('out\n[stderr]\nerr\n')
+  })
+
+  it('readOutput flags lossy reads and reports stdout spill paths', async () => {
+    const { bash } = await setup({ maxOutputBytes: 100 })
+    const proc = bash.start(bash.resolve({ command: '1..100 | ForEach-Object { "line-$_" }' }))
+    await proc.done
+    const read = proc.readOutput()
+    // Window slid past offset 0 → lossy, spill path points at the full stream.
+    expect(read.lossy).toBe(true)
+    expect(read.stdoutSpillPath).toBeDefined()
+  })
+
+  it('readOutput reports stderr spill paths', async () => {
+    const { bash } = await setup({ maxOutputBytes: 100 })
+    const proc = bash.start(bash.resolve({ command: '1..100 | ForEach-Object { [Console]::Error.WriteLine("line-$_") }' }))
+    await proc.done
+    const read = proc.readOutput()
+    expect(read.lossy).toBe(true)
+    expect(read.stderrSpillPath).toBeDefined()
+    expect(lf(read.delta)).toContain('[stderr]')
+  })
+
+  it('kill() terminates the process tree: true once, false after settlement', async () => {
+    const { bash } = await setup()
+    const proc = bash.start(bash.resolve({ command: 'Start-Sleep -Seconds 60' }))
+    expect(proc.kill()).toBe(true)
+    await proc.done
+    expect(proc.status).toBe('killed')
+    expect(proc.kill()).toBe(false)
+  })
+
+  it('kill() returns false for a naturally completed process', async () => {
+    const { bash } = await setup()
+    const proc = bash.start(bash.resolve({ command: 'Write-Output ok' }))
+    await proc.done
+    expect(proc.status).toBe('completed')
+    expect(proc.kill()).toBe(false)
+  })
+
+  it('a spec.signal abort settles the handle as killed, not completed', async () => {
+    const { bash } = await setup()
+    const controller = new AbortController()
+    const proc = bash.start(bash.resolve({ command: 'Start-Sleep -Seconds 60', signal: controller.signal }))
+    controller.abort()
+    await proc.done
+    expect(proc.status).toBe('killed')
+  })
+
+  it.skipIf(process.platform === 'win32')('a self-signal exit settles the handle as killed, not completed (POSIX)', async () => {
+    const { bash } = await setup()
+    const proc = bash.start(bash.resolve({ command: 'Stop-Process -Id $PID' }))
+    await proc.done
+    expect(proc.status).toBe('killed')
+    expect(proc.exitCode).toBeNull()
+    expect(proc.signal).toBe('SIGTERM')
+  })
+
+  it('a background spawn failure settles as killed with the error readable on stderr', async () => {
+    const { bash } = await setup()
+    const proc = bash.start(bash.resolve({ command: 'Write-Output ok', workdir: '/nonexistent-dsh' }))
+    // done resolves (never rejects) even though the process never ran.
+    await expect(proc.done).resolves.toBeUndefined()
+    expect(proc.status).toBe('killed')
+    expect(proc.readOutput().delta).toContain('spawn failed:')
+  })
+})
+
+describe.skipIf(!hasPwsh)('process lifecycle ownership (the subprocess service, not the executor)', () => {
+  it('a background process survives executor-fiber disposal and dies with the subprocess service', async () => {
+    const ctx = new Context()
+    const managerFiber = await ctx.plugin(LocalSubprocessService)
+    ;(ctx.subprocess as LocalSubprocessService).internals = { spillDir }
+    const executorFiber = await ctx.plugin(PwshLocalExecutor, { graceMs: 200 })
+    const bash = ctx.bash as PwshLocalExecutor
+
+    // The child prints its own pid so the test can probe liveness through the
+    // public read surface alone.
+    const proc = bash.start(bash.resolve({ command: 'Write-Output $PID; Start-Sleep -Seconds 60' }))
+    const pid = Number((await readUntil(proc, '\n')).trim())
+    expect(Number.isInteger(pid) && pid > 0).toBe(true)
+
+    // Executor reload/disposal leaves background work running — the
+    // handle stays live and readable, mirroring the task runtime's
+    // registrations-outlive-producer-fibers contract.
+    await executorFiber.dispose()
+    expect(proc.status).toBe('running')
+    expect(() => process.kill(pid, 0)).not.toThrow()
+
+    // Service disposal kills the group and AWAITS its exit (no orphans).
+    await managerFiber.dispose()
+    expect(() => process.kill(pid, 0)).toThrow()
+    await proc.done
+    // POSIX reports the kill as a signal; Windows reports a forced
+    // termination as exit 1 with no signal (indistinguishable from a crash),
+    // so the status stamp follows the platform's exit facts.
+    expect(proc.status).toBe(process.platform === 'win32' ? 'completed' : 'killed')
+  })
+
+  it('service disposal settles running handles and leaves settled ones untouched', async () => {
+    const ctx = new Context()
+    const managerFiber = await ctx.plugin(LocalSubprocessService)
+    ;(ctx.subprocess as LocalSubprocessService).internals = { spillDir }
+    await ctx.plugin(PwshLocalExecutor, { graceMs: 200 })
+    const bash = ctx.bash as PwshLocalExecutor
+
+    const finished = bash.start(bash.resolve({ command: 'Write-Output done' }))
+    await finished.done
+    expect(finished.status).toBe('completed')
+    const running = bash.start(bash.resolve({ command: 'Start-Sleep -Seconds 60' }))
+
+    await managerFiber.dispose()
+    // A settled process was untouched; the live one was terminated and joined.
+    expect(finished.status).toBe('completed')
+    await running.done
+    expect(running.status).toBe(process.platform === 'win32' ? 'completed' : 'killed')
+  })
+})

packages/bash/pwsh-local/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../util/timeout"
+    },
+    {
+      "path": "../../bash/bash"
+    },
+    {
+      "path": "../../subprocess/subprocess"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}