ccdeck 3.29.11 → 3.31.0

package/bin/cli/one-shot.js

@@ -0,0 +1,254 @@
+// The one-shot commands: `--status`, `--logs` and `--stop`, and the way in for
+// the three login-item commands, which bin/cli/login-item.js answers.
+//
+// One-shot commands in the shape `--uninstall` already established: do the
+// thing, print, exit, and never start a server. bin/deck.js asks them ABOVE the
+// migration and well above the heavy imports, because a command that ends a
+// deck has no business moving that deck's files on the way past, and because
+// asking a server to stop should not require starting one.
+//
+// The glyphs and the palette are the boot's own, from bin/cli/screen.js, which
+// answers them when it loads — so these lines can use them even though they run
+// before the boot has drawn anything (#797).
+import { readFileSync as readLog, statSync as statLog } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { isPortValue } from "../../src/server/args.mjs";
+import { sinceLabel } from "../../src/server/term.mjs";
+import { installGlobally, loginItemCommand } from "./login-item.js";
+import { COMMAND, PKG_ROOT } from "./package.js";
+import { G, P } from "./screen.js";
+
+/**
+ * Answer one of the six one-shot flags and resolve to the exit code. The
+ * caller exits with it; nothing here starts a server.
+ */
+export async function oneShot(flags) {
+  const voice = oneShotVoice();
+  reportFlagRows(flags, voice);
+  if (flags.stop && refusesPort(flags, voice)) return 1;
+
+  const { deckDataDir, deckLogDir } = await import(pathToFileURL(join(PKG_ROOT, "src/server/deck-home.mjs")).href);
+
+  // --install, --install-service and --uninstall-service: the login item, in
+  // bin/cli/login-item.js. Answered before the registry is read, since neither
+  // is about a deck that is running.
+  if (flags.install) return installGlobally({ ...voice, deckDataDir, deckLogDir });
+  if (flags.installService || flags.uninstallService) return loginItemCommand(flags, { ...voice, deckDataDir, deckLogDir });
+  if (flags.logs) return printLogs(deckLogDir, voice);
+
+  const { liveDecks } = await import(pathToFileURL(join(PKG_ROOT, "src/server/running-deck.mjs")).href);
+  const decks = await liveDecks().catch(() => []);
+  if (flags.status) return printStatus(decks, await defaultShape(deckLogDir), voice);
+  return stopDecks(flags, decks, voice);
+}
+
+/** The screen's glyphs and palette, by the names the one-shots use, and `say`. */
+function oneShotVoice() {
+  const { dash, ok: gOk, warn: gWarn, bullet, arrow, ellipsis: gEllipsis } = G;
+  const tone = P;
+  const say = (line) => process.stdout.write(`${line}\n`);
+  return { dash, gOk, gWarn, bullet, arrow, gEllipsis, tone, say };
+}
+
+const age = (d) => sinceLabel(Date.now() - Date.parse(d.startedAt ?? ""));
+const where = (d) => (d.workspace ? d.workspace : "(all)");
+const url = (d) => `http://127.0.0.1:${d.port}`;
+
+// WHAT THE ONE-SHOTS USED TO SWALLOW.
+//
+// The boot's reportUnknownFlags and reportIncompleteFlags live in bin/deck.js,
+// which is the script itself and cannot be imported, and they write the boot's
+// label-column rows to stdout. So a one-shot's are written here, to stderr, in
+// the one-shots' own shape.
+//
+// Without them `--help`'s closing promise — "Anything else on the command
+// line is reported as an unknown option and then ignored" — held for a boot
+// and for none of the nine one-shots: `ccdeck --status --prot 4317` printed
+// the status and never mentioned the flag.
+function reportFlagRows(flags, { tone, gWarn, dash }) {
+  for (const token of flags.unknown ?? []) {
+    process.stderr.write(`  ${tone.warn}${gWarn}  unknown option${tone.reset}  ${token} ${dash} see \`${COMMAND} --help\`\n`);
+  }
+  for (const { flag, expects } of flags.incomplete ?? []) {
+    process.stderr.write(`  ${tone.warn}${gWarn}  missing value${tone.reset}   ${flag} ${dash} expected ${expects}\n`);
+  }
+}
+
+// AND `--stop` FAILS CLOSED ON A PORT IT CANNOT USE.
+//
+// The selector below reads "no usable port" and "no port asked for" as the
+// same thing, and the second means every deck — so `ccdeck --stop --port
+// 431x`, or `--port $UNSET`, ended every deck on the machine and exited 0.
+// The guard that refuses a bad port is in bin/deck.js, below the line that
+// brings a one-shot here, and a one-shot always exits before reaching it.
+//
+// A narrowing flag that fails open to "everything" is the wrong default for
+// an off switch: failing closed costs a retype, failing open costs a deck
+// somebody else was watching. So this answers true, having said why, when
+// `--stop` was pointed at a port it cannot use.
+function refusesPort(flags, { dash }) {
+  const askedPort = (flags.incomplete ?? []).some(x => x.flag === "--port" || x.flag === "-p");
+  const badPort = flags.port != null && !isPortValue(flags.port);
+  if (badPort || askedPort) {
+    const shown = badPort ? ` ${flags.port}` : "";
+    console.error(`${COMMAND}: --port${shown}: not a port number ${dash} expected 0-65535.`);
+    console.error(`${COMMAND}: refusing to stop every deck when you asked for one.`);
+    return true;
+  }
+  return false;
+}
+
+// ── --logs ────────────────────────────────────────────────────────────────
+// What the deck wrote where a terminal would have shown it. Printed RAW,
+// escapes and all: the launcher passes its own colour tier down to a detached
+// deck, so this file is a mirror of the terminal the deck was started from
+// and re-rendering it is the whole point. The path goes last, because that is
+// the line somebody copies into `tail -f`.
+function printLogs(deckLogDir, { say, tone, dash, bullet }) {
+  const logPath = join(deckLogDir(), "deck.log");
+  let text = null;
+  try { text = readLog(logPath, "utf8"); } catch { /* never started, or swept */ }
+  if (text === null) {
+    say(`\n  ${tone.muted}${dash}  nothing logged yet ${dash} ${logPath}${tone.reset}\n`);
+    return 0;
+  }
+  // The tail, not the file. It is truncated at the first start on an idle
+  // machine, so it is normally small — but an attach appends to a running
+  // deck's log every time, and a long-lived deck's log is somebody's week.
+  const lines = text.split("\n");
+  const shown = lines.slice(Math.max(0, lines.length - 200));
+  if (shown.length < lines.length) {
+    say(`  ${tone.muted}${dash}  showing the last ${shown.length} of ${lines.length} lines${tone.reset}`);
+  }
+  process.stdout.write(shown.join("\n"));
+  if (!text.endsWith("\n")) say("");
+  const size = (() => { try { return statLog(logPath).size; } catch { return 0; } })();
+  say(`  ${tone.muted}${dash}  ${logPath} ${bullet} ${size} bytes${tone.reset}\n`);
+  return 0;
+}
+
+/**
+ * The shape a bare start would have, for the deck `--status` marks as the one
+ * it opens.
+ */
+async function defaultShape(deckLogDir) {
+  const { canonicalLogPath } = await import(pathToFileURL(join(PKG_ROOT, "src/server/log-election.mjs")).href);
+  const { hasCodexInstalled, codexHomeField } = await import(pathToFileURL(join(PKG_ROOT, "src/server/installer.mjs")).href);
+  const { hasClaudeInstalled } = await import(pathToFileURL(join(PKG_ROOT, "src/server/claude-dir.mjs")).href);
+
+  // The default shape, spelled the same way deck.js's boot spells it. NOT the
+  // shape of the flags on THIS command line: `--stop --no-codex` is not a
+  // request to stop a Codex-less deck, it is a flag that means nothing here,
+  // and reading it as a selector would make `--stop` miss the deck it was
+  // pointed at and say "nothing is running".
+  const mine = {
+    workspace: "",
+    persist: canonicalLogPath(join(deckLogDir(), "events.jsonl")),
+    codex: hasCodexInstalled(),
+    claude: hasClaudeInstalled(),
+  };
+  // And the Codex tree, the one field of a start's shape that is not a flag. A
+  // bare start has passed it since #1123 and replaces a deck on another tree, so
+  // without it here every tree matched, and `--status` could mark as "opens this
+  // one" exactly the deck the next `ccdeck` stops (#1134). Worked out by the
+  // function the start and the discovery record use, so all three agree.
+  mine.codexHome = codexHomeField(mine.codex);
+  return mine;
+}
+
+/** `--status`: every deck on this machine, and which one a bare start would open. */
+async function printStatus(decks, mine, { say, tone, dash, gOk, bullet, arrow }) {
+  const { sameShape } = await import(pathToFileURL(join(PKG_ROOT, "src/server/running-deck.mjs")).href);
+  if (!decks.length) {
+    say(`\n  ${tone.muted}${dash}  no deck is running ${dash} \`${COMMAND}\` starts one${tone.reset}\n`);
+    return 0;
+  }
+  // The one a bare `ccdeck` would open is marked, because with two decks up
+  // that is the only question this command is really being asked.
+  const opens = decks.find(d => sameShape(d, mine)) ?? null;
+  say("");
+  for (const d of decks) {
+    // The version chunk is dropped rather than printed as "v?" for a deck too
+    // old to publish one — same rule as the attach line, and for the same
+    // reason: a question mark beside two real facts reads as a fault.
+    const head = [d.version ? `v${d.version}` : "", `pid ${d.pid}`, `up ${age(d)}`]
+      .filter(Boolean).join(`  ${bullet}  `);
+    const mark = d === opens ? `${tone.ok}${gOk}${tone.reset}` : `${tone.muted}${bullet}${tone.reset}`;
+    const tail = d === opens ? `${tone.muted}   ${arrow} \`${COMMAND}\` opens this one${tone.reset}` : "";
+    say(`  ${mark}  ${tone.muted}${head}${tone.reset}${tail}`);
+    say(`     ${tone.accent}${tone.bold}${url(d)}${tone.reset}`);
+    say(`     ${tone.muted}${where(d)} ${bullet} ${d.persist ?? "no log (--no-persist)"}${tone.reset}`);
+  }
+  say("");
+  return 0;
+}
+
+// ── --stop ────────────────────────────────────────────────────────────────
+//
+// WHICH DECK. Every one, unless `--port <n>` names one. A start keeps at most
+// one deck now, so a second is a leftover from before that rule, and an off
+// switch that ended one of two would leave the machine running. (`--all` is the
+// legacy capture flag, a no-op since it became the default; beside `--stop` it
+// always meant "every deck", and that is what the bare command means now.)
+async function stopDecks(flags, decks, { say, tone, dash, gOk, gWarn, bullet }) {
+  const { stopDeck } = await import(pathToFileURL(join(PKG_ROOT, "src/server/stop-deck.mjs")).href);
+  // `flags.port`, not the `rawPort` deck.js computes: that folds in
+  // AGENT_DAG_PORT, which is how somebody RUNS a deck rather than which deck
+  // they mean to stop — and a deck started on a custom port still has the
+  // default SHAPE, so the matcher finds it without help. It is also a binding
+  // deck.js declares after it asks this, so it is not there to read (#797).
+  const named = flags.port != null && isPortValue(flags.port) ? Number(flags.port) : null;
+  // EVERY DECK, unless one is named. There is meant to be one — a start keeps
+  // at most one now — so a second here is a leftover from before that rule, and
+  // an off switch that ended one of two would leave the machine running. `--all`
+  // is still accepted, and now means what the bare command means.
+  const wanted = named !== null ? decks.filter(d => d.port === named) : decks;
+
+  if (!wanted.length) {
+    // Two different silences, and saying the wrong one sends the reader looking
+    // in the wrong place.
+    const why = named !== null && decks.length
+      ? `no deck is listening on ${named} ${dash} \`${COMMAND} --status\` lists them`
+      : `no deck is running`;
+    say(`\n  ${tone.muted}${dash}  ${why}${tone.reset}\n`);
+    return 0;
+  }
+
+  say("");
+  let refused = false;
+  for (const d of wanted) {
+    const was = age(d);
+    const out = await stopDeck(d);
+    if (!out.ok) {
+      refused = true;
+      say(`  ${tone.err}${gWarn}  could not stop pid ${d.pid} on ${d.port} ${dash} ${out.reason}${tone.reset}`);
+      continue;
+    }
+    // HOW it went out, not just that it did. "asked" means the deck closed its
+    // listener, unlinked its registration and left the LAN cleanly; anything
+    // else means none of that happened and the next boot has litter to sweep.
+    const how = out.how === "asked"
+      ? ""
+      : out.old
+        ? `  ${tone.muted}(${out.how} ${dash} that deck predates \`--stop\`)${tone.reset}`
+        : `  ${tone.muted}(${out.how} ${dash} it did not answer)${tone.reset}`;
+    say(`  ${tone.ok}${gOk}${tone.reset}  stopped${tone.muted}  ${bullet}  pid ${d.pid}  ${bullet}  port ${d.port}  ${bullet}  was up ${was}${tone.reset}${how}`);
+  }
+
+  // What is still up, named. A command that ends one of three decks and says
+  // only "stopped" leaves the reader believing the machine is clear.
+  const left = decks.filter(d => !wanted.includes(d));
+  if (left.length) {
+    say("");
+    say(`  ${tone.muted}${dash}  ${left.length} other deck${left.length === 1 ? "" : "s"} still running:${tone.reset}`);
+    for (const d of left) say(`       ${tone.muted}pid ${d.pid} ${bullet} ${d.port} ${bullet} ${where(d)}${tone.reset}`);
+    // `--stop --all` used to be named here as the way to reach every deck. It
+    // is not: `--all` is a parsed no-op, and a bare `--stop` already ends every
+    // deck — which is why this line is only reachable after `--stop --port <n>`
+    // narrowed one. Naming the narrowing form is the half that is true.
+    say(`     ${tone.muted}\`${COMMAND} --stop\` ends every deck ${bullet} \`--stop --port <n>\` ends one${tone.reset}`);
+  }
+  say("");
+  return refused ? 1 : 0;
+}

package/bin/cli/package.js

@@ -0,0 +1,39 @@
+// Which package this worker belongs to, and the name it was started under.
+//
+// Worked out from where THIS file is, so a copy of bin/ in another tree — an npx
+// cache, a package a test assembled by hand — answers for that tree and not for
+// the one it was copied from. Lifted out of bin/deck.js so that every file in
+// bin/cli/ imports the three answers instead of having them handed down.
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+import { PRODUCT } from "../../src/server/brand.mjs";
+import { invokedName } from "../../src/server/invoked-as.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const PKG_ROOT = resolve(__dirname, "../..");
+
+/**
+ * The version package.json names right now, or null when it cannot be read.
+ *
+ * Asked twice in a deck's life, and the second answer is only worth having
+ * because it can differ from the first: once at boot, for the version this
+ * process runs, and again as a restart is about to land, for the version it
+ * will land on — whatever an upgrade has installed underneath it since.
+ */
+export function versionOnDisk() {
+  try { return JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8")).version ?? null; }
+  catch { return null; }
+}
+
+export const PKG_VERSION = versionOnDisk() ?? "0.0.0";
+
+// The command the user typed, handed down by the supervisor — the worker's own
+// argv[1] is bin/deck.js under every one of the three names. Null when it cannot be
+// proven, and null is the answer that prints nothing.
+export const INVOKED_AS = invokedName({ pkgRoot: PKG_ROOT });
+
+// The command a hint tells somebody to type: the one they typed, or ours when
+// that cannot be told (#1501). INVOKED_AS stays null in that case for the one
+// caller that must say nothing rather than guess — the rename notice.
+export const COMMAND = INVOKED_AS ?? PRODUCT;

package/bin/cli/pulse.js

@@ -0,0 +1,98 @@
+// The pulse line: the last line of the boot's screen, and the only one that can
+// still move once the report is done.
+//
+// Lifted out of bin/deck.js, which starts it at the same point in the boot.
+//
+// The whole line is rewritten each beat rather than just the dot: anything else
+// on this deck that has something to say writes a newline first, and after that
+// the line under the cursor is no longer the one we drew — a partial repaint
+// would leave the message behind and pulse into empty space. Sized to the real
+// terminal, because at 40 columns the old fixed 61-character line wrapped, and
+// from then on \r only ever reached its second row.
+//
+// AND IT STOPS MOVING (#742). The dot alternated green and grey every 800ms for
+// as long as the deck ran, and a blinking indicator beside a status line is the
+// vocabulary of "working on it" — so a boot that finished in a second read as
+// one that never finished, which is what people reported. Motion is now spent
+// on the two states where something really is outstanding, and the frame is
+// compared against what is already on screen so a deck at rest paints once and
+// then leaves the terminal alone. See pulseMoves.
+import { pulseDot, pulseText } from "../../src/server/pulse-line.mjs";
+import { G, MOTION, P, UNICODE, cols, write } from "./screen.js";
+import { busyLabel } from "./startup.js";
+
+/**
+ * Put the pulse line up, when anything on this terminal is allowed to move.
+ *
+ * `registered` is asked on every beat rather than passed once: the discovery
+ * check changes it for as long as the deck runs, and the line says so.
+ */
+export function startPulse({ registered: isRegistered, wantClaude }) {
+  if (!MOTION) return;
+  let pi = 0;
+  let painted = null;
+  // The line is on screen and is the last thing written to this terminal.
+  let ours = false;
+  // We are the one writing right now, so the guard below leaves us alone.
+  let writing = false;
+
+  // The pulse line's tenancy, enforced rather than agreed.
+  //
+  // The convention was that anything with something to say writes a newline
+  // first, so the pulse's `\r` never lands on somebody else's text. The boot
+  // keeps it everywhere. src/server/quota.mjs does not — it calls console.error
+  // directly — and a Windows user with no Claude Code sent a screenshot of the
+  // result: `listening — Ctrl+C to stop        ccdeck quota: claude CLI failed`
+  // on one row, three times over, the pulse and the complaint interleaved.
+  //
+  // An invariant every writer has to remember is one a writer will forget, and
+  // the writers here are server modules that know nothing about a terminal. So
+  // it is enforced at the stream instead: while our line is the last thing on
+  // screen, anything else that speaks gets a newline first, and the memo is
+  // dropped so the next beat repaints the line under whatever was said.
+  //
+  // Both streams, because console.error goes to stderr and lands on the same
+  // screen. Only when MOTION is on — with no pulse there is no line to defend,
+  // and a piped deck must not have its output rewritten.
+  for (const stream of [process.stdout, process.stderr]) {
+    const real = stream.write.bind(stream);
+    stream.write = (chunk, ...rest) => {
+      if (!writing && ours) {
+        ours = false;
+        // Dropped, not kept: the line is no longer where we left it, so the
+        // next beat has to draw it again even though the frame is unchanged.
+        painted = null;
+        // Unless the speaker already did it. Every late message the boot writes
+        // opens with one, and two blank lines is its own kind of mess.
+        if (!String(chunk).startsWith("\n")) real("\n");
+      }
+      return real(chunk, ...rest);
+    };
+  }
+
+  setInterval(() => {
+    const registered = isRegistered();
+    // The colour follows the words. A Codex-only deck keeps saying "listening"
+    // when it is unregistered — see pulseText — and painting that sentence in
+    // the warning tone would restore the alarm the sentence just retired.
+    const alarm = !registered && wantClaude;
+    const state = { registered, claude: wantClaude, busy: busyLabel() };
+    const text = pulseText({ ...state, columns: cols(), unicode: UNICODE });
+    // At rest every beat is lit, which is what makes the line still: the frame
+    // is then identical to the one already on screen and the write below is
+    // skipped. See pulseDot.
+    const dot = pulseDot(pi++, state) === "on" ? (alarm ? P.warn : P.ok) : P.muted;
+    const tone = alarm ? P.warn : P.muted;
+    const frame = `\r  ${dot}${G.pulse}${P.reset}  ${tone}${text}${P.reset}`;
+    // Unchanged frames are not written at all. That is what makes "at rest"
+    // visible: one paint, and then a still line for as long as nothing happens.
+    // `painted` is dropped by the guard above whenever somebody else writes, so
+    // this can only skip a beat while the line is genuinely still where we left
+    // it.
+    if (frame === painted) return;
+    painted = frame;
+    writing = true;
+    try { write(frame); } finally { writing = false; }
+    ours = true;
+  }, 800).unref();
+}

package/bin/cli/restart.js

@@ -0,0 +1,179 @@
+// The restart latch: one restart at a time, held until the boot can take it,
+// and let go of on every way it can fail.
+//
+// Lifted out of bin/deck.js. The latch is the only state here, and the two
+// things it acts through are handed in rather than reached for: `shutdown`,
+// deck.js's own way out, which a restart ends in, and `releaseRestart`, the
+// server's half of the same latch. What comes back is requestRestart, for
+// startServer's onRestart, and the two calls deck.js makes when its boot ends.
+import { oneLine } from "../../src/server/term.mjs";
+import { RESTART_CODE, UPGRADE_CODE } from "../../src/server/supervisor.mjs";
+import { PKG_VERSION, versionOnDisk } from "./package.js";
+import { G, P, cols, write } from "./screen.js";
+
+/**
+ * Arm the latch, and the supervisor's answer to an upgrade with it. Called once,
+ * before the server can take a request.
+ */
+export function restartLatch({ shutdown, releaseRestart }) {
+  // Asking the supervisor to bring us back. It is the only party that can, and
+  // only after this process is gone — which is precisely what keeps the
+  // replacement from racing this listener onto a random fallback port.
+  let restarting = false;
+  // Outer bound on the supervisor's answer below. It cannot be reached today —
+  // the fetch has a deadline of its own and every path through it replies — but
+  // `restarting` is a latch, and a latch with no way out is how a deck ends up
+  // silently refusing every restart for the rest of its life.
+  const UPGRADE_ANSWER_MS = 150_000;
+  let upgradeTimer = null;
+
+  // Whether the boot has finished: markBooted, called by deck.js at its end.
+  //
+  // The server starts accepting connections from inside startServer, before
+  // that call has returned — so /api/restart is reachable for the whole of the
+  // boot that follows it: the startup report, the port report to the supervisor,
+  // the discovery file and its first fsynced write, and on a cold start the
+  // browser spawn. A restart landing in that window used to reach `shutdown`
+  // before the binding holding it was initialised and die of a ReferenceError,
+  // having already set the latch above, with nothing left to clear it — after
+  // which every restart from every tab was answered "ok" and did nothing, for the
+  // life of the process (#448).
+  //
+  // So an ask that arrives too early is held rather than run: the user asked for
+  // something this deck can genuinely give a moment later, and refusing outright
+  // would put back the same silence in a politer form. BOOT_RESTART_MS is the
+  // outer bound, for the reason UPGRADE_ANSWER_MS above is one. It used to be a
+  // bound that got used — before #742 the report waited out a real `uv tool
+  // install`, so the window it covers was minutes wide. It is now the boot
+  // deadline plus the browser spawn, comfortably inside ten seconds, and this
+  // stays as the thing that makes that a fact rather than a belief. Ten seconds
+  // in, the ask is run; the respawn skips the report entirely and is up in about
+  // a second.
+  let booted = false;
+  let heldRestart = null;
+  let bootTimer = null;
+  const BOOT_RESTART_MS = 10_000;
+
+  const requestRestart = (mode) => {
+    if (restarting) return;
+    restarting = true;
+    if (!booted) {
+      heldRestart = { mode };
+      bootTimer = setTimeout(() => { bootTimer = null; runHeldRestart(); }, BOOT_RESTART_MS);
+      bootTimer.unref?.();
+      // Said out loud for the same reason abandonUpgrade below is: the tab has
+      // already been told its restart was accepted, and a second of nothing
+      // happening on this terminal is otherwise indistinguishable from the bug
+      // this replaces.
+      write(`\n  ${P.warn}${G.restart}${P.reset}  ${P.muted}restart queued ${G.dash} still starting up${P.reset}\n`);
+      return;
+    }
+    beginRestart(mode);
+  };
+
+  // The restart itself, once there is a booted deck to end. Split out of
+  // requestRestart so the held ask above can re-enter it without tripping the
+  // latch it is already holding.
+  //
+  // Everything here runs inside one try: the whole point of #448 is that a throw
+  // on this path is not merely a failed restart but a permanent one, because the
+  // latch it leaves behind outlives it. There is no line in here worth dying for.
+  function beginRestart(mode) {
+    try {
+      // "npx" means the newer code is not on this disk at all, so it has to be
+      // fetched — and this process keeps serving while that happens. Exiting first
+      // is what made every failed upgrade an outage: the SSE stream dropped, hook
+      // events fired into the gap were lost outright (hook/hook.js is
+      // fire-and-forget with a 1s timeout and no retry), and the canvas came back
+      // with whatever was in flight stuck until the stale sweeper reaped it — all
+      // of it paid before anyone knew whether npm could even resolve the version.
+      // Nothing is torn down here now; the supervisor answers when it knows.
+      if (mode === "npx") {
+        upgradeTimer = setTimeout(() => abandonUpgrade("no answer from the supervisor"), UPGRADE_ANSWER_MS);
+        upgradeTimer.unref?.();
+        // Armed before the ask, not after: a send that throws is a supervisor that
+        // can no longer answer, and the deck has to come back out of the latch on
+        // its own rather than wait out an answer that cannot arrive.
+        try { process.send({ type: "upgrade" }); }
+        catch (err) { abandonUpgrade(err?.message ?? "the supervisor is no longer listening"); }
+        return;
+      }
+      // What a restart would land on. Read from disk now rather than remembered
+      // from boot, because the whole point is that the two differ.
+      const to = versionOnDisk();
+      write(`\n  ${P.warn}${G.restart}${P.reset}  ${P.muted}restarting${to ? ` ${G.arrow} v${to}` : ""}${G.ellipsis}${P.reset}\n`);
+      shutdown(RESTART_CODE);
+    } catch (err) {
+      abandonRestart(err);
+    }
+  }
+
+  // The ask that was waiting for the boot to finish, now that it has. Safe to
+  // call when nothing is waiting, which is every ordinary boot.
+  function runHeldRestart() {
+    if (!heldRestart) return;
+    const { mode } = heldRestart;
+    heldRestart = null;
+    clearTimeout(bootTimer);
+    bootTimer = null;
+    beginRestart(mode);
+  }
+
+  // A restart that could not be started, said out loud and then let go of.
+  //
+  // Both halves of the latch have to come down — this one's and the server's —
+  // because a latch nothing clears is precisely how one failed request turned
+  // into a deck that refused every restart afterwards while answering "ok" to
+  // each one (#448). The reason is folded onto one line by oneLine: the terminal
+  // under this is repainted every 800ms by the pulse, and a stack written into
+  // that is a stack nobody can read (#432).
+  //
+  // A declaration rather than a const, like deck.js's `shutdown` and for the same
+  // reason: this is the handler for a binding that was not there yet, and it must
+  // not be capable of becoming the next one.
+  function abandonRestart(err) {
+    clearTimeout(bootTimer);
+    bootTimer = null;
+    heldRestart = null;
+    restarting = false;
+    releaseRestart();
+    write(
+      `\n  ${P.err}${G.fail}${P.reset}  ${P.muted}restart failed ${G.dash} still on ${P.reset}v${PKG_VERSION}\n` +
+      `     ${P.muted}${oneLine(err?.stack ?? err, Math.max(20, cols() - 6), G.ellipsis)}${P.reset}\n`,
+    );
+  }
+
+  // The upgrade did not happen and this deck is still the deck. Said out loud
+  // because the terminal has just printed that a fetch was starting, and left
+  // unsaid it reads as a restart that hung.
+  const abandonUpgrade = (why) => {
+    clearTimeout(upgradeTimer);
+    restarting = false;
+    // The server's own latch, which no longer has an exiting process to clear it.
+    releaseRestart();
+    write(
+      `\n  ${P.warn}${G.cancel}${P.reset}  ${P.muted}update not applied ${G.dash} still on ${P.reset}v${PKG_VERSION}\n` +
+      (why ? `     ${P.muted}${why}${P.reset}\n` : ""),
+    );
+  };
+
+  // The supervisor's verdict on the fetch it was asked for. Only it can answer:
+  // the fetch is its child, and it is the process that will still be here when
+  // this one exits.
+  process.on("message", (m) => {
+    if (!restarting || !m || typeof m !== "object") return;
+    if (m.type === "upgrade-ready") {
+      clearTimeout(upgradeTimer);
+      // The replacement is on the machine now, so this is the last moment the
+      // port is worth holding: exiting hands it straight over.
+      write(`\n  ${P.warn}${G.restart}${P.reset}  ${P.muted}updating via npx${G.ellipsis}${P.reset}\n`);
+      shutdown(UPGRADE_CODE);
+    } else if (m.type === "upgrade-refused") {
+      abandonUpgrade(m.error);
+    }
+  });
+
+  /** The boot is over, so an ask that arrives from now on is run, not held. */
+  const markBooted = () => { booted = true; };
+  return { requestRestart, markBooted, runHeldRestart };
+}