agent-dag 3.22.1 → 3.22.3

package/src/server/stop-deck.mjs

@@ -1,171 +0,0 @@
-// Ending a deck that is not our child.
-//
-// `ccdeck --stop` holds a pid and a port out of a discovery file and nothing
-// else — no ChildProcess, no IPC channel, no shell job. That rules out
-// exec.mjs's killTree, which takes a ChildProcess and calls `child.kill`, and it
-// is why the Windows half of that function is spelled a second time here rather
-// than shared: the two have the same shape and different inputs.
-//
-// THREE RUNGS, and each one exists for a failure the one above it cannot cover:
-//
-//   THE POST. /api/shutdown, with the token out of the record, ending in the
-//   deck's own shutdown(): the listener closes, the registration is unlinked,
-//   the LAN beacon says goodbye so paired colleagues see it LEAVE rather than
-//   time out. This is the rung that behaves identically on all three platforms,
-//   which is the whole reason the route exists — Windows has no signals.
-//
-//   SIGTERM, POSIX only. Not a fallback for a wedged deck — a wedged deck is
-//   wedged for this too — but the only way to end a deck OLDER than the route,
-//   which answers the POST with a 404 and would otherwise be unstoppable by its
-//   own command. bin/deck.js has handled SIGTERM with shutdown(0) for years, so
-//   this is still a clean exit on every version that has ever shipped.
-//
-//   THE HARD KILL. SIGKILL, or `taskkill /T /F` on Windows. Leaves the discovery
-//   file behind for the next boot to sweep and gives the LAN no goodbye, and is
-//   still better than a process the user cannot end with the tool that started
-//   it — which is the outcome this whole file is written against.
-//
-// THE PARENT GOES FIRST on both kill rungs. A worker killed under a live
-// supervisor is a worker the supervisor puts back: that is what it is for. So
-// the supervisor is ended first and the worker second, which is also what the
-// record's `parent` field is written for.
-import { request as httpRequest } from "node:http";
-import { spawn } from "node:child_process";
-import { isProcessAlive } from "./deck-probe.mjs";
-
-/** Long enough for a loopback POST and the deck's own teardown to begin; short
- *  enough that a wedged deck does not hold the terminal. */
-export const STOP_ASK_MS = 2000;
-/** How long a deck gets to actually disappear after each rung. A clean shutdown
- *  drains SSE connections and closes the listener; 1500ms of that is the
- *  fallback timer in bin/deck.js's shutdown(), so this has to outlast it. */
-export const STOP_GONE_MS = 3000;
-
-/**
- * Ask one deck to end itself, politely.
- *
- * Never rejects: every failure is a verdict the caller has a next rung for. A
- * 404 is a deck too old to know the route, a refused connection is a record
- * whose port is already gone, a timeout is a deck that is not answering — and
- * all three lead to the same place.
- */
-export function askDeckToStop(rec, { timeoutMs = STOP_ASK_MS, request = httpRequest } = {}) {
-  return new Promise(resolve => {
-    let settled = false;
-    const finish = (v) => { if (settled) return; settled = true; resolve(v); };
-    let req;
-    try {
-      req = request({
-        hostname: "127.0.0.1",
-        port: rec.port,
-        path: "/api/shutdown",
-        method: "POST",
-        timeout: timeoutMs,
-        headers: {
-          // The one spelling the server reads. The token came out of a file
-          // only this user can open, which is the whole of the access control.
-          "x-ccdeck-token": String(rec.token ?? ""),
-          "content-length": "0",
-        },
-      }, res => {
-        // The body is drained rather than read: the verdict is the status, and
-        // a response left unconsumed keeps the socket open past our exit.
-        res.resume();
-        res.on("end", () => finish({
-          ok: res.statusCode === 200,
-          status: res.statusCode ?? 0,
-          // A route that is not there is a deck older than this feature, and
-          // the caller says so rather than reporting a mysterious refusal.
-          old: res.statusCode === 404,
-        }));
-      });
-    } catch (err) {
-      return finish({ ok: false, status: 0, old: false, reason: err?.code ?? "request_failed" });
-    }
-    req.on("error", (err) => finish({ ok: false, status: 0, old: false, reason: err?.code ?? "unreachable" }));
-    req.on("timeout", () => { req.destroy(); finish({ ok: false, status: 0, old: false, reason: "timeout" }); });
-    req.end();
-  });
-}
-
-/**
- * End a pid and everything under it.
- *
- * exec.mjs's killTree with a pid where its ChildProcess goes — see the note at
- * the top of this file. `/T` is the half that matters: the supervisor's worker
- * is a child of the pid being ended, and on Windows there is no process group
- * to signal as one.
- *
- * On Windows a "polite" rung does not exist. `taskkill` without `/F` posts
- * WM_CLOSE to a window, and the deck has none, so the only thing to do there is
- * the forceful one — which is why the caller skips the SIGTERM rung on win32
- * rather than running it twice under a different name.
- */
-export function killPidTree(pid, signal = "SIGTERM", {
-  platform = process.platform, spawnFn = spawn, kill = (p, s) => process.kill(p, s),
-} = {}) {
-  if (!Number.isInteger(pid) || pid <= 0) return;
-  const plain = () => { try { kill(pid, signal); } catch { /* already gone */ } };
-  if (platform !== "win32") return plain();
-  try {
-    const root = process.env.SystemRoot || process.env.systemroot;
-    const exe = root ? `${root}\\System32\\taskkill.exe` : "taskkill";
-    const killer = spawnFn(exe, ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
-    killer.on("error", plain);
-    killer.on("exit", (code) => { if (code !== 0) plain(); });
-    killer.unref?.();
-  } catch {
-    plain();
-  }
-}
-
-/** Has this pid actually gone, within the deadline? Polled rather than waited
- *  on: this process is not the parent, so there is no exit to listen for. */
-async function gone(pid, { alive, deadlineMs, sleep, now }) {
-  const until = now() + deadlineMs;
-  for (;;) {
-    if (!alive(pid)) return true;
-    if (now() >= until) return false;
-    await sleep(50);
-  }
-}
-
-/**
- * Stop one deck, and say how it went out.
- *
- * `how` is not decoration. "asked" means the deck closed its listener, unlinked
- * its registration and left the LAN cleanly; "killed" means none of that
- * happened and the next boot has litter to sweep. A command that reported both
- * as "stopped" would hide the one case worth knowing about.
- */
-export async function stopDeck(rec, {
-  ask = askDeckToStop,
-  alive = isProcessAlive,
-  kill = killPidTree,
-  platform = process.platform,
-  now = Date.now,
-  sleep = (ms) => new Promise(r => setTimeout(r, ms)),
-  askMs = STOP_ASK_MS,
-  goneMs = STOP_GONE_MS,
-} = {}) {
-  const wait = () => gone(rec.pid, { alive, deadlineMs: goneMs, sleep, now });
-  const parent = Number.isInteger(rec.parent) ? rec.parent : null;
-
-  const answer = await ask(rec, { timeoutMs: askMs });
-  if (answer.ok && await wait()) return { ok: true, how: "asked" };
-
-  if (platform !== "win32") {
-    // Parent first: see the note at the top. A supervisor left alive over a
-    // killed worker is a supervisor doing its job, which here means undoing
-    // ours.
-    if (parent !== null) kill(parent, "SIGTERM", { platform });
-    kill(rec.pid, "SIGTERM", { platform });
-    if (await wait()) return { ok: true, how: "signalled", old: answer.old === true };
-  }
-
-  if (parent !== null) kill(parent, "SIGKILL", { platform });
-  kill(rec.pid, "SIGKILL", { platform });
-  if (await wait()) return { ok: true, how: "killed", old: answer.old === true };
-
-  return { ok: false, how: "stuck", reason: answer.reason ?? `http ${answer.status}` };
-}

package/src/server/supervisor.mjs

@@ -1,392 +0,0 @@
-// What bin/agent-dag.js does when the worker dies: bring it back, fetch a
-// newer one, or let the whole thing stop — and, for a worker that was killed
-// rather than exited, how to hand that on to whoever started the deck. Plus the
-// question that now comes BEFORE any of that, since the fetch happens while the
-// worker is still serving: whether this upgrade is worth attempting at all.
-//
-// It lives here rather than inline in the supervisor because the supervisor
-// launches a real child process the moment it is imported, so the rule could
-// not be checked any other way — and it is a rule with a race in it.
-//
-// The race: the worker exits 75 because the user clicked Restart, and Ctrl+C
-// lands in the same instant. The supervisor's signal handler runs first and
-// sets `stopping`, then the exit event arrives carrying 75 — and a supervisor
-// that reads the code without asking whether it is still supposed to be
-// running spawns a fresh deck AFTER the user stopped it. That deck prints
-// `restarted → vX` over the shutdown and keeps serving until the handler's
-// 2.5s retry timer happens to kill it; the 76 variant starts a whole npx
-// registry fetch first. So `stopping` outranks the code, always.
-//
-// Ctrl+C reaches this process on every platform we support — POSIX delivers it
-// to the foreground process group, and on Windows the console raises
-// CTRL_C_EVENT for every process attached to it, which Node surfaces as
-// 'SIGINT'. What differs is only how the child dies, which is not this
-// function's business.
-
-import { constants } from "node:os";
-
-// Chosen because they mean nothing else here: the worker exits 0 normally and
-// non-zero on failure, both of which must pass straight through.
-export const RESTART_CODE = 75; // come back running the files on disk
-export const UPGRADE_CODE = 76; // come back through npx, which fetches newer files
-
-/**
- * What a dead worker means.
- *
- *   { relaunch: "disk" }  — spawn it again from the files on disk
- *   { relaunch: "npx" }   — spawn it again through npx, which fetches newer ones
- *   { relaunch: null, code } — stop, exiting with `code`
- *
- * `stopping` is a parameter rather than the supervisor's module-level flag for
- * the same reason `spawnSpec` takes a platform: it is the input that decides
- * the answer, and both answers have to be testable.
- *
- * A stop exits 0 for 75 and 76. Those two are a private protocol between the
- * worker and its supervisor — nobody outside knows they mean "come back", and
- * 75 is EX_TEMPFAIL to anything that reads sysexits, so handing either to the
- * shell would report a failure the user did not have. Every other code is the
- * worker's own verdict and passes through untouched.
- */
-export function workerExitAction(code, stopping) {
-  const ours = code === RESTART_CODE || code === UPGRADE_CODE;
-  if (ours && !stopping) return { relaunch: code === UPGRADE_CODE ? "npx" : "disk" };
-  return { relaunch: null, code: ours ? 0 : code ?? 0 };
-}
-
-// ── putting a crashed deck back ──────────────────────────────────────────────
-//
-// Before the deck ran in the background, a crash was self-reporting: the
-// terminal came back, the stack was on screen, and you knew within a second.
-// Detached, nothing says anything. The deck stops receiving hook events, stops
-// answering the LAN beacon, stops watching the quota — and the first sign is
-// noticing, hours later, that a day of work was never recorded.
-//
-// So the supervisor puts it back. WITH A CEILING, because the other failure is
-// worse than the one being fixed: a deck that dies on its own boot, respawned
-// forever, is a process spinning on a machine nobody is watching, writing the
-// same stack into the same log a thousand times an hour.
-//
-// The window is what makes the ceiling mean "is this broken" rather than "how
-// long has this machine been up". Five crashes in ten minutes is a deck that
-// cannot run; five crashes over three weeks is a machine that went to sleep
-// oddly three times, and putting it back each time is exactly right.
-
-/** Five, then stop and say why. */
-export const CRASH_CEILING = 5;
-/** The window those five are counted in. */
-export const CRASH_WINDOW_MS = 10 * 60 * 1000;
-/** The first wait, doubling per crash inside the window. */
-export const CRASH_BACKOFF_MS = 1000;
-/** …and where the doubling stops. Past this the delay is no longer protecting
- *  anything: five attempts at 30s already span most of the window. */
-export const CRASH_BACKOFF_MAX_MS = 30_000;
-
-/**
- * Should this crash be answered with another deck, and after how long?
- *
- * `history` is the timestamps of the crashes already answered; the caller adds
- * this one only if the answer is yes, so a refusal does not push the count
- * further out of reach.
- *
- * The backoff doubles rather than waiting a fixed beat, because the two shapes
- * of crash want opposite things. A deck that falls over once an hour should
- * come back immediately — a second of downtime is a second of unrecorded work.
- * A deck that dies in its own first instruction should be tried slowly enough
- * that the log is readable and the CPU is idle between attempts.
- */
-export function crashPolicy(history = [], {
-  now = Date.now(),
-  ceiling = CRASH_CEILING,
-  windowMs = CRASH_WINDOW_MS,
-  backoffMs = CRASH_BACKOFF_MS,
-  maxMs = CRASH_BACKOFF_MAX_MS,
-} = {}) {
-  const recent = history.filter(t => now - t < windowMs);
-  if (recent.length >= ceiling) {
-    return { restart: false, delayMs: 0, recent: recent.length, history: recent };
-  }
-  return {
-    restart: true,
-    delayMs: Math.min(backoffMs * 2 ** recent.length, maxMs),
-    recent: recent.length + 1,
-    // The pruned list, so a caller that keeps it does not carry crashes from
-    // last Tuesday into this decision forever.
-    history: [...recent, now],
-  };
-}
-
-/**
- * Was this a deck falling over, as opposed to one leaving?
- *
- * THREE THINGS HAVE TO BE TRUE, and each one removes a way this could respawn
- * something nobody asked for:
- *
- *   It was UP. `served` is the supervisor having seen the worker bind a port. A
- *   worker that never got that far did not crash, it failed to start — a port
- *   the OS will not give us, a `dist/` that was never built — and retrying that
- *   five times prints the same refusal six times and fixes nothing.
- *
- *   We are not STOPPING. Ctrl+C, a SIGTERM, and `--stop`'s fallback ladder all
- *   set it, and every one of them is somebody asking for this deck to be gone.
- *
- *   It did not exit ZERO. That is the deck ending itself — the shutdown that
- *   /api/shutdown runs, which is what `ccdeck --stop` asks for. Answering a
- *   clean stop with a restart would make the off switch a no-op.
- *
- * A signal counts as a crash. `kill -9` on the worker alone is an OOM killer or
- * a stray hand, not a request to end the deck: `--stop` ends the supervisor
- * FIRST precisely so that this rule and that ladder do not fight.
- */
-export function isCrash({ code, signal, served, stopping } = {}) {
-  if (!served || stopping) return false;
-  if (signal) return true;
-  return code !== 0 && code !== null && code !== undefined;
-}
-
-/**
- * How to report a worker that did not exit at all but was killed by a signal.
- *
- *   { reraise: "SIGHUP", code: 129 } — die of the same signal; `code` is only
- *                                      the fallback if that somehow returns
- *   { reraise: null, code: 129 }     — no signal to die of, exit with the number
- *
- * A supervisor that just exits 0 here tells the shell the deck stopped cleanly
- * after somebody killed it. The status a caller expects is the shell's own
- * convention, 128 + the signal number: 129 for SIGHUP, 143 for SIGTERM. On
- * POSIX the honest way to produce it is to die of the signal rather than to
- * exit with the arithmetic — only that also sets the "killed by a signal" bit
- * every wait(2)-based caller reads, and `$?` comes out the same either way.
- *
- * Windows has no signals: a process there cannot die of one, and `process.kill`
- * against ourselves would be a TerminateProcess with an unrelated status. So
- * the number is all we can offer, and it is still better than 0 — the deck was
- * killed, and whatever started it should be able to see that.
- *
- * The signal numbers come from `os.constants.signals`, which is also the table
- * `process.kill` accepts, so a name missing from it is a name we could not
- * re-raise anyway; it becomes a plain failure exit.
- */
-export function signalExitAction(signal, platform = process.platform, numbers = constants.signals) {
-  const n = numbers?.[signal];
-  if (typeof n !== "number") return { reraise: null, code: 1 };
-  return { reraise: platform === "win32" ? null : signal, code: 128 + n };
-}
-
-/**
- * End this process the way the worker ended: killed by `signal`.
- *
- * The re-raise is the obvious half and on its own it does not work, which is
- * the reason this is a function rather than one line at the call site. The
- * supervisor traps SIGINT, SIGTERM and SIGHUP — and those are exactly the
- * signals a worker is most likely to die of, since deck.js does not handle
- * SIGHUP at all and registers the other two only after a boot that takes
- * seconds. For all three the re-raise lands back in our own handler, which
- * finds no child left and exits 0: `kill -HUP` on the deck was reported to the
- * shell as a clean, successful stop. Dropping the handler first restores the
- * default action, which is to die of the signal.
- *
- * `proc` is a parameter so the whole sequence can be driven in a test child.
- */
-/**
- * What to say when the upgrade that just succeeded took this install with it,
- * or null when that is not what happened.
- *
- * `npm i -g ccdeck` performed before #340 nests the deck inside a launcher
- * package. Upgrading such an install now writes the deck itself over that
- * launcher, and npm's reify removes everything that was underneath — including
- * the directory this supervisor and its worker are running from. The process
- * survives, because everything it needs is already loaded. The next spawn does
- * not: bin/deck.js is a path, and npm has just deleted it.
- *
- * That reached the user as `could not start …/bin/deck.js: ENOENT` and an exit
- * 1 — a dead deck and an errno, one click after an upgrade that reported
- * success. Nothing was broken. The new version is on the machine, and the
- * command they typed already points at it, because npm rewrote the bin shim in
- * the same install. The only thing missing was a sentence saying so.
- *
- * Deliberately not a hand-off. This process could spawn the successor's worker
- * instead, and that would be a new worker under an old supervisor — a pair
- * nothing has ever tested together, decided at the worst possible moment. One
- * command the user runs themselves is the smaller promise and the one that
- * cannot go wrong.
- *
- * Pure, and given its two filesystem answers rather than asking for them,
- * because the state it describes only ever exists in a process whose own files
- * were deleted after it started — which no test can produce by spawning one.
- */
-export function replacedNote({ workerExists, moved, product = "ccdeck", command = "ccdeck" }) {
-  if (workerExists || !moved) return null;
-  return [
-    `${product}: the upgrade replaced this install, so it cannot restart in place.`,
-    `  the new version is in ${moved}`,
-    `  run \`${command}\` again to start it`,
-  ].join("\n");
-}
-
-export function dieOfSignal(signal, proc = process) {
-  const { reraise, code } = signalExitAction(signal, proc.platform);
-  if (reraise) {
-    proc.removeAllListeners(reraise);
-    try { proc.kill(proc.pid, reraise); } catch { /* fall through to the number */ }
-  }
-  // Reached on Windows, and on POSIX only when the signal is ignored or
-  // blocked — inherited dispositions survive spawn — so the kill above returns
-  // instead of ending us.
-  proc.exit(code);
-}
-
-// ── how often an upgrade that failed may be attempted again ──────────────────
-//
-// Reported from a terminal that had been left alone: the same version, the same
-// npm error, the same teardown, four times over. Nothing anywhere remembered
-// that this exact target had already failed, so every path back into the deck
-// offered the identical attempt — and each one cost a real interruption.
-//
-// Five minutes is chosen against what actually fails. A registry blip or a
-// version that has not finished propagating is gone well inside it; being
-// offline, behind a proxy that blocks the registry, or on the broken npx shim
-// of #184 is not, and no amount of retrying will change that. So the second
-// attempt waits, and there is no third: the copyable command is already on
-// screen beside the failure and is the honest escape hatch. A newer target
-// resets both — that is a different question, and it deserves its own answer.
-export const UPGRADE_COOLDOWN_MS = 300_000;
-export const UPGRADE_MAX_ATTEMPTS = 2;
-
-/** Whether a note on disk is a failure at all, and one about `target`.
- *
- *  Both sides of the comparison can be null — the version check is cached for
- *  an hour and can be off entirely — and two unknowns count as the same target
- *  rather than as two different ones. Guessing "different" would hand back the
- *  unbounded retry this exists to end. A note from a deck older than this rule
- *  carries no target at all, which is genuinely unknown against a target we do
- *  know, so it is not held against a fresh version. */
-function noteAbout(note, target) {
-  if (!note || typeof note.error !== "string" || !note.error) return false;
-  return (note.target ?? null) === (target ?? null);
-}
-
-/** How many attempts the note already stands for. A note written before this
- *  rule existed has no count and is exactly one failure. */
-function attemptsOf(note) {
-  return Number.isInteger(note?.attempts) && note.attempts > 0 ? note.attempts : 1;
-}
-
-/** When the attempt behind the note actually failed, which is not when the note
- *  was last written: a refusal re-stamps `at` so the browser can tell it from
- *  the failure before it, and the cooldown must not be pushed out by being
- *  asked. */
-function failedAtOf(note) {
-  if (typeof note?.failedAt === "number") return note.failedAt;
-  return typeof note?.at === "number" ? note.at : null;
-}
-
-/**
- * Whether an upgrade to `target` may be attempted, given what the last one left
- * behind.
- *
- *   { allow: true, attempt: n }                     — go ahead; this is the nth
- *   { allow: false, reason: "cooling", waitMs, attempt }
- *   { allow: false, reason: "exhausted", attempt }
- *
- * Pure, and the note is a parameter rather than a read, because this is the
- * rule that has to terminate an unattended loop and a rule worth a bug is worth
- * a test.
- */
-export function upgradeAttempt({
-  note, target = null, now = Date.now(),
-  cooldownMs = UPGRADE_COOLDOWN_MS, maxAttempts = UPGRADE_MAX_ATTEMPTS,
-} = {}) {
-  if (!noteAbout(note, target)) return { allow: true, attempt: 1 };
-  const attempt = attemptsOf(note);
-  if (attempt >= maxAttempts) return { allow: false, reason: "exhausted", attempt, waitMs: 0 };
-  const failedAt = failedAtOf(note);
-  // A clock that moved backwards — a laptop waking, an NTP correction — must
-  // not leave the deck cooling forever, so an unmeasurable wait counts as
-  // elapsed. The attempt cap is what makes that safe: it holds however the
-  // clock behaves, and it is the half that ends the loop.
-  const waited = typeof failedAt === "number" && now >= failedAt ? now - failedAt : cooldownMs;
-  if (waited < cooldownMs) {
-    return { allow: false, reason: "cooling", attempt, waitMs: cooldownMs - waited };
-  }
-  return { allow: true, attempt: attempt + 1 };
-}
-
-/** The refusal as the deck should state it — this is the whole of what the
- *  banner and the terminal say, so it has to name the version, say what already
- *  happened to it, and leave the user somewhere to go. The copyable command is
- *  already on screen next to it. */
-export function upgradeRefusalText({ reason, waitMs = 0, attempt = 0, dash = "—" } = {}, target = null) {
-  const what = target ? `v${target}` : "this update";
-  if (reason === "exhausted") {
-    return `${what} failed to fetch ${attempt} times ${dash} not trying again from here; run the command yourself`;
-  }
-  const left = waitMs >= 60_000 ? `${Math.ceil(waitMs / 60_000)}m` : `${Math.max(1, Math.ceil(waitMs / 1000))}s`;
-  return `${what} failed to fetch a moment ago ${dash} waiting ${left} before trying again`;
-}
-
-/**
- * Die when the process that started this one does — on all three operating
- * systems (#702).
- *
- * The deck is two processes: bin/agent-dag.js supervises, bin/deck.js serves.
- * The supervisor kills the worker on every path it knows about — a restart, an
- * upgrade, a Ctrl+C, its own exit — and cannot kill it on the one path it never
- * gets to run: being killed itself. SIGKILL cannot be handled, a crash runs no
- * handler, and a `taskkill` without `/T` reaches only the process it names. On
- * POSIX the worker is then re-parented to init and keeps its port, its temp
- * directory and its 40-60 MB of RSS forever. 310 of those were alive on one
- * development machine, the oldest a day and four hours old, every one a worker
- * whose supervisor a test's teardown had SIGKILLed.
- *
- * WHY THE IPC CHANNEL, AND NOT ANY OF THE OBVIOUS ALTERNATIVES. The requirement
- * is one signal meaning "whoever started me is gone", and the usual answers are
- * each missing a platform:
- *
- *   • `process.ppid === 1` — POSIX re-parents an orphan to init, so polling ppid
- *     works there and answers nothing on Windows, which does not re-parent at
- *     all: the ppid goes on naming a pid that no longer exists.
- *   • process groups and `kill(-pgid)` — a POSIX concept. Windows job objects
- *     are the nearest equivalent and Node exposes none of it.
- *   • a SIGTERM the parent sends on its way out — Windows delivers no signals to
- *     a Node process, so `process.on("SIGTERM")` there never fires; and a parent
- *     that was killed sends nothing anywhere.
- *
- * The channel is the one mechanism that behaves the same everywhere, because
- * Node normalises it: a Unix socketpair on POSIX, a named pipe on Windows, both
- * closed by the kernel when the process holding the other end stops existing,
- * however it stopped. Node turns that close into a single `disconnect` event on
- * the child's own `process`, and it arrives for a SIGKILL, a crash, a
- * `taskkill /F`, a closed console window and an ordinary exit alike. That is the
- * same reasoning the header above gives for Ctrl+C: what differs between
- * platforms is how a process dies, not that this notices.
- *
- * The channel is not created for this. It already carries `{type:"listening"}`
- * and the upgrade handshake; this only says what its closure means.
- *
- * ARMED ONLY WHERE THERE IS A PARENT TO DIE WITH — `process.send` is a function
- * exactly when a channel was given. `node bin/deck.js` run by hand has none, and
- * that is the same question `SUPERVISED` in bin/deck.js already asks before it
- * offers /api/restart.
- *
- * WHAT IT DELIBERATELY DOES NOT COVER: a parent that calls `child.disconnect()`
- * and stays alive would look identical from here. Nothing in this repo does
- * that, and the alternative — an "are you still there" ping — is a second
- * protocol to keep correct in exchange for a case that does not exist.
- *
- * Returns whether a leash was armed, so a caller can state it rather than infer
- * it. `proc` is a parameter for the reason `workerExitAction` takes `stopping`:
- * the behaviour has to be checkable without a second process.
- */
-export function dieWithParent(stop, proc = process) {
-  if (!proc || typeof proc.once !== "function" || typeof proc.send !== "function") return false;
-  let done = false;
-  proc.once("disconnect", () => {
-    if (done) return;
-    done = true;
-    // A stop that throws must still end the process: the whole point is that
-    // nothing is left behind, and there is no parent left to notice a child
-    // that failed to leave.
-    try { stop(); } catch { proc.exit?.(0); }
-  });
-  return true;
-}