@akira-tl/forgerelay 0.10.1 → 0.10.2

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.10.2] - 2026-09-06
+
+### Added
+
+- Added first-class Windows PowerShell 5.1 (`powershell.exe`) execution for Agent commands, Hooks, pipe/PTY sessions, shell identity guidance, and packaged Windows acceptance while preserving PowerShell 5.1-specific syntax and quoting semantics.
+
+### Fixed
+
+- Hardened the Windows ConPTY lifecycle used by PowerShell runtimes: process-tree interruption no longer passes unsupported Windows signals, leaked ConPTY input/output resources are released after exit, and Windows PowerShell text I/O is normalized to UTF-8 so PTY completion, Unicode output, durable output, and child cleanup complete reliably.
+
 ## [0.10.1] - 2026-09-05
 
 ### Added

package/dist/mcp/process/process-platform.js

@@ -46,11 +46,29 @@ export function resolveShellCommandForRuntime(command, runtime, options = {}) {
                     command,
                 ],
             };
-        case "fish":
         case "powershell":
+            return {
+                executable: runtime.executable,
+                args: [
+                    "-NoLogo",
+                    "-NoProfile",
+                    ...(options.interactive ? [] : ["-NonInteractive"]),
+                    "-Command",
+                    windowsPowerShellUtf8Command(command),
+                ],
+            };
+        case "fish":
             throw new Error(`Command shell runtime ${runtime.family} is identified but native execution support is not enabled in this release stage. ForgeRelay will not silently execute the command through another shell.`);
     }
 }
+function windowsPowerShellUtf8Command(command) {
+    return [
+        "[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)",
+        "[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)",
+        "$OutputEncoding = [Console]::OutputEncoding",
+        command,
+    ].join("; ");
+}
 export function terminateProcessTree(child, signal, detached, runtime = defaultProcessTreeRuntime) {
     if (runtime.platform === "win32" && child.pid) {
         if (runtime.killWindowsTree(child.pid))
@@ -68,3 +86,40 @@ export function terminateProcessTree(child, signal, detached, runtime = defaultP
     }
     child.kill(signal);
 }
+export function releasePtyProcessResources(pty, platform = process.platform) {
+    if (platform !== "win32")
+        return;
+    // node-pty 1.1.0 leaves ConPTY resources referenced after exit: the input
+    // PipeWrap is not destroyed (microsoft/node-pty#947), and the system-ConPTY
+    // natural-exit path does not dispose its conout worker. Keep both workarounds
+    // at the PTY boundary so the shared ProcessManager stays platform-neutral.
+    const agent = pty._agent;
+    try {
+        agent?._conoutSocketWorker?.dispose?.();
+    }
+    catch {
+        // The worker may already be disposing after an explicit PTY kill.
+    }
+    const inputSocket = agent?.inSocket;
+    if (!inputSocket || inputSocket.destroyed || typeof inputSocket.destroy !== "function")
+        return;
+    try {
+        inputSocket.destroy();
+    }
+    catch {
+        // Completion must remain observable even if node-pty already released it.
+    }
+}
+export function terminatePtyProcessTree(pty, signal, runtime = defaultProcessTreeRuntime) {
+    if (runtime.platform === "win32") {
+        runtime.killWindowsTree(pty.pid);
+        try {
+            pty.kill();
+        }
+        catch {
+            // The PTY may already have completed after tree termination.
+        }
+        return;
+    }
+    pty.kill(signal);
+}

package/dist/mcp/process/process-sessions.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { resolveShellCommandForRuntime, terminateProcessTree } from "./process-platform.js";
+import { releasePtyProcessResources, resolveShellCommandForRuntime, terminateProcessTree, terminatePtyProcessTree } from "./process-platform.js";
 import { resolveCompatibilityCommandShellRuntime, snapshotCommandShellRuntime } from "../../runtime/shell/command-shell-runtime.js";
 const DEFAULT_EXEC_YIELD_MS = 10_000;
 const DEFAULT_INTERACTIVE_YIELD_MS = 250;
@@ -240,7 +240,7 @@ export class ProcessManager {
         const processEntry = this.createProcess(input);
         this.processes.set(processEntry.id, processEntry);
         try {
-            if (input.tty && process.platform !== "win32")
+            if (input.tty)
                 await this.startPty(processEntry, input);
             else
                 this.startPipe(processEntry, input);
@@ -455,7 +455,6 @@ export class ProcessManager {
         processEntry.process = {
             write: (data) => child.stdin.write(data),
             kill: (signal = "SIGTERM") => terminateProcessTree(child, signal, detached),
-            resize: input.tty ? () => undefined : undefined,
         };
         child.stdout.on("data", (data) => this.append(processEntry, "stdout", data));
         child.stderr.on("data", (data) => this.append(processEntry, "stderr", data));
@@ -471,30 +470,25 @@ export class ProcessManager {
             throw new Error("PTY support requires the optional node-pty dependency.");
         }
         const shell = resolveShellCommandForRuntime(input.command, this.commandShellRuntime, { interactive: true });
-        let pty;
-        try {
-            pty = nodePty.spawn(shell.executable, shell.args, {
-                cwd: input.cwd,
-                env: processEnvironment({
-                    workspaceId: input.workspaceId,
-                    workspaceRoot: input.workspaceRoot,
-                    codexCi: input.codexCi,
-                }),
-                name: "xterm-256color",
-                cols: processEntry.columns,
-                rows: processEntry.rows,
-            });
-        }
-        catch (error) {
-            throw error;
-        }
+        const pty = nodePty.spawn(shell.executable, shell.args, {
+            cwd: input.cwd,
+            env: processEnvironment({
+                workspaceId: input.workspaceId,
+                workspaceRoot: input.workspaceRoot,
+                codexCi: input.codexCi,
+            }),
+            name: "xterm-256color",
+            cols: processEntry.columns,
+            rows: processEntry.rows,
+        });
         processEntry.process = {
             write: (data) => pty.write(data),
-            kill: (signal) => pty.kill(signal),
+            kill: (signal = "SIGTERM") => terminatePtyProcessTree(pty, signal),
             resize: (columns, rows) => pty.resize(columns, rows),
         };
         pty.onData((data) => this.append(processEntry, "pty", data));
         pty.onExit(({ exitCode, signal }) => {
+            releasePtyProcessResources(pty);
             this.finish(processEntry, exitCode, signal === 0 ? undefined : String(signal));
         });
     }

package/dist/runtime/shell/command-shell-runtime.js

@@ -45,7 +45,7 @@ export function resolveConfiguredCommandShellRuntime(preference, platform = proc
             runtime = resolveCommandShellRuntime({ recordedFallback });
         }
     }
-    return enrichConfiguredCommandShellRuntime(runtime, metadata.probePowerShell7Version ?? probePowerShell7Version);
+    return enrichConfiguredCommandShellRuntime(runtime, metadata.probePowerShell7Version ?? probePowerShell7Version, metadata.probeWindowsPowerShellVersion ?? probeWindowsPowerShellVersion);
 }
 export function resolveCompatibilityCommandShellRuntime(platform = process.platform, environment = process.env) {
     if (platform === "win32") {
@@ -129,39 +129,67 @@ export function formatCommandShellRuntime(runtime) {
 export function snapshotCommandShellRuntime(runtime) {
     return { ...runtime, capabilities: [...runtime.capabilities] };
 }
-function enrichConfiguredCommandShellRuntime(runtime, powerShell7VersionProbe) {
-    if (runtime.family !== "pwsh")
-        return runtime;
-    const version = powerShell7VersionProbe(runtime.executable).trim();
-    const major = Number.parseInt(version.split(".", 1)[0] ?? "", 10);
-    if (!version || !Number.isInteger(major)) {
-        throw new Error(`Unable to determine PowerShell 7 version from ${runtime.executable}.`);
+function enrichConfiguredCommandShellRuntime(runtime, powerShell7VersionProbe, windowsPowerShellVersionProbe) {
+    if (runtime.family === "pwsh") {
+        const version = powerShell7VersionProbe(runtime.executable).trim();
+        const major = Number.parseInt(version.split(".", 1)[0] ?? "", 10);
+        if (!version || !Number.isInteger(major)) {
+            throw new Error(`Unable to determine PowerShell 7 version from ${runtime.executable}.`);
+        }
+        if (major < 7) {
+            throw new Error(`Configured pwsh runtime must be PowerShell 7 or newer; detected ${version} at ${runtime.executable}.`);
+        }
+        return {
+            ...runtime,
+            version,
+            capabilities: Array.from(new Set([
+                ...runtime.capabilities,
+                "profile-isolation",
+                "pipeline-chain-operators",
+            ])),
+        };
     }
-    if (major < 7) {
-        throw new Error(`Configured pwsh runtime must be PowerShell 7 or newer; detected ${version} at ${runtime.executable}.`);
+    if (runtime.family === "powershell") {
+        const version = windowsPowerShellVersionProbe(runtime.executable).trim();
+        const [majorText, minorText] = version.split(".", 3);
+        const major = Number.parseInt(majorText ?? "", 10);
+        const minor = Number.parseInt(minorText ?? "", 10);
+        if (!version || !Number.isInteger(major) || !Number.isInteger(minor)) {
+            throw new Error(`Unable to determine Windows PowerShell version from ${runtime.executable}.`);
+        }
+        if (major !== 5 || minor !== 1) {
+            throw new Error(`Configured powershell runtime must be Windows PowerShell 5.1; detected ${version} at ${runtime.executable}. ForgeRelay will not substitute pwsh for the selected runtime.`);
+        }
+        return {
+            ...runtime,
+            version,
+            capabilities: Array.from(new Set([
+                ...runtime.capabilities,
+                "profile-isolation",
+                "powershell-5.1",
+            ])),
+        };
     }
-    return {
-        ...runtime,
-        version,
-        capabilities: Array.from(new Set([
-            ...runtime.capabilities,
-            "profile-isolation",
-            "pipeline-chain-operators",
-        ])),
-    };
+    return runtime;
 }
 function probePowerShell7Version(executable) {
+    return probePowerShellVersion(executable, "PowerShell 7");
+}
+function probeWindowsPowerShellVersion(executable) {
+    return probePowerShellVersion(executable, "Windows PowerShell");
+}
+function probePowerShellVersion(executable, label) {
     const result = spawnSync(executable, ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", "$PSVersionTable.PSVersion.ToString()"], { encoding: "utf8", windowsHide: true, timeout: 5_000 });
     if (result.error) {
-        throw new Error(`Unable to query PowerShell 7 version from ${executable}: ${result.error.message}`);
+        throw new Error(`Unable to query ${label} version from ${executable}: ${result.error.message}`);
     }
     if (result.status !== 0) {
         const detail = result.stderr?.trim();
-        throw new Error(`Unable to query PowerShell 7 version from ${executable}: exited with code ${result.status ?? "unknown"}${detail ? `: ${detail}` : ""}.`);
+        throw new Error(`Unable to query ${label} version from ${executable}: exited with code ${result.status ?? "unknown"}${detail ? `: ${detail}` : ""}.`);
     }
     const version = result.stdout?.trim();
     if (!version)
-        throw new Error(`Unable to query PowerShell 7 version from ${executable}: no version was reported.`);
+        throw new Error(`Unable to query ${label} version from ${executable}: no version was reported.`);
     return version;
 }
 export function commandShellAgentInstruction(runtime) {
@@ -173,6 +201,9 @@ export function commandShellAgentInstruction(runtime) {
         `Executable: ${runtime.executable}.`,
         `Selection source: ${runtime.source}.`,
         "Write shell commands for this runtime rather than assuming Bash syntax.",
+        ...(runtime.family === "powershell"
+            ? ["Windows PowerShell 5.1 does not support PowerShell 7 pipeline-chain operators && or ||."]
+            : []),
     ].join(" ");
 }
 function runtimeFromSelection(selection, source) {

package/dist/server.js

@@ -124,7 +124,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         };
     };
     const toolDescriptions = buildToolDescriptions(config);
-    const hooks = new HookRunner(config.hooks, config.logging, process.env, (workspaceId, result) => attachCompletedProcessNotices(processSessions, workspaceId, result, (snapshot) => recordBashCompletion(activityLifecycle, bashOutputStore, snapshot.outputId)));
+    const hooks = new HookRunner(config.hooks, config.logging, process.env, (workspaceId, result) => attachCompletedProcessNotices(processSessions, workspaceId, result, (snapshot) => recordBashCompletion(activityLifecycle, bashOutputStore, snapshot.outputId)), config.commandShellRuntime);
     const incomingArtifactRegistry = new IncomingArtifactAdapterRegistry(incomingArtifactAdapters);
     const artifactDownloadAvailable = config.artifactsEnabled && isArtifactDownloadSupportedPlatform();
     const reviewChangesAvailable = config.widgets === "changes";

package/dist/subagents/sessions/execution.js

@@ -13,7 +13,7 @@ export async function executeSubagentRun(config, input, providerRunner = runSuba
         if (record.activeRun?.id !== input.runId) {
             throw new Error(`Subagent Run ${input.runId} is not active for Session ${record.id}.`);
         }
-        const hooks = new HookRunner(config.hooks, config.logging);
+        const hooks = new HookRunner(config.hooks, config.logging, process.env, undefined, config.commandShellRuntime);
         const hookInvocation = {
             workspaceId: record.workspaceId,
             workspaceRoot: record.workspaceRoot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -43,6 +43,7 @@
     "traffic:audit": "node --import tsx scripts/debug/traffic/traffic-audit.mjs",
     "lsp:interop": "node scripts/lsp/interop.mjs",
     "pwsh:accept": "node scripts/ci/pwsh-acceptance.mjs",
+    "powershell51:accept": "node scripts/ci/powershell51-acceptance.mjs",
     "wiki:check": "node scripts/wiki/sync.mjs check",
     "wiki:publish": "node scripts/wiki/sync.mjs publish",
     "architecture:check": "node scripts/ci/architecture.mjs",

package/scripts/ci/powershell51-acceptance.mjs

@@ -0,0 +1,483 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+if (process.platform !== "win32") {
+  console.log("Windows PowerShell 5.1 packaged acceptance skipped outside Windows.");
+  process.exit(0);
+}
+
+const npmCli = process.env.npm_execpath;
+if (!npmCli) throw new Error("Windows PowerShell acceptance must run through npm so npm_execpath is available");
+
+const root = await mkdtemp(join(tmpdir(), "forgerelay-powershell51-acceptance-"));
+try {
+  const powershell = resolveWindowsPowerShell();
+  const version = powerShellVersion(powershell);
+  const [majorText, minorText] = version.split(".", 3);
+  const major = Number.parseInt(majorText ?? "", 10);
+  const minor = Number.parseInt(minorText ?? "", 10);
+  assert.equal(major, 5, `Windows PowerShell acceptance requires major version 5; got ${version}`);
+  assert.equal(minor, 1, `Windows PowerShell acceptance requires version 5.1; got ${version}`);
+
+  const { resolveConfiguredCommandShellRuntime } = await import("../../dist/runtime/shell/command-shell-runtime.js");
+  const resolvedRuntime = resolveConfiguredCommandShellRuntime({
+    mode: "pinned",
+    family: "powershell",
+    executable: powershell,
+  }, "win32", process.env);
+  assert.equal(resolvedRuntime.family, "powershell");
+  assert.equal(resolvedRuntime.executable, powershell);
+  assert.equal(resolvedRuntime.version, version);
+  assert.ok(resolvedRuntime.capabilities.includes("windows-powershell"));
+  assert.ok(resolvedRuntime.capabilities.includes("profile-isolation"));
+  assert.ok(!resolvedRuntime.capabilities.includes("pipeline-chain-operators"));
+
+  await exerciseAgentRuntime(resolvedRuntime);
+  await exerciseHookRuntime(resolvedRuntime);
+  await exercisePackagedPowerShellShim(powershell, version);
+
+  console.log(`Windows PowerShell 5.1 acceptance passed with ${powershell} (${version}).`);
+} finally {
+  await rm(root, { recursive: true, force: true });
+}
+
+function resolveWindowsPowerShell() {
+  const result = spawnSync("where.exe", ["powershell.exe"], {
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    throw new Error("Windows release acceptance requires Windows PowerShell 5.1 (powershell.exe) on PATH.");
+  }
+  const executable = result.stdout?.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+  if (!executable) throw new Error("where.exe reported no powershell.exe path.");
+  return executable;
+}
+
+function powerShellVersion(executable) {
+  const result = spawnSync(
+    executable,
+    ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", "$PSVersionTable.PSVersion.ToString()"],
+    { encoding: "utf8", windowsHide: true },
+  );
+  if (result.error || result.status !== 0) {
+    throw new Error(`Unable to query ${executable} version: ${result.error?.message ?? result.stderr ?? result.status}`);
+  }
+  const version = result.stdout?.trim();
+  if (!version) throw new Error(`${executable} did not report a version.`);
+  return version;
+}
+
+async function exerciseAgentRuntime(runtime) {
+  const [{ ProcessManager }, { BashOutputStore }] = await Promise.all([
+    import("../../dist/mcp/process/process-sessions.js"),
+    import("../../dist/activity/history/bash-output-store.js"),
+  ]);
+  const durableStateDir = join(root, "durable-output-state");
+  const outputStore = new BashOutputStore(durableStateDir, {
+    outputId: () => "out_powershell51_pty_acceptance",
+    flushBytes: 1,
+  });
+  const manager = new ProcessManager({
+    commandShellRuntime: runtime,
+    outputAudit: outputStore,
+  });
+  const originalMarker = process.env.FORGERELAY_POWERSHELL51_ACCEPTANCE;
+  process.env.FORGERELAY_POWERSHELL51_ACCEPTANCE = "inherited environment";
+  try {
+    const node = powerShellLiteral(process.execPath);
+    const semantics = await manager.start({
+      workspaceId: "powershell51-agent",
+      cwd: process.cwd(),
+      command: [
+        'Write-Output "edition=$($PSVersionTable.PSEdition)"',
+        'Write-Output "version=$($PSVersionTable.PSVersion.ToString())"',
+        'Write-Output "env=$env:FORGERELAY_POWERSHELL51_ACCEPTANCE"',
+        "Write-Output 'pipe-unicode-雪'",
+        '1,2,3 | Measure-Object -Sum | ForEach-Object { Write-Output "sum=$($_.Sum)" }',
+        `$exe = ${node}`,
+        "& $exe -e 'console.log(JSON.stringify(process.argv.slice(1)))' 'native arg with spaces' 'plain-arg'",
+        "if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }",
+        "$redirect = Join-Path $env:TEMP 'forgerelay-powershell51-redirection.txt'",
+        "'redirected-through-windows-powershell' > $redirect",
+        "Get-Content $redirect",
+        "Remove-Item $redirect -Force",
+      ].join("; "),
+      yieldTimeMs: 10_000,
+    });
+    assert.equal(semantics.running, false);
+    assert.equal(semantics.exitCode, 0);
+    assert.match(semantics.output, /edition=Desktop/);
+    assert.match(semantics.output, /version=5\.1\./);
+    assert.match(semantics.output, /env=inherited environment/);
+    assert.match(semantics.output, /pipe-unicode-雪/);
+    assert.match(semantics.output, /sum=6/);
+    assert.match(semantics.output, /\["native arg with spaces","plain-arg"\]/);
+    assert.match(semantics.output, /redirected-through-windows-powershell/);
+
+    const errorSemantics = await manager.start({
+      workspaceId: "powershell51-agent",
+      cwd: process.cwd(),
+      command: [
+        "Write-Error 'nonterminating-windows-powershell-error'",
+        "Write-Output 'continued-after-nonterminating-error'",
+        "try { Get-Item 'forgerelay-definitely-missing-item' -ErrorAction Stop; exit 31 } catch { Write-Output 'terminating-error-caught' }",
+      ].join("; "),
+      yieldTimeMs: 10_000,
+    });
+    assert.equal(errorSemantics.exitCode, 0);
+    assert.match(errorSemantics.output, /nonterminating-windows-powershell-error/);
+    assert.match(errorSemantics.output, /continued-after-nonterminating-error/);
+    assert.match(errorSemantics.output, /terminating-error-caught/);
+
+    const nativeExit = await manager.start({
+      workspaceId: "powershell51-agent",
+      cwd: process.cwd(),
+      command: `$exe = ${node}; & $exe -e 'process.exit(7)'; exit $LASTEXITCODE`,
+      yieldTimeMs: 10_000,
+    });
+    assert.equal(nativeExit.exitCode, 7);
+
+    const chainMarker = join(root, "powershell7-chain-operator-marker.txt");
+    const powerShell7OnlySyntax = await manager.start({
+      workspaceId: "powershell51-agent",
+      cwd: process.cwd(),
+      command: `Write-Output 'left-side' && Set-Content -LiteralPath ${powerShellLiteral(chainMarker)} -Value 'ran'`,
+      yieldTimeMs: 10_000,
+    });
+    assert.notEqual(powerShell7OnlySyntax.exitCode, 0);
+    assert.equal(existsSync(chainMarker), false, "PowerShell 7 pipeline-chain syntax unexpectedly executed under Windows PowerShell 5.1");
+
+    const background = await manager.start({
+      workspaceId: "powershell51-agent",
+      cwd: process.cwd(),
+      command: "Write-Output 'powershell51-background-start'; Start-Sleep -Milliseconds 250; Write-Output 'powershell51-background-done'",
+      yieldTimeMs: 5,
+    });
+    assert.equal(background.running, true);
+    assert.ok(background.processId);
+    const completed = await manager.write({
+      workspaceId: "powershell51-agent",
+      processId: background.processId,
+      yieldTimeMs: 5_000,
+    });
+    assert.equal(completed.running, false);
+    assert.equal(completed.exitCode, 0);
+    assert.match(completed.output, /powershell51-background-done/);
+
+    const timedOut = await manager.start({
+      workspaceId: "powershell51-agent",
+      cwd: process.cwd(),
+      command: "Start-Sleep -Seconds 30",
+      yieldTimeMs: 5_000,
+      timeoutMs: 100,
+    });
+    assert.equal(timedOut.running, false);
+    assert.equal(timedOut.timedOut, true);
+
+    const interruptible = await manager.start({
+      workspaceId: "powershell51-agent",
+      cwd: process.cwd(),
+      command: "Write-Output 'powershell51-interrupt-ready'; Start-Sleep -Seconds 30",
+      yieldTimeMs: 5,
+    });
+    assert.equal(interruptible.running, true);
+    assert.ok(interruptible.processId);
+    const interrupted = await manager.write({
+      workspaceId: "powershell51-agent",
+      processId: interruptible.processId,
+      chars: "\u0003",
+      yieldTimeMs: 5_000,
+    });
+    assert.equal(interrupted.running, false);
+
+    await exercisePtyLifecycle(manager, outputStore, node);
+  } finally {
+    if (originalMarker === undefined) delete process.env.FORGERELAY_POWERSHELL51_ACCEPTANCE;
+    else process.env.FORGERELAY_POWERSHELL51_ACCEPTANCE = originalMarker;
+    manager.shutdown();
+    outputStore.close();
+  }
+}
+
+async function exercisePtyLifecycle(manager, outputStore, node) {
+  const pty = await manager.start({
+    workspaceId: "powershell51-agent",
+    workspaceRoot: process.cwd(),
+    audit: {
+      activityId: "act-powershell51-pty",
+      turnId: "turn-powershell51-pty",
+      conversationScopeId: "conversation-powershell51-pty",
+    },
+    cwd: process.cwd(),
+    command: [
+      "Write-Output 'powershell51-pty-ready-雪'",
+      "$line = [Console]::In.ReadLine()",
+      "Start-Sleep -Milliseconds 100",
+      'Write-Output "stdin=$line"',
+      'Write-Output "cols=$([Console]::WindowWidth);rows=$([Console]::WindowHeight)"',
+      "Write-Output 'powershell51-pty-unicode-雪'",
+      "exit 23",
+    ].join("; "),
+    tty: true,
+    columns: 80,
+    rows: 24,
+    yieldTimeMs: 5,
+  });
+  assert.equal(pty.running, true);
+  assert.ok(pty.processId);
+  assert.equal(pty.outputId, "out_powershell51_pty_acceptance");
+
+  const interacted = await manager.write({
+    workspaceId: "powershell51-agent",
+    processId: pty.processId,
+    columns: 120,
+    rows: 30,
+    chars: "input-plain\r",
+    yieldTimeMs: 5_000,
+  });
+  assert.equal(interacted.running, false);
+  assert.equal(interacted.exitCode, 23);
+  const ptyOutput = `${pty.output}${interacted.output}`;
+  assert.match(ptyOutput, /powershell51-pty-ready-雪/);
+  assert.match(ptyOutput, /stdin=input-plain/);
+  assert.match(ptyOutput, /cols=120;rows=30/);
+  assert.match(ptyOutput, /powershell51-pty-unicode-雪/);
+
+  const durable = outputStore.read(pty.outputId);
+  assert.ok(durable);
+  assert.equal(durable.tty, true);
+  assert.equal(durable.exitCode, 23);
+  assert.equal(durable.status, "failed");
+  assert.match(durable.output, /powershell51-pty-ready-雪/);
+  assert.match(durable.output, /stdin=input-plain/);
+  assert.match(durable.output, /powershell51-pty-unicode-雪/);
+
+  const background = await manager.start({
+    workspaceId: "powershell51-agent",
+    cwd: process.cwd(),
+    command: "Write-Output 'powershell51-pty-background-start'; Start-Sleep -Milliseconds 250; Write-Output 'powershell51-pty-background-done'",
+    tty: true,
+    yieldTimeMs: 5,
+  });
+  assert.equal(background.running, true);
+  assert.ok(background.processId);
+  const backgroundDone = await manager.write({
+    workspaceId: "powershell51-agent",
+    processId: background.processId,
+    yieldTimeMs: 5_000,
+  });
+  assert.equal(backgroundDone.running, false);
+  assert.equal(backgroundDone.exitCode, 0);
+  assert.match(`${background.output}${backgroundDone.output}`, /powershell51-pty-background-done/);
+
+  const timedOut = await manager.start({
+    workspaceId: "powershell51-agent",
+    cwd: process.cwd(),
+    command: "Start-Sleep -Seconds 30",
+    tty: true,
+    yieldTimeMs: 5_000,
+    timeoutMs: 100,
+  });
+  assert.equal(timedOut.running, false);
+  assert.equal(timedOut.timedOut, true);
+
+  const pidPath = join(root, "powershell51-pty-child.pid");
+  const childScript = "require('node:fs').writeFileSync(process.argv[1], String(process.pid)); setInterval(() => {}, 1000)";
+  const interruptible = await manager.start({
+    workspaceId: "powershell51-agent",
+    cwd: process.cwd(),
+    command: [
+      "Write-Output 'powershell51-pty-interrupt-ready'",
+      `$exe = ${node}`,
+      `& $exe -e ${powerShellLiteral(childScript)} ${powerShellLiteral(pidPath)}`,
+    ].join("; "),
+    tty: true,
+    yieldTimeMs: 5,
+  });
+  assert.equal(interruptible.running, true);
+  assert.ok(interruptible.processId);
+  const childPid = Number.parseInt(await waitForFile(pidPath), 10);
+  assert.ok(Number.isInteger(childPid) && childPid > 0, `invalid PTY child pid: ${childPid}`);
+  assert.equal(windowsProcessExists(childPid), true);
+
+  const interrupted = await manager.write({
+    workspaceId: "powershell51-agent",
+    processId: interruptible.processId,
+    chars: "\u0003",
+    yieldTimeMs: 5_000,
+  });
+  assert.equal(interrupted.running, false);
+  await waitForWindowsProcessExit(childPid);
+  assert.equal(windowsProcessExists(childPid), false, `PTY child process ${childPid} leaked after interrupt`);
+}
+
+async function exerciseHookRuntime(runtime) {
+  const { HookRunner, parseHookConfig } = await import("../../dist/mcp/hooks/hooks.js");
+  const logging = {
+    level: "silent",
+    format: "json",
+    requests: false,
+    assets: false,
+    toolCalls: false,
+    shellCommands: false,
+    trustProxy: false,
+  };
+  const runner = new HookRunner(
+    parseHookConfig({
+      BeforeTool: [{
+        handlers: [{
+          name: "Windows PowerShell policy",
+          command: [
+            "if ($PSVersionTable.PSVersion.Major -ne 5 -or $PSVersionTable.PSVersion.Minor -ne 1) { exit 17 }",
+            "if ($env:FORGERELAY_WORKSPACE_ID -ne 'powershell51-hook') { exit 19 }",
+            "Write-Error 'windows powershell policy denied'",
+            "exit 13",
+          ].join("; "),
+        }],
+      }],
+    }),
+    logging,
+    process.env,
+    undefined,
+    runtime,
+  );
+
+  await assert.rejects(
+    () => runner.run("BeforeTool", {
+      workspaceId: "powershell51-hook",
+      workspaceRoot: process.cwd(),
+      workspaceMode: "checkout",
+      payload: { tool: "bash", command: "Write-Output 'agent command'" },
+    }),
+    /Windows PowerShell policy exited with code 13: .*windows powershell policy denied/i,
+  );
+}
+
+async function exercisePackagedPowerShellShim(powershell, expectedVersion) {
+  const artifactDir = join(root, "artifact");
+  const prefix = join(root, "prefix");
+  const configDir = join(root, "config");
+  const stateDir = join(root, "state");
+  await Promise.all([
+    mkdir(artifactDir, { recursive: true }),
+    mkdir(prefix, { recursive: true }),
+    mkdir(configDir, { recursive: true }),
+    mkdir(stateDir, { recursive: true }),
+  ]);
+
+  const packed = runNpm(["pack", "--json", "--pack-destination", artifactDir]);
+  const packResult = JSON.parse(packed.stdout);
+  const filename = packResult?.[0]?.filename;
+  if (!filename) throw new Error(`npm pack did not report a package filename: ${packed.stdout}`);
+  const tarball = join(artifactDir, filename);
+  assert.ok(existsSync(tarball), `packed artifact is missing: ${tarball}`);
+
+  runNpm(["install", "--global", "--prefix", prefix, tarball]);
+  const shim = join(prefix, "forgerelay.ps1");
+  assert.ok(existsSync(shim), `npm did not create the PowerShell launcher shim: ${shim}`);
+
+  await writeFile(
+    join(configDir, "config.json"),
+    JSON.stringify({
+      host: "127.0.0.1",
+      port: 7678,
+      allowedRoots: [process.cwd()],
+      stateDir,
+      worktreeRoot: join(root, "worktrees"),
+      commandShell: {
+        mode: "follow-launcher",
+        family: "powershell",
+        executable: powershell,
+      },
+      shellInstructions: false,
+    }, null, 2),
+    "utf8",
+  );
+
+  const launcherEnv = {
+    ...process.env,
+    FORGERELAY_CONFIG_DIR: configDir,
+    FORGERELAY_OAUTH_OWNER_TOKEN: "powershell51-acceptance-owner-token-long-enough",
+  };
+  delete launcherEnv.npm_lifecycle_event;
+  delete launcherEnv.FORGERELAY_COMMAND_SHELL;
+
+  const result = spawnSync(
+    powershell,
+    ["-NoLogo", "-NoProfile", "-NonInteractive", "-File", shim, "doctor"],
+    {
+      cwd: process.cwd(),
+      env: launcherEnv,
+      encoding: "utf8",
+      windowsHide: true,
+    },
+  );
+  if (result.error || result.status !== 0) {
+    throw new Error(`Packaged Windows PowerShell launcher failed: ${result.error?.message ?? result.stderr ?? result.status}`);
+  }
+  assert.match(
+    result.stdout ?? "",
+    new RegExp(`Command shell: powershell ${escapeRegExp(expectedVersion)} \\(.+; launcher\\)`),
+  );
+  assert.doesNotMatch(result.stdout ?? "", /Command shell: pwsh/);
+}
+
+function runNpm(args) {
+  const result = spawnSync(process.execPath, [npmCli, ...args], {
+    cwd: process.cwd(),
+    env: process.env,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    throw new Error(`npm ${args.join(" ")} failed: ${result.error?.message ?? result.stderr ?? result.status}`);
+  }
+  return result;
+}
+
+async function waitForFile(path, timeoutMs = 5_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      return await readFile(path, "utf8");
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error(`Timed out waiting for file: ${path}`);
+}
+
+function windowsProcessExists(pid) {
+  const result = spawnSync(
+    "tasklist.exe",
+    ["/fi", `PID eq ${pid}`, "/fo", "csv", "/nh"],
+    { encoding: "utf8", windowsHide: true },
+  );
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`tasklist.exe failed with exit ${result.status ?? "unknown"}`);
+  return new RegExp(`"${pid}"(?:,|$)`).test(result.stdout ?? "");
+}
+
+async function waitForWindowsProcessExit(pid, timeoutMs = 5_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!windowsProcessExists(pid)) return;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
+function powerShellLiteral(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/scripts/ci/pwsh-acceptance.mjs

@@ -2,7 +2,7 @@
 
 import assert from "node:assert/strict";
 import { existsSync } from "node:fs";
-import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
@@ -72,8 +72,19 @@ function powerShellVersion(executable) {
 }
 
 async function exerciseAgentRuntime(runtime) {
-  const { ProcessManager } = await import("../../dist/mcp/process/process-sessions.js");
-  const manager = new ProcessManager({ commandShellRuntime: runtime });
+  const [{ ProcessManager }, { BashOutputStore }] = await Promise.all([
+    import("../../dist/mcp/process/process-sessions.js"),
+    import("../../dist/activity/history/bash-output-store.js"),
+  ]);
+  const durableStateDir = join(root, "durable-output-state");
+  const outputStore = new BashOutputStore(durableStateDir, {
+    outputId: () => "out_pwsh_pty_acceptance",
+    flushBytes: 1,
+  });
+  const manager = new ProcessManager({
+    commandShellRuntime: runtime,
+    outputAudit: outputStore,
+  });
   const originalMarker = process.env.FORGERELAY_PWSH_ACCEPTANCE;
   process.env.FORGERELAY_PWSH_ACCEPTANCE = "inherited environment";
   try {
@@ -167,23 +178,127 @@ async function exerciseAgentRuntime(runtime) {
     });
     assert.equal(interrupted.running, false);
 
-    const pty = await manager.start({
-      workspaceId: "pwsh-agent",
-      cwd: process.cwd(),
-      command: "Write-Output 'pwsh-pty-ok'",
-      tty: true,
-      yieldTimeMs: 10_000,
-    });
-    assert.equal(pty.running, false);
-    assert.equal(pty.exitCode, 0);
-    assert.match(pty.output, /pwsh-pty-ok/);
+    await exercisePtyLifecycle(manager, outputStore, node);
   } finally {
     if (originalMarker === undefined) delete process.env.FORGERELAY_PWSH_ACCEPTANCE;
     else process.env.FORGERELAY_PWSH_ACCEPTANCE = originalMarker;
     manager.shutdown();
+    outputStore.close();
   }
 }
 
+async function exercisePtyLifecycle(manager, outputStore, node) {
+  const pty = await manager.start({
+    workspaceId: "pwsh-agent",
+    workspaceRoot: process.cwd(),
+    audit: {
+      activityId: "act-pwsh-pty",
+      turnId: "turn-pwsh-pty",
+      conversationScopeId: "conversation-pwsh-pty",
+    },
+    cwd: process.cwd(),
+    command: [
+      "Write-Output 'pwsh-pty-ready-雪'",
+      "$line = [Console]::In.ReadLine()",
+      "Start-Sleep -Milliseconds 100",
+      'Write-Output "stdin=$line"',
+      'Write-Output "cols=$([Console]::WindowWidth);rows=$([Console]::WindowHeight)"',
+      "Write-Output 'pwsh-pty-unicode-🙂'",
+      "exit 23",
+    ].join("; "),
+    tty: true,
+    columns: 80,
+    rows: 24,
+    yieldTimeMs: 5,
+  });
+  assert.equal(pty.running, true);
+  assert.ok(pty.processId);
+  assert.equal(pty.outputId, "out_pwsh_pty_acceptance");
+
+  const interacted = await manager.write({
+    workspaceId: "pwsh-agent",
+    processId: pty.processId,
+    columns: 120,
+    rows: 30,
+    chars: "input-plain\r",
+    yieldTimeMs: 5_000,
+  });
+  assert.equal(interacted.running, false);
+  assert.equal(interacted.exitCode, 23);
+  const ptyOutput = `${pty.output}${interacted.output}`;
+  assert.match(ptyOutput, /pwsh-pty-ready-雪/);
+  assert.match(ptyOutput, /stdin=input-plain/);
+  assert.match(ptyOutput, /cols=120;rows=30/);
+  assert.match(ptyOutput, /pwsh-pty-unicode-🙂/);
+
+  const durable = outputStore.read(pty.outputId);
+  assert.ok(durable);
+  assert.equal(durable.tty, true);
+  assert.equal(durable.exitCode, 23);
+  assert.equal(durable.status, "failed");
+  assert.match(durable.output, /pwsh-pty-ready-雪/);
+  assert.match(durable.output, /stdin=input-plain/);
+  assert.match(durable.output, /pwsh-pty-unicode-🙂/);
+
+  const background = await manager.start({
+    workspaceId: "pwsh-agent",
+    cwd: process.cwd(),
+    command: "Write-Output 'pwsh-pty-background-start'; Start-Sleep -Milliseconds 250; Write-Output 'pwsh-pty-background-done'",
+    tty: true,
+    yieldTimeMs: 5,
+  });
+  assert.equal(background.running, true);
+  assert.ok(background.processId);
+  const backgroundDone = await manager.write({
+    workspaceId: "pwsh-agent",
+    processId: background.processId,
+    yieldTimeMs: 5_000,
+  });
+  assert.equal(backgroundDone.running, false);
+  assert.equal(backgroundDone.exitCode, 0);
+  assert.match(`${background.output}${backgroundDone.output}`, /pwsh-pty-background-done/);
+
+  const timedOut = await manager.start({
+    workspaceId: "pwsh-agent",
+    cwd: process.cwd(),
+    command: "Start-Sleep -Seconds 30",
+    tty: true,
+    yieldTimeMs: 5_000,
+    timeoutMs: 100,
+  });
+  assert.equal(timedOut.running, false);
+  assert.equal(timedOut.timedOut, true);
+
+  const pidPath = join(root, "pwsh-pty-child.pid");
+  const childScript = "require('node:fs').writeFileSync(process.argv[1], String(process.pid)); setInterval(() => {}, 1000)";
+  const interruptible = await manager.start({
+    workspaceId: "pwsh-agent",
+    cwd: process.cwd(),
+    command: [
+      "Write-Output 'pwsh-pty-interrupt-ready'",
+      `$exe = ${node}`,
+      `& $exe -e ${powerShellLiteral(childScript)} ${powerShellLiteral(pidPath)}`,
+    ].join("; "),
+    tty: true,
+    yieldTimeMs: 5,
+  });
+  assert.equal(interruptible.running, true);
+  assert.ok(interruptible.processId);
+  const childPid = Number.parseInt(await waitForFile(pidPath), 10);
+  assert.ok(Number.isInteger(childPid) && childPid > 0, `invalid PTY child pid: ${childPid}`);
+  assert.equal(windowsProcessExists(childPid), true);
+
+  const interrupted = await manager.write({
+    workspaceId: "pwsh-agent",
+    processId: interruptible.processId,
+    chars: "\u0003",
+    yieldTimeMs: 5_000,
+  });
+  assert.equal(interrupted.running, false);
+  await waitForWindowsProcessExit(childPid);
+  assert.equal(windowsProcessExists(childPid), false, `PTY child process ${childPid} leaked after interrupt`);
+}
+
 async function exerciseHookRuntime(runtime) {
   const { HookRunner, parseHookConfig } = await import("../../dist/mcp/hooks/hooks.js");
   const logging = {
@@ -299,6 +414,38 @@ function runNpm(args) {
   return result;
 }
 
+async function waitForFile(path, timeoutMs = 5_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      return await readFile(path, "utf8");
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error(`Timed out waiting for file: ${path}`);
+}
+
+function windowsProcessExists(pid) {
+  const result = spawnSync(
+    "tasklist.exe",
+    ["/fi", `PID eq ${pid}`, "/fo", "csv", "/nh"],
+    { encoding: "utf8", windowsHide: true },
+  );
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`tasklist.exe failed with exit ${result.status ?? "unknown"}`);
+  return new RegExp(`"${pid}"(?:,|$)`).test(result.stdout ?? "");
+}
+
+async function waitForWindowsProcessExit(pid, timeoutMs = 5_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!windowsProcessExists(pid)) return;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
 function powerShellLiteral(value) {
   return `'${String(value).replaceAll("'", "''")}'`;
 }

package/scripts/release/release-gate.test.mjs

@@ -108,3 +108,17 @@ test("release workflow is tag-only and promotes the verified npm artifact withou
   assert.doesNotMatch(workflow, /run:\s*\|/);
   assert.doesNotMatch(workflow, /shell:\s*bash/);
 });
+
+test("manual Windows shell acceptance can never publish a release", async () => {
+  const workflow = await readFile(
+    resolve(repoRoot, ".github/workflows/windows-shell-acceptance.yml"),
+    "utf8",
+  );
+  assert.match(workflow, /workflow_dispatch:/);
+  assert.match(workflow, /runs-on:\s*windows-2022/);
+  assert.match(workflow, /run:\s*npm run pwsh:accept/);
+  assert.doesNotMatch(workflow, /release:publish/);
+  assert.doesNotMatch(workflow, /npm publish/);
+  assert.doesNotMatch(workflow, /contents:\s*write/);
+  assert.doesNotMatch(workflow, /id-token:\s*write/);
+});