@blackbelt-technology/pi-agent-dashboard 0.3.0 → 0.4.1

package/packages/shared/src/platform/process-scan.ts

@@ -0,0 +1,94 @@
+/**
+ * Cross-platform process enumeration primitives: is-process-running,
+ * ps/tasklist pattern-matching, elapsed-time parsing.
+ *
+ * Every OS-dependent helper accepts injectable `platform` and `exec`
+ * parameters (defaulting to `process.platform` and `execSync`), so tests
+ * can exercise both branches without mutating the global `process.platform`.
+ * See change: consolidate-platform-handlers.
+ */
+
+import { execSync } from "./exec.js";
+
+type ExecFn = (cmd: string, opts: { encoding: "utf-8"; stdio?: any }) => string;
+
+export interface ProcessScanOpts {
+  /** Override platform (defaults to process.platform). */
+  platform?: NodeJS.Platform;
+  /** Override execSync (for tests). */
+  exec?: ExecFn;
+}
+
+function defaultExec(cmd: string, opts: { encoding: "utf-8"; stdio?: any }): string {
+  return execSync(cmd, { ...opts, windowsHide: true }) as unknown as string;
+}
+
+// ── Elapsed-time parsing (pure, platform-agnostic) ──────────────────────────
+
+/**
+ * Parse `ps -o etime=` format into milliseconds. Handles:
+ *   - `mm:ss`          (e.g. "02:15" → 135000)
+ *   - `hh:mm:ss`       (e.g. "01:30:00" → 5400000)
+ *   - `dd-hh:mm:ss`    (e.g. "2-03:00:00" → 183600000)
+ *
+ * Returns 0 for empty or unparseable input.
+ */
+export function parseEtime(etime: string): number {
+  const trimmed = etime.trim();
+  if (!trimmed) return 0;
+
+  let days = 0;
+  let rest = trimmed;
+
+  const dashIdx = rest.indexOf("-");
+  if (dashIdx !== -1) {
+    days = parseInt(rest.slice(0, dashIdx), 10);
+    if (isNaN(days)) return 0;
+    rest = rest.slice(dashIdx + 1);
+  }
+
+  const parts = rest.split(":").map((p) => parseInt(p, 10));
+  if (parts.some(isNaN)) return 0;
+
+  let hours = 0, minutes = 0, seconds = 0;
+  if (parts.length === 3) {
+    [hours, minutes, seconds] = parts;
+  } else if (parts.length === 2) {
+    [minutes, seconds] = parts;
+  } else {
+    return 0;
+  }
+
+  return ((days * 86400) + (hours * 3600) + (minutes * 60) + seconds) * 1000;
+}
+
+// ── Process-running check ───────────────────────────────────────────────────
+
+/**
+ * Check whether a process matching `pattern` is currently running.
+ *   - win32: `tasklist /FI "IMAGENAME eq <pattern>" /NH` — pattern is the
+ *            executable image name (e.g. "Code.exe"). Returns true if the
+ *            output contains the pattern.
+ *   - unix:  `pgrep -f "<pattern>"` — pattern is any substring of the
+ *            command-line (e.g. "/Applications/Zed.app"). Returns true if
+ *            pgrep exits with code 0 (at least one match).
+ *
+ * Best-effort: any failure returns `false`.
+ */
+export function isProcessRunning(pattern: string, opts: ProcessScanOpts = {}): boolean {
+  const platform = opts.platform ?? process.platform;
+  const exec = opts.exec ?? defaultExec;
+  try {
+    if (platform === "win32") {
+      const result = exec(`tasklist /FI "IMAGENAME eq ${pattern}" /NH`, {
+        encoding: "utf-8",
+        stdio: "pipe",
+      });
+      return String(result).includes(pattern);
+    }
+    exec(`pgrep -f "${pattern}"`, { encoding: "utf-8", stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/packages/shared/src/platform/process.ts

@@ -0,0 +1,168 @@
+/**
+ * Cross-platform process primitives: port cleanup, kill, liveness, group-kill.
+ *
+ * Every OS-dependent helper takes an optional `platform` parameter
+ * (defaulting to `process.platform`) so tests can exercise both branches
+ * without mutating the global `process.platform`. See change:
+ * consolidate-platform-handlers.
+ */
+
+import { execSync } from "./exec.js";
+
+export type ExecFn = (cmd: string, opts: { encoding: "utf-8" }) => string;
+export type KillFn = (pid: number, signal: NodeJS.Signals | number) => void;
+
+export interface ProcessOpts {
+  /** Override platform (defaults to process.platform). */
+  platform?: NodeJS.Platform;
+  /** Override execSync (for tests). */
+  exec?: ExecFn;
+  /** Override process.kill (for tests). */
+  kill?: KillFn;
+}
+
+function defaultExec(cmd: string, opts: { encoding: "utf-8" }): string {
+  // Always suppress the cmd.exe window flash on Windows. The primitives that
+  // use this (findPortHolders via netstat, killProcess via taskkill) don't
+  // need user visibility.
+  return execSync(cmd, { ...opts, windowsHide: true }) as unknown as string;
+}
+
+function defaultKill(pid: number, signal: NodeJS.Signals | number): void {
+  process.kill(pid, signal);
+}
+
+// ── Port-holder detection ────────────────────────────────────────────────────
+
+/**
+ * Parse `netstat -ano -p tcp` output for PIDs listening on a port (Windows).
+ * Pure function, exported for testing.
+ *
+ * Example input line:
+ *   "  TCP    0.0.0.0:8000   0.0.0.0:0   LISTENING   12345"
+ */
+export function parseNetstatListeners(output: string, port: number, selfPid: number): number[] {
+  const pids: number[] = [];
+  const portSuffix = `:${port}`;
+  for (const line of output.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || !/^\s*TCP/i.test(line)) continue;
+    if (!/LISTENING/i.test(line)) continue;
+    const cols = trimmed.split(/\s+/);
+    if (cols.length < 5) continue;
+    const local = cols[1];
+    if (!local.endsWith(portSuffix)) continue;
+    const pid = Number.parseInt(cols[cols.length - 1], 10);
+    if (Number.isFinite(pid) && pid > 0 && pid !== selfPid) pids.push(pid);
+  }
+  return pids;
+}
+
+/**
+ * Find PIDs holding a TCP port. Cross-platform:
+ *   - win32: `netstat -ano -p tcp` → parse LISTENING rows
+ *   - unix:  `lsof -t -i :<port> -sTCP:LISTEN`
+ *
+ * Best-effort: any failure returns []. Excludes the current process PID.
+ */
+export function findPortHolders(port: number, opts: ProcessOpts = {}): number[] {
+  const platform = opts.platform ?? process.platform;
+  const exec = opts.exec ?? defaultExec;
+  try {
+    if (platform === "win32") {
+      const output = exec("netstat -ano -p tcp", { encoding: "utf-8" });
+      return parseNetstatListeners(String(output), port, process.pid);
+    }
+    const output = exec(`lsof -t -i :${port} -sTCP:LISTEN 2>/dev/null`, { encoding: "utf-8" });
+    return String(output).trim().split("\n").map(Number).filter((n) => n > 0 && n !== process.pid);
+  } catch {
+    return [];
+  }
+}
+
+// ── Liveness ─────────────────────────────────────────────────────────────────
+
+/**
+ * Check whether a PID is alive. Cross-platform via `process.kill(pid, 0)`.
+ */
+export function isProcessAlive(pid: number, opts: { kill?: KillFn } = {}): boolean {
+  const kill = opts.kill ?? defaultKill;
+  try {
+    kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Termination ──────────────────────────────────────────────────────────────
+
+export interface KillProcessResult {
+  ok: boolean;
+  forced: boolean;
+}
+
+/**
+ * Terminate a process, cross-platform:
+ *   - win32: `taskkill /F /T /PID <pid>` (tree kill, immediate)
+ *   - unix:  SIGTERM → wait up to `timeoutMs` → SIGKILL if still alive
+ *
+ * Returns `{ ok, forced }`. `ok` is true if the process was terminated (or
+ * was already dead); `forced` is true if SIGKILL was needed on Unix.
+ */
+export async function killProcess(
+  pid: number,
+  opts: ProcessOpts & { timeoutMs?: number } = {},
+): Promise<KillProcessResult> {
+  const platform = opts.platform ?? process.platform;
+  const exec = opts.exec ?? defaultExec;
+  const kill = opts.kill ?? defaultKill;
+  const timeoutMs = opts.timeoutMs ?? 5000;
+
+  if (!isProcessAlive(pid, { kill })) return { ok: false, forced: false };
+
+  if (platform === "win32") {
+    try {
+      exec(`taskkill /F /T /PID ${pid}`, { encoding: "utf-8" });
+      return { ok: true, forced: false };
+    } catch {
+      return { ok: false, forced: false };
+    }
+  }
+
+  try {
+    kill(pid, "SIGTERM");
+  } catch {
+    return { ok: false, forced: false };
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 200));
+    if (!isProcessAlive(pid, { kill })) return { ok: true, forced: false };
+  }
+  try {
+    kill(pid, "SIGKILL");
+  } catch {
+    /* already dead */
+  }
+  return { ok: true, forced: true };
+}
+
+// ── Process-group kill (for detached children) ───────────────────────────────
+
+/**
+ * Signal a process, targeting the process group on Unix (negative PID) and
+ * the PID directly on Windows. Used for detached children spawned with their
+ * own process group.
+ */
+export function killPidWithGroup(
+  pid: number,
+  signal: NodeJS.Signals,
+  opts: ProcessOpts = {},
+): void {
+  const platform = opts.platform ?? process.platform;
+  const kill = opts.kill ?? defaultKill;
+  const target = platform === "win32" ? pid : -pid;
+  kill(target, signal);
+}

package/packages/shared/src/platform/runner.ts

@@ -0,0 +1,369 @@
+/**
+ * Recipe runner — the engine that executes structured subprocess Recipes.
+ *
+ * A Recipe is pure data: it describes *what* to run (argv from input),
+ * *how to parse* the stdout, and policy (timeout, tolerated exit codes).
+ * The runner owns *how to spawn*: binary resolution via `ToolResolver`,
+ * always-safe defaults (`windowsHide: true`, no shell interpolation),
+ * timeout enforcement, and uniform error normalization to `Result<T>`.
+ *
+ * Tool modules (`platform/git.ts`, `platform/openspec.ts`, `platform/npm.ts`)
+ * declare Recipes and call `run()`. They never touch `child_process`,
+ * `process.platform`, or `windowsHide`.
+ *
+ * See change: platform-command-executor.
+ */
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { spawnSync, spawn, buildSafeArgv } from "./exec.js";
+import { ToolResolver } from "./binary-lookup.js";
+// The tool registry publishes itself on a well-known `globalThis` symbol
+// when `getDefaultRegistry()` is first called from any consumer. The
+// runner reads that global to avoid a load-order cycle (tool-registry
+// → platform/npm.ts → this file) that would otherwise trip Node's
+// ESM/CJS translator with ERR_INTERNAL_ASSERTION on certain boots.
+// See change: consolidate-tool-resolution.
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+/** A Recipe is a pure-data description of a subprocess operation. */
+export interface Recipe<Input, Output> {
+  /** Build the command + args from the typed input. First element is the command name. */
+  argv: (input: Input) => readonly string[];
+  /** Parse stdout (and optionally the input) into the typed result. */
+  parse: (stdout: string, input: Input) => Output;
+  /** Per-recipe timeout override (default: 5000ms). */
+  timeout?: number;
+  /**
+   * Exit codes to treat as "empty success" instead of an error. Useful for
+   * commands like `git diff` that exit 1 when there's no diff.
+   */
+  tolerate?: readonly number[];
+}
+
+/** Context passed to `run()` alongside the input. */
+export interface RunCtx {
+  /** Working directory for the spawn. */
+  cwd?: string;
+  /** Environment variables (merged over process.env). */
+  env?: NodeJS.ProcessEnv;
+  /** Override timeout for this call (takes precedence over recipe.timeout). */
+  timeout?: number;
+}
+
+/** Discriminated error type surfaced by `run()`. */
+export type ExecError =
+  | { kind: "not-found"; binary: string }
+  | { kind: "timeout"; timeoutMs: number; binary: string }
+  | { kind: "exit"; code: number | null; signal: NodeJS.Signals | null; stdout: string; stderr: string }
+  | { kind: "spawn-failure"; message: string };
+
+/** Typed Result — no thrown exceptions for the 4 error kinds above. */
+export type Result<T> = { ok: true; value: T } | { ok: false; error: ExecError };
+
+// ── Resolver cache ──────────────────────────────────────────────────────────
+
+/**
+ * Low-level ToolResolver kept as the fallback for unregistered binary
+ * names. Registered names flow through the shared `ToolRegistry` so
+ * user overrides apply uniformly to every Recipe.
+ * See change: consolidate-tool-resolution.
+ */
+const sharedResolver = new ToolResolver({
+  processExecPath: process.execPath,
+  useLoginShell: true,
+});
+
+/**
+ * Test-only hook: invalidate the registry cache. Preserved as a thin
+ * shim over `registry.rescan()` so existing test suites keep working
+ * after migrating away from the runner's private `resolverCache`.
+ */
+export function resetResolverCache(): void {
+  try {
+    const reg = tryGetRegistry();
+    if (reg) reg.rescan();
+  } catch { /* isolated tests */ }
+}
+
+// Lazy registry accessor via `globalThis` symbol. The tool-registry
+// module writes itself there inside `getDefaultRegistry()`. Returns
+// `null` until some consumer (e.g. the server's `/api/tools` route or
+// the package-manager wrapper) constructs the registry; the runner
+// then falls back to `ToolResolver.which()` for that single call.
+interface LazyRegistry {
+  has(n: string): boolean;
+  resolve(n: string): { ok: boolean; path: string | null };
+  resolveExecutor(n: string): { ok: boolean; argv: string[] };
+  rescan(): void;
+}
+const GLOBAL_REGISTRY_KEY = Symbol.for("pi-dashboard.tool-registry");
+function tryGetRegistry(): LazyRegistry | null {
+  const reg = (globalThis as unknown as { [k: symbol]: LazyRegistry | undefined })[GLOBAL_REGISTRY_KEY];
+  return reg ?? null;
+}
+
+/**
+ * Is the argv[0] already a filesystem path (absolute or relative)? Then the
+ * caller supplied the binary directly and we should not try to resolve it
+ * via PATH/where/which — just use it as-is.
+ */
+function isPathLike(cmd: string): boolean {
+  if (path.isAbsolute(cmd)) return true;
+  if (cmd.startsWith("./") || cmd.startsWith("../")) return true;
+  if (cmd.startsWith(".\\") || cmd.startsWith("..\\")) return true;
+  return false;
+}
+
+/**
+ * Resolve a binary name to an absolute path.
+ *
+ * Strategy:
+ *   1. Path-like argv (absolute / relative) → use as-is if it exists.
+ *   2. Name is registered in `ToolRegistry` → delegate to the registry
+ *      so overrides, managed strategies, and diagnostics apply
+ *      uniformly. The registry has its own per-instance cache; the
+ *      runner no longer maintains a private `resolverCache`.
+ *   3. Name is not registered → fall back to `ToolResolver.which` for
+ *      ad-hoc binaries (zrok, code-server, custom tools) that the
+ *      dashboard hasn't formally declared.
+ *
+ * Imported lazily from `../tool-registry/index.js` to keep the runner
+ * usable at module-init time even if the registry hasn't finished
+ * loading its overrides yet.
+ */
+function resolveBinary(name: string): string | null {
+  if (isPathLike(name)) {
+    if (existsSync(name)) return name;
+    return null;
+  }
+  // Registered tools flow through the registry (overrides + diagnostics).
+  // The `tool-registry` module imports this file transitively via
+  // `platform/npm.ts`; the cycle is benign at function-call time because
+  // every module has finished evaluating by the time `resolveBinary` is
+  // first invoked (it's called only from inside `run()`).
+  const registry = tryGetRegistry();
+  if (registry && registry.has(name)) {
+    const resolved = registry.resolve(name);
+    return resolved.ok ? resolved.path : null;
+  }
+  return sharedResolver.which(name);
+}
+
+/**
+ * Resolve a Recipe's argv[0] to a spawn-ready argv via the tool
+ * registry's `resolveExecutor`. This is the path that lets `npm`,
+ * `openspec`, `pi` all resolve to `[node.exe, <script>.js]` on
+ * Windows — bypassing `.cmd` shims and the console-flash chain.
+ *
+ * Returns `null` when the binary is unknown AND not on PATH.
+ *
+ * Non-registered names fall back to `ToolResolver.which()` (single
+ * path, no executor wrapping). Path-like names (absolute/relative
+ * paths) are trusted as-is.
+ */
+function resolveExecutorArgv(name: string, recipeArgs: readonly string[]): string[] | null {
+  if (isPathLike(name)) {
+    if (existsSync(name)) return [name, ...recipeArgs];
+    return null;
+  }
+  const registry = tryGetRegistry();
+  if (registry && registry.has(name)) {
+    const exec = registry.resolveExecutor(name);
+    if (exec.ok && exec.argv.length > 0) {
+      return [...exec.argv, ...recipeArgs];
+    }
+    return null;
+  }
+  const p = sharedResolver.which(name);
+  return p ? [p, ...recipeArgs] : null;
+}
+
+// ── The engine ──────────────────────────────────────────────────────────────
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+/**
+ * Execute a Recipe against a typed input. Returns a `Result<Output>`.
+ * Never throws for recognized error conditions (not-found / timeout /
+ * exit / spawn-failure) — surfaces them as typed errors instead.
+ */
+export function run<Input, Output>(
+  recipe: Recipe<Input, Output>,
+  input: Input,
+  ctx: RunCtx = {},
+): Result<Output> {
+  const argv = recipe.argv(input);
+  if (argv.length === 0) {
+    return { ok: false, error: { kind: "spawn-failure", message: "Recipe produced empty argv" } };
+  }
+
+  const [rawCmd, ...recipeArgs] = argv;
+  const execArgv = resolveExecutorArgv(rawCmd, recipeArgs);
+  if (!execArgv) {
+    return { ok: false, error: { kind: "not-found", binary: rawCmd } };
+  }
+
+  const timeout = ctx.timeout ?? recipe.timeout ?? DEFAULT_TIMEOUT_MS;
+
+  // Route every command through `buildSafeArgv` — the canonical
+  // Windows-safe subprocess invocation. `execArgv` is already
+  // `[node.exe, <script>.js, ...args]` for executor-kind tools, so
+  // buildSafeArgv sees node.exe (.exe → direct spawn) and returns
+  // the argv unchanged. For non-executor tools resolving to `.cmd`,
+  // buildSafeArgv wraps in `cmd.exe /d /s /c`.
+  //
+  // See change: consolidate-windows-spawn-and-platform-handlers.
+  const [execCmd, ...execArgs] = execArgv;
+  const { argv: safeArgv, spawnOptions } = buildSafeArgv(execCmd, execArgs);
+
+  try {
+    const result = spawnSync(safeArgv[0], safeArgv.slice(1), {
+      cwd: ctx.cwd,
+      env: ctx.env ? { ...process.env, ...ctx.env } : undefined,
+      encoding: "utf-8",
+      timeout,
+      stdio: ["pipe", "pipe", "pipe"],
+      ...spawnOptions, // shell: false, windowsHide: true
+    });
+
+    // spawnSync error path: either it set .error (e.g. spawn failure) or
+    // it timed out (in which case signal === "SIGTERM" on Node >= 15).
+    if (result.error) {
+      const err = result.error as NodeJS.ErrnoException;
+      if (err.code === "ETIMEDOUT" || err.message?.includes("ETIMEDOUT")) {
+        return { ok: false, error: { kind: "timeout", timeoutMs: timeout, binary: rawCmd } };
+      }
+      return { ok: false, error: { kind: "spawn-failure", message: err.message } };
+    }
+
+    // Node's spawnSync signals timeout by setting signal = SIGTERM and status = null.
+    if (result.status === null && result.signal) {
+      return { ok: false, error: { kind: "timeout", timeoutMs: timeout, binary: rawCmd } };
+    }
+
+    const stdout = typeof result.stdout === "string" ? result.stdout : String(result.stdout ?? "");
+    const stderr = typeof result.stderr === "string" ? result.stderr : String(result.stderr ?? "");
+
+    const status = result.status;
+    const tolerated = status !== 0 && recipe.tolerate?.includes(status ?? -1);
+    if (status === 0 || tolerated) {
+      return { ok: true, value: recipe.parse(stdout, input) };
+    }
+    return { ok: false, error: { kind: "exit", code: status, signal: result.signal, stdout, stderr } };
+  } catch (err) {
+    return {
+      ok: false,
+      error: { kind: "spawn-failure", message: err instanceof Error ? err.message : String(err) },
+    };
+  }
+}
+
+/**
+ * Async sibling of `run()`. Same Recipe contract, same binary
+ * resolution, same `.cmd`/shell handling, same error normalization
+ * — but spawns via `platform/exec.ts`'s wrapped `spawn` (with stdout
+ * captured to a Promise) instead of `spawnSync`, so callers can run
+ * many recipes concurrently without blocking the event loop.
+ *
+ * Use this from server code paths that iterate over many inputs (e.g.
+ * `openspec status --change <name>` across ~20 changes). The sync
+ * `run()` is fine for one-off calls or for callers that must stay
+ * sync (the bridge extension's sync hooks).
+ *
+ * `windowsHide: true` comes from the shared `spawn` wrapper — the
+ * same invariant the sync runner relies on. Do not re-introduce a
+ * bare `child_process.spawn` elsewhere.
+ *
+ * See change: consolidate-tool-resolution (async runner follow-up).
+ */
+export function runAsync<Input, Output>(
+  recipe: Recipe<Input, Output>,
+  input: Input,
+  ctx: RunCtx = {},
+): Promise<Result<Output>> {
+  const argv = recipe.argv(input);
+  if (argv.length === 0) {
+    return Promise.resolve({ ok: false, error: { kind: "spawn-failure", message: "Recipe produced empty argv" } });
+  }
+
+  const [rawCmd, ...recipeArgs] = argv;
+  const execArgv = resolveExecutorArgv(rawCmd, recipeArgs);
+  if (!execArgv) {
+    return Promise.resolve({ ok: false, error: { kind: "not-found", binary: rawCmd } });
+  }
+
+  const timeout = ctx.timeout ?? recipe.timeout ?? DEFAULT_TIMEOUT_MS;
+
+  // Executor-kind tools resolve to `[node.exe, script.js, ...]` on
+  // Windows so buildSafeArgv's `.cmd` wrapping is a no-op here — pure
+  // node.exe spawn, no cmd.exe in the chain.
+  const [execCmd, ...execArgs] = execArgv;
+  const { argv: safeArgv, spawnOptions } = buildSafeArgv(execCmd, execArgs);
+
+  return new Promise<Result<Output>>((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const settle = (r: Result<Output>) => {
+      if (settled) return;
+      settled = true;
+      resolve(r);
+    };
+
+    let child: import("node:child_process").ChildProcess;
+    try {
+      child = spawn(safeArgv[0], safeArgv.slice(1), {
+        cwd: ctx.cwd,
+        env: ctx.env ? { ...process.env, ...ctx.env } : undefined,
+        stdio: ["ignore", "pipe", "pipe"],
+        ...spawnOptions, // shell: false, windowsHide: true
+      });
+    } catch (err) {
+      settle({ ok: false, error: { kind: "spawn-failure", message: err instanceof Error ? err.message : String(err) } });
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      try { child.kill("SIGTERM"); } catch { /* ignore */ }
+      settle({ ok: false, error: { kind: "timeout", timeoutMs: timeout, binary: rawCmd } });
+    }, timeout);
+
+    child.stdout?.on("data", (chunk: Buffer) => { stdout += chunk.toString("utf-8"); });
+    child.stderr?.on("data", (chunk: Buffer) => { stderr += chunk.toString("utf-8"); });
+
+    child.on("error", (err: NodeJS.ErrnoException) => {
+      clearTimeout(timer);
+      if (err.code === "ETIMEDOUT" || err.message?.includes("ETIMEDOUT")) {
+        settle({ ok: false, error: { kind: "timeout", timeoutMs: timeout, binary: rawCmd } });
+        return;
+      }
+      settle({ ok: false, error: { kind: "spawn-failure", message: err.message } });
+    });
+
+    child.on("close", (code: number | null, signal: NodeJS.Signals | null) => {
+      clearTimeout(timer);
+      const tolerated = code !== 0 && code !== null && recipe.tolerate?.includes(code);
+      if (code === 0 || tolerated) {
+        try {
+          settle({ ok: true, value: recipe.parse(stdout, input) });
+        } catch (err) {
+          settle({ ok: false, error: { kind: "spawn-failure", message: err instanceof Error ? err.message : String(err) } });
+        }
+        return;
+      }
+      settle({ ok: false, error: { kind: "exit", code, signal, stdout, stderr } });
+    });
+  });
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Get the value or a fallback. Use when the caller doesn't care about the
+ * error discriminant (best-effort operations).
+ *
+ *   const branch = unwrap(git.currentBranch({ cwd }), null);
+ */
+export function unwrap<T>(result: Result<T>, fallback: T): T {
+  return result.ok ? result.value : fallback;
+}

package/packages/shared/src/platform/shell.ts

@@ -0,0 +1,44 @@
+/**
+ * Cross-platform shell and terminal-environment primitives.
+ *
+ * `detectShell` and `getTerminalEnvHints` accept an injectable `platform`
+ * and `env` parameters (defaulting to `process.platform` and `process.env`)
+ * so tests can exercise both branches without global mutation.
+ * See change: consolidate-platform-handlers.
+ */
+
+export interface ShellOpts {
+  /** Override platform (defaults to process.platform). */
+  platform?: NodeJS.Platform;
+  /** Override env (defaults to process.env). */
+  env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * Detect the appropriate shell for the current platform:
+ *   - win32: `%COMSPEC%` if set, else `"powershell.exe"`
+ *   - unix:  `$SHELL` if set, else `"/bin/bash"`
+ */
+export function detectShell(opts: ShellOpts = {}): string {
+  const platform = opts.platform ?? process.platform;
+  const env = opts.env ?? process.env;
+  if (platform === "win32") {
+    return env.COMSPEC || "powershell.exe";
+  }
+  return env.SHELL || "/bin/bash";
+}
+
+/**
+ * Extra environment variables to set when spawning a PTY, per platform.
+ * Currently only Windows sets `TERM=cygwin` (when not already set) so that
+ * curses/readline-style apps render correctly in node-pty on Windows.
+ */
+export function getTerminalEnvHints(opts: ShellOpts = {}): Record<string, string> {
+  const platform = opts.platform ?? process.platform;
+  const env = opts.env ?? process.env;
+  const hints: Record<string, string> = {};
+  if (platform === "win32" && !env.TERM) {
+    hints.TERM = "cygwin";
+  }
+  return hints;
+}