@codeyam-editor/codeyam-editor 0.1.3 → 0.1.5

package/npm/utils.js

@@ -2,6 +2,7 @@ const { execSync, spawn, spawnSync } = require("child_process");
 const net = require("net");
 const path = require("path");
 const fs = require("fs");
+const readline = require("readline");
 
 const rootDir = path.resolve(__dirname, "..");
 const serverStatePath = path.join(rootDir, ".codeyam", "server-state.json");
@@ -276,6 +277,25 @@ function enforceFreshBinary(buildOk, { action, continueVerb = "continuing with"
   );
 }
 
+// Default boot budget for the editor server. A real cold boot legitimately
+// spends ~7–10s on plan-claims git migration + reap, a PTY-broker probe/respawn
+// (worse when a stale orphan broker's socket is dead), and a branch-tip fetch.
+// 30s is ~3× that — comfortable headroom without letting a genuinely hung
+// server hang indefinitely.
+const DEFAULT_START_TIMEOUT_MS = 30000;
+
+/**
+ * Resolve the boot budget (ms) for `ensureServer`, honoring the
+ * `CODEYAM_EDITOR_START_TIMEOUT_MS` override. Mirrors the existing env-read
+ * style (`CODEYAM_ALLOW_STALE`): parse the raw value, accept only a positive
+ * integer, and fall back to the 30s default on missing/non-numeric/≤0 input.
+ * Exported so it's unit-testable without spawning the real binary.
+ */
+function resolveStartTimeoutMs(env = process.env) {
+  const parsed = Number.parseInt(env.CODEYAM_EDITOR_START_TIMEOUT_MS, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_START_TIMEOUT_MS;
+}
+
 function isPlainJsonObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -491,9 +511,14 @@ async function requestServerShutdown(port = 14199, timeoutMs = 1500) {
 
 /**
  * GET /api/codeyam-server-identity from the listener on `port` with a
- * sub-second timeout. Returns the parsed `{projectDir, pid, version,
- * startedAt}` body on a 2xx response, or `null` on any failure
- * (timeout, non-200, parse failure, connection refused).
+ * sub-second timeout. Returns the parsed identity body on a 2xx response,
+ * or `null` on any failure (timeout, non-200, parse failure, connection
+ * refused). Two identity shapes are recognized:
+ *   - a per-project editor: `{projectDir, pid, version, startedAt}`
+ *   - the Project Launcher (selector): `{role: "launcher", pid, version}`
+ *     — deliberately NO `projectDir`, since the selector isn't bound to one
+ *     project. We must NOT reject it for the missing `projectDir`, or the
+ *     wrapper would misclassify the live selector as a foreign squatter.
  *
  * `null` carries two distinct meanings that the caller must
  * disambiguate by also checking `isPortInUse`:
@@ -513,9 +538,10 @@ async function fetchServerIdentity(port, timeoutMs = 500) {
     });
     if (!resp.ok) return null;
     const body = await resp.json();
-    if (!body || typeof body !== "object" || typeof body.projectDir !== "string") {
-      return null;
-    }
+    if (!body || typeof body !== "object") return null;
+    // The Project Launcher advertises a `launcher` role and no projectDir.
+    if (body.role === "launcher") return body;
+    if (typeof body.projectDir !== "string") return null;
     return body;
   } catch {
     return null;
@@ -572,11 +598,47 @@ function formatCrossProjectError(port, holder, verb) {
   );
 }
 
+/**
+ * Build the "server never bound the port" failure message, shown only after
+ * the boot budget AND one automatic retry have both been exhausted. Pure
+ * string builder (same shape as `formatForeignListenerError` /
+ * `formatCrossProjectError`): names what happened, the likely cause, where to
+ * look, and concrete next steps. Stack-agnostic — no app-type/framework
+ * assumptions.
+ */
+function formatServerStartTimeoutError(port, timeoutMs) {
+  const seconds = Math.round(timeoutMs / 1000);
+  return [
+    `codeyam-editor server did not bind port ${port} within ${seconds}s, ` +
+      `even after one automatic retry.`,
+    "",
+    "Likely cause: a slow cold boot (plan-claims git migration, PTY-broker " +
+      "respawn) — often a stale codeyam-editor-pty-broker whose socket is gone.",
+    "",
+    "Or: with 2+ projects registered this launch diverts to the Project " +
+      "Launcher (selector). An old binary that still discards --port binds the " +
+      "selector on a DIFFERENT ephemeral port, so the wait for this one times " +
+      "out — check .codeyam/logs/editor-server.out.log for a `Project Launcher " +
+      "running at` line and rebuild the editor.",
+    "",
+    "Where to look:",
+    "  .codeyam/logs/editor-server.log",
+    "  .codeyam/logs/editor-server.out.log",
+    "",
+    "What to try:",
+    "  - Re-run the launcher.",
+    "  - If a stale codeyam-editor-pty-broker is lingering, kill it, then re-run.",
+    "  - If boots are consistently slow, raise the budget, e.g. " +
+      "CODEYAM_EDITOR_START_TIMEOUT_MS=60000.",
+  ].join("\n");
+}
+
 /**
  * Classify whatever is listening on `port` relative to `projectDir`.
  * Returns one of:
  *   - `{ kind: "free" }`                    — nothing on the port
  *   - `{ kind: "foreign" }`                 — port held by a non-editor process
+ *   - `{ kind: "launcher", identity }`      — held by the Project Launcher (selector)
  *   - `{ kind: "cross-project", wantDir, haveDir, identity }`
  *                                           — held by another project's editor
  *   - `{ kind: "same-project", identity }`  — held by THIS project's editor
@@ -596,6 +658,12 @@ async function classifyPortHolder(port, projectDir = process.cwd()) {
   if (identity === null) {
     return { kind: "foreign" };
   }
+  // The Project Launcher (selector) holds the port in multi-project mode. It is
+  // codeyam-editor, not a foreign process and not a per-project editor, so it
+  // gets its own kind — the caller just re-opens it rather than refusing.
+  if (identity.role === "launcher") {
+    return { kind: "launcher", identity };
+  }
   const wantDir = await canonicalisePath(projectDir);
   const haveDir = await canonicalisePath(identity.projectDir);
   if (wantDir !== haveDir) {
@@ -620,6 +688,184 @@ function tryKillPid(pid) {
   }
 }
 
+/**
+ * True when the launcher is attached to an interactive terminal — i.e. a human
+ * could have typed Ctrl+C. Headless / agent-driven launchers (cloud containers,
+ * `npm run editor` under a supervisor) have no tty here. Used to decide whether a
+ * received SIGINT is a deliberate "stop the editor" (forward it) or a stray
+ * group / spurious signal that must NOT reap the now-detached server.
+ */
+function isInteractiveLauncher(stream = process.stdout) {
+  return Boolean(stream && stream.isTTY);
+}
+
+/**
+ * Ask a yes/no question at the terminal and resolve `true` only on an
+ * affirmative `y`/`yes` (case-insensitive). A bare Enter, EOF, `n`, or any
+ * other text resolves `false` — the safe default for a destructive prompt.
+ *
+ * Mirrors `promptForInstanceName` in `npm/cloud.js`: readline reads from stdin
+ * and writes its prompt to stderr by default, so the question never pollutes a
+ * piped stdout. `input`/`output` are injectable so the helper is unit-testable
+ * by feeding a fake stream without a real TTY.
+ */
+function promptYesNo(question, { input = process.stdin, output = process.stderr } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input, output });
+    rl.question(question, (ans) => {
+      rl.close();
+      const normalized = String(ans).trim().toLowerCase();
+      resolve(normalized === "y" || normalized === "yes");
+    });
+  });
+}
+
+/**
+ * Decide what to do when `port` is held by a DIFFERENT project's editor server.
+ *
+ * Policy (shared by both launcher entry points so the wording and gating stay
+ * identical):
+ *   - Non-interactive launcher (cloud container, agent-driven, piped/CI): print
+ *     `formatCrossProjectError` and return `{ action: "abort" }` — never kill
+ *     another project's server without a human at the keyboard, since the kill
+ *     also tears down any Claude agent attached via the PTY broker.
+ *   - Interactive launcher: print the full who/what/where, then ask whether to
+ *     stop the other server and take over. On `y` → `stopServer(port)` and
+ *     return `{ action: "took-over" }`. On anything else → `{ action: "declined" }`.
+ *
+ * Gates on `process.stdin.isTTY` (the INPUT stream — a human can only answer a
+ * prompt when stdin is a terminal), not stdout. The resolver prints the full
+ * `formatCrossProjectError` message in BOTH the abort and the interactive paths,
+ * so the caller only decides exit-vs-continue.
+ *
+ * Dependencies are injected (defaulting to the real implementations) so the
+ * resolver is unit-testable without a TTY or a live server — same style as
+ * `classifyPortHolder` / `resolveBootedServer`.
+ */
+async function resolveCrossProjectCollision(
+  port,
+  holder,
+  verb,
+  {
+    isInteractive = isInteractiveLauncher,
+    prompt = promptYesNo,
+    stop = stopServer,
+  } = {},
+) {
+  console.error(formatCrossProjectError(port, holder, verb));
+  if (!isInteractive(process.stdin)) {
+    return { action: "abort" };
+  }
+  const pidNote = Number.isInteger(holder.identity && holder.identity.pid)
+    ? ` (pid ${holder.identity.pid})`
+    : "";
+  const accepted = await prompt(
+    `\nKill that server${pidNote} and start this project's editor instead? [y/N] `,
+  );
+  if (!accepted) {
+    return { action: "declined" };
+  }
+  await stop(port);
+  return { action: "took-over" };
+}
+
+/**
+ * Spawn options for the editor server child. The server is spawned `detached:
+ * true` so it leads its OWN session + process group (setsid), decoupling its
+ * lifetime from the launcher's controlling terminal and process group — a stray
+ * tty Ctrl+C or a group-wide `kill(-pgid, SIGINT)` can no longer reach it. stdio
+ * is detached from the terminal for the same reason (an inherited tty can still
+ * deliver tty signals to a detached child): stdout/stderr go to `logFd` when one
+ * is supplied, else are ignored — the Rust server writes its own
+ * `.codeyam/logs/editor-server.log` regardless.
+ */
+function buildServerSpawnOptions({ cwd, env, logFd = null }) {
+  return {
+    stdio: logFd === null ? "ignore" : ["ignore", logFd, logFd],
+    cwd,
+    detached: true,
+    env,
+  };
+}
+
+/**
+ * Open (creating dirs as needed) the launcher-managed server stdout/stderr log
+ * in append mode and return its fd, or null if it can't be opened. Kept separate
+ * from the Rust server's own structured `editor-server.log` so the two streams
+ * never interleave. Best-effort: a failure here just means the detached server's
+ * stdio is ignored, never that the launch itself fails.
+ */
+function openServerOutputLog(cwd) {
+  try {
+    const dir = path.join(cwd, ".codeyam", "logs");
+    fs.mkdirSync(dir, { recursive: true });
+    return fs.openSync(path.join(dir, "editor-server.out.log"), "a");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format one launcher-teardown-signal record for
+ * `.codeyam/logs/launcher-signals.log`. Pure: every input is passed in, so the
+ * formatting is unit-testable without a real signal or `ps`. Captures the
+ * launcher's own pid/ppid/pgid, whether it was interactive (a tty Ctrl+C) vs
+ * headless (a stray/spurious signal), the decision taken (forwarded teardown vs
+ * kept the server alive), and a best-effort `ps` group snapshot so the SENDER of
+ * a spurious `kill()` can be identified on the next repro.
+ */
+function formatLauncherSignalRecord({ signal, pid, ppid, pgid, interactive, forwarded, ps, timestamp }) {
+  const lines = [
+    `[${timestamp}] launcher-signal signal=${signal} pid=${pid} ppid=${ppid} pgid=${pgid} ` +
+      `interactive=${interactive} action=${forwarded ? "forwarded-teardown" : "ignored-kept-server-alive"}`,
+  ];
+  if (ps && ps.trim() !== "") {
+    lines.push(ps.trimEnd());
+  }
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Append a launcher-teardown-signal forensic record. Called from each launcher's
+ * SIGINT handler BEFORE it decides whether to forward, so a server reaped by a
+ * stray group SIGINT (or a spurious `kill()` to a headless launcher) always
+ * leaves a trail naming the launcher's process group. Best-effort: never throws,
+ * so a logging failure can never block the teardown decision.
+ */
+function logLauncherTeardownSignal(signal, projectDir, { interactive, forwarded }) {
+  try {
+    const pid = process.pid;
+    const ppid = typeof process.ppid === "number" ? process.ppid : -1;
+    let pgid = -1;
+    let ps = "";
+    if (process.platform !== "win32") {
+      const pgidOut = spawnSync("ps", ["-o", "pgid=", "-p", String(pid)], { encoding: "utf8" });
+      if (!pgidOut.error) {
+        pgid = parseInt(pgidOut.stdout.trim(), 10);
+      }
+      if (Number.isInteger(pgid) && pgid > 0) {
+        const grp = spawnSync("ps", ["-o", "pid,ppid,pgid,tpgid,comm", "-g", String(pgid)], { encoding: "utf8" });
+        if (!grp.error) ps = grp.stdout;
+      }
+    }
+    const dir = path.join(projectDir, ".codeyam", "logs");
+    fs.mkdirSync(dir, { recursive: true });
+    const record = formatLauncherSignalRecord({
+      signal,
+      pid,
+      ppid,
+      pgid,
+      interactive: Boolean(interactive),
+      forwarded: Boolean(forwarded),
+      ps,
+      timestamp: new Date().toISOString(),
+    });
+    fs.appendFileSync(path.join(dir, "launcher-signals.log"), record);
+  } catch {
+    /* best-effort forensics — never block teardown on a logging failure */
+  }
+}
+
 /**
  * Send the platform-correct termination signal to a spawned child process.
  * Used by editor.js / editor-dev.js / container.js when the user hits Ctrl+C —
@@ -634,22 +880,60 @@ function killChildProcess(child) {
   }
 }
 
-function findListeningPids(port) {
-  // Process discovery on Windows is best-effort — `lsof` is not installed and
-  // a `netstat -ano` parser is a follow-up. The API-shutdown path and the
-  // PID-file path together stop the server cleanly in normal operation.
-  if (process.platform === "win32") return [];
+/** Parse `lsof -t` stdout (one pid per line) into an array of integer pids. */
+function parseLsofPids(stdout) {
+  return (stdout || "")
+    .split(/\s+/)
+    .map((line) => parseInt(line, 10))
+    .filter((pid) => Number.isInteger(pid));
+}
 
-  const result = spawnSync("lsof", [`-tiTCP:${port}`, "-sTCP:LISTEN"], {
+/** Run `lsof` for the listeners on a TCP port. Returns the raw spawnSync
+ * result (`{ error?, stdout }`) so callers can distinguish a spawn failure
+ * from a genuinely empty result. */
+function defaultRunLsof(port) {
+  return spawnSync("lsof", [`-tiTCP:${port}`, "-sTCP:LISTEN"], {
     encoding: "utf8",
   });
+}
 
-  if (result.error) return [];
+/** Synchronous millisecond sleep — used to back off between lsof retries. */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 
-  return result.stdout
-    .split(/\s+/)
-    .map((line) => parseInt(line, 10))
-    .filter((pid) => Number.isInteger(pid));
+/**
+ * Find the pids listening on a TCP port via `lsof`. Returns [] on Windows
+ * (lsof absent) or when no process is listening.
+ *
+ * A transient *spawn* failure (e.g. fork `EAGAIN` under heavy concurrent load —
+ * the cause of the flaky multi-runner test failure) is RETRIED with a short
+ * backoff rather than swallowed into "no listeners found". This matters because
+ * `findListeningPids` feeds `stopServer`: a one-off lsof spawn error must not be
+ * mistaken for "the server isn't running" and leave it alive. A clean run that
+ * legitimately reports no listeners returns [] on the first attempt (no error,
+ * so no retry) — free-port behavior and latency are unchanged.
+ *
+ * `runLsof` and `sleep` are injectable so the retry path is unit-testable
+ * without depending on real system load.
+ */
+function findListeningPids(port, runLsof = defaultRunLsof, sleep = sleepSync) {
+  // Process discovery on Windows is best-effort — `lsof` is not installed and
+  // a `netstat -ano` parser is a follow-up. The API-shutdown path and the
+  // PID-file path together stop the server cleanly in normal operation.
+  if (process.platform === "win32") return [];
+
+  const MAX_ATTEMPTS = 5;
+  const BACKOFF_MS = 50;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    const result = runLsof(port);
+    // No spawn error → trust the result (empty stdout legitimately means "no
+    // listeners"; a non-empty stdout yields the pids).
+    if (!result.error) return parseLsofPids(result.stdout);
+    // Transient spawn failure — back off and retry, unless we're out of tries.
+    if (attempt < MAX_ATTEMPTS) sleep(BACKOFF_MS);
+  }
+  return [];
 }
 
 /** Stop the Rust backend server if it is running. */
@@ -711,10 +995,31 @@ async function ensureServer(port = 14199) {
       console.error(formatForeignListenerError(port));
       process.exit(1);
       break;
-    case "cross-project":
-      console.error(formatCrossProjectError(port, holder, "attach"));
+    case "cross-project": {
+      const outcome = await resolveCrossProjectCollision(port, holder, "attach");
+      if (outcome.action === "took-over") {
+        // `stopServer` already waited for the port to close, so fall through to
+        // the fresh-boot path below — `spawnAndAwait` binds the now-free port.
+        break;
+      }
+      // "abort" (non-TTY) or "declined" (user said no): the resolver already
+      // printed the cross-project message. On decline, remind how to keep both.
+      if (outcome.action === "declined") {
+        console.error(
+          "Leaving the existing server running. Change controlPort in " +
+            ".codeyam/editor.local.json to run both, e.g.:\n" +
+            "  codeyam-editor editor config-override proxy.controlPort 14399",
+        );
+      }
       process.exit(1);
       break;
+    }
+    case "launcher":
+      // The selector is already up on this port (multi-project mode). Treat it
+      // like an already-running same-project server: don't refuse, don't
+      // double-spawn — just let the caller re-open the port.
+      console.error(`Project selector already running on port ${port}`);
+      return null;
     case "same-project":
       console.error(`Server already running on port ${port}`);
       return null;
@@ -724,36 +1029,130 @@ async function ensureServer(port = 14199) {
   }
 
   const binary = ensureBinary();
+  const startTimeoutMs = resolveStartTimeoutMs();
+
+  // Spawn a fresh server child and race its boot against `timeoutMs`. Factored
+  // into a closure so the auto-retry path re-runs an identical spawn with a
+  // longer budget without duplicating the spawn options.
+  //
   // UI bundle is embedded in the Rust binary; CODEYAM_EDITOR_UI_DIR is
   // now an explicit dev-override only.
-  const child = spawn(binary, ["start", "--no-open", "--port", String(port)], {
-    stdio: "inherit",
-    cwd: process.cwd(),
-    detached: false,
-    env: process.env,
-  });
-
-  const { outcome, exitedBeforeBind } = await awaitServerReadyOrChildExit(child, port);
-
-  if (outcome === "exited" || (outcome === "timeout" && exitedBeforeBind !== null)) {
-    const { code, signal } = exitedBeforeBind ?? { code: null, signal: null };
-    const detail = signal != null ? `signal ${signal}` : `code ${code}`;
-    console.error(
-      `codeyam-editor server exited (${detail}) before binding port ${port}. ` +
-        "Likely a preflight bail; see output above.",
+  //
+  // The server is spawned into its OWN session/process group (detached: true)
+  // with stdio detached from the launcher's controlling terminal, so a stray
+  // tty Ctrl+C or a group-wide SIGINT can no longer reap it — its lifetime is
+  // governed only by the launcher's deliberate teardown forward and the
+  // pidfile / API-shutdown paths. stdout/stderr are appended to
+  // `.codeyam/logs/editor-server.out.log` (the Rust server also writes its own
+  // editor-server.log). `unref()` keeps the detached child from pinning the
+  // launcher's event loop alive on its own.
+  const spawnAndAwait = async (timeoutMs) => {
+    const logFd = openServerOutputLog(process.cwd());
+    const child = spawn(
+      binary,
+      ["start", "--no-open", "--port", String(port)],
+      buildServerSpawnOptions({ cwd: process.cwd(), env: process.env, logFd }),
+    );
+    if (logFd !== null) {
+      try {
+        fs.closeSync(logFd);
+      } catch {
+        /* child holds its own dup of the fd; the launcher's copy is no longer needed */
+      }
+    }
+    child.unref();
+    const race = await awaitServerReadyOrChildExit(child, port, (p) =>
+      waitForPort(p, timeoutMs),
     );
-    // Always propagate as a real failure — even on code 0 the caller
-    // needs to know the server isn't running.
-    process.exit(code != null && code !== 0 ? code : 1);
+    return { child, ...race };
+  };
+
+  // Orchestrate the boot (re-check-before-kill + one auto-retry) with the real
+  // effects injected, then map the discriminated result onto the process-exit
+  // policy. Keeping the orchestration in `resolveBootedServer` (pure control
+  // flow over injected effects) is what makes the re-check guard and the retry
+  // unit-testable without spawning the real binary or stubbing process.exit.
+  const result = await resolveBootedServer({
+    port,
+    startTimeoutMs,
+    spawnAndAwait,
+    isPortInUseFn: isPortInUse,
+  });
+  switch (result.kind) {
+    case "ready":
+      return result.child;
+    case "early-exit": {
+      // A genuine early exit (preflight bail) is always a hard fail — even on
+      // code 0: the caller needs to know the server isn't running.
+      const { code, signal } = result.exitedBeforeBind ?? { code: null, signal: null };
+      const detail = signal != null ? `signal ${signal}` : `code ${code}`;
+      console.error(
+        `codeyam-editor server exited (${detail}) before binding port ${port}. ` +
+          "Likely a preflight bail; see .codeyam/logs/editor-server.out.log " +
+          "and .codeyam/logs/editor-server.log.",
+      );
+      process.exit(code != null && code !== 0 ? code : 1);
+      break;
+    }
+    case "timeout-exhausted":
+    default:
+      console.error(formatServerStartTimeoutError(port, result.retryTimeoutMs));
+      process.exit(1);
   }
+}
 
-  if (outcome === "timeout") {
-    console.error("Server failed to start within 10 seconds");
-    child.kill();
-    process.exit(1);
-  }
+/**
+ * Boot orchestration for `ensureServer`, isolated from the process-exit policy
+ * and from the spawn/port effects so the re-check-before-kill guard and the
+ * single auto-retry are unit-testable. Pure control flow over two injected
+ * effects:
+ *   - `spawnAndAwait(timeoutMs)` → `{ child, outcome, exitedBeforeBind }` —
+ *     one boot attempt racing the port against the child exit.
+ *   - `isPortInUseFn(port)` → bool — the final re-check probe.
+ *
+ * Returns a discriminated result the caller maps to an action:
+ *   - `{ kind: "ready", child }`                  — server bound; keep this child.
+ *   - `{ kind: "early-exit", exitedBeforeBind }`  — child exited before bind
+ *     (preflight bail); a hard fail, never retried.
+ *   - `{ kind: "timeout-exhausted", retryTimeoutMs }` — both the budget and a
+ *     longer-budget retry missed; give up with actionable guidance.
+ *
+ * The destructive `child.kill()` only fires after a re-check confirms the port
+ * is NOT listening — a server that bound a hair after the deadline is kept, not
+ * torn down (the reported race). The retry runs at most once.
+ */
+async function resolveBootedServer({ port, startTimeoutMs, spawnAndAwait, isPortInUseFn }) {
+  // One boot attempt, with the re-check folded in: a post-deadline bind is
+  // reported as "ready" rather than "timeout" so the caller never kills it.
+  const attempt = async (timeoutMs) => {
+    const { child, outcome, exitedBeforeBind } = await spawnAndAwait(timeoutMs);
+    if (outcome === "ready") return { kind: "ready", child };
+    if (outcome === "exited" || (outcome === "timeout" && exitedBeforeBind !== null)) {
+      return { kind: "early-exit", exitedBeforeBind };
+    }
+    // Genuine timeout — re-check before reporting a miss.
+    if (await isPortInUseFn(port)) return { kind: "ready", child };
+    return { kind: "timeout", child };
+  };
+
+  const first = await attempt(startTimeoutMs);
+  if (first.kind !== "timeout") return first;
+
+  // The boot was just slow (cold caches, broker respawn). Kill the stalled
+  // attempt and auto-retry ONCE with a longer budget — a single retry, not a
+  // loop, so a truly broken server isn't masked behind endless retries.
+  const retryTimeoutMs = startTimeoutMs * 2;
+  console.error(
+    `Server did not bind port ${port} within ${Math.round(startTimeoutMs / 1000)}s; ` +
+      `retrying once with a longer budget...`,
+  );
+  first.child.kill();
+
+  const second = await attempt(retryTimeoutMs);
+  if (second.kind !== "timeout") return second;
 
-  return child;
+  second.child.kill();
+  return { kind: "timeout-exhausted", retryTimeoutMs };
 }
 
 /**
@@ -808,12 +1207,23 @@ module.exports = {
   classifyPortHolder,
   formatForeignListenerError,
   formatCrossProjectError,
+  formatServerStartTimeoutError,
+  resolveStartTimeoutMs,
   tryKillPid,
   findListeningPids,
+  parseLsofPids,
   stopServer,
   restartServer,
   ensureServer,
+  resolveBootedServer,
   awaitServerReadyOrChildExit,
+  isInteractiveLauncher,
+  promptYesNo,
+  resolveCrossProjectCollision,
+  buildServerSpawnOptions,
+  openServerOutputLog,
+  formatLauncherSignalRecord,
+  logLauncherTeardownSignal,
   killChildProcess,
   deepMergeJson,
   stripUnderscoreTopLevelKeys,