@akira-tl/forgerelay 0.10.2 → 0.10.3

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.10.3] - 2026-09-06
+
+### Added
+
+- Added first-class `cmd.exe` execution for Agent commands and Hooks with explicit cmd shell identity, editable cmd Instructions, Windows-native quoting/escaping guidance, and package-level `.cmd` launcher acceptance.
+- Added Windows cmd PTY/ConPTY lifecycle coverage for stdin, resize, background completion, timeout, interrupt, durable output, Unicode, exit codes, and child-process-tree cleanup without introducing a separate Windows Process Manager.
+
+### Fixed
+
+- Preserved raw `cmd.exe /S /C` command-line quoting through node-pty by using the Windows pre-escaped CommandLine path for interactive cmd sessions, preventing ConPTY from rewriting quoted commands and exit semantics.
+
 ## [0.10.2] - 2026-09-06
 
 ### Added

package/README.md

@@ -295,9 +295,10 @@ See [Security Model](docs/security.md) for the full boundary and threat model.
 | --- | --- | --- |
 | Linux | Supported | Requires Node, npm, Git, and Bash. |
 | macOS | Supported | Requires Node, npm, Git, and Bash. |
-| Windows with PowerShell 7 (`pwsh`) | Supported | Agent commands and Hooks use one native `pwsh` runtime without loading the user profile. |
+| Windows with PowerShell 7 (`pwsh`) | Supported | Agent commands, Hooks, and PTY execution use one native `pwsh` runtime without loading the user profile. |
+| Windows with Windows PowerShell 5.1 (`powershell.exe`) | Supported | Agent commands, Hooks, and PTY execution use the selected 5.1 runtime with 5.1-specific syntax guidance. |
+| Windows with `cmd.exe` | Supported for Agent commands and Hooks | ForgeRelay preserves cmd syntax and reports the selected runtime explicitly; PTY/packaged-launcher lifecycle coverage is completed separately. |
 | Windows with Git Bash, WSL, MSYS2, or Cygwin Bash | Supported | Bash remains available as a compatibility path. |
-| Windows PowerShell 5.1 (`powershell.exe`) or `cmd.exe` only | Not supported yet | These runtimes are separate follow-up stages. |
 
 You can check the local runtime with:
 

package/capabilities/shell-processes/GUIDE.md

@@ -48,6 +48,6 @@ PTY 依赖 optional `node-pty`。缺少该依赖时 ForgeRelay 会明确报错
 
 ## Platform notes
 
-ForgeRelay 在 Windows 上支持 PowerShell 7 (`pwsh`) 作为原生 Command Shell Runtime；非 TTY Agent 命令与 Hooks 使用同一个 `pwsh`，禁止加载用户 profile，PTY 也复用同一 executable。公共工具名仍保留为 `bash` 以兼容 Host contract，实际命令语言以 ForgeRelay 报告的 Command Shell Runtime 为准。Windows PowerShell 5.1 (`powershell.exe`) 与 `cmd.exe` 仍属于后续 runtime 阶段；Git Bash、WSL、MSYS2 或 Cygwin Bash 仍可作为 Bash 兼容路径。用 `forgerelay doctor` 检查当前 shell identity、version 与 executable。
+ForgeRelay 在 Windows 上原生支持 PowerShell 7 (`pwsh`) 与 Windows PowerShell 5.1 (`powershell.exe`) 的 Agent、Hook 和 PTY 执行，也支持 `cmd.exe` 作为 Agent 命令与 Hook 的一等 Command Shell Runtime。Agent 命令与 Hooks 始终复用已选择的 runtime，不会为了兼容性静默切换到 Bash 或 PowerShell；PowerShell runtime 不加载用户 profile。公共工具名仍保留为 `bash` 以兼容 Host contract，实际命令语言以 ForgeRelay 报告的 Command Shell Runtime 为准。`cmd.exe` 的 PTY/ConPTY 与 packaged `.cmd` launcher lifecycle 属于下一阶段验收，不应由本阶段的非 TTY 支持推断。Git Bash、WSL、MSYS2 或 Cygwin Bash 仍可作为 Bash 兼容路径。用 `forgerelay doctor` 检查当前 shell identity、version 与 executable。
 
 Shell 可以作为用户开发任务的一部分修改普通项目文件，但始终受 ForgeRelay core mutation/safety contract 约束。涉及 privileged OS files、credentials、configuration 或外部硬件持久写入时，不要用本指南替代 core authorization/safety 规则。

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

@@ -27,6 +27,10 @@ export function resolveShellCommandForRuntime(command, runtime, options = {}) {
                 // cmd.exe /S applies special quote stripping, so the whole command must
                 // be wrapped even when the executable inside it is already quoted.
                 args: ["/d", "/s", "/c", `"${command}"`],
+                // node-pty accepts a pre-escaped Windows CommandLine string. Passing the
+                // cmd arguments as string[] makes node-pty escape embedded quotes using
+                // CommandLineToArgvW rules, which changes cmd.exe /S /C semantics.
+                ...(options.interactive ? { ptyCommandLine: `/d /s /c "${command}"` } : {}),
                 windowsVerbatimArguments: true,
             };
         case "bash":

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

@@ -470,7 +470,7 @@ export class ProcessManager {
             throw new Error("PTY support requires the optional node-pty dependency.");
         }
         const shell = resolveShellCommandForRuntime(input.command, this.commandShellRuntime, { interactive: true });
-        const pty = nodePty.spawn(shell.executable, shell.args, {
+        const pty = nodePty.spawn(shell.executable, shell.ptyCommandLine ?? shell.args, {
             cwd: input.cwd,
             env: processEnvironment({
                 workspaceId: input.workspaceId,

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

@@ -203,7 +203,9 @@ export function commandShellAgentInstruction(runtime) {
         "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 ||."]
-            : []),
+            : runtime.family === "cmd"
+                ? ["cmd.exe uses %NAME% environment expansion and %ERRORLEVEL% process status. Do not emit PowerShell or Bash syntax unless explicitly launching those shells as child processes."]
+                : []),
     ].join(" ");
 }
 function runtimeFromSelection(selection, source) {

package/docs/gotchas.md

@@ -162,10 +162,7 @@ ForgeRelay does not intentionally leave the source checkout in a merge-conflict
 
 ## Windows shell commands fail
 
-ForgeRelay supports PowerShell 7 (`pwsh`) as a native Windows Command Shell Runtime.
-Agent commands and Hooks share that runtime and do not load the user PowerShell profile.
-Windows PowerShell 5.1 (`powershell.exe`) and `cmd.exe` remain separate follow-up runtimes.
-Git Bash, WSL, MSYS2, and Cygwin Bash also remain supported compatibility paths.
+ForgeRelay supports PowerShell 7 (`pwsh`) and Windows PowerShell 5.1 (`powershell.exe`) as native Windows Command Shell Runtimes. Agent commands and Hooks share the selected runtime and PowerShell execution does not load the user profile. `cmd.exe` is also a first-class Agent/Hook runtime: use `%NAME%`, `%ERRORLEVEL%`, cmd quoting/chaining/redirection, and `^` escaping rather than silently substituting PowerShell or Bash syntax. cmd PTY/ConPTY and packaged `.cmd` launcher lifecycle coverage is completed separately. Git Bash, WSL, MSYS2, and Cygwin Bash remain supported compatibility paths.
 
 Check the selected runtime with:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -44,6 +44,7 @@
     "lsp:interop": "node scripts/lsp/interop.mjs",
     "pwsh:accept": "node scripts/ci/pwsh-acceptance.mjs",
     "powershell51:accept": "node scripts/ci/powershell51-acceptance.mjs",
+    "cmd:accept": "node scripts/ci/cmd-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",
@@ -54,7 +55,7 @@
     "release:push-ready": "node scripts/release/push-ready.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/push-ready.test.mjs scripts/release/release-version.test.mjs && tsx src/mcp/oauth/router.test.ts && tsx src/workspaces/relay/auth/remote-auth-cli.test.ts && tsx src/workspaces/relay/auth/remote-ssh-auth-cli.test.ts && tsx src/workspaces/relay/tests/lifecycle.test.ts && tsx src/workspaces/relay/tests/routing.test.ts && tsx src/workspaces/relay/tests/ssh.test.ts && tsx src/workspaces/relay/tests/process.test.ts && tsx src/workspaces/relay/tests/recovery.test.ts && tsx src/workspaces/relay/tests/checkpoint.test.ts && tsx src/runtime/config/config.test.ts && tsx src/runtime/instructions/powershell-skill.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/runtime/managed-language-servers.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/runtime/logging/logger.test.ts && tsx src/runtime/logging/proxy-trust.test.ts && tsx src/runtime/state/lock/file-lock.test.ts && tsx src/runtime/state/runtime-lease.test.ts && tsx src/mcp/panel/mcp-app-template.test.ts && tsx src/mcp/hooks/hooks.test.ts && tsx src/mcp/server/core/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/mcp/request-meta.test.ts && tsx src/mcp/artifacts/incoming-artifacts.test.ts && tsx src/mcp/artifacts/artifact-download.test.ts && tsx src/ui/core/card-types.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/activity/detail-card.test.ts && tsx src/ui/review/patch-display.test.ts && tsx src/ui/core/tool-display.test.ts && tsx src/mcp/filesystem/apply-patch.test.ts && tsx src/mcp/process/process-platform.test.ts && tsx src/mcp/process/process-sessions.test.ts && tsx src/mcp/server/transport/mcp-sessions.test.ts && tsx src/mcp/server/transport/server-shutdown.test.ts && tsx src/mcp/server/operations/mutation-diagnostics.test.ts && tsx src/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/adapters/pi.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/mcp/filesystem/roots.test.ts && tsx src/mcp/filesystem/file-mutations.test.ts && tsx src/mcp/operations/edit-preflight.test.ts && tsx src/workspaces/resources/skills.test.ts && tsx src/runtime/state/db/migrations.test.ts && tsx src/workspaces/state/workspace-store.test.ts && tsx src/workspaces/tasks/workspace-tasks.test.ts && tsx src/workspaces/tasks/workspace-task-reminders.test.ts && tsx src/activity/history/audit-store.test.ts && tsx src/activity/history/bash-output-store.test.ts && tsx src/activity/runtime/lifecycle.test.ts && tsx src/activity/history/query-service.test.ts && tsx src/mcp/operations/core-operation-executor.test.ts && tsx src/mcp/operations/bulk-mutation.test.ts && tsx src/mcp/operations/batch/scheduler.test.ts && tsx src/mcp/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspaces/conversation-checkout.test.ts && tsx src/workspaces/conversation-worktree.test.ts && tsx src/workspaces/git/worktree-recovery.test.ts && tsx src/mcp/server/workspace/workspace-inventory.test.ts && tsx src/mcp/server/workspace/workspace-recovery.test.ts && tsx src/mcp/server/workspace/workspace-checkpoint.test.ts && tsx src/workspaces/review/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/mcp/process/server.test.ts && tsx src/mcp/panel/server.test.ts && tsx src/mcp/server/server.test.ts && tsx src/mcp/oauth/oauth-store.test.ts && tsx src/cli/maintenance.test.ts && tsx src/cli/maintenance-prune.test.ts && tsx src/cli/cli.test.ts",
+    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/push-ready.test.mjs scripts/release/release-version.test.mjs && tsx src/mcp/oauth/router.test.ts && tsx src/workspaces/relay/auth/remote-auth-cli.test.ts && tsx src/workspaces/relay/auth/remote-ssh-auth-cli.test.ts && tsx src/workspaces/relay/tests/lifecycle.test.ts && tsx src/workspaces/relay/tests/routing.test.ts && tsx src/workspaces/relay/tests/ssh.test.ts && tsx src/workspaces/relay/tests/process.test.ts && tsx src/workspaces/relay/tests/recovery.test.ts && tsx src/workspaces/relay/tests/checkpoint.test.ts && tsx src/runtime/config/config.test.ts && tsx src/runtime/shell/command-shell-runtime.test.ts && tsx src/runtime/instructions/shell-instructions.test.ts && tsx src/runtime/instructions/powershell-skill.test.ts && tsx src/cli/shell/setup.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/runtime/managed-language-servers.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/runtime/logging/logger.test.ts && tsx src/runtime/logging/proxy-trust.test.ts && tsx src/runtime/state/lock/file-lock.test.ts && tsx src/runtime/state/runtime-lease.test.ts && tsx src/mcp/panel/mcp-app-template.test.ts && tsx src/mcp/hooks/hooks.test.ts && tsx src/mcp/server/core/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/mcp/request-meta.test.ts && tsx src/mcp/artifacts/incoming-artifacts.test.ts && tsx src/mcp/artifacts/artifact-download.test.ts && tsx src/ui/core/card-types.test.ts && tsx src/ui/activity/model.test.ts && tsx src/ui/activity/detail-card.test.ts && tsx src/ui/review/patch-display.test.ts && tsx src/ui/core/tool-display.test.ts && tsx src/mcp/filesystem/apply-patch.test.ts && tsx src/mcp/process/process-platform.test.ts && tsx src/mcp/process/process-sessions.test.ts && tsx src/mcp/server/transport/mcp-sessions.test.ts && tsx src/mcp/server/transport/server-shutdown.test.ts && tsx src/mcp/server/operations/mutation-diagnostics.test.ts && tsx src/mcp/server/operations/hooks.test.ts && tsx src/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/adapters/pi.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/mcp/filesystem/roots.test.ts && tsx src/mcp/filesystem/file-mutations.test.ts && tsx src/mcp/operations/edit-preflight.test.ts && tsx src/workspaces/resources/skills.test.ts && tsx src/runtime/state/db/migrations.test.ts && tsx src/workspaces/state/workspace-store.test.ts && tsx src/workspaces/tasks/workspace-tasks.test.ts && tsx src/workspaces/tasks/workspace-task-reminders.test.ts && tsx src/activity/history/audit-store.test.ts && tsx src/activity/history/bash-output-store.test.ts && tsx src/activity/runtime/lifecycle.test.ts && tsx src/activity/history/query-service.test.ts && tsx src/mcp/operations/core-operation-executor.test.ts && tsx src/mcp/operations/bulk-mutation.test.ts && tsx src/mcp/operations/batch/scheduler.test.ts && tsx src/mcp/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspaces/conversation-checkout.test.ts && tsx src/workspaces/conversation-worktree.test.ts && tsx src/workspaces/git/worktree-recovery.test.ts && tsx src/mcp/server/workspace/workspace-inventory.test.ts && tsx src/mcp/server/workspace/workspace-recovery.test.ts && tsx src/mcp/server/workspace/workspace-checkpoint.test.ts && tsx src/workspaces/review/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/mcp/process/server.test.ts && tsx src/mcp/panel/server.test.ts && tsx src/mcp/server/server.test.ts && tsx src/mcp/oauth/oauth-store.test.ts && tsx src/cli/maintenance.test.ts && tsx src/cli/maintenance-prune.test.ts && tsx src/cli/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",

package/scripts/ci/cmd-acceptance.mjs

@@ -0,0 +1,295 @@
+#!/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("cmd.exe packaged acceptance skipped outside Windows.");
+  process.exit(0);
+}
+
+const npmCli = process.env.npm_execpath;
+if (!npmCli) throw new Error("cmd acceptance must run through npm so npm_execpath is available");
+
+const root = await mkdtemp(join(tmpdir(), "forgerelay-cmd-acceptance-"));
+try {
+  const cmd = resolveCmd();
+  const runtime = {
+    family: "cmd",
+    executable: cmd,
+    source: "explicit",
+    capabilities: ["cmd-command-language"],
+  };
+
+  await exercisePtyLifecycle(runtime);
+  await exercisePackagedCmdShim(cmd);
+
+  console.log(`cmd.exe acceptance passed with ${cmd}.`);
+} finally {
+  await rm(root, { recursive: true, force: true });
+}
+
+function resolveCmd() {
+  const executable = process.env.ComSpec ?? process.env.COMSPEC;
+  if (!executable || !existsSync(executable)) {
+    throw new Error(`Windows cmd acceptance requires a valid ComSpec; got ${executable ?? "unset"}.`);
+  }
+  return executable;
+}
+
+async function exercisePtyLifecycle(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_cmd_pty_acceptance",
+    flushBytes: 1,
+  });
+  const manager = new ProcessManager({
+    commandShellRuntime: runtime,
+    outputAudit: outputStore,
+  });
+
+  try {
+    const node = quoteCmdArg(process.execPath);
+    const ptyScriptDir = join(root, "cmd pty script");
+    const ptyScript = join(ptyScriptDir, "interactive lifecycle.cmd");
+    await mkdir(ptyScriptDir, { recursive: true });
+    await writeFile(
+      ptyScript,
+      [
+        "@echo off",
+        "chcp 65001 >nul",
+        "echo cmd-pty-ready-雪",
+        "set /p FR_CMD_LINE=",
+        "echo stdin=%FR_CMD_LINE%",
+        `${node} -e "console.log('cols=' + process.stdout.columns + ';rows=' + process.stdout.rows)"`,
+        `${node} -e "console.log('cmd-pty-unicode-🙂')"`,
+        "exit /b 23",
+        "",
+      ].join("\r\n"),
+      "utf8",
+    );
+    const pty = await manager.start({
+      workspaceId: "cmd-agent",
+      workspaceRoot: process.cwd(),
+      audit: {
+        activityId: "act-cmd-pty",
+        turnId: "turn-cmd-pty",
+        conversationScopeId: "conversation-cmd-pty",
+      },
+      cwd: process.cwd(),
+      command: quoteCmdArg(ptyScript),
+      tty: true,
+      columns: 80,
+      rows: 24,
+      yieldTimeMs: 5,
+    });
+    assert.equal(pty.running, true);
+    assert.ok(pty.processId);
+    assert.equal(pty.outputId, "out_cmd_pty_acceptance");
+
+    const interacted = await manager.write({
+      workspaceId: "cmd-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, /cmd-pty-ready-雪/);
+    assert.match(ptyOutput, /stdin=input-plain/);
+    assert.match(ptyOutput, /cols=120;rows=30/);
+    assert.match(ptyOutput, /cmd-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, /cmd-pty-ready-雪/);
+    assert.match(durable.output, /stdin=input-plain/);
+    assert.match(durable.output, /cmd-pty-unicode-🙂/);
+
+    const background = await manager.start({
+      workspaceId: "cmd-agent",
+      cwd: process.cwd(),
+      command: `${node} -e "console.log('cmd-pty-background-start'); setTimeout(() => console.log('cmd-pty-background-done'), 250)"`,
+      tty: true,
+      yieldTimeMs: 5,
+    });
+    assert.equal(background.running, true);
+    assert.ok(background.processId);
+    const backgroundDone = await manager.write({
+      workspaceId: "cmd-agent",
+      processId: background.processId,
+      yieldTimeMs: 5_000,
+    });
+    assert.equal(backgroundDone.running, false);
+    assert.equal(backgroundDone.exitCode, 0);
+    assert.match(`${background.output}${backgroundDone.output}`, /cmd-pty-background-done/);
+
+    const timedOut = await manager.start({
+      workspaceId: "cmd-agent",
+      cwd: process.cwd(),
+      command: `${node} -e "setTimeout(() => {}, 30000)"`,
+      tty: true,
+      yieldTimeMs: 5_000,
+      timeoutMs: 100,
+    });
+    assert.equal(timedOut.running, false);
+    assert.equal(timedOut.timedOut, true);
+
+    const pidPath = join(root, "cmd-pty-child.pid");
+    const childScript = "require('node:fs').writeFileSync(process.argv[1], String(process.pid)); setInterval(() => {}, 1000)";
+    const interruptible = await manager.start({
+      workspaceId: "cmd-agent",
+      cwd: process.cwd(),
+      command: `${node} -e ${quoteCmdArg(childScript)} ${quoteCmdArg(pidPath)}`,
+      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: "cmd-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`);
+  } finally {
+    manager.shutdown();
+    outputStore.close();
+  }
+}
+
+async function exercisePackagedCmdShim(cmd) {
+  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.cmd");
+  assert.ok(existsSync(shim), `npm did not create the cmd 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: "cmd",
+        executable: cmd,
+      },
+      shellInstructions: false,
+    }, null, 2),
+    "utf8",
+  );
+
+  const launcherEnv = {
+    ...process.env,
+    FORGERELAY_CONFIG_DIR: configDir,
+    FORGERELAY_OAUTH_OWNER_TOKEN: "cmd-acceptance-owner-token-that-is-long-enough",
+  };
+  delete launcherEnv.npm_lifecycle_event;
+  delete launcherEnv.FORGERELAY_COMMAND_SHELL;
+
+  const result = spawnSync(
+    cmd,
+    ["/d", "/s", "/c", `"\"${shim}\" doctor"`],
+    {
+      cwd: process.cwd(),
+      env: launcherEnv,
+      encoding: "utf8",
+      windowsHide: true,
+      windowsVerbatimArguments: true,
+    },
+  );
+  if (result.error || result.status !== 0) {
+    throw new Error(`Packaged cmd launcher failed: ${result.error?.message ?? result.stderr ?? result.status}`);
+  }
+  assert.match(result.stdout ?? "", /Command shell: cmd \(.+; launcher\)/);
+}
+
+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 quoteCmdArg(value) {
+  return `"${String(value).replaceAll('"', '""')}"`;
+}