@blackbelt-technology/pi-agent-dashboard 0.5.0 → 0.5.2

package/packages/server/src/rpc-keeper/keeper-manager.ts

@@ -0,0 +1,364 @@
+/**
+ * KeeperManager — server-side helper for spawning, writing to, killing,
+ * and discovering RPC keeper sidecars.
+ *
+ * One keeper process per headless session. The keeper itself is
+ * `keeper.cjs` (CJS-pure). KeeperManager bridges between the dashboard
+ * server's TypeScript world and the spawned CJS subprocess.
+ *
+ * Tasks: 4.1, 4.2, 4.3, 4.4, 4.5.
+ * See: openspec/changes/add-rpc-stdin-dispatch-with-keeper-sidecar
+ *   - specs/rpc-keeper-sidecar/spec.md (lifecycle + discovery contract)
+ *   - design.md Decisions 4 + 8
+ */
+import {
+  existsSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  unlinkSync,
+} from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ChildProcess } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
+import {
+  spawnDetached as defaultSpawnDetached,
+  type SpawnDetachedOptions,
+  type SpawnDetachedResult,
+} from "@blackbelt-technology/pi-dashboard-shared/platform/detached-spawn.js";
+import {
+  isProcessAlive,
+  killPidWithGroup,
+} from "@blackbelt-technology/pi-dashboard-shared/platform/process.js";
+
+// ── Path conventions ─────────────────────────────────────────────────────────
+
+function defaultSessionsDir(): string {
+  return path.join(os.homedir(), ".pi", "dashboard", "sessions");
+}
+
+function defaultKeeperPath(): string {
+  // `keeper.cjs` sits alongside this module. Works under jiti (source dir)
+  // and any preserve-structure build (dist/rpc-keeper/keeper.cjs).
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.join(here, "keeper.cjs");
+}
+
+export function sockPathFor(
+  sessionsDir: string,
+  sessionId: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  return platform === "win32"
+    ? `\\\\.\\pipe\\pi-rpc-${sessionId}`
+    : path.join(sessionsDir, `${sessionId}.rpc.sock`);
+}
+
+export function pidPathFor(
+  sessionsDir: string,
+  sessionId: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  return platform === "win32"
+    ? path.join(sessionsDir, `pi-rpc-${sessionId}.pid`)
+    : `${sockPathFor(sessionsDir, sessionId, platform)}.pid`;
+}
+
+function keeperLogPath(sessionsDir: string, sessionId: string): string {
+  return path.join(sessionsDir, `keeper-${sessionId}.log`);
+}
+
+// ── Public types ─────────────────────────────────────────────────────────────
+
+export interface KeeperSpawnResult {
+  success: boolean;
+  /** Keeper process PID. NOT pi's PID (pi PID is linked later via token correlation). */
+  pid?: number;
+  /** Absolute path to the UDS / named pipe the keeper listens on. */
+  sockPath?: string;
+  /** Underlying child process handle. */
+  process?: ChildProcess;
+  /** Error message when `success: false`. */
+  error?: string;
+}
+
+export interface KeeperEntry {
+  sessionId: string;
+  keeperPid: number;
+  sockPath: string;
+}
+
+export interface KeeperManager {
+  /** Spawn a keeper for `sessionId`. Resolves once the keeper has a PID. */
+  spawnKeeperFor(
+    sessionId: string,
+    cwd: string,
+    env: NodeJS.ProcessEnv,
+    piArgs?: string[],
+  ): Promise<KeeperSpawnResult>;
+  /** Connect to keeper UDS, write `line + \n`, close. Never throws. */
+  writeRpc(sessionId: string, line: string): Promise<boolean>;
+  /**
+   * Connect to an arbitrary UDS / named-pipe path, write `line + \n`, close.
+   * Used by `headless-pid-registry.writeRpc` so the registry can delegate
+   * line-write semantics (3-attempt retry with backoffs, never throws)
+   * without re-implementing the connect logic. Returns false on all-attempts-failed.
+   * See change: add-rpc-stdin-dispatch-with-keeper-sidecar (Phase 6).
+   */
+  writeRpcToSockPath(sockPath: string, line: string): Promise<boolean>;
+  /** SIGTERM the keeper PID for `sessionId` (via process-group on Unix). */
+  killKeeper(sessionId: string): boolean;
+  /** Scan sessions dir; return live keeper+pi pairs; unlink stale entries. */
+  discoverExistingKeepers(): Promise<KeeperEntry[]>;
+  /** For tests / introspection. */
+  readonly sessionsDir: string;
+}
+
+// ── Dependency-injection options ─────────────────────────────────────────────
+
+export interface KeeperManagerOptions {
+  /** Override the sessions dir (default `~/.pi/dashboard/sessions`). */
+  sessionsDir?: string;
+  /** Override the absolute path to `keeper.cjs`. */
+  keeperPath?: string;
+  /** Override the node binary used to invoke the keeper (default `process.execPath`). */
+  nodeBinary?: string;
+  /**
+   * Callback used by `discoverExistingKeepers` to verify the corresponding
+   * pi process is alive (the keeper-pid liveness is checked internally).
+   * Default: always returns true — caller MUST inject a real probe (typically
+   * wired to `headlessPidRegistry`) when using `discoverExistingKeepers` for
+   * orphan reconciliation.
+   */
+  isPiAliveForSession?: (sessionId: string, keeperPid: number) => boolean;
+  /**
+   * Override the OS for path-convention computation. Default: `process.platform`.
+   * Only affects socket / pid-sidecar path shape; spawn dispatch is handled
+   * inside `spawnDetached` already.
+   */
+  platform?: NodeJS.Platform;
+  /** Test seam — override `spawnDetached`. */
+  spawnDetached?: (opts: SpawnDetachedOptions) => Promise<SpawnDetachedResult>;
+  /** Test seam — override `net.createConnection`. */
+  createConnection?: typeof net.createConnection;
+}
+
+// ── Implementation ───────────────────────────────────────────────────────────
+
+/** Per-attempt connect timeout for `writeRpc`. */
+const WRITE_RPC_ATTEMPT_TIMEOUT_MS = 350;
+/** Backoffs before retry attempts 2 and 3. Task 4.3. */
+const WRITE_RPC_RETRY_DELAYS_MS = [50, 150];
+/** Total attempts including the initial one. */
+const WRITE_RPC_MAX_ATTEMPTS = 3;
+
+export function createKeeperManager(opts: KeeperManagerOptions = {}): KeeperManager {
+  const sessionsDir = opts.sessionsDir ?? defaultSessionsDir();
+  const keeperPath = opts.keeperPath ?? defaultKeeperPath();
+  const nodeBinary = opts.nodeBinary ?? process.execPath;
+  const platform = opts.platform ?? process.platform;
+  const isPiAlive = opts.isPiAliveForSession ?? (() => true);
+  const spawnDetached = opts.spawnDetached ?? defaultSpawnDetached;
+  const createConnection = opts.createConnection ?? net.createConnection;
+
+  // sessionId → keeperPid for fast killKeeper without rescanning the dir.
+  // (Discovery rebuilds this from the filesystem on startup.)
+  const tracked = new Map<string, number>();
+
+  function ensureSessionsDir(): void {
+    try { mkdirSync(sessionsDir, { recursive: true }); } catch { /* mkdir failure surfaced by keeper itself */ }
+  }
+
+  async function spawnKeeperFor(
+    sessionId: string,
+    cwd: string,
+    env: NodeJS.ProcessEnv,
+    piArgs?: string[],
+  ): Promise<KeeperSpawnResult> {
+    if (!sessionId || typeof sessionId !== "string") {
+      return { success: false, error: "sessionId required" };
+    }
+    if (!existsSync(keeperPath)) {
+      return { success: false, error: `keeper.cjs not found at ${keeperPath}` };
+    }
+    ensureSessionsDir();
+
+    // Per-spawn log for the parent-side stdio capture. The keeper itself
+    // writes its primary log to `keeper-<sid>.log`; this captures any
+    // bootstrap stderr (e.g. keeper failed to open its own log).
+    const launchLogPath = path.join(sessionsDir, `keeper-launch-${sessionId}.log`);
+    let logFd: number | undefined;
+    try { logFd = openSync(launchLogPath, "a"); } catch { logFd = undefined; }
+
+    // Forward pi argv to the keeper via env var (avoids shell-quoting
+    // pitfalls of stuffing them into argv). Keeper reads PI_KEEPER_PI_ARGS
+    // and strips it from pi's env before spawning pi. Defaults to bare RPC
+    // when piArgs is omitted, preserving simple test/direct-invocation use.
+    const keeperEnv: NodeJS.ProcessEnv = piArgs && piArgs.length > 0
+      ? { ...env, PI_KEEPER_PI_ARGS: JSON.stringify(piArgs) }
+      : env;
+
+    // Delegate to the shared cross-platform primitive so libuv-correct
+    // defaults (detached: true on POSIX, Job-Object exclusion + windowsHide
+    // on win32) are uniform.
+    const r = await spawnDetached({
+      cmd: nodeBinary,
+      args: [keeperPath, sessionId],
+      cwd,
+      env: keeperEnv,
+      logFd,
+      stdinMode: "ignore",
+      detach: true,
+    });
+
+    if (!r.ok || typeof r.pid !== "number") {
+      return { success: false, error: r.error ?? "spawn returned no pid" };
+    }
+
+    // Detach: let the keeper continue if this Node process exits.
+    try { r.process?.unref(); } catch { /* ignore */ }
+
+    tracked.set(sessionId, r.pid);
+
+    return {
+      success: true,
+      pid: r.pid,
+      sockPath: sockPathFor(sessionsDir, sessionId, platform),
+      process: r.process,
+    };
+  }
+
+  function tryConnectAndWrite(sockPath: string, line: string, timeoutMs: number): Promise<boolean> {
+    return new Promise((resolve) => {
+      let settled = false;
+      const settle = (ok: boolean): void => {
+        if (settled) return;
+        settled = true;
+        resolve(ok);
+      };
+
+      let sock: net.Socket;
+      try {
+        sock = createConnection(sockPath);
+      } catch {
+        settle(false);
+        return;
+      }
+
+      const timer = setTimeout(() => {
+        try { sock.destroy(); } catch { /* ignore */ }
+        settle(false);
+      }, timeoutMs);
+
+      sock.once("connect", () => {
+        sock.end(line.endsWith("\n") ? line : line + "\n", "utf8", () => {
+          clearTimeout(timer);
+          settle(true);
+        });
+      });
+      sock.once("error", () => {
+        clearTimeout(timer);
+        settle(false);
+      });
+    });
+  }
+
+  async function writeRpcToSockPath(sockPath: string, line: string): Promise<boolean> {
+    for (let attempt = 0; attempt < WRITE_RPC_MAX_ATTEMPTS; attempt++) {
+      if (attempt > 0) {
+        await new Promise((r) => setTimeout(r, WRITE_RPC_RETRY_DELAYS_MS[attempt - 1]));
+      }
+      const ok = await tryConnectAndWrite(sockPath, line, WRITE_RPC_ATTEMPT_TIMEOUT_MS).catch(() => false);
+      if (ok) return true;
+    }
+    return false;
+  }
+
+  async function writeRpc(sessionId: string, line: string): Promise<boolean> {
+    const sockPath = sockPathFor(sessionsDir, sessionId, platform);
+    return writeRpcToSockPath(sockPath, line);
+  }
+
+  function killKeeper(sessionId: string): boolean {
+    const pid = tracked.get(sessionId);
+    if (typeof pid !== "number") return false;
+    try {
+      killPidWithGroup(pid, "SIGTERM");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function readPidSidecar(p: string): number | null {
+    try {
+      const raw = readFileSync(p, "utf8").trim();
+      const n = Number.parseInt(raw, 10);
+      return Number.isFinite(n) && n > 0 ? n : null;
+    } catch {
+      return null;
+    }
+  }
+
+  function unlinkQuiet(p: string): void {
+    try { unlinkSync(p); } catch { /* ignore */ }
+  }
+
+  async function discoverExistingKeepers(): Promise<KeeperEntry[]> {
+    if (!existsSync(sessionsDir)) return [];
+    let names: string[];
+    try { names = readdirSync(sessionsDir); } catch { return []; }
+
+    const result: KeeperEntry[] = [];
+    // The PID sidecar is the source of truth (Windows named pipes have no
+    // filesystem entry to scan). On Unix the .pid sidecar lives alongside
+    // the .sock; on Windows it's named `pi-rpc-<sid>.pid`.
+    const isWin = platform === "win32";
+    for (const name of names) {
+      let sessionId: string | null = null;
+      if (isWin) {
+        const m = name.match(/^pi-rpc-(.+)\.pid$/);
+        if (m) sessionId = m[1];
+      } else {
+        const m = name.match(/^(.+)\.rpc\.sock\.pid$/);
+        if (m) sessionId = m[1];
+      }
+      if (!sessionId) continue;
+
+      const pidFile = path.join(sessionsDir, name);
+      const sockPath = sockPathFor(sessionsDir, sessionId, platform);
+      const keeperPid = readPidSidecar(pidFile);
+
+      if (!keeperPid || !isProcessAlive(keeperPid)) {
+        // Stale keeper sidecar: clean it up. Best-effort socket unlink too.
+        unlinkQuiet(pidFile);
+        if (!isWin) unlinkQuiet(sockPath);
+        continue;
+      }
+
+      if (!isPiAlive(sessionId, keeperPid)) {
+        // Keeper alive but pi dead → kill keeper, clean up.
+        try { killPidWithGroup(keeperPid, "SIGTERM"); } catch { /* ignore */ }
+        unlinkQuiet(pidFile);
+        if (!isWin) unlinkQuiet(sockPath);
+        continue;
+      }
+
+      tracked.set(sessionId, keeperPid);
+      result.push({ sessionId, keeperPid, sockPath });
+    }
+    return result;
+  }
+
+  return {
+    spawnKeeperFor,
+    writeRpc,
+    writeRpcToSockPath,
+    killKeeper,
+    discoverExistingKeepers,
+    sessionsDir,
+  };
+}

package/packages/server/src/rpc-keeper/keeper.cjs

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+/**
+ * RPC keeper sidecar.
+ *
+ * Spawned by the dashboard server as `node keeper.cjs <sessionId>`.
+ * Owns pi's stdin pipe; forwards JSON-line writes received on a per-session
+ * UDS / named pipe to pi's stdin verbatim. Outlives the dashboard server.
+ *
+ * CommonJS-pure: only Node built-ins. No jiti / tsx / typescript loader.
+ * Mirrors the constraint pattern of `preload-fastify.cjs`.
+ *
+ * See: openspec/changes/add-rpc-stdin-dispatch-with-keeper-sidecar
+ *   - specs/rpc-keeper-sidecar/spec.md
+ *   - design.md (Decisions 1, 2, 3, 8, 9)
+ */
+
+"use strict";
+
+const child_process = require("child_process");
+const fs = require("fs");
+const net = require("net");
+const os = require("os");
+const path = require("path");
+
+// ---------------------------------------------------------------------------
+// Args + paths
+// ---------------------------------------------------------------------------
+
+const sessionId = process.argv[2];
+if (!sessionId || typeof sessionId !== "string") {
+  // Cannot open the keeper log without a sessionId. Write to stderr (which the
+  // KeeperManager wires to the spawn log) and exit non-zero.
+  process.stderr.write("[keeper] FATAL: missing sessionId argv[2]\n");
+  process.exit(2);
+}
+
+const SESSIONS_DIR = path.join(os.homedir(), ".pi", "dashboard", "sessions");
+try {
+  fs.mkdirSync(SESSIONS_DIR, { recursive: true });
+} catch (_e) { /* ignore — fs.openSync below will fail with a clearer error */ }
+
+// Socket / pipe path conventions per spec (Decision 3 in design.md)
+const isWindows = process.platform === "win32";
+const sockPath = isWindows
+  ? `\\\\.\\pipe\\pi-rpc-${sessionId}`
+  : path.join(SESSIONS_DIR, `${sessionId}.rpc.sock`);
+
+// PID sidecar conventions per rpc-keeper-sidecar Requirement
+const pidPath = isWindows
+  ? path.join(SESSIONS_DIR, `pi-rpc-${sessionId}.pid`)
+  : `${sockPath}.pid`;
+
+const logPath = path.join(SESSIONS_DIR, `keeper-${sessionId}.log`);
+
+// ---------------------------------------------------------------------------
+// Logger
+// ---------------------------------------------------------------------------
+
+let logFd;
+try {
+  logFd = fs.openSync(logPath, "a");
+} catch (e) {
+  process.stderr.write(`[keeper ${sessionId}] FATAL: cannot open log ${logPath}: ${e && e.message}\n`);
+  process.exit(2);
+}
+
+function log(line) {
+  try {
+    fs.writeSync(logFd, `[${new Date().toISOString()}] ${line}\n`);
+  } catch (_e) { /* swallow — log failure should not crash the keeper */ }
+}
+
+log(`keeper starting: sessionId=${sessionId} pid=${process.pid} sockPath=${sockPath}`);
+
+// ---------------------------------------------------------------------------
+// Shutdown coordination
+// ---------------------------------------------------------------------------
+
+let shuttingDown = false;
+let server; // net.Server
+let piChild; // child_process.ChildProcess
+
+function unlinkQuiet(p) {
+  try { fs.unlinkSync(p); } catch (_e) { /* ignore */ }
+}
+
+function shutdown(exitCode, reason) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  log(`shutdown: code=${exitCode} reason=${reason || "n/a"}`);
+
+  // Close the server first so no new connections come in.
+  try { if (server) server.close(); } catch (_e) { /* ignore */ }
+
+  // Best-effort cleanup. On Windows named pipes the socket file itself is
+  // virtual and need not be unlinked; on Unix we unlink the socket file.
+  if (!isWindows) unlinkQuiet(sockPath);
+  unlinkQuiet(pidPath);
+
+  // Don't wait on logFd close — process.exit will tear down fds.
+  process.exit(exitCode);
+}
+
+process.on("SIGTERM", () => shutdown(0, "SIGTERM"));
+process.on("SIGINT", () => shutdown(0, "SIGINT"));
+process.on("uncaughtException", (e) => {
+  log(`uncaughtException: ${e && e.stack ? e.stack : e}`);
+  shutdown(1, "uncaughtException");
+});
+
+// ---------------------------------------------------------------------------
+// Bind socket BEFORE spawning pi (Decision 4 / Failure-modes Requirement)
+// ---------------------------------------------------------------------------
+
+function startServer(retried) {
+  return new Promise((resolve) => {
+    const s = net.createServer(handleConnection);
+
+    s.once("error", (err) => {
+      // EADDRINUSE (Unix) / EADDRINUSE-like on Windows pipes: stale socket file
+      // from a previous keeper that crashed without cleanup. Per spec: unlink
+      // and retry exactly once.
+      if (!retried && err && (err.code === "EADDRINUSE" || err.code === "EACCES")) {
+        log(`bind failed (${err.code}); unlinking stale path and retrying once`);
+        if (!isWindows) unlinkQuiet(sockPath);
+        // small backoff before retry
+        setTimeout(() => {
+          startServer(true).then(resolve);
+        }, 50);
+        return;
+      }
+      log(`FATAL: bind failed (retried=${retried}): ${err && err.message}`);
+      shutdown(2, "bind-failed");
+      resolve(null);
+    });
+
+    s.listen(sockPath, () => {
+      log(`socket bound: ${sockPath}`);
+      // Set restrictive permissions on Unix UDS file (Windows pipes use ACLs).
+      if (!isWindows) {
+        try { fs.chmodSync(sockPath, 0o600); } catch (_e) { /* best-effort */ }
+      }
+      resolve(s);
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Connection handler — JSON-lines, fire-and-forget, dumb wire
+// ---------------------------------------------------------------------------
+
+function handleConnection(sock) {
+  log(`connection accepted`);
+  let buf = "";
+
+  sock.setEncoding("utf8");
+  sock.on("data", (chunk) => {
+    buf += chunk;
+    // Split on \n; keep the trailing partial in buf.
+    let nl;
+    // eslint-disable-next-line no-cond-assign
+    while ((nl = buf.indexOf("\n")) !== -1) {
+      const line = buf.slice(0, nl);
+      buf = buf.slice(nl + 1);
+      forwardLine(line);
+    }
+  });
+  sock.on("end", () => {
+    // Flush a trailing line without newline as a complete line. Pi's RPC
+    // reader expects newline-framed lines, so we must append \n anyway.
+    if (buf.length > 0) {
+      forwardLine(buf);
+      buf = "";
+    }
+    log(`connection ended`);
+  });
+  sock.on("error", (err) => {
+    log(`connection error: ${err && err.message}`);
+  });
+}
+
+function forwardLine(line) {
+  // No JSON parsing or content validation — keeper is a dumb wire.
+  if (!piChild || !piChild.stdin || piChild.stdin.destroyed) {
+    log(`drop line (pi stdin unavailable): ${line.slice(0, 80)}`);
+    return;
+  }
+  try {
+    piChild.stdin.write(line + "\n");
+  } catch (e) {
+    // pi.stdin EPIPE etc. Logged, but the actual EPIPE handler below will
+    // trigger shutdown via pi.stdin.on("error", ...) on the next event-loop tick.
+    log(`forwardLine error: ${e && e.message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pi spawn + lifecycle
+// ---------------------------------------------------------------------------
+
+const CRASH_WINDOW_MS = 300;
+let piSpawnedAt = 0;
+
+function readPiArgs() {
+  // PI_KEEPER_PI_ARGS is a JSON-encoded string array of pi argv tokens.
+  // Set by KeeperManager to forward the dashboard's per-spawn flags
+  // (--session-file, --mode continue, --fork, etc.) so resume / fork
+  // round-trip correctly through the keeper. Default falls back to
+  // bare RPC mode for direct invocations and tests.
+  const raw = process.env.PI_KEEPER_PI_ARGS;
+  if (!raw) return ["--mode", "rpc"];
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed) && parsed.every((s) => typeof s === "string")) {
+      return parsed;
+    }
+    log(`WARN: PI_KEEPER_PI_ARGS not a string[]; falling back to default`);
+  } catch (e) {
+    log(`WARN: PI_KEEPER_PI_ARGS parse failed (${e && e.message}); falling back to default`);
+  }
+  return ["--mode", "rpc"];
+}
+
+function spawnPi() {
+  const piArgs = readPiArgs();
+  log(`spawning pi ${piArgs.join(" ")}`);
+  // env is inherited from process.env (KeeperManager already set up the
+  // proper PATH and PI_DASHBOARD_SPAWNED). Defensively set the flag again
+  // here in case the keeper is invoked manually. Strip the keeper-internal
+  // PI_KEEPER_PI_ARGS so it doesn't leak into pi's env.
+  const env = Object.assign({}, process.env, { PI_DASHBOARD_SPAWNED: "1" });
+  delete env.PI_KEEPER_PI_ARGS;
+
+  piSpawnedAt = Date.now();
+  const c = child_process.spawn("pi", piArgs, {
+    stdio: ["pipe", logFd, logFd],
+    env,
+    cwd: process.cwd(),
+    windowsHide: true,
+  });
+
+  c.on("error", (err) => {
+    log(`pi spawn error: ${err && err.message}`);
+    shutdown(1, "pi-spawn-error");
+  });
+
+  c.on("exit", (code, signal) => {
+    const elapsed = Date.now() - piSpawnedAt;
+    log(`pi exited code=${code} signal=${signal} elapsed=${elapsed}ms`);
+    // If pi exited within the crash-detection window, surface a non-zero
+    // exit code so the parent (KeeperManager / process-manager) can preserve
+    // the existing dashboard PI_CRASHED semantic. Otherwise a graceful pi
+    // exit → keeper exit 0.
+    if (elapsed < CRASH_WINDOW_MS) {
+      shutdown(1, "pi-crashed-early");
+    } else {
+      shutdown(0, "pi-exit");
+    }
+  });
+
+  // Detect EPIPE / closed-stream errors on pi.stdin: per spec, treat as same
+  // as pi.exit (the pipe is gone; pi will follow shortly if not already).
+  if (c.stdin) {
+    c.stdin.on("error", (err) => {
+      log(`pi.stdin error: ${err && err.code}/${err && err.message}`);
+      // EPIPE is the canonical case; treat any stdin error as terminal.
+      shutdown(0, "pi-stdin-error");
+    });
+  }
+
+  return c;
+}
+
+// ---------------------------------------------------------------------------
+// Startup orchestration
+// ---------------------------------------------------------------------------
+
+async function main() {
+  // 1. Bind socket FIRST so the server can start retrying immediately.
+  server = await startServer(false);
+  if (!server) return; // shutdown already triggered
+
+  // 2. Write PID sidecar.
+  try {
+    fs.writeFileSync(pidPath, String(process.pid), "utf8");
+  } catch (e) {
+    log(`FATAL: cannot write PID sidecar ${pidPath}: ${e && e.message}`);
+    shutdown(2, "pid-sidecar-write");
+    return;
+  }
+
+  // 3. Spawn pi.
+  piChild = spawnPi();
+
+  // 4. Crash-detection window: emit the "keeper ready" marker once pi has
+  // survived the crash window. The crash-on-early-exit decision itself is
+  // made by the c.on("exit") handler comparing elapsed vs CRASH_WINDOW_MS
+  // — unifying the two paths so the early-exit code wins regardless of
+  // which fires first.
+  setTimeout(() => {
+    if (shuttingDown) return;
+    if (piChild && piChild.exitCode === null && piChild.signalCode === null) {
+      log(`keeper ready: ${sessionId}`);
+    }
+    // If pi already exited, c.on("exit") has already (or will imminently)
+    // call shutdown(1) via the elapsed-time check.
+  }, CRASH_WINDOW_MS);
+}
+
+main().catch((e) => {
+  log(`FATAL main: ${e && e.stack ? e.stack : e}`);
+  shutdown(2, "main-rejected");
+});