ccdeck 3.29.10 → 3.30.0

package/src/server/lifecycle.mjs

@@ -0,0 +1,421 @@
+// How this process is replaced or ended: the version, upgrade, restart and
+// stop routes, the latches that keep two asks from starting two of either, and
+// the away-update that presses Upgrade or Restart by itself while nobody is
+// looking.
+//
+// These lived in src/server/index.mjs — the latches beside startServer, the
+// routes after the SSE stream, the away-update before pushEvent. They share one
+// piece of state, the restart latch, which a press and the away-update both
+// take, and none of them reads the ring, the SSE fan-out or the scanners; so
+// they moved together and the latch stayed private. index.mjs arms them once
+// per boot (armLifecycle, startAwayUpdate), routes to the five handlers, feeds
+// `activity` from pushEvent, and re-exports the launcher's two calls,
+// releaseRestart and markDeckReady. The bodies are unchanged.
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createActivity } from "./activity.mjs";
+import { AWAY_BOOT_GRACE_MS, AWAY_RECHECK_MS, AWAY_TICK_MS, awayGate, awayUpdateStep } from "./auto-update.mjs";
+import { PRODUCT } from "./brand.mjs";
+import { logWritableNow } from "./event-log.mjs";
+import { readBody, send } from "./http-io.mjs";
+import { invokedName, renameNotice } from "./invoked-as.mjs";
+// The build this process runs, loaded before an install can replace it: the
+// Upgrade press and the away-update wait on it, and markDeckReady starts it —
+// see pinned-build.mjs.
+import { pinRunningBuild } from "./pinned-build.mjs";
+import { heldPrefs } from "./prefs-state.mjs";
+import { createPresence } from "./presence.mjs";
+import { presentsDeckToken } from "./request-gates.mjs";
+// The version this process runs, read at boot by a leaf so that the LAN
+// engine's card and /api/version give one answer — see running-version.mjs.
+import { RUNNING_VERSION } from "./running-version.mjs";
+
+// Resolved the way pinned-build.mjs resolves it, from a file in the same
+// directory, so every lazy import below is the URL the pin has already evaluated.
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+// Set from startServer's options. The server cannot restart itself — the
+// process lifecycle belongs to the supervisor in bin/agent-dag.js, which is the
+// only thing that can bring a replacement up on the same port without racing
+// the dying listener. Absent (running the module directly, or under an older
+// launcher), /api/restart answers 501 and the UI hides the control rather than
+// offering a button that does nothing.
+let _onRestart = null;
+// How this process ends itself, handed down by bin/deck.js for the same reason
+// _onRestart is: the server does not own the process lifecycle and must be told
+// how to leave. Absent when nothing handed one down — running the module
+// directly, or an embedder — and /api/shutdown then answers 501 rather than
+// pretending.
+let _onStop = null;
+// A stop is in flight. Two sockets asking at once must not both start one, and
+// the response's 'finish' and 'close' can both fire for the same request.
+let _stopping = false;
+// A restart is in flight. Several browser tabs watching the same deck will each
+// ask; the second ask must not re-enter the shutdown.
+let _restarting = false;
+// Whether the launcher has finished booting — see markDeckReady. False for the
+// whole window between this listener accepting its first connection and
+// bin/deck.js reaching the end of its startup, which is a window /api/restart
+// is reachable in and cannot answer for on its own.
+let _deckReady = false;
+
+/**
+ * What this boot's launcher handed down, and the latches reset for it.
+ *
+ * Lifted out of startServer, which calls it first, once per boot: the restart
+ * and the stop it may hand to, whether a restart would have a log to replay,
+ * and the two in-flight flags and the ready flag, all back to a fresh boot's.
+ */
+function armLifecycle({ onRestart, onStop, persist }) {
+  _onRestart = typeof onRestart === "function" ? onRestart : null;
+  _onStop = typeof onStop === "function" ? onStop : null;
+  _stopping = false;
+  _canRestart = _onRestart != null && persist != null;
+  // A new listener is a new boot, whatever a previous one had got as far as
+  // reporting. Nothing but bin/deck.js ever sets this, and it does so once, at
+  // the end of the startup that begins with this call.
+  _deckReady = false;
+}
+
+// True only when a supervisor is listening AND the event log is being written.
+// Without persistence a restart wipes the canvas irrecoverably — replayLog has
+// no file to read — so the deck must not offer to do it. Whether the log is
+// being written is event-log.mjs's to answer; see logWritableNow.
+let _canRestart = false;
+
+/**
+ * Can this deck be restarted without losing the canvas?
+ *
+ * Asked at the moment of the press rather than read off a boot-time flag,
+ * because the writable half of it changes while the deck runs, and in both
+ * directions: a drive unmounted or a volume filled mid-session is discovered by
+ * the appender, not by the probe, and so is one that comes back. See
+ * logWritableNow.
+ */
+function canRestartNow() {
+  return _canRestart && logWritableNow();
+}
+
+async function handleVersion(req, res) {
+  const { versionReport } = await import(
+    pathToFileURL(join(PKG_ROOT, "src/server/self-update.mjs")).href
+  );
+  // ?refresh=1 asks npm now rather than reusing the cached answer — what the
+  // version chip does when clicked, for the user who has just published or is
+  // wondering whether the check is working at all.
+  const force = new URL(req.url, "http://localhost").searchParams.get("refresh") === "1";
+  const report = await versionReport({ running: RUNNING_VERSION, pkgRoot: PKG_ROOT, force });
+  // Attached here rather than inside versionReport for the same reason
+  // canRestart is: the report is what this package root says about itself,
+  // while both of these are facts about the process serving it — the command
+  // the user typed lives in this process's environment and argv, not on disk.
+  //
+  // It is deliberately not folded into `name`, which is documented as the
+  // package an upgrade would install and is load-bearing for the update flow.
+  // The two answer different questions and give different answers: `name` is
+  // read off the install on disk and is always known, while this one is the
+  // command that was typed and is silent wherever it cannot be proven — every
+  // Windows global install, and every `npm i -g ccdeck`, whose stub spawns the
+  // deck by absolute path and leaves nothing in argv to read.
+  const invoked = invokedName({ pkgRoot: PKG_ROOT });
+  // The second half of that notice, computed here rather than in the browser.
+  //
+  // The banner needs one more fact than the name: whether typing `ccdeck` is
+  // enough (a global install ships all three commands, so it already is) or
+  // whether the whole answer is `npx ccdeck`. The browser used to derive that
+  // from `upgradeMode`, which reads like the same question and is not — it
+  // answers "may this copy install over itself", and `AGENTS_DECK_NO_INSTALL=1`
+  // makes it null for EVERY shape including npx, because upgradeBlockedReason
+  // tests the opt-out before it tests npx. So an npx user who opted out of
+  // installs was told the global-install line and sent to a command that does
+  // not exist on their machine, while the terminal row two feet away said
+  // `npx ccdeck` — one fact, two surfaces, opposite answers (#363).
+  //
+  // renameNotice is where that fact is decided for the terminal, so it decides
+  // it here too and the browser renders the string rather than a branch. No
+  // `dash` argument on purpose: the glyph tier is a terminal concern, and the
+  // default em dash is what a browser should get.
+  const rename = renameNotice({ invoked, pkgRoot: PKG_ROOT });
+  send(res, 200, {
+    ...report, canRestart: canRestartNow(), invokedAs: invoked, renameFix: rename?.fix ?? null,
+  });
+}
+
+// Runs `npm i -g <this deck>@latest`, and only that: the argument vector is
+// fixed inside npm-upgrade.mjs — including which of the three published names
+// it installs, which comes from the layout npm built rather than from the
+// request. Answers immediately — progress is read back from /api/version.
+async function handleUpgrade(_req, res) {
+  const { startUpgrade } = await import(
+    pathToFileURL(join(PKG_ROOT, "src/server/self-update.mjs")).href
+  );
+  // Every module this process will ever load, loaded BEFORE npm starts
+  // rewriting the tree they come from — see pinned-build.mjs. On a deck that
+  // has finished booting this settled long ago; it only waits for a press that
+  // lands in the first moments of a boot, or on a server nothing marked ready.
+  await pinRunningBuild();
+  const out = startUpgrade({ pkgRoot: PKG_ROOT });
+  send(res, out.ok ? 200 : 409, out);
+}
+
+// Restart is a two-party act: this half answers before it stops listening, so
+// the caller learns it was accepted rather than losing the socket mid-reply.
+//
+// `{ upgrade: true }` asks for the npx variant: come back through
+// `npx -y <spec>@latest` instead of re-running the files already here. Granted
+// only where that is genuinely how this copy updates — the mode is decided from
+// the install on disk, never from the request.
+async function handleRestart(req, res) {
+  if (!_onRestart) return send(res, 501, { ok: false, reason: "unsupervised" });
+  // Enforced here and not only in the UI. Under --no-persist a restart destroys
+  // the whole canvas — replayLog has no file to read — and a destructive act
+  // must not be prevented by a hidden button alone.
+  if (!_canRestart) return send(res, 409, { ok: false, reason: "no_persist" });
+  // A configured log that cannot be written is the same destruction by another
+  // route, and it deserves its own word: "no_persist" would tell a user who
+  // passed `--history` that they had not, which is the sort of answer that
+  // sends someone looking in the wrong place. See canRestartNow.
+  if (!canRestartNow()) return send(res, 409, { ok: false, reason: "log_unwritable" });
+
+  let wantUpgrade = false;
+  if (req.method === "POST") {
+    const body = await readBody(req, res).catch(() => null);
+    try { wantUpgrade = JSON.parse(body ?? "")?.upgrade === true; } catch { /* a plain restart */ }
+  }
+  let mode = null;
+  if (wantUpgrade) {
+    const { upgradeBlock, upgradeMode, npxRestartSpec } = await import(
+      pathToFileURL(join(PKG_ROOT, "src/server/self-update.mjs")).href
+    );
+    if (upgradeMode(upgradeBlock(PKG_ROOT)) !== "npx" || !npxRestartSpec(PKG_ROOT)) {
+      return send(res, 409, { ok: false, reason: "not_npx" });
+    }
+    mode = "npx";
+  }
+
+  if (_restarting) return send(res, 202, { ok: true, already: true });
+  _restarting = true;
+  // Accepted either way — the ask is good and the launcher holds on to it — but
+  // the two are not the same event and answering 200 to both would be this
+  // window's second untruth rather than its first. Between this listener
+  // accepting its first connection and bin/deck.js finishing the rest of its
+  // startup there is a real stretch during which a restart cannot be run yet,
+  // and a caller that reads the body should be able to tell that it is waiting
+  // on a boot rather than on a supervisor. See markDeckReady, and requestRestart
+  // in bin/deck.js for the half that does the waiting.
+  if (_deckReady) send(res, 200, { ok: true, mode });
+  else send(res, 202, { ok: true, mode, booting: true, detail: "the deck is still starting up; the restart runs as soon as it has finished booting" });
+  // Let the response flush before the listener goes away.
+  handOffRestart(mode);
+}
+
+/**
+ * Hand a restart the latch has already admitted to the launcher — from a press
+ * (handleRestart, once its answer is on its way) or from the away-update
+ * (awayUpdateTick). The delay is the press's: its response has to leave before
+ * the listener does.
+ */
+function handOffRestart(mode) {
+  setTimeout(() => {
+    try { _onRestart(mode); }
+    catch (err) {
+      // This catch is where #448 lived: it released the server's half of the
+      // latch and said nothing, while the launcher's half stayed set with
+      // nothing left to clear it, and every later restart answered "ok" and did
+      // nothing for the rest of the process's life. The launcher now owns its
+      // own failures; this stays as the outer net, and it says so — one line,
+      // message only, because the terminal underneath is repainted every 800ms
+      // by the pulse and a stack dumped into it is a stack nobody can read.
+      _restarting = false;
+      console.error(`${PRODUCT}: restart request failed: ${err?.message ?? err}`);
+    }
+  }, 120).unref();
+}
+
+/** The other end of the latch above, for the upgrade that never happened.
+ *
+ * An npx upgrade is now fetched before anything is torn down, so a fetch that
+ * fails leaves this process serving — with `_restarting` still set from a
+ * restart that is not coming. Nothing would ever clear it: the only path that
+ * did was the process ending. Every later click, from any tab, answered 202
+ * "already restarting" for the rest of the deck's life. */
+export function releaseRestart() {
+  _restarting = false;
+}
+
+/** The launcher saying its boot is over: everything a shutdown would have to
+ *  tear down now exists.
+ *
+ *  This server starts accepting from inside startServer, before that call has
+ *  even returned to bin/deck.js — so /api/restart is answerable for the whole
+ *  of the startup that follows it, which on a cold boot includes the discovery
+ *  file's first fsynced write and spawning the browser. The listener cannot see
+ *  any of that from here; it has to be told. Called once, from bin/deck.js.
+ *
+ *  Only /api/restart reads it, and only to answer honestly. Nothing is refused
+ *  on the strength of it: the restart is still handed to the launcher, which
+ *  holds it until it can run it (#448).
+ *
+ *  IT IS ALSO WHERE THE BUILD IS PINNED (#1042) — see pinned-build.mjs. After
+ *  the boot, so the laziness still keeps that work off the path to the socket;
+ *  and before anything can replace the tree, because `npm i -g` typed in a
+ *  terminal rewrites it exactly as startUpgrade's does, and the drift path then
+ *  leaves this process serving until an idle moment just the same. The promise
+ *  is handed back for the test that has to know when the pin has landed;
+ *  bin/deck.js has no reason to wait for it, and it never rejects. */
+export function markDeckReady() {
+  _deckReady = true;
+  return pinRunningBuild();
+}
+
+/**
+ * POST /api/shutdown — end this deck, from `ccdeck --stop`.
+ *
+ * THE TOKEN AND NOTHING ELSE. Every other mutating route accepts either the
+ * token or the deck's own page (isAuthorizedMutation), and this one must not:
+ * there is no button for it, so a page asking to end the deck is a page doing
+ * something no part of this product asks it to do. Refusing the browser half
+ * costs nothing and removes the whole class.
+ *
+ * WHY A ROUTE AND NOT A SIGNAL. Windows has none. `process.kill(pid, "SIGTERM")`
+ * there is TerminateProcess: the deck stops mid-instruction, its discovery file
+ * is left for the next boot to sweep, and its LAN beacon never says goodbye — so
+ * every paired colleague watches it time out instead of seeing it leave. One
+ * loopback POST behaves identically on all three platforms and ends in the
+ * deck's own shutdown(), which closes the listener, unlinks the registration and
+ * stops the beacon. The pid ladder still exists in `--stop`, as the fallback for
+ * a deck too wedged to answer this.
+ *
+ * ANSWERED BEFORE ANYTHING IS TORN DOWN. shutdown() calls
+ * server.closeAllConnections(), which would cut this very socket — so the
+ * teardown is hung off the response having left rather than run beside it, and
+ * the caller gets a 200 instead of a dropped connection it has to interpret.
+ */
+async function handleStop(req, res) {
+  if (!presentsDeckToken(req?.headers ?? {})) return send(res, 401, { ok: false, reason: "unauthenticated" });
+  if (!_onStop) return send(res, 501, { ok: false, reason: "no_launcher" });
+  if (_stopping) return send(res, 200, { ok: true, pid: process.pid, already: true });
+  _stopping = true;
+  let left = false;
+  const leave = () => {
+    if (left) return;
+    left = true;
+    // A throw here must still end the process: the caller has already been told
+    // this deck is going, and a deck that answered "ok" and stayed up is worse
+    // than one that never answered.
+    try { _onStop(); } catch { process.exit(0); }
+  };
+  // 'finish' is the response handed to the OS; 'close' covers the caller that
+  // hung up before it got there. Either one means nothing is left to flush.
+  res.once("finish", leave);
+  res.once("close", leave);
+  send(res, 200, { ok: true, pid: process.pid });
+}
+
+// The two facts the away-update waits on (awayUpdateTick): whether a turn is
+// running, fed from pushEvent, and whether a tab is being looked at, fed from
+// POST /api/presence. They sat at the top of index.mjs while pushEvent was
+// that file's, because pushEvent can run before the module holding it has
+// finished evaluating; made here, they exist before event-pipeline.mjs's own
+// body runs at all.
+const activity = createActivity();
+const presence = createPresence();
+
+// ── updating while nobody is looking ────────────────────────────────────────
+//
+// auto-update.mjs has the why and the rules; this is the timer and the three
+// effects — install, restart, npx relaunch — each through the code a press
+// uses.
+let _awayTry = null;
+let _awayTimer = null;
+let _bootedAt = Date.now();
+// Until when a report that found nothing newer stands — see AWAY_RECHECK_MS.
+let _awayNothingUntil = 0;
+
+/**
+ * One tick of the away-update. Returns what it did, or null.
+ *
+ * Every clock is the real one: presence and activity are stamped with it, and
+ * the boot grace is AWAY_BOOT_GRACE_MS. This used to be exported and take the
+ * grace as an argument, so a test could drive it without waiting that out; the
+ * tests drive awayGate and awayUpdateStep in auto-update.mjs instead, and the
+ * one caller left is the `_awayTimer` interval.
+ */
+async function awayUpdateTick() {
+  const now = Date.now();
+  if (!awayGate({
+    enabled: heldPrefs.current()?.autoUpdate !== false,
+    supervised: _onRestart != null && _canRestart,
+    restarting: _restarting,
+    sinceBootMs: now - _bootedAt,
+    looking: presence.looking(now),
+    busy: activity.busy(now),
+    quietMs: activity.quietMs(now),
+    graceMs: AWAY_BOOT_GRACE_MS,
+  })) return null;
+  // A standing "nothing newer", unless the clock has moved back past it.
+  if (now < _awayNothingUntil && _awayNothingUntil - now <= AWAY_RECHECK_MS) return null;
+  const su = await import(pathToFileURL(join(PKG_ROOT, "src/server/self-update.mjs")).href);
+  const report = await su.versionReport({ running: RUNNING_VERSION, pkgRoot: PKG_ROOT });
+  if (!report.notice) {
+    _awayNothingUntil = now + AWAY_RECHECK_MS;
+    return null;
+  }
+  const step = awayUpdateStep({
+    notice: report.notice, mode: report.upgradeMode,
+    installing: report.upgrade?.state === "running", lastTry: _awayTry, now,
+  });
+  if (!step.act) return null;
+  // Asked again, because the lookup above can take seconds on a slow line and
+  // somebody may have sat down, or started a turn, in them.
+  const again = Date.now();
+  if (presence.looking(again) || activity.busy(again) || _restarting) return null;
+  _awayTry = { target: step.target, at: again };
+  if (step.act === "install") {
+    // Pinned before npm is spawned, never after it — see pinned-build.mjs. On a
+    // deck bin/deck.js has marked ready this is a promise that settled long ago.
+    await pinRunningBuild();
+    su.startUpgrade({ pkgRoot: PKG_ROOT });
+    return step.act;
+  }
+  // handleRestart's own check for the npx path, for the same reason: the mode
+  // comes from the install on disk, and a spec it cannot name is no relaunch.
+  if (step.act === "npx" && !su.npxRestartSpec(PKG_ROOT)) return null;
+  _restarting = true;
+  handOffRestart(step.act === "npx" ? "npx" : null);
+  return step.act;
+}
+
+/**
+ * The away-update's clock. The boot grace counts from here, and the timer is
+ * unref'd so it never keeps a process alive on its own. It does nothing until
+ * the launcher has handed down a restart — see awayGate's `supervised`.
+ *
+ * Lifted out of startServer, which calls it once per boot; a second boot in the
+ * same process replaces the timer rather than adding one.
+ */
+function startAwayUpdate() {
+  _bootedAt = Date.now();
+  clearInterval(_awayTimer);
+  _awayTimer = setInterval(() => { awayUpdateTick().catch(() => {}); }, AWAY_TICK_MS);
+  _awayTimer.unref?.();
+}
+
+/** POST {tab, looking} — a tab saying whether it is being looked at. See
+ *  presence.mjs, and src/web/presence.ts for the sender. */
+async function handlePresence(req, res) {
+  const raw = await readBody(req, res).catch(() => null);
+  let body = null;
+  try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
+  if (!body || typeof body !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
+  const ok = presence.report(body.tab, body.looking === true, Date.now());
+  return send(res, ok ? 200 : 400, { ok });
+}
+
+// What index.mjs calls besides the two exported above. Listed rather than
+// marked at each declaration, so the declarations read as they did where they
+// came from.
+export {
+  activity, armLifecycle, handlePresence, handleRestart, handleStop,
+  handleUpgrade, handleVersion, startAwayUpdate,
+};

package/src/server/listen.mjs

@@ -0,0 +1,110 @@
+// Getting a port: the random fallback candidates, one listen attempt, and what
+// to say when an attempt fails.
+//
+// These lived in src/server/index.mjs near startServer, whose listen loop is
+// their only caller, and they ask nothing of the deck — a port range in, a
+// bound server or a worded error out. The loop itself stays in startServer,
+// because what it starts after the bind that takes is the deck's business, and
+// the order of those starts is pinned there. portRetryable, listenHint and
+// listenFailure were exported already, so that every platform's answer can be
+// asserted on any of them.
+
+export function randomPort(min, max) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+// One attempt, leaving the server with no more listeners on it than it started
+// with. `server.listen(port, host, cb)` registers `cb` for a 'listening' event
+// that a failed bind never emits, so the previous shape left one behind per
+// attempt — eleven candidates printed Node's "MaxListenersExceededWarning:
+// 11 listening listeners added to [Server]" into the middle of a boot that was
+// already going wrong. Both sides are removed by whichever fires first.
+export async function tryListen(server, port, host) {
+  return new Promise((res, rej) => {
+    const onListening = () => { server.removeListener("error", onError); res(); };
+    const onError = (err) => { server.removeListener("listening", onListening); rej(err); };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, host);
+  });
+}
+
+/**
+ * Whether another PORT could fix this failed `listen`.
+ *
+ * startServer builds ten random fallback candidates and they exist for exactly
+ * one situation: "this port is unavailable". Until #552 only EADDRINUSE reached
+ * them, which is the POSIX spelling of that answer and not the only one.
+ *
+ * WINDOWS. `winnat` hands out contiguous TCP blocks to Hyper-V, WSL2 and Docker
+ * Desktop, and a bind INSIDE one of those reserved exclusion ranges — the ones
+ * `netsh interface ipv4 show excludedportrange protocol=tcp` prints — is refused
+ * with WSAEACCES, which libuv reports as EACCES. Any machine with containers or
+ * WSL on it can therefore have 4317 blocked without a single socket being open
+ * on it. The loop rethrew on the first candidate, bin/deck.js printed
+ * `server failed: listen EACCES: permission denied 127.0.0.1:4317`, and the deck
+ * exited 1 with the fallback range untouched.
+ *
+ * On POSIX the same code is what a bind below 1024 gets without privilege.
+ * Retrying is right there too: 4317 and the whole fallback range are above 1024,
+ * so a random candidate is a port the user can actually have — and the deck
+ * coming up on 4322 beats it refusing to come up at all, which is already how
+ * EADDRINUSE on a privileged port behaves today.
+ *
+ * The other direction is the half that keeps this honest. EADDRNOTAVAIL,
+ * ENOTFOUND, EAI_AGAIN and EAFNOSUPPORT are about the HOST, not the port: the
+ * address does not exist on this machine or does not resolve, and no candidate
+ * can help. Walking eleven of them only delays the one sentence that would have
+ * explained it, so anything not named here stops the loop.
+ */
+export const portRetryable = (err) =>
+  Boolean(err) && (err.code === "EADDRINUSE" || err.code === "EACCES");
+
+/**
+ * The sentence that goes beside a listen errno, or "" when the errno says it
+ * all.
+ *
+ * Pure, and the platform is a parameter, for the reason every Windows answer in
+ * this repo is written that way: the branch that matters most is the one the
+ * author cannot run. A raw `listen EACCES: permission denied 127.0.0.1:4317` is
+ * true and useless — the thing the user needs is the name of the command that
+ * lists the ranges their machine has reserved.
+ */
+export function listenHint(code, { host = "", port = 0, platform = process.platform } = {}) {
+  if (code === "EACCES") {
+    if (platform === "win32") {
+      return "a reserved port range is the usual cause on Windows: Hyper-V, WSL2 and Docker Desktop have winnat hold contiguous TCP blocks. Run `netsh interface ipv4 show excludedportrange protocol=tcp` to see them, then pass --port with a number outside every range";
+    }
+    if (port > 0 && port < 1024) return "ports below 1024 need root — pass --port with a number above 1024";
+    return "the OS refused the bind; a sandbox or a security policy is the usual cause";
+  }
+  if (code === "EADDRNOTAVAIL") {
+    return `no interface on this machine holds ${host || "that address"}, so no other port can help — pass --host with an address it does hold, or 127.0.0.1 for local only`;
+  }
+  if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
+    return `${host || "that host"} does not resolve, so no other port can help — pass --host with an address rather than a name`;
+  }
+  return "";
+}
+
+/**
+ * The error startServer throws, with the hint already in it.
+ *
+ * `exhausted` is the difference between "every candidate was refused" and "this
+ * one was refused for a reason more candidates cannot fix". The exhausted
+ * message keeps its opening words — bin/deck.js prints them and
+ * boot-listen-before-report.test.ts reads them — and now names the LAST errno
+ * rather than asserting EADDRINUSE, which was a lie the moment EACCES could
+ * reach the end of the loop.
+ */
+export function listenFailure(err, { host = "", port = 0, platform = process.platform, exhausted = false } = {}) {
+  const code = err?.code;
+  const head = exhausted
+    ? `all ports tried — none available (last: ${code ?? "unknown"} on ${host}:${port})`
+    : String(err?.message ?? err ?? "listen failed");
+  const hint = listenHint(code, { host, port, platform });
+  const out = new Error(hint ? `${head} — ${hint}` : head);
+  if (code !== undefined) out.code = code;
+  if (err) out.cause = err;
+  return out;
+}

package/src/server/live-decks.mjs

@@ -0,0 +1,138 @@
+// Which decks are up right now, as their own discovery records spell them —
+// and only the ones that proved, over their own port, that they are still the
+// deck the record describes (#695).
+//
+// This lived in src/server/index.mjs, inside the Codex rollout watcher, and has
+// two readers: the watcher's log election (writesCodexLog) in codex-watch.mjs,
+// and logSharing in event-log.mjs, which tells the Clear dialog who owns the
+// log. Neither needs anything from the server but the registry directory and
+// the challenge, so it moved to a leaf both can import. The verdict cache moved with it and is still
+// the only state.
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { claudeConfigDir } from "./claude-dir.mjs";
+import { challengeDeck, isProcessAlive } from "./deck-probe.mjs";
+
+// How long one record's challenge verdict is trusted. The rollout scan runs
+// every 1.5s and would otherwise pay a round trip per record per tick for an
+// answer that changes about once per deck lifetime.
+//
+// Both answers are cached, and neither one delays a takeover, because the pid
+// probe runs first and is not cached at all: a deck killed with SIGTERM or
+// SIGKILL loses its pid immediately and its record is dropped on the very next
+// tick whatever this map says. What the TTL bounds is only the ghost case — a
+// record whose pid was recycled by an unrelated process — where five seconds of
+// believing a stale "yes" is at most a few unwritten lines, against a directory
+// listing plus an HTTP round trip on every tick of every deck forever.
+const DECK_PROOF_TTL_MS = 5000;
+// `${pid}:${port}:${token}` -> { at, ok }. Keyed on the record's own identity so
+// a rewritten record — a deck that restarted onto the same port with a fresh
+// token — is a new question rather than an inherited answer.
+const deckProofs = new Map();
+
+/**
+ * Is the process listening on this record's port the deck the record describes?
+ *
+ * WHY THE SERVER ASKS AT ALL (#695). readLiveDecks used to trust the pid and
+ * nothing else, and a pid is not evidence: a record left behind by a deck that
+ * is gone — SIGKILL, an OOM kill, a power cut, a console window closed on
+ * Windows, none of which run the shutdown that unlinks it — passes a signal-0
+ * probe forever once the OS hands that number to some other long-lived process.
+ * writesCodexLog then elected it, because it named a lower port than any real
+ * deck, and every deck tailing the rollout drew the events while none of them
+ * appended a line. The canvas looked perfectly normal and events.jsonl stopped
+ * growing, so nothing said so until a restart replayed a log that had stopped
+ * days earlier.
+ *
+ * hook.js has had the answer to this since the handshake landed and the Codex
+ * half never got it — this is that half. The record carries the deck's own token
+ * in plaintext (mode 0600, same user, and it is written there precisely so that
+ * another process can challenge with it), so we can ask its port to hash that
+ * token against a nonce it has never seen. A stranger cannot answer; the deck
+ * that wrote the file can.
+ *
+ * Two records pass without being asked:
+ *
+ *   • our own. We are the process the record describes, and challenging
+ *     ourselves over loopback inside our own scan is a question we already know
+ *     the answer to. It also must never fail: writesCodexLog looks itself up in
+ *     this list, and a deck that cannot find its own record falls back to
+ *     writing — so a self-challenge that timed out under load would turn one
+ *     unwritten line into a duplicated one.
+ *   • a record with no token, written by a deck older than the handshake. That
+ *     is exactly requiresProof's fallback in hook.js, kept in step with it on
+ *     purpose: refusing those would make every pre-1.33.71 deck invisible to the
+ *     election, which elects a writer for a log those decks are still appending
+ *     to.
+ *
+ * A timeout counts as a failure, like a refusal and a wrong answer. That is the
+ * same verdict hook.js reaches — a target that misses the deadline is not posted
+ * to either — and it errs the direction the server has always erred: the deck
+ * writes, and "a line written twice is recoverable; a deck that quietly stops
+ * recording anything is not" (writesCodexLog).
+ */
+async function provesDeck(d) {
+  if (d.pid === process.pid) return true;
+  if (typeof d.token !== "string" || d.token === "") return true;
+
+  const key = `${d.pid}:${d.port}:${d.token}`;
+  const cached = deckProofs.get(key);
+  const now = Date.now();
+  if (cached && now - cached.at < DECK_PROOF_TTL_MS) return cached.ok;
+
+  const ok = await challengeDeck(d.port, d.token);
+  deckProofs.set(key, { at: now, ok });
+  // Records come and go; without this the map would grow by one entry per deck
+  // that ever registered on this machine while the process is up.
+  for (const [k, v] of deckProofs) {
+    if (now - v.at >= DECK_PROOF_TTL_MS) deckProofs.delete(k);
+  }
+  return ok;
+}
+
+
+/**
+ * Every deck registered right now, as its own discovery record spells it — and
+ * only the ones that proved they are still the deck their record describes.
+ *
+ * These are the files hook.js enumerates; this is the server reading them for
+ * itself, because the rollout watcher has no hook to do it and still has to know
+ * which other decks are tailing the same file into the same log. Dead pids are
+ * ignored rather than unlinked — sweepStaleDiscovery owns that, and a poll
+ * running every 1.5s is no place to be deleting other decks' registrations. A
+ * record that fails the challenge is likewise left alone HERE. The hook is the one
+ * reader that does delete a record, and only one that stayed silent through both
+ * of its challenge deadlines and has not been restamped for a minute, which a
+ * live deck does every five seconds (proveTargets in hook/hook.js, #1119). One
+ * missed answer on this poll's timer is not that evidence, so nothing here acts
+ * on it.
+ *
+ * The pid probe stays, in front of the challenge, because it is free and it is
+ * the one test that answers instantly when a deck is killed — which is what
+ * keeps the takeover immediate rather than TTL-bound. See provesDeck.
+ */
+async function readLiveDecks() {
+  const dir = join(claudeConfigDir(), "agent-dag");
+  let files;
+  try { files = await readdir(dir); } catch { return []; }
+  const candidates = [];
+  for (const f of files) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const d = JSON.parse(await readFile(join(dir, f), "utf8"));
+      // Without both numbers there is nothing to group or tie-break on, so the
+      // record cannot take part in an election either way.
+      if (!d || typeof d.pid !== "number" || typeof d.port !== "number") continue;
+      if (!isProcessAlive(d.pid)) continue;
+      candidates.push(d);
+    } catch { /* corrupt, or gone between listing and read */ }
+  }
+  // In parallel: with several decks up this is the difference between one 400ms
+  // deadline for the scan and one per record.
+  const proven = await Promise.all(candidates.map(provesDeck));
+  return candidates.filter((_, i) => proven[i]);
+}
+
+// What index.mjs calls. Listed rather than marked at the declaration, so the
+// declaration reads as it did where it came from.
+export { readLiveDecks };