agent-dag 3.22.0 → 3.22.3

package/bin/agent-dag.js

@@ -1,626 +0,0 @@
-#!/usr/bin/env node
-// Supervisor. Owns one thing: the worker's lifecycle.
-//
-// Why this exists at all: Node caches every module at import, so a deck that is
-// running when an upgrade lands keeps executing the old code until the process
-// is replaced. The deck can now see that (GET /api/version) — this is the half
-// that can act on it.
-//
-// The tempting shortcut is to have the server respawn itself and exit. Every
-// version of that is worse than it looks:
-//   • the replacement races the dying listener, and startServer answers
-//     EADDRINUSE by binding one of ten RANDOM ports in 4318–4400 — so the tab
-//     you are looking at reconnects forever next to a healthy invisible server;
-//   • an orphan spawned from a dying parent leaves the shell's foreground
-//     process group, so Ctrl+C stops reaching it;
-//   • with stdio ignored it also loses the banner, the URL line and every
-//     console.error the server writes.
-// A parent that stays alive avoids all three: the child is dead — and its
-// listening socket released — before the next one is spawned, stdio is
-// inherited so the terminal is unchanged, and Ctrl+C keeps working because the
-// process group never changes.
-//
-// The upgrade path has one more constraint, learned the expensive way: the
-// worker must not be torn down to find out whether an upgrade is possible. It
-// used to be — the worker exited 76, and only then did npx discover it was
-// offline — so every failed update cost a full outage and could be retried
-// identically forever. Now the worker ASKS (an `upgrade` message), the fetch
-// happens beside it while it keeps serving, and only a fetch that worked is
-// answered with the exit that gives up the port. See prefetchUpgrade.
-//
-// Everything else the deck does still lives in bin/deck.js. This file must stay
-// boring: it is the one process that is never replaced.
-import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { connect } from "node:net";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { killTree } from "../src/server/exec.mjs";
-import { invokedAs } from "../src/server/invoked-as.mjs";
-import { isOneShot, parseArgs } from "../src/server/args.mjs";
-import { npxFailureHint, npxFailureSummary, npxLaunch, npxPrefetch } from "../src/server/npx.mjs";
-import {
-  bareSpecName, claimRestartFailureKey, clearRestartFailure, installedName, installedVersion,
-  isNpxInstall, lastKnownLatest, npxRestartSpec, readRestartFailure, recordRestartFailure,
-  successorRoot,
-} from "../src/server/self-update.mjs";
-import {
-  CRASH_CEILING, CRASH_WINDOW_MS, crashPolicy, dieOfSignal, dieWithParent, isCrash, replacedNote,
-  upgradeAttempt, upgradeRefusalText, workerExitAction,
-} from "../src/server/supervisor.mjs";
-import { colorProfile, glyphs, palette, termColumns, unicodeOK } from "../src/server/term.mjs";
-import { DETACHED_ENV, detachAndWatch, stopCommand } from "../src/server/detach.mjs";
-import { PRODUCT } from "../src/server/brand.mjs";
-
-const BIN_DIR = dirname(fileURLToPath(import.meta.url));
-const WORKER = join(BIN_DIR, "deck.js");
-const PKG_ROOT = dirname(BIN_DIR);
-
-const VERSION = installedVersion(PKG_ROOT) ?? "?";
-
-// Which of the three published commands the user typed, when that is knowable.
-// This process is the one the shell exec'd, so its argv[1] is the only place
-// the answer exists — the worker's is `…/bin/deck.js` under every one of them —
-// and launch() carries it down rather than letting the worker ask a question it
-// cannot answer. Null wherever it cannot be proven, which is a Windows global
-// install and a git checkout; see src/server/invoked-as.mjs for why those two
-// have to stay silent rather than guess.
-const INVOKED_AS = invokedAs({ pkgRoot: PKG_ROOT, argv1: process.argv[1], platform: process.platform });
-
-// The supervisor prints exactly one line of its own — the fetch — and it has to
-// look like it came from the same product as the worker's rows. That is all the
-// presentation this file gets: it is the process that is never replaced, and a
-// colour profile plus a glyph tier is the most it can carry without becoming
-// something that can fail. Everything else it says is an error, on stderr, in
-// plain text, where it belongs.
-const P = palette(colorProfile({ isTTY: Boolean(process.stdout.isTTY) }));
-const G = glyphs(unicodeOK());
-
-// Who the restart-failure note below belongs to. Several decks of the same
-// package run out of one home directory — two `npx ccdeck` runs even share the
-// _npx directory and therefore the version — so a note named after the package
-// alone was read by every one of them, and a deck that had never asked for an
-// update reported someone else's failed npx as its own. Our pid is unique among
-// the decks alive on the machine, and putting it in our own environment is what
-// carries it to the worker: launch() spawns with a copy of it.
-// ── the terminal stops being the deck's leash ────────────────────────────────
-//
-// Everything about why is in src/server/detach.mjs. Here is only the decision,
-// and it has exactly two ways out:
-//
-//   ALREADY DETACHED — we ARE the background copy. Carry on as this file always
-//   has: spawn the worker, supervise it, never come back here.
-//
-//   A ONE-SHOT — `--version`, `--stop`, `--status`, `--help`, `--uninstall`.
-//   Those answer and leave, and a one-shot that detached would print its answer
-//   into a log file and hand the terminal back empty. They run in the
-//   foreground exactly as they always have.
-//
-// Anything else is a start, and a start goes to the background.
-const DETACHED = process.env[DETACHED_ENV] === "1";
-// A parent already holding our lifecycle. `process.send` exists only when
-// somebody spawned us with an IPC channel, and that somebody has armed
-// dieWithParent below and is waiting on our exit code — running away from them
-// into our own process group is precisely the wrong answer to being supervised.
-// The suite's spawnSupervised is the caller that does this today.
-const LEASHED = typeof process.send === "function";
-// And the way to ask for the old behaviour out loud.
-//
-// Every version before this one held the terminal, and something out there
-// depends on that: a wrapper script, a CI step, a supervisor of somebody else's
-// that starts `ccdeck` and waits on it, a `ccdeck && open …`. Handing all of
-// those an immediate exit and no way to say otherwise would be a breaking change
-// with no escape hatch — and the marker above is an internal one, not something
-// to tell a user to export.
-const FLAGS = parseArgs(process.argv.slice(2));
-if (!DETACHED && !LEASHED && FLAGS.foreground !== true && !isOneShot(FLAGS)) {
-  const { deckLogDir } = await import("../src/server/deck-home.mjs");
-  const { registeredDecks } = await import("../src/server/running-deck.mjs");
-  const isTTY = Boolean(process.stdout.isTTY);
-  const profile = colorProfile({ isTTY });
-  const tone = palette(profile);
-  const npx = isNpxInstall(PKG_ROOT);
-  const stop = stopCommand({ npx, invokedAs: INVOKED_AS, product: PRODUCT });
-  // THE ONE THING AN NPX RUN CANNOT HAVE, said where it is missing. A login item
-  // must name a path that will still be there tomorrow, and npx runs out of a
-  // cache npm deletes whenever it likes — so an npx deck runs in the background
-  // and cannot come back after a reboot. One line, no disk written, offered
-  // rather than done: `npx` means "run without installing", and a tool that
-  // installs itself anyway is the one people uninstall.
-  const offer = npx
-    ? `     ${tone.muted}\`${INVOKED_AS ?? PRODUCT} --install\` also starts it at login${tone.reset}\n`
-    : "";
-  const outcome = await detachAndWatch({
-    file: fileURLToPath(import.meta.url),
-    argv: process.argv.slice(2),
-    logDir: deckLogDir(),
-    // Only the count, and only to decide whether deck.log is anybody's — see
-    // logMode. No handshake: this is a directory listing and a signal-0 each.
-    liveCount: (await registeredDecks().catch(() => [])).length,
-    isTTY,
-    profile,
-    columns: termColumns(process.stdout),
-    backgroundLine: `  ${tone.muted}${G.dash}  running in the background ${G.bullet} \`${stop}\` ends it${tone.reset}\n${offer}\n`,
-  });
-  // detachAndWatch never returns on the paths that worked. Reaching this line
-  // means the log could not be opened at all — a read-only home, a full disk —
-  // and a deck that will not start over a LOG is a worse answer than one that
-  // stays in the terminal, which is what every version before this did anyway.
-  console.error(`${PRODUCT}: could not open ${PRODUCT}'s log (${outcome.reason}) ${G.dash} staying in the foreground.`);
-}
-
-claimRestartFailureKey();
-
-// The port the worker actually bound, which is not necessarily the one it was
-// asked for — the first launch falls back to a random port when 4317 is taken.
-// Re-launching without this is how a restart silently moves the deck out from
-// under an open tab.
-let boundPort = null;
-let restarts = 0;
-let child = null;
-// The npx process fetching a replacement, while the worker above keeps serving.
-// Held separately from `child` for exactly that reason: for the length of a
-// fetch there are two of them, and only one is the deck.
-let fetching = null;
-// The upgrade this supervisor has committed to, from the moment the pre-flight
-// allowed it until the replacement is serving or the attempt has been written
-// off. giveUp runs long after the decision that permitted the attempt and has
-// to record that decision's count, not a fresh one.
-let attempting = null;
-// Set by the signal handlers, and the first thing every exit path asks. Without
-// it, Ctrl+C during an npx fetch looks exactly like a failed fetch, and a
-// worker that was already exiting 75 or 76 when the signal landed reads as a
-// restart request — both resurrect the deck the user just stopped.
-let stopping = false;
-// When this supervisor has put a crashed worker back, pruned to the window the
-// ceiling is counted in. See crashPolicy: a deck that dies once an hour comes
-// back every time; one that dies five times in ten minutes is broken, and the
-// answer to broken is to stop and say so rather than to spin.
-let crashes = [];
-
-function launch(respawn) {
-  // Asked on every spawn rather than once at boot: the deletion this catches
-  // happens while the deck is running, so a constant read at import time would
-  // be the one answer that cannot see it. See supervisor.mjs for the whole case.
-  const replaced = replacedNote({
-    workerExists: existsSync(WORKER),
-    moved: successorRoot(PKG_ROOT),
-    product: PRODUCT,
-    command: INVOKED_AS ?? PRODUCT,
-  });
-  if (replaced) {
-    console.error(replaced);
-    process.exit(1);
-  }
-  const args = [WORKER, ...process.argv.slice(2)];
-  // Appended last so it wins: the worker's parser keeps the final --port.
-  if (respawn && boundPort != null) args.push("--port", String(boundPort));
-
-  const worker = spawn(process.execPath, args, {
-    // stdio inherited so the child owns the same terminal the user started:
-    // same banner, same colours, same Ctrl+C. The fourth slot adds an IPC
-    // channel — the only way the worker can tell us which port it got, since
-    // parsing its stdout would be guesswork.
-    stdio: ["inherit", "inherit", "inherit", "ipc"],
-    env: {
-      ...process.env,
-      // Boot did the slow, once-per-session work already (hook install, the
-      // claude-swap probe with its 8s timeout, the ccusage prime). Repeating it
-      // is what would make a restart feel like a restart.
-      AGENTS_DECK_RESPAWN: respawn ? "1" : "",
-      AGENTS_DECK_RESTARTS: String(restarts),
-      // Empty for "we could not tell", which knownCommand reads as unknown just
-      // like an absent one. Set on the worker's environment only: the npx
-      // relaunch below spawns a whole new supervisor, and that one has to ask
-      // its own _npx directory rather than inherit an answer about a cache
-      // directory it is not running from.
-      AGENTS_DECK_INVOKED_AS: INVOKED_AS ?? "",
-    },
-  });
-
-  child = worker;
-
-  worker.on("message", (m) => {
-    if (!m || typeof m !== "object") return;
-    if (m.type === "listening" && typeof m.port === "number") boundPort = m.port;
-    // The worker saying its boot is finished — every row printed, the browser
-    // launched. Forwarded to whoever detached us, who has been tailing the log
-    // into the user's terminal and is waiting for exactly this to stop.
-    //
-    // GUARDED BY `process.connected`, AND GIVEN A CALLBACK, and it took a real
-    // crash restart to find out why: the launcher disconnects the moment the
-    // first boot finishes, so every LATER boot forwards this down a dead
-    // channel — and `process.send` on a closed channel does not throw where the
-    // call is, it emits 'error' on `process` a tick later. Unhandled, that ends
-    // the supervisor. So a try/catch here was decoration: the guard is the
-    // check, and the callback is what turns the remaining race (disconnect
-    // between the check and the send) into a value nobody has to catch.
-    else if (m.type === "booted" && process.connected) {
-      try { process.send({ type: "booted" }, () => {}); } catch { /* the launcher left */ }
-    }
-    // The worker asking to be replaced, while it is still serving. Answered by
-    // prefetchUpgrade, which is the whole of this file's new shape: the fetch
-    // happens here, and only then does that worker exit — see UPGRADE_CODE.
-    else if (m.type === "upgrade") prefetchUpgrade(worker);
-  });
-
-  worker.on("exit", (code, signal) => {
-    child = null;
-    // A fetch is for the worker that asked for it. That worker is gone, so the
-    // download is spent effort and the process holding it has to be stopped:
-    // left running it would keep writing into the npx cache directory the next
-    // attempt reads, minutes after the deck stopped waiting for it.
-    if (fetching) { killTree(fetching); fetching = null; attempting = null; }
-    // `stopping` outranks the exit code — see supervisor.mjs. A restart and a
-    // Ctrl+C can land together, and honouring the code first is how the deck
-    // came back to life after the user stopped it.
-    const next = workerExitAction(code, stopping);
-    if (next.relaunch === "disk") {
-      restarts++;
-      launch(true);
-      return;
-    }
-    if (next.relaunch === "npx") {
-      restarts++;
-      launchNpx();
-      return;
-    }
-    // THE DECK FELL OVER, and nobody is watching it any more.
-    //
-    // Before this ran in the background a crash was self-reporting: the terminal
-    // came back with the stack on it. Detached, the first sign is noticing hours
-    // later that a day of work was never recorded — so it goes back up. The
-    // whole of which crashes qualify is in isCrash, and the ceiling that stops
-    // this becoming a spin loop is in crashPolicy.
-    if (isCrash({ code, signal, served: boundPort != null, stopping })) {
-      const verdict = crashPolicy(crashes);
-      if (verdict.restart) {
-        crashes = verdict.history;
-        const how = signal ? `killed by ${signal}` : `exit ${code}`;
-        console.error(`${PRODUCT}: the deck stopped on its own (${how}) ${G.dash} starting it again in ${Math.round(verdict.delayMs / 1000)}s (${verdict.recent}/${CRASH_CEILING}).`);
-        restarts++;
-        // Unref'd would be wrong here: this timer IS the supervisor's reason to
-        // stay alive, and without it the event loop empties and the process
-        // exits before the deck it promised to bring back.
-        setTimeout(() => { if (!stopping) launch(true); }, verdict.delayMs);
-        return;
-      }
-      // Said once, with the two numbers that make it actionable, and then this
-      // process really does end — a supervisor that keeps trying forever is the
-      // failure the ceiling exists to prevent.
-      console.error(`${PRODUCT}: the deck has stopped ${CRASH_CEILING} times in ${Math.round(CRASH_WINDOW_MS / 60000)} minutes ${G.dash} not starting it again. Run \`${INVOKED_AS ?? PRODUCT}\` when you have looked at the log above.`);
-    }
-
-    // Anything else is the worker's own verdict and belongs to whoever started
-    // us — including the ccdeck wrapper, which exits with our code in turn. A
-    // worker killed by a signal is reported by dying of the same one; doing
-    // that naively re-enters the handlers below and exits 0 — see
-    // supervisor.mjs.
-    if (signal) dieOfSignal(signal);
-    else process.exit(next.code);
-  });
-
-  worker.on("error", (err) => {
-    console.error(`${PRODUCT}: could not start ${WORKER}: ${err.message}`);
-    process.exit(1);
-  });
-}
-
-/** Drop the two flags launchNpx sets itself. `--port` takes a value, and both
- *  spellings npm's parser accepts (`--port 4317`, `--port=4317`) have to go. */
-function withoutPortAndOpen(args) {
-  const out = [];
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === "--no-open") continue;
-    if (a === "--port") { i++; continue; } // and its value
-    if (a.startsWith("--port=")) continue;
-    out.push(a);
-  }
-  return out;
-}
-
-/**
- * Which package an npx upgrade here names, and the spec that installs it — or
- * null when this deck was not started by npx and there is nothing to re-run.
- *
- * One function because there is one answer, and the worker above us reaches it
- * independently: `upgradeName` in self-update.mjs resolves the npx case as
- * `bareSpecName(npxRestartSpec(pkgRoot, installedName(pkgRoot)))`, and
- * everything registry-shaped on that side — the dist-tag it fetched, the marker
- * it cached the answer in, the failure note the browser reads — is keyed by it.
- * This supervisor keyed the same four things off `npxRestartSpec(PKG_ROOT)`
- * with the module's own default, which is the literal string "agents-deck".
- *
- * Both read `_npx/<hash>/package.json`, so they agreed for as long as that
- * metadata was readable, and #340 made the disagreement matter when it is not:
- * the three names are one tarball now, so the manifest under a `npx ccdeck` run
- * genuinely says `ccdeck` where it once always said `agents-deck`. A cache
- * directory written by an npm whose `_npx.packages` layout differs — or a
- * truncated file — split the two apart: the worker asked npm about `ccdeck` and
- * read `.restart-failed-ccdeck-<pid>` while this process wrote
- * `.restart-failed-agents-deck-<pid>`, took `lastKnownLatest("agents-deck")`
- * off a marker nobody had written — so `target` was null and upgradeAttempt's
- * per-target cap degraded to "any failure counts" — and relaunched
- * `npx -y agents-deck@latest`, moving a `npx ccdeck` user onto a different
- * published name. The note went where the browser never looks, which is the
- * exact class of bug NOTE_PREFIX's naming exists to prevent.
- *
- * So the fallback is the name npm's rename wrote into this build's own manifest,
- * which is what the worker falls back to as well. Read on each call rather than
- * once at import for the reason installedVersion gives: the manifest is a file
- * on disk, and this process outlives more than one of them.
- */
-function npxUpgrade() {
-  const self = installedName(PKG_ROOT);
-  const spec = npxRestartSpec(PKG_ROOT, self);
-  return spec ? { spec, pkgName: bareSpecName(spec) ?? self } : null;
-}
-
-/** The note the browser reads, written by the only process that knows why an
- *  upgrade did not happen. `failedAt` is when the FETCH failed, which a refusal
- *  restating an earlier failure carries forward — see upgradeAttempt. */
-function noteFailure({ pkgName, spec, error, target, attempts, failedAt = Date.now() }) {
-  recordRestartFailure({
-    name: pkgName,
-    command: `npx -y ${spec}`,
-    error,
-    version: VERSION === "?" ? null : VERSION,
-    target,
-    attempts,
-    failedAt,
-  });
-}
-
-/**
- * Fetch the replacement while the deck this supervisor started keeps serving.
- *
- * The order used to be: kill the working deck, attempt, fail, rebuild the deck.
- * Every failed upgrade was therefore a real interruption — the SSE stream
- * dropped, hook events fired into the gap lost outright, the canvas back with
- * tools stuck in flight — and it was paid in full even when the update never
- * had a chance of working. Reported from a terminal that had been left alone:
- * the same version, the same ETARGET, the same teardown, four times over.
- *
- * npm can resolve and download without the deck dying. So the fetch is done
- * first, and the worker is only asked to exit once there is something to hand
- * the port to. There is never a second server: npxPrefetch installs the package
- * and runs nothing out of it, and the replacement is spawned only after this
- * process has watched the old worker's exit.
- *
- * A refusal costs nothing but the click. The deck keeps its port, its stream
- * and its hooks; the failure reaches the browser through the note, exactly as a
- * failed fetch always has.
- */
-async function prefetchUpgrade(worker) {
-  if (stopping || fetching || attempting) return;
-  const reply = (msg) => { try { worker.send?.(msg); } catch { /* the worker is gone */ } };
-
-  const upgrade = npxUpgrade();
-  // Not an npx run after all, so there is nothing to fetch and the files on
-  // disk are already the newest this deck can reach.
-  if (!upgrade) { reply({ type: "upgrade-refused", error: "this deck was not started by npx" }); return; }
-  const { spec, pkgName } = upgrade;
-  // What the banner offered, straight off the marker the version check writes.
-  // The note is keyed by it so that "this exact version already failed here" is
-  // a question anything can answer — and so a newer release clears the slate.
-  const target = lastKnownLatest(pkgName);
-
-  const note = readRestartFailure(pkgName);
-  const decision = upgradeAttempt({ note, target, now: Date.now() });
-  if (!decision.allow) {
-    const error = upgradeRefusalText({ ...decision, dash: G.dash }, target);
-    // Re-stamped even though nothing was attempted: the tab ends its attempt on
-    // a failure note it has not seen before, so a refusal that left the note
-    // untouched would leave the button reading "fetching…" for the full three
-    // minutes it allows, over a deck that never went anywhere.
-    noteFailure({
-      pkgName, spec, error, target,
-      attempts: decision.attempt,
-      failedAt: typeof note?.failedAt === "number" ? note.failedAt : Date.now(),
-    });
-    reply({ type: "upgrade-refused", error });
-    return;
-  }
-
-  attempting = { pkgName, spec, target, attempt: decision.attempt };
-  process.stdout.write(`\n  ${P.warn}${G.restart}${P.reset}  ${P.muted}fetching ${spec}${G.ellipsis}${P.reset}\n`);
-  const got = await npxPrefetch(spec, { onChild: (c) => { fetching = c; } });
-  fetching = null;
-  // Ctrl+C, or a worker that died on its own while npm was working: either way
-  // the deck this fetch was for is not there to be replaced, and the exit path
-  // that noticed has already had its say.
-  if (stopping || child !== worker) { attempting = null; return; }
-  if (got.ok) { reply({ type: "upgrade-ready" }); return; }
-
-  const error = [got.error, got.hint].filter(Boolean).join(" — ");
-  noteFailure({ pkgName, spec, error, target, attempts: decision.attempt });
-  attempting = null;
-  reply({ type: "upgrade-refused", error });
-}
-
-/**
- * Come back on a newer version, for a deck that npx started.
- *
- * There is nothing to install here: npx unpacks each spec into its own
- * content-addressed directory under _npx, so `npm i -g` would upgrade something
- * this process could never reach. `npx -y <spec>@latest` resolves fresh, gets a
- * DIFFERENT directory, and starts the deck there — on the port we hand it, so
- * the tab that asked for the update reconnects to the same URL.
- *
- * This process stays as the parent rather than exec-ing, for the same reasons
- * the file's header gives, plus one more: a fetch can fail (offline, registry
- * down), and someone has to bring the working copy back when it does.
- */
-function launchNpx() {
-  const upgrade = npxUpgrade();
-  if (!upgrade) { launch(true); return; } // not an npx run after all
-  // The same package prefetchUpgrade fetched and the worker asked npm about —
-  // one answer, so the spec that is run, the note that records it and the
-  // marker its target came from all name one package. See npxUpgrade.
-  const { spec, pkgName } = upgrade;
-  // Our two are appended, so the originals are dropped rather than left to be
-  // overridden — `--port 4317 --no-open --port 4317 --no-open` works, but it is
-  // what the next person reads in `ps`.
-  const args = ["-y", spec, ...withoutPortAndOpen(process.argv.slice(2))];
-  if (boundPort != null) args.push("--port", String(boundPort));
-  // The tab that asked for this is open and reconnecting; a second one would be
-  // the deck talking over itself.
-  args.push("--no-open");
-
-  // A retry answers for itself: whatever the last attempt left on disk is about
-  // to be replaced by this attempt's outcome, and leaving it there would keep
-  // the browser showing an old failure over a running fetch.
-  clearRestartFailure(pkgName);
-
-  // No "fetching…" line here any more: prefetchUpgrade printed it and the
-  // tarball is already unpacked, so this resolves out of the npx cache and the
-  // next thing on screen is the new deck's own banner.
-  //
-  // npxLaunch prefers npm's own npx-cli.js next to this Node binary, which
-  // needs no PATH lookup and no batch shim; the PATH shim is the fallback and
-  // still goes through cmd.exe with each argument quoted.
-  //
-  // Not `shell: true` on either path. Everything after the spec is the user's
-  // own argv, and Node would paste it into one command line unquoted:
-  // `--workspace C:\Users\John Smith\proj` would reach the new deck as two
-  // arguments, the second one silently dropped by its parser — an upgraded deck
-  // watching the wrong directory.
-  const { file, args: argv, opts } = npxLaunch(args);
-  // stderr is piped rather than inherited so a crash can be summarised instead
-  // of dumped: npm's MODULE_NOT_FOUND stack, with its `requireStack` and its
-  // caret line, is not something a user of a DAG dashboard can act on. stdout
-  // stays inherited — the new deck's banner, colours and URL line are the whole
-  // point of the supervisor staying out of the way.
-  const started = spawn(file, argv, { stdio: ["inherit", "inherit", "pipe"], ...opts });
-  child = started;
-
-  // Held, not discarded: the moment the replacement is serving, everything it
-  // wrote goes to the terminal and every later byte passes straight through.
-  // Until then it is only evidence for a failure that may not happen.
-  let tail = "";
-  let teeing = false;
-  const tee = () => {
-    if (teeing) return;
-    teeing = true;
-    if (tail) process.stderr.write(tail);
-  };
-  started.stderr?.on("data", (d) => {
-    const s = String(d);
-    if (teeing) { process.stderr.write(s); return; }
-    tail = (tail + s).slice(-8000);
-  });
-
-  // Whether the replacement ever got as far as serving. An npx that cannot
-  // resolve exits in seconds having bound nothing; a deck the user stops with
-  // Ctrl+C exits non-zero too, and only this tells the two apart.
-  let served = false;
-  const probe = setInterval(() => {
-    if (boundPort == null || served) return;
-    const sock = connect({ port: boundPort, host: "127.0.0.1" });
-    sock.setTimeout(1000);
-    sock.on("connect", () => { served = true; tee(); sock.destroy(); });
-    sock.on("timeout", () => sock.destroy());
-    sock.on("error", () => { /* not up yet */ });
-  }, 1000);
-  probe.unref?.();
-
-  const giveUp = (why) => {
-    clearInterval(probe);
-    child = null;
-    if (stopping || served) return; // the user stopped it, or it ran and ended
-    const summary = npxFailureSummary(tail);
-    const hint = npxFailureHint(tail);
-    console.error(`${PRODUCT}: ${why} ${G.dash} staying on v${VERSION}`);
-    if (summary) console.error(`  ${summary}`);
-    if (hint) console.error(`  ${hint}`);
-    // Left for the worker about to be launched: it is the only way the browser
-    // learns this happened at all. See recordRestartFailure.
-    //
-    // This is the outage the pre-flight cannot spare anyone: the fetch worked,
-    // the port was handed over, and the replacement still did not serve. It
-    // counts against the same target as any other failed attempt, so a copy
-    // that starts and dies is not offered forever either.
-    noteFailure({
-      pkgName, spec,
-      error: [summary ?? why, hint].filter(Boolean).join(" — "),
-      target: attempting?.target ?? null,
-      attempts: attempting?.attempt ?? 1,
-    });
-    attempting = null;
-    restarts++;
-    launch(true);
-  };
-
-  started.on("exit", (code, signal) => {
-    clearInterval(probe);
-    child = null;
-    if (stopping || served) {
-      if (signal) dieOfSignal(signal);
-      else process.exit(code ?? 0);
-      return;
-    }
-    giveUp(`npx ${spec} exited ${code ?? signal}`);
-  });
-  started.on("error", (err) => giveUp(`could not run npx: ${err.message}`));
-}
-
-// Ctrl+C already reaches the child directly — it shares this process group — so
-// forwarding would deliver it twice. These handlers exist only to keep the
-// supervisor alive long enough for the child's own graceful shutdown to run and
-// for its exit code to arrive.
-for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
-  process.on(sig, () => {
-    // On Windows none of these are delivered to a Node process, which is fine:
-    // there the console kills the whole tree and sweepStaleDiscovery cleans up
-    // on the next boot.
-    const second = stopping; // an impatient user pressing Ctrl+C again
-    stopping = true;
-    // A fetch in flight is not the deck and does not stop with it. On POSIX the
-    // Ctrl+C that reached us reached it too — it is in this process group — but
-    // a plain `kill` of the supervisor, or a systemd stop, is not, and on
-    // Windows the shim path leaves npm as a grandchild of cmd.exe that only
-    // killTree can reach. Stopped before the worker, since the worker's own
-    // exit path is what ends this process.
-    if (fetching) { killTree(fetching, second ? "SIGKILL" : sig); fetching = null; }
-    if (!child) { process.exit(0); return; }
-    try { child.kill(second ? "SIGKILL" : sig); } catch { /* already gone */ }
-    // The npx step is a shell that exec's the new deck, and a signal can land in
-    // the gap: the shell dies, the process replacing it never saw it. One more
-    // attempt a moment later catches that; it is a no-op when the first worked.
-    if (!second) {
-      setTimeout(() => {
-        if (stopping && child) { try { child.kill("SIGTERM"); } catch { /* gone */ } }
-      }, 2500).unref();
-    }
-  });
-}
-
-// And the same leash the worker is on, one link up (#702).
-//
-// Inert for every published way of starting the deck: `ccdeck`, `npx ccdeck` and
-// the npx relaunch in launchNpx all spawn this file with no IPC channel, so
-// dieWithParent declines to arm and this line costs nothing. It is armed by a
-// harness that DOES hand one over — the suite's spawnSupervised — and what it
-// buys there is the case no teardown can cover, because the teardown is not
-// running: a vitest worker killed outright leaves this supervisor orphaned, and
-// an orphaned supervisor keeps a worker alive under it.
-//
-// Taking the worker with us is the whole of the stop. `stopping` first, so the
-// worker's exit is not read as a request to bring it back; the kill is the
-// signal on POSIX and, through killTree, `taskkill /T /F` on Windows, which has
-// neither SIGTERM nor a process group to aim at.
-// NOT IN THE DETACHED COPY. There the parent is the launcher, which disconnects
-// and exits the moment the deck is up — by design — and arming this would have
-// the deck kill itself a second after every successful start.
-if (!DETACHED) dieWithParent(() => {
-  stopping = true;
-  if (fetching) { killTree(fetching, "SIGTERM"); fetching = null; }
-  if (child) killTree(child, "SIGTERM");
-  // Long enough for the worker to unregister its discovery file and let the
-  // port go, short enough that nothing is waiting on us. Unref'd: if the worker
-  // leaves first its exit handler ends this process and the timer never fires.
-  setTimeout(() => process.exit(0), 3000).unref();
-});
-
-launch(false);