@blackbelt-technology/pi-agent-dashboard 0.2.9 → 0.4.0

package/packages/server/src/process-manager.ts

@@ -1,310 +1,491 @@
 /**
- * Process manager for spawning pi sessions via tmux or headless (RPC mode).
+ * Process manager for spawning pi sessions.
+ *
+ * Dispatch is owned by `platform/spawn-mechanism.ts`'s `selectMechanism`.
+ * Per-mechanism spawn is owned by `platform/detached-spawn.ts`. This
+ * module's job is: resolve pi + tool availability, build per-mechanism
+ * command, delegate.
+ *
+ * Invariants:
+ *   - No direct `process.platform === "..."` branches in this file.
+ *     All platform-aware behaviour lives in `platform/**`.
+ *   - Every mechanism branch builds pi argv uniformly from
+ *     `buildHeadlessArgs` or its wt/tmux counterpart; `sessionFile`
+ *     and `mode` are never dropped by any branch.
+ *
+ * See change: consolidate-windows-spawn-and-platform-handlers.
  */
-import { execSync, spawn, type ChildProcess } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync, openSync, closeSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import type { ChildProcess } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
 import type { SpawnStrategy } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import { MANAGED_BIN } from "@blackbelt-technology/pi-dashboard-shared/managed-paths.js";
-import { ToolResolver } from "@blackbelt-technology/pi-dashboard-shared/tool-resolver.js";
+import { ToolResolver } from "@blackbelt-technology/pi-dashboard-shared/platform/binary-lookup.js";
+import { execSync, spawnSync, buildSafeArgv } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
+import {
+  spawnDetached,
+  waitForNoCrash,
+} from "@blackbelt-technology/pi-dashboard-shared/platform/detached-spawn.js";
+import {
+  selectMechanism,
+  buildWtArgs,
+  sessionFlagsToArgv,
+  type SpawnMechanism,
+  type UserSpawnStrategy,
+} from "@blackbelt-technology/pi-dashboard-shared/platform/spawn-mechanism.js";
+
+// ── Resolver seam (injectable for tests) ────────────────────────────────────
+
+let resolver: ToolResolver = new ToolResolver({ processExecPath: process.execPath });
+
+/** Inject a resolver — used by tests. Production code never calls this. */
+export function setResolver(r: ToolResolver): void {
+  resolver = r;
+}
 
-/** Server-side resolver — knows the current process node binary. */
-const resolver = new ToolResolver({ processExecPath: process.execPath });
+/** Reset to default — used by tests to clean up. */
+export function resetResolver(): void {
+  resolver = new ToolResolver({ processExecPath: process.execPath });
+}
 
-/** Build env with managed install bin + current node binary dir prepended to PATH.
- *  Delegates to ToolResolver.buildSpawnEnv().
- */
+// ── Public API ─────────────────────────────────────────────────────────────
+
+export interface SessionOptions {
+  sessionFile?: string;
+  mode?: "continue" | "fork";
+  strategy?: SpawnStrategy;
+}
+
+export interface SpawnResult {
+  success: boolean;
+  message: string;
+  pid?: number;
+  process?: ChildProcess;
+  /** True when spawned from the dashboard (for writing session meta) */
+  dashboardSpawned?: boolean;
+}
+
+/** Build env with managed install bin + current node binary dir prepended to PATH. */
 export function buildSpawnEnv(baseEnv: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
   return resolver.buildSpawnEnv(baseEnv);
 }
 
-export interface PlatformInfo {
-  strategy: "tmux" | "wsl" | "cmd";
-  platform: string;
+/**
+ * Escape a string for safe use inside a POSIX shell command.
+ * Used by buildTmuxCommand for tmux/wsl-tmux argv construction.
+ */
+export function shellEscape(s: string): string {
+  if (/^[a-zA-Z0-9_./:=@-]+$/.test(s)) return s;
+  return `'${s.replace(/'/g, "'\\''")}'`;
 }
 
-export function detectPlatform(platform?: string): PlatformInfo {
-  const p = platform ?? process.platform;
-
-  if (p === "darwin" || p === "linux") {
-    return { strategy: "tmux", platform: p };
-  }
-  if (p === "win32") {
-    return { strategy: "wsl", platform: p };
-  }
-  return { strategy: "tmux", platform: p };
+/**
+ * Build the argv tail for a headless pi invocation: `--mode rpc` plus
+ * `--session <file>` or `--fork <file>` when options provide them.
+ */
+export function buildHeadlessArgs(options?: SessionOptions): string[] {
+  return ["--mode", "rpc", ...sessionFlagsToArgv(options ?? {})];
 }
 
-export interface SessionOptions {
-  sessionFile?: string;
-  mode?: "continue" | "fork";
-  strategy?: SpawnStrategy;
+/**
+ * Build the argv tail for an INTERACTIVE pi invocation (wt, tmux, wsl-tmux):
+ * no `--mode rpc`; just session/fork flags when provided.
+ */
+export function buildInteractivePiArgs(options?: SessionOptions): string[] {
+  return sessionFlagsToArgv(options ?? {});
 }
 
+/**
+ * Build a tmux shell command string to run pi in a new tmux window/session.
+ * Kept as a string (not argv) because tmux is invoked via `execSync(cmd)`.
+ */
 export function buildTmuxCommand(cwd: string, sessionExists: boolean, options?: SessionOptions): string {
   const safeCwd = shellEscape(cwd);
-  let piCmd = `cd ${safeCwd} && pi`;
-
-  if (options?.sessionFile && options?.mode === "continue") {
-    piCmd = `cd ${safeCwd} && pi --session ${shellEscape(options.sessionFile)}`;
-  } else if (options?.sessionFile && options?.mode === "fork") {
-    piCmd = `cd ${safeCwd} && pi --fork ${shellEscape(options.sessionFile)}`;
-  }
-
+  const flags = sessionFlagsToArgv(options ?? {})
+    .map(shellEscape)
+    .join(" ");
+  const piCmd = flags ? `cd ${safeCwd} && pi ${flags}` : `cd ${safeCwd} && pi`;
   if (sessionExists) {
     return `tmux new-window -t pi-dashboard -c ${safeCwd} "${piCmd}"`;
   }
   return `tmux new-session -d -s pi-dashboard -c ${safeCwd} "${piCmd}"`;
 }
 
+// ── Availability probes (isolated, one place) ───────────────────────────────
+
 function isTmuxAvailable(): boolean {
   try {
-    execSync("which tmux", { stdio: "ignore" });
-    return true;
+    // `which` / `where` already baked into ToolResolver.
+    return resolver.which("tmux") !== null;
   } catch {
     return false;
   }
 }
 
-function dashboardSessionExists(): boolean {
+function isWtAvailable(): boolean {
   try {
-    execSync("tmux has-session -t pi-dashboard 2>/dev/null", { stdio: "ignore" });
-    return true;
+    return resolver.which("wt") !== null;
   } catch {
     return false;
   }
 }
 
-export interface SpawnResult {
-  success: boolean;
-  message: string;
-  pid?: number;
-  process?: ChildProcess;
-  /** True when spawned from the dashboard (for writing session meta) */
-  dashboardSpawned?: boolean;
+// Cache the WSL-tmux probe for the server lifetime. On machines with a broken
+// WSL install (e.g. Docker Desktop WSL mount failure) this single probe can
+// cost 30+ seconds — we MUST NOT pay it on every + Session click. The result
+// can only change if the user installs/uninstalls WSL or tmux, which requires
+// a server restart anyway.
+let _wslTmuxAvailabilityCache: boolean | null = null;
+let _wslFallbackLogged = false;
+
+/** Test-only: reset the cache so tests can exercise both branches. */
+export function _resetWslTmuxCacheForTests(): void {
+  _wslTmuxAvailabilityCache = null;
+  _wslFallbackLogged = false;
 }
 
-export function buildHeadlessArgs(options?: SessionOptions): string[] {
-  const args = ["--mode", "rpc"];
-
-  if (options?.sessionFile && options?.mode === "continue") {
-    args.push("--session", options.sessionFile);
-  } else if (options?.sessionFile && options?.mode === "fork") {
-    args.push("--fork", options.sessionFile);
+function isWslTmuxAvailable(): boolean {
+  // WSL tmux probe. Route through `buildSafeArgv` so there is NO
+  // cmd.exe-as-shell in the path — `spawnSync("wsl", ["which", "tmux"])`
+  // with windowsHide:true + shell:false keeps the console invisible.
+  // `wsl.exe` itself still spins up WSL briefly, but that's background
+  // (no visible window). Only invoked after `wt` is known absent.
+  //
+  // Cached for the server lifetime (see comment on _wslTmuxAvailabilityCache).
+  if (_wslTmuxAvailabilityCache !== null) return _wslTmuxAvailabilityCache;
+  try {
+    const { argv, spawnOptions } = buildSafeArgv("wsl", ["which", "tmux"]);
+    const r = spawnSync(argv[0], argv.slice(1), {
+      stdio: "ignore",
+      timeout: 1500,
+      ...spawnOptions,
+    });
+    _wslTmuxAvailabilityCache = r.status === 0;
+  } catch {
+    _wslTmuxAvailabilityCache = false;
   }
+  if (!_wslTmuxAvailabilityCache && !_wslFallbackLogged) {
+    _wslFallbackLogged = true;
+    console.error(
+      "[spawn] Windows Terminal (wt.exe) not on PATH and WSL tmux unavailable \u2014 " +
+      "falling back to headless session spawn. Install Windows Terminal for a " +
+      "nicer UX: https://aka.ms/terminal",
+    );
+  }
+  return _wslTmuxAvailabilityCache;
+}
 
-  return args;
+function dashboardSessionExists(): boolean {
+  try {
+    execSync("tmux has-session -t pi-dashboard 2>/dev/null", { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
 }
 
-/** Resolve the pi command as [command, ...prefixArgs].
- *  Delegates to ToolResolver.resolvePi().
- */
+/** Resolve pi as argv. Prefers node.exe + cli.js on Windows (avoids .cmd). */
 function resolvePiCommand(): string[] | null {
   return resolver.resolvePi();
 }
 
-/** Windows-specific headless spawn with error detection and stderr capture.
- *  Waits briefly to detect immediate process death (e.g., missing deps, config errors).
+// ── Mechanism dispatch ─────────────────────────────────────────────────────
+
+/**
+ * Select the spawn mechanism for this invocation using lazy tool
+ * availability probing. Each probe runs a subprocess, so we short-
+ * circuit as soon as a mechanism is decided — crucially, the WSL
+ * probe (`wsl which tmux`) spins up the WSL VM on Windows and is
+ * the most expensive, so we only run it when wt is ALREADY known
+ * absent and the user hasn't asked for headless.
+ *
+ * Ordering mirrors `selectMechanism`'s decision rules:
+ *   1. electronMode or userStrategy=headless → no probes at all
+ *   2. Unix → probe tmux only
+ *   3. Windows → probe wt first; probe wsl-tmux only if wt is absent
  */
-async function spawnHeadlessWindows(
-  cwd: string,
-  piCmd: string[],
-  args: string[],
-  env: NodeJS.ProcessEnv,
-): Promise<SpawnResult> {
-  const [bin, ...prefixArgs] = piCmd;
-  const needsShell = bin.endsWith(".cmd");
-  const spawnBin = needsShell ? `"${bin}"` : bin;
-  const spawnArgs = needsShell
-    ? [...prefixArgs, ...args].map(a => `"${a}"`)
-    : [...prefixArgs, ...args];
+function chooseMechanism(options?: SessionOptions, electronMode = false): SpawnMechanism {
+  const userStrategy: UserSpawnStrategy = options?.strategy === "headless" ? "headless" : "tmux";
+  const platform = process.platform;
 
-  const cmdForLog = `${bin} ${[...prefixArgs, ...args].join(" ")}`;
-  console.error(`[spawn] Windows headless: ${cmdForLog} (cwd=${cwd})`);
+  // Short-circuit #1: headless requires no probes.
+  if (electronMode || userStrategy === "headless") {
+    return "headless";
+  }
 
-  // Capture stderr for diagnostics (pi might log errors there)
-  const child = spawn(spawnBin, spawnArgs, {
-    cwd,
-    detached: false,
-    stdio: ["pipe", "ignore", "pipe"],
-    env,
-    shell: needsShell,
-    windowsHide: true,
-  });
+  // Unix: tmux or headless.
+  if (platform === "linux" || platform === "darwin") {
+    return selectMechanism({
+      platform,
+      userStrategy,
+      electronMode,
+      available: { tmux: isTmuxAvailable(), wt: false, wslTmux: false },
+    });
+  }
 
-  // Collect stderr for early crash diagnostics
-  let stderrBuf = "";
-  child.stderr?.on("data", (chunk: Buffer) => {
-    stderrBuf += chunk.toString();
-    // Limit memory: keep only last 4 KB
-    if (stderrBuf.length > 4096) stderrBuf = stderrBuf.slice(-4096);
-  });
+  // Windows: wt first (cheap `where wt`). Only probe WSL when wt is
+  // absent — `wsl which tmux` starts the WSL VM and is slow + flashy.
+  if (platform === "win32") {
+    const wt = isWtAvailable();
+    if (wt) {
+      return selectMechanism({
+        platform,
+        userStrategy,
+        electronMode,
+        available: { tmux: false, wt: true, wslTmux: false },
+      });
+    }
+    const wslTmux = isWslTmuxAvailable();
+    return selectMechanism({
+      platform,
+      userStrategy,
+      electronMode,
+      available: { tmux: false, wt: false, wslTmux },
+    });
+  }
 
-  // Handle async spawn errors (e.g., ENOENT if binary disappears between check and exec)
-  let spawnError: string | null = null;
-  child.on("error", (err: Error) => {
-    spawnError = err.message;
-    console.error(`[spawn] Windows spawn error: ${err.message}`);
-  });
+  // Unknown platform → headless.
+  return "headless";
+}
 
-  child.unref();
-  (child.stdin as any)?.unref();
-  child.stderr?.unref();
+// ── Main entry point ───────────────────────────────────────────────────────
 
-  // Guard: if pid is undefined, spawn failed synchronously
-  if (!child.pid) {
-    // Wait briefly for the async error event
-    await new Promise(r => setTimeout(r, 200));
-    return {
-      success: false,
-      message: `Failed to spawn pi: ${spawnError || "unknown error (no PID)"}. Command: ${cmdForLog}`,
-    };
+export async function spawnPiSession(
+  cwd: string,
+  options?: SessionOptions & { electronMode?: boolean },
+): Promise<SpawnResult> {
+  if (!existsSync(cwd)) {
+    return { success: false, message: `Directory does not exist: ${cwd}` };
   }
 
-  // Wait briefly to detect immediate crash (e.g., missing module, config error)
-  const exitCode = await Promise.race([
-    new Promise<number | null>(resolve => child.on("exit", resolve)),
-    new Promise<undefined>(resolve => setTimeout(() => resolve(undefined), 1500)),
-  ]);
-
-  if (exitCode !== undefined) {
-    const detail = stderrBuf.trim()
-      ? `\nstderr: ${stderrBuf.trim().split("\n").slice(-5).join("\n")}`
-      : "";
-    console.error(`[spawn] Pi exited immediately with code ${exitCode}${detail}`);
+  const mechanism = chooseMechanism(options, options?.electronMode ?? false);
+
+  switch (mechanism) {
+    case "tmux":     return spawnTmux(cwd, options);
+    case "wt":       return spawnWt(cwd, options);
+    case "wsl-tmux": return spawnWslTmux(cwd, options);
+    case "headless": return spawnHeadless(cwd, options);
+  }
+}
+
+// ── Per-mechanism spawn ────────────────────────────────────────────────────
+
+function spawnTmux(cwd: string, options?: SessionOptions): SpawnResult {
+  const exists = dashboardSessionExists();
+  const cmd = buildTmuxCommand(cwd, exists, options);
+  try {
+    execSync(cmd, { stdio: "ignore" });
     return {
-      success: false,
-      message: `Pi process exited immediately (code ${exitCode}).${detail}\nCommand: ${cmdForLog}`,
+      success: true,
+      dashboardSpawned: true,
+      message: `Pi session spawned in tmux (${exists ? "new window" : "new session"})`,
     };
+  } catch (err: any) {
+    return { success: false, message: `Failed to spawn session: ${err.message}` };
+  }
+}
+
+function spawnWslTmux(cwd: string, options?: SessionOptions): SpawnResult {
+  try {
+    const cmd = `wsl ${buildTmuxCommand(cwd, false, options)}`;
+    execSync(cmd, { stdio: "ignore" });
+    return { success: true, dashboardSpawned: true, message: "Pi session spawned via WSL tmux" };
+  } catch (err: any) {
+    return { success: false, message: `Failed to spawn via WSL tmux: ${err.message}` };
+  }
+}
+
+async function spawnWt(cwd: string, options?: SessionOptions): Promise<SpawnResult> {
+  const wt = resolver.which("wt");
+  if (!wt) {
+    return { success: false, message: "Windows Terminal (wt.exe) not found" };
+  }
+  const piCmd = resolvePiCommand();
+  if (!piCmd) {
+    return { success: false, message: `pi binary not found. Checked: ${MANAGED_BIN} and system PATH.` };
+  }
+
+  const piArgv = [...piCmd, ...buildInteractivePiArgs(options)];
+  const args = buildWtArgs({ cwd, title: path.basename(cwd) || "pi", piArgv });
+
+  const r = await spawnDetached({
+    cmd: wt,
+    args,
+    cwd,
+    env: buildSpawnEnv(),
+  });
+
+  if (!r.ok) {
+    return { success: false, message: `Failed to launch Windows Terminal: ${r.error}` };
   }
 
   return {
     success: true,
     dashboardSpawned: true,
-    message: `Pi session spawned headless (pid ${child.pid})`,
-    pid: child.pid,
-    process: child,
+    message: "Pi session spawned in Windows Terminal",
+    pid: r.pid,
+    process: r.process,
   };
 }
 
 async function spawnHeadless(cwd: string, options?: SessionOptions): Promise<SpawnResult> {
-  try {
-    const args = buildHeadlessArgs(options);
-    const env = buildSpawnEnv();
-
-    // Pre-check: verify pi binary exists
-    const piCmd_ = resolvePiCommand();
-    if (!piCmd_) {
-      return {
-        success: false,
-        message: `pi binary not found. Checked: ${MANAGED_BIN}/pi and system PATH.`,
-      };
-    }
-
-    if (process.platform === "win32") {
-      return await spawnHeadlessWindows(cwd, piCmd_, args, env);
-    }
-
-    // Unix (macOS / Linux / WSL): wrap with "tail -f /dev/null | pi" so stdin
-    // is an internal pipe that survives GC and server restarts.
-    // detached: true creates a new process group; we kill via -pid later.
-    const piBin = piCmd_[0];
-    const piCmd = [shellEscape(piBin), ...args.map(shellEscape)].join(" ");
-    // Use "tail -f /dev/null" to keep stdin pipe open for pi.
-    // Unlike "sleep N", tail -f /dev/null works correctly even when
-    // the outer shell's stdin is /dev/null (stdio:"ignore"),
-    // which breaks "sleep | pi" on some Linux systems.
-    const child = spawn("sh", ["-c", `tail -f /dev/null | ${piCmd}`], {
-      cwd,
-      detached: true,
-      stdio: "ignore",
-      env,
-    });
-    child.unref();
+  const args = buildHeadlessArgs(options);
+  const env = buildSpawnEnv();
+  const piCmd = resolvePiCommand();
+  if (!piCmd) {
+    return { success: false, message: `pi binary not found. Checked: ${MANAGED_BIN} and system PATH.` };
+  }
+  const [bin, ...prefixArgs] = piCmd;
 
-    return {
-      success: true,
-      dashboardSpawned: true,
-      message: `Pi session spawned headless (pid ${child.pid})`,
-      pid: child.pid,
-      process: child,
-    };
-  } catch (err: any) {
-    return {
-      success: false,
-      message: `Failed to spawn headless session: ${err.message}`,
-    };
+  const platform = process.platform;
+  if (platform === "win32") {
+    return spawnHeadlessDetached(cwd, bin, prefixArgs, args, env);
   }
-}
 
-/** Escape a string for safe use in a shell command. */
-export function shellEscape(s: string): string {
-  if (/^[a-zA-Z0-9_./:=@-]+$/.test(s)) return s;
-  return `'${s.replace(/'/g, "'\\''")}'`;
+  // Unix: use the sh -c "tail -f /dev/null | pi" wrapper so pi's stdin is
+  // an internal pipe that survives GC. Pass through the detached-spawn
+  // primitive so all the libuv defaults (detached, stdio, windowsHide) are
+  // uniform. The wrapper is a domain-specific stdin-survival trick — it
+  // belongs here (process-manager), not inside the primitive.
+  const piLine = [shellEscape(bin), ...[...prefixArgs, ...args].map(shellEscape)].join(" ");
+  const r = await spawnDetached({
+    cmd: "sh",
+    args: ["-c", `tail -f /dev/null | ${piLine}`],
+    cwd,
+    env,
+  });
+  if (!r.ok) {
+    return { success: false, message: `Failed to spawn headless (Unix): ${r.error}` };
+  }
+  return {
+    success: true,
+    dashboardSpawned: true,
+    message: `Pi session spawned headless (pid ${r.pid})`,
+    pid: r.pid,
+    process: r.process,
+  };
 }
 
-export async function spawnPiSession(cwd: string, options?: SessionOptions & { electronMode?: boolean }): Promise<SpawnResult> {
-  if (!existsSync(cwd)) {
+/**
+ * Windows headless spawn using the detached-spawn primitive.
+ *
+ * Key correctness fixes vs. the previous spawnHeadlessWindows:
+ *   • detached: true            (via primitive) — excludes from libuv's
+ *                                kill-on-close job; sessions survive
+ *                                server restart.
+ *   • shell: false              (via primitive) — sidesteps Node issue
+ *                                #21825 and cmd.exe /d /s /c edge cases.
+ *                                Requires pi to be [node.exe, cli.js],
+ *                                NOT pi.cmd. If only pi.cmd is on PATH,
+ *                                we surface an actionable error.
+ *   • stdio[0] = "ignore"       — no parent-owned stdin pipe.
+ *   • stdio[2] = logFd          — stderr to a persisted log file (not
+ *                                a pipe that dies with the parent).
+ *   • Crash window 300 ms       (was 1500 ms) — via waitForNoCrash.
+ */
+async function spawnHeadlessDetached(
+  cwd: string,
+  bin: string,
+  prefixArgs: string[],
+  args: string[],
+  env: NodeJS.ProcessEnv,
+): Promise<SpawnResult> {
+  // Refuse to go through cmd.exe — the managed install must be present
+  // so resolvePiCommand returned [node.exe, cli.js]. If someone has
+  // only pi.cmd on PATH, point them at the wizard / managed install.
+  if (bin.toLowerCase().endsWith(".cmd") || bin.toLowerCase().endsWith(".bat")) {
     return {
       success: false,
-      message: `Directory does not exist: ${cwd}`,
+      message:
+        "Windows pi spawn requires node.exe + cli.js (managed install). " +
+        "Found only pi.cmd on PATH. Run the dashboard setup wizard or " +
+        "install pi via the dashboard's Packages view.",
     };
   }
 
-  // Electron mode always forces headless, skipping tmux detection entirely
-  if (options?.electronMode || options?.strategy === "headless") {
-    return spawnHeadless(cwd, options);
+  // Prepare a per-session log file for stderr capture.
+  const logDir = path.join(os.homedir(), ".pi", "dashboard", "sessions");
+  try { mkdirSync(logDir, { recursive: true }); } catch { /* ignore */ }
+  const logPath = path.join(logDir, `pi-spawn-${Date.now()}-${Math.floor(Math.random() * 1e6)}.log`);
+
+  let logFd: number | undefined;
+  try {
+    logFd = openSync(logPath, "a");
+  } catch {
+    // If we can't open the log, proceed without stderr capture; still spawn.
+    logFd = undefined;
   }
 
-  const platform = detectPlatform();
+  const cmdForLog = `${bin} ${[...prefixArgs, ...args].join(" ")}`;
+  console.error(`[spawn] Windows headless (detached): ${cmdForLog} (cwd=${cwd}, log=${logPath})`);
+
+  // CRITICAL: pi's `--mode rpc` listens for `process.stdin.on("end")`
+  // and calls shutdown() on EOF. With `stdio[0] = "ignore"`, stdin
+  // closes immediately and pi exits before resume completes. Use a
+  // parent-held pipe so pi's stdin stays open as long as the dashboard
+  // server is alive.
+  //
+  // Trade-off: when the dashboard server process dies, Windows closes
+  // the pipe handle, pi sees EOF, and shuts down. This is the opposite
+  // of the Unix `sh -c "tail -f /dev/null | pi"` wrapper (which keeps
+  // stdin open via an internal process-group pipe that survives
+  // parent death). On Windows we accept "pi dies with dashboard" as
+  // the cost of RPC mode working reliably. A future keeper-process
+  // approach could restore the durability invariant.
+  //
+  // detach: false — restores the behaviour of commit d331850 that was
+  // silently overridden by 5ab7956's universal `detached: true` invariant.
+  // On Windows, `detached: true` allocates a new console for the child
+  // unless all stdio slots are "ignore" (libuv `src/win/process.c` only
+  // sets CREATE_NO_WINDOW when no slot has UV_INHERIT_FD). With `stdin:
+  // "pipe"` we ALWAYS have UV_INHERIT_FD on stdio[0], so CREATE_NO_WINDOW
+  // can never fire, and `windowsHide: true` only applies SW_HIDE after
+  // allocation — producing brief console flashes on every session spawn.
+  // `detach: false` keeps the child inside the parent's Job Object (no
+  // new console needed — no flash). "pi dies with dashboard" invariant is
+  // unchanged: stdin-EOF on parent death already ties them together.
+  //
+  // See change: prep-for-develop-merge.
+  const r = await spawnDetached({
+    cmd: bin,
+    args: [...prefixArgs, ...args],
+    cwd,
+    env,
+    logFd,
+    stdinMode: "pipe",
+    detach: false,
+  });
 
-  if (platform.strategy === "tmux") {
-    if (!isTmuxAvailable()) {
-      return {
-        success: false,
-        message: "tmux is not installed. Install it to spawn sessions from the dashboard.",
-      };
-    }
+  // We don't need the parent's copy of the log fd; the child has its own.
+  if (logFd !== undefined) {
+    try { closeSync(logFd); } catch { /* ignore */ }
+  }
 
-    const exists = dashboardSessionExists();
-    const cmd = buildTmuxCommand(cwd, exists, options);
-
-    try {
-      execSync(cmd, { stdio: "ignore" });
-      return {
-        success: true,
-        dashboardSpawned: true,
-        message: `Pi session spawned in tmux (${exists ? "new window" : "new session"})`,
-      };
-    } catch (err: any) {
-      return {
-        success: false,
-        message: `Failed to spawn session: ${err.message}`,
-      };
-    }
+  if (!r.ok || !r.process || !r.pid) {
+    return {
+      success: false,
+      message: `Failed to spawn pi: ${r.error ?? "unknown error"}. Command: ${cmdForLog}`,
+    };
   }
 
-  if (platform.strategy === "wsl") {
-    try {
-      // Try WSL tmux first
-      execSync("wsl which tmux", { stdio: "ignore" });
-      const cmd = `wsl ${buildTmuxCommand(cwd, false)}`;
-      execSync(cmd, { stdio: "ignore" });
-      return { success: true, dashboardSpawned: true, message: "Pi session spawned via WSL tmux" };
-    } catch {
-      // Fallback to cmd
-      try {
-        spawn("cmd", ["/c", `cd /d "${cwd}" && pi`], {
-          detached: true,
-          stdio: "ignore",
-        }).unref();
-        return { success: true, dashboardSpawned: true, message: "Pi session spawned via cmd" };
-      } catch (err: any) {
-        return { success: false, message: `Failed to spawn: ${err.message}` };
-      }
-    }
+  // Short crash-detection window so we return fast on the happy path
+  // but still catch immediate crashes (missing modules, config errors).
+  const gate = await waitForNoCrash({ child: r.process, windowMs: 300 });
+  if (!gate.ok) {
+    return {
+      success: false,
+      message:
+        `Pi process exited immediately (code ${gate.exitCode}). ` +
+        `See ${logPath} for details.\nCommand: ${cmdForLog}`,
+    };
   }
 
-  return { success: false, message: "Unsupported platform" };
+  return {
+    success: true,
+    dashboardSpawned: true,
+    message: `Pi session spawned headless (pid ${r.pid})`,
+    pid: r.pid,
+    process: r.process,
+  };
 }