synabun 2.0.10 → 2.1.0

package/lib/release-scan.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/** Shared required scan stage; failures still write auditable reports. */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { applyReviews, credentials, hashFile, reports, VirusTotal } from './virustotal.mjs';
+
+export async function scanRelease({ files = [], urls = [], out, prefix = 'virustotal', reviewFile, client = new VirusTotal(), now = Date.now() }) {
+  if (!files.length && !urls.length) throw new Error('No scan subjects supplied');
+  const items = [];
+  for (const file of files) {
+    const path = typeof file === 'string' ? file : file.path;
+    const expected = typeof file === 'string' ? undefined : file.sha256;
+    // Missing/mismatched local bytes are hard errors, never reviewable detections.
+    const sha256 = await hashFile(path);
+    if (expected && sha256 !== expected) throw new Error(`SHA-256 mismatch: ${basename(path)}`);
+    try { items.push(await client.file(path, sha256)); }
+    catch (error) { items.push({ kind: 'file', name: basename(path), sha256, status: 'error', analysis_status: 'unavailable', error: error.message }); }
+  }
+  for (const url of urls) {
+    try { items.push(await client.url(url)); }
+    catch (error) { items.push({ kind: 'url', name: url, status: 'error', analysis_status: 'unavailable', error: error.message }); }
+  }
+  const reviews = reviewFile ? JSON.parse(await readFile(reviewFile, 'utf8')) : [];
+  const result = reports(applyReviews(items, reviews, now));
+  await mkdir(out, { recursive: true });
+  await writeFile(resolve(out, `${prefix}.json`), result.json);
+  await writeFile(resolve(out, `${prefix}.md`), result.markdown);
+  if (!result.report.approved) throw new Error(`VirusTotal gate blocked; inspect ${prefix}.json/.md. Retry failures/inconclusive scans; detections require a hash- and evidence-specific review (docs/release-pipeline.md).`);
+  return result;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    credentials();
+    const files = []; const urls = []; let out, reviewFile, prefix = 'virustotal';
+    const args = process.argv.slice(2);
+    while (args.length) {
+      const arg = args.shift();
+      if (arg === '--out') out = args.shift();
+      else if (arg === '--prefix') prefix = args.shift();
+      else if (arg === '--review') reviewFile = args.shift();
+      else if (arg === '--url') urls.push(args.shift());
+      else if (arg.startsWith('-')) throw new Error(`Unknown option: ${arg}`);
+      else files.push(arg);
+    }
+    if (!out) throw new Error('Usage: node lib/release-scan.mjs --out DIR [--review FILE] [--url https://synabun.ai/] [FILE ...]');
+    if (!['virustotal', 'npm-virustotal'].includes(prefix)) throw new Error('Use prefix virustotal or npm-virustotal');
+    await scanRelease({ files, urls, out, prefix, reviewFile });
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/lib/server-crash-record.js

@@ -0,0 +1,123 @@
+/**
+ * SynaBun — the record of a crash the supervisor recovered from
+ *
+ * When the server crashes after it was up, its supervisor (lib/server-supervisor.js)
+ * starts it again and leaves this record for the server it starts:
+ * DATA_HOME/data/server-crash.json. That server shows it to the owner's pages
+ * (GET /api/system/crash-notice, neural-interface/lib/crash-notice-api.js) until
+ * it is dismissed; a dismissal removes it, so it stays gone in every tab and
+ * window, and the next crash writes a new one, with a new id, which shows again.
+ *
+ * One writer at a time: the supervisor writes the record only while no server
+ * runs (between a crash and the next start) and removes it when it ends without
+ * a running server after all (the crash-loop guard gave up, the server it
+ * started again never came up: the app's stopped page says what happened then);
+ * the server removes it, while it runs, when the owner dismisses it. Nothing is
+ * written for a stop, a restart, an update or a start that failed.
+ *
+ * Never throws. `fs` can be handed in (tests).
+ */
+
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const CRASH_RECORD_NAME = 'server-crash.json';
+export const CRASH_RECORD_VERSION = 1;
+
+const NODE_FS = Object.freeze({ mkdirSync, readFileSync, renameSync, rmSync, writeFileSync });
+const ID = /^[0-9a-f]{16}$/;
+const HEX = /^0x[0-9A-F]{8}$/;
+const SIGNAL = /^SIG[A-Z0-9]{1,10}$/;
+const KIND = /^[a-z][a-z-]{0,23}$/;
+
+/** Where the record is: beside the supervisor record and the server's logs. */
+export function crashRecordPath(dataHome) {
+  return join(dataHome, 'data', CRASH_RECORD_NAME);
+}
+
+/** A record, checked field by field (what a page is shown comes from here only); null when it is not one. */
+export function normalizeCrashRecord(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (raw.v !== CRASH_RECORD_VERSION || typeof raw.id !== 'string' || !ID.test(raw.id)) return null;
+  const at = Number(raw.at);
+  if (!Number.isFinite(at) || at <= 0) return null;
+  const firstAt = Number(raw.firstAt);
+  const exit = raw.exit && typeof raw.exit === 'object' && !Array.isArray(raw.exit) ? raw.exit : {};
+  const uptimeMs = Number(raw.uptimeMs);
+  return {
+    v: CRASH_RECORD_VERSION,
+    id: raw.id,
+    at,
+    firstAt: Number.isFinite(firstAt) && firstAt > 0 && firstAt <= at ? firstAt : at,
+    count: Number.isInteger(raw.count) && raw.count > 0 ? Math.min(raw.count, 999) : 1,
+    exit: {
+      ...(Number.isInteger(exit.code) ? { code: exit.code } : {}),
+      ...(typeof exit.hex === 'string' && HEX.test(exit.hex) ? { hex: exit.hex } : {}),
+      ...(typeof exit.signal === 'string' && SIGNAL.test(exit.signal) ? { signal: exit.signal } : {}),
+      kind: typeof exit.kind === 'string' && KIND.test(exit.kind) ? exit.kind : 'exit',
+    },
+    ...(raw.uptimeMs !== undefined && raw.uptimeMs !== null && Number.isFinite(uptimeMs) && uptimeMs >= 0 ? { uptimeMs: Math.round(uptimeMs) } : {}),
+  };
+}
+
+/** The record in the data home, or null. */
+export function readCrashRecord(dataHome, { fs = NODE_FS } = {}) {
+  try {
+    return normalizeCrashRecord(JSON.parse(fs.readFileSync(crashRecordPath(dataHome), 'utf8')));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The supervisor's side: the server crashed after it was up and is being started
+ * again. `exit` is lib/server-exit.js describeExit's answer. A record the owner
+ * has not dismissed yet is counted on (`count` + 1, its `firstAt` kept); the id
+ * is always new. Written whole (a temporary file renamed over it). Returns the
+ * record written, or null.
+ */
+export function writeCrashRecord(dataHome, { exit = {}, at = Date.now(), uptimeMs = null, pid = process.pid } = {}, {
+  fs = NODE_FS, newId = () => randomBytes(8).toString('hex'),
+} = {}) {
+  const path = crashRecordPath(dataHome);
+  const before = readCrashRecord(dataHome, { fs });
+  const record = normalizeCrashRecord({
+    v: CRASH_RECORD_VERSION,
+    id: newId(),
+    at,
+    firstAt: before ? before.firstAt : at,
+    count: before ? before.count + 1 : 1,
+    exit: { code: exit?.code, hex: exit?.hex, signal: exit?.signal, kind: exit?.kind },
+    uptimeMs,
+  });
+  if (!record) return null;
+  const temp = `${path}.${pid}.tmp`;
+  try {
+    fs.mkdirSync(dirname(path), { recursive: true });
+    fs.writeFileSync(temp, `${JSON.stringify(record)}\n`);
+    fs.renameSync(temp, path);
+    return record;
+  } catch {
+    try { fs.rmSync(temp, { force: true }); } catch {}
+    return null;
+  }
+}
+
+/**
+ * Remove the record: only the one named `id` when an id is given (a page that
+ * dismisses an older crash leaves a newer one in place), else whatever is there.
+ * Returns true when no record of that id is left.
+ */
+export function clearCrashRecord(dataHome, { id = null, fs = NODE_FS } = {}) {
+  if (id !== null) {
+    const current = readCrashRecord(dataHome, { fs });
+    if (!current || current.id !== id) return !current;
+  }
+  try {
+    fs.rmSync(crashRecordPath(dataHome), { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/server-exit.js

@@ -0,0 +1,318 @@
+/**
+ * SynaBun — what the end of the server process says, and what its supervisor does
+ *
+ * setup.js runs the Neural Interface server as a child and decides, when that
+ * child ends, whether to start it again (lib/server-supervisor.js). The exit
+ * status alone cannot say whether an end was asked for: every way out of
+ * server.js passes its `exit` handler, which ends the process by force to skip
+ * native teardown (Windows then reports exit code 1, macOS and Linux SIGKILL).
+ * So the server says so for a stop that was asked for (a restart has its own
+ * marker), twice over: a stop marker in the data home, and a line on its stdout
+ * with the token its supervisor gave it, which needs no disk. The status is read
+ * for what it can tell: a crash, and of which kind.
+ *
+ *   describeExit({ code, signal })   the status in plain words, for the log, the
+ *                                    supervisor record and the app's stopped page
+ *   serverExitDecision({ ... })      restart / stopped / crashed / failed
+ *   writeStopMarker / readStopMarker the marker, written whole, read strictly
+ *   readRestartMarker                when the restart was asked for
+ *   stopAnnouncement / readStopAnnouncement   the stop line on stdout
+ *   watchChildEnd(child, ...)        the end of the child, once its output is read
+ *   createRestartGuard({ ... })      the crash-loop guard: so many starts in a window
+ *
+ * No imports and no I/O of its own (a writer is handed its file functions). The
+ * words are English: the desktop app localizes a status by its `kind`
+ * (packaging/desktop/src/server-exit-view.mjs), the page by its `kind` too.
+ */
+
+/** The sentinel a supervised server exits with to be started again (sysexits EX_TEMPFAIL). */
+export const RESTART_EXIT_CODE = 75;
+
+/** The marker server.js leaves in the data home before a stop that was asked for (shutdown, update, signal). */
+export const STOP_MARKER_NAME = 'stop-requested';
+
+/** The environment variable that hands a server its supervisor's stop token (one per start, never inherited further). */
+export const STOP_TOKEN_ENV = 'SYNABUN_STOP_TOKEN';
+
+/** What a stop reason may be in a marker or a stop line: a short word ("shutdown", "run-update", "sigterm"). */
+export function cleanStopReason(reason) {
+  return typeof reason === 'string' ? reason.replace(/[^\w-]/g, '').slice(0, 40) : '';
+}
+
+/**
+ * Write the stop marker whole: a temporary file beside it, renamed over it, so
+ * the supervisor never reads half a marker. `fs` is { writeFileSync,
+ * renameSync, rmSync }. Returns { ok: true } when it is in place, else
+ * { ok: false, error } (its code: ENOSPC, EROFS, EPERM, …). Never throws.
+ */
+export function writeStopMarker(path, { reason, pid, at }, fs) {
+  const temp = `${path}.${pid}.tmp`;
+  const text = JSON.stringify({ reason: cleanStopReason(reason), pid, at });
+  try {
+    fs.writeFileSync(temp, text);
+    fs.renameSync(temp, path);
+    return { ok: true };
+  } catch (error) {
+    try { fs.rmSync(temp, { force: true }); } catch {}
+    return { ok: false, error: String(error?.code || error?.message || error || 'unknown').slice(0, 60) };
+  }
+}
+
+/** How much earlier than the server's start a marker may say it was written: a clock that moved a little. */
+export const MARKER_CLOCK_SLACK_MS = 60_000;
+
+/**
+ * The marker as the supervisor takes it: complete JSON left by `pid` (the
+ * server it started, never "any server"), written no earlier than `since` (when
+ * it started that server) less a minute for a clock that moved. Returns
+ * { reason, at } or null: an empty, truncated, foreign or stale file is no stop.
+ */
+export function readStopMarker(text, { pid, since = 0 } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  let saved;
+  try { saved = JSON.parse(String(text ?? '')); } catch { return null; }
+  if (!saved || typeof saved !== 'object' || Array.isArray(saved)) return null;
+  if (saved.pid !== pid) return null;
+  if (!Number.isFinite(saved.at) || saved.at < Number(since || 0) - MARKER_CLOCK_SLACK_MS) return null;
+  return { reason: cleanStopReason(saved.reason), at: saved.at };
+}
+
+/** When the restart marker says the restart was asked for (server.js writes its Date.now() in it), or null. */
+export function readRestartMarker(text) {
+  const value = String(text ?? '').trim();
+  if (!/^\d{1,16}$/.test(value)) return null;
+  const at = Number(value);
+  return Number.isSafeInteger(at) && at > 0 ? at : null;
+}
+
+/** The line a server prints when a stop was asked of it: its supervisor reads it on stdout, with no disk involved. */
+export function stopAnnouncement(token, reason) {
+  return `[server] Stop requested: ${cleanStopReason(reason) || 'stop'} (supervisor ${token})`;
+}
+
+/** The reason of a stop line that carries `token` (the one the supervisor gave this server), or null. */
+export function readStopAnnouncement(line, token) {
+  if (typeof token !== 'string' || !/^[0-9a-f]{32}$/.test(token)) return null;
+  const found = /^\[server\] Stop requested: ([\w-]{1,40}) \(supervisor ([0-9a-f]{32})\)\s*$/.exec(String(line ?? '').trim());
+  return found && found[2] === token ? { reason: found[1] } : null;
+}
+
+/** Signals that stop a process on request. Any other signal is a crash or a forced end (systemd's "clean" set). */
+export const CLEAN_SIGNALS = Object.freeze(['SIGTERM', 'SIGINT', 'SIGHUP', 'SIGPIPE']);
+
+/** What each kind is called in a sentence: "0xC0000409, native crash". */
+export const EXIT_KIND_WORDS = Object.freeze({
+  'native-crash': 'native crash',
+  'out-of-memory': 'out of memory',
+  'node-fatal': 'Node.js fatal error',
+  error: 'stopped by an error',
+  killed: 'ended by force',
+  interrupted: 'interrupted',
+  stopped: 'stopped on request',
+  restart: 'restart requested',
+  exit: '',
+});
+
+// Windows ends a crashed process with an NTSTATUS. These are the ones a Node.js
+// server meets; anything else in the error range is still reported by number.
+const WINDOWS_STATUS = new Map([
+  [0xC0000409, ['STATUS_STACK_BUFFER_OVERRUN', 'native-crash', 'a fail-fast inside the process: abort() (an uncaught C++ exception, a failed native assertion) or a failed security check']],
+  [0xC0000005, ['STATUS_ACCESS_VIOLATION', 'native-crash', 'an invalid memory access']],
+  [0xC00000FD, ['STATUS_STACK_OVERFLOW', 'native-crash', 'a native stack overflow']],
+  [0xC0000374, ['STATUS_HEAP_CORRUPTION', 'native-crash', 'corrupted native memory']],
+  [0xC000001D, ['STATUS_ILLEGAL_INSTRUCTION', 'native-crash', 'an instruction this processor does not have']],
+  [0xC0000096, ['STATUS_PRIVILEGED_INSTRUCTION', 'native-crash', 'a privileged instruction']],
+  [0xC0000094, ['STATUS_INTEGER_DIVIDE_BY_ZERO', 'native-crash', 'an integer division by zero']],
+  [0xC0000006, ['STATUS_IN_PAGE_ERROR', 'native-crash', 'a page of the program could not be read (a disk or network error)']],
+  [0xC0000420, ['STATUS_ASSERTION_FAILURE', 'native-crash', 'a failed native assertion']],
+  [0xC0000142, ['STATUS_DLL_INIT_FAILED', 'native-crash', 'a DLL could not initialize']],
+  [0x80000003, ['STATUS_BREAKPOINT', 'native-crash', 'a fatal error trap (V8 or libuv stopping the process)']],
+  [0xC0000017, ['STATUS_NO_MEMORY', 'out-of-memory', 'Windows had no memory left to give it']],
+  [0xC000012D, ['STATUS_COMMITMENT_LIMIT', 'out-of-memory', 'the system commit limit was reached']],
+  [0xC000013A, ['STATUS_CONTROL_C_EXIT', 'interrupted', 'Ctrl+C, or the console it ran in was closed']],
+  [0x40010004, ['DBG_TERMINATE_PROCESS', 'killed', 'ended by a debugger or by Windows']],
+]);
+
+// Exit codes of a Node.js process.
+const NODE_CODES = new Map([
+  [1, ['error', 'an error the server did not handle (printed above), or it was ended by force']],
+  [7, ['error', 'its own error handler failed']],
+  [134, ['node-fatal', 'Node.js stopped it ("FATAL ERROR" above: out of memory, or an internal check)']],
+  [RESTART_EXIT_CODE, ['restart', 'it asked to be started again']],
+]);
+
+const SIGNALS = new Map([
+  ['SIGSEGV', ['native-crash', 'a segmentation fault (invalid memory access)']],
+  ['SIGBUS', ['native-crash', 'a bus error (invalid memory access)']],
+  ['SIGILL', ['native-crash', 'an illegal instruction']],
+  ['SIGFPE', ['native-crash', 'an arithmetic error']],
+  ['SIGABRT', ['native-crash', 'abort(): an uncaught C++ exception, a failed native assertion or a fatal error']],
+  ['SIGTRAP', ['native-crash', 'a fatal error trap']],
+  ['SIGSYS', ['native-crash', 'a bad system call']],
+  ['SIGKILL', ['killed', 'by force, or by the system when memory ran out']],
+  ['SIGTERM', ['stopped', 'it was asked to stop']],
+  ['SIGINT', ['stopped', 'it was interrupted']],
+  ['SIGHUP', ['stopped', 'its terminal went away']],
+  ['SIGPIPE', ['stopped', 'its output was closed']],
+]);
+
+/**
+ * `code` as an unsigned 32-bit hex status ("0xC0000409") when it is one: an
+ * NTSTATUS-sized value (as Node reports it, or as a negative 32-bit number).
+ * Null for ordinary exit codes.
+ */
+export function exitStatusHex(code) {
+  if (typeof code !== 'number' || !Number.isInteger(code)) return null;
+  if (code < 0 && code >= -0x80000000) code >>>= 0;
+  if (code < 0x40000000 || code > 0xFFFFFFFF) return null;
+  return `0x${code.toString(16).toUpperCase().padStart(8, '0')}`;
+}
+
+/**
+ * The exit status in plain words. Returns
+ *   { code, signal, hex, name, kind, detail, label, text }
+ * `kind` is one of the keys of EXIT_KIND_WORDS; `label` its words; `text` the
+ * short form a person reads ("0xC0000409, native crash", "exit code 1, …",
+ * "SIGSEGV, native crash"); `detail` what it means, for the log.
+ */
+export function describeExit({ code = null, signal = null } = {}) {
+  const numeric = typeof code === 'number' && Number.isInteger(code) ? code : null;
+  const sig = typeof signal === 'string' && /^SIG[A-Z0-9]+$/.test(signal) ? signal : null;
+  const hex = exitStatusHex(numeric);
+  let name = null;
+  let kind = 'exit';
+  let detail = '';
+  if (sig) {
+    name = sig;
+    const known = SIGNALS.get(sig);
+    if (known) [kind, detail] = known;
+    else { kind = 'killed'; detail = 'ended by that signal'; }
+  } else if (hex) {
+    const unsigned = Number.parseInt(hex.slice(2), 16);
+    const known = WINDOWS_STATUS.get(unsigned);
+    if (known) [name, kind, detail] = known;
+    else if (unsigned >= 0xC0000000 && unsigned <= 0xCFFFFFFF) { kind = 'native-crash'; detail = 'a Windows error status'; }
+  } else if (numeric !== null) {
+    const known = NODE_CODES.get(numeric);
+    if (known) [kind, detail] = known;
+    else if (numeric === 0) detail = 'a normal exit';
+  }
+  const label = EXIT_KIND_WORDS[kind] || '';
+  const head = sig || hex || (numeric !== null ? `exit code ${numeric}` : 'no exit status');
+  return {
+    code: numeric,
+    signal: sig,
+    hex,
+    name,
+    kind,
+    detail,
+    label,
+    text: label ? `${head}, ${label}` : head,
+  };
+}
+
+/**
+ * One line for the supervisor's log: "exit code 3221226505 = 0xC0000409,
+ * native crash (STATUS_STACK_BUFFER_OVERRUN): a fail-fast inside …".
+ */
+export function formatExit(described) {
+  const d = described && typeof described === 'object' && 'kind' in described ? described : describeExit(described || {});
+  const head = d.signal ? `signal ${d.signal}` : d.code !== null ? `exit code ${d.code}${d.hex ? ` = ${d.hex}` : ''}` : 'no exit status';
+  const label = d.label ? `, ${d.label}` : '';
+  const name = d.name && d.name !== d.signal ? ` (${d.name})` : '';
+  const detail = d.detail ? `: ${d.detail}` : '';
+  return `${head}${label}${name}${detail}`;
+}
+
+/**
+ * What the supervisor does when the server it runs has ended:
+ *   'restart'  it asked to be started again (exit code 75 or the restart marker)
+ *   'stopped'  it was asked to stop (the stop marker), or stopped cleanly
+ *              (exit code 0, a clean signal, Windows' Ctrl+C status): the
+ *              supervisor ends too
+ *   'failed'   it ended before it was listening: a start that failed, reported
+ *              as one (starting it again would fail the same way)
+ *   'crashed'  it ended on its own after it was up: started again, within the
+ *              supervisor's crash-loop guard
+ * Asked for both, the later request wins: `stopAfterRestart` (the stop was
+ * asked when, or after, the restart was: the desktop app quitting while a
+ * restart shuts down) is a stop; otherwise the restart goes ahead.
+ */
+export function serverExitDecision({ code = null, signal = null, restartRequested = false, stopRequested = false, stopAfterRestart = false, listened = false } = {}) {
+  if (stopRequested && stopAfterRestart) return 'stopped';
+  if (restartRequested || code === RESTART_EXIT_CODE) return 'restart';
+  if (stopRequested) return 'stopped';
+  if (code === 0) return 'stopped';
+  if ((code === null || code === undefined) && CLEAN_SIGNALS.includes(signal)) return 'stopped';
+  // Windows' own Ctrl+C, or the console it ran in closing: what SIGINT and SIGHUP are elsewhere.
+  if (exitStatusHex(code) === '0xC000013A') return 'stopped';
+  if (!listened) return 'failed';
+  return 'crashed';
+}
+
+/**
+ * The fields a supervisor record's error keeps about an exit (lib/start-launcher.js
+ * supervisorError): what the desktop app's stopped page shows.
+ */
+export function exitRecordFields(described) {
+  const d = described && typeof described === 'object' && 'kind' in described ? described : describeExit(described || {});
+  return {
+    ...(d.code !== null ? { exitCode: d.code } : {}),
+    ...(d.signal ? { exitSignal: d.signal } : {}),
+    ...(d.hex ? { exitHex: d.hex } : {}),
+    exitKind: d.kind,
+  };
+}
+
+/**
+ * Call `onEnd({ code, signal })` once, when `child` has ended and its output
+ * has been read to the end ('close'), or `drainMs` after it exited when
+ * something it started still holds that output open. Reading to the end
+ * first keeps a crash's last words: what a native assertion or an uncaught
+ * error printed just before the process died. `cancel()` stops it (the child
+ * could not be started, and that was reported already).
+ */
+export function watchChildEnd(child, { drainMs = 1500, onEnd, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
+  let ended = null;
+  let done = false;
+  let drain = null;
+  const decide = () => {
+    if (done || !ended) return;
+    done = true;
+    if (drain !== null) clearTimer(drain);
+    onEnd?.(ended);
+  };
+  child.on('exit', (code, signal) => {
+    ended = { code, signal };
+    drain = setTimer(decide, drainMs);
+  });
+  child.on('close', (code, signal) => {
+    ended ??= { code, signal };
+    decide();
+  });
+  return {
+    cancel() {
+      done = true;
+      if (drain !== null) clearTimer(drain);
+    },
+    get decided() { return done; },
+  };
+}
+
+/**
+ * The crash-loop guard: `note()` counts one more start of the server and says
+ * whether that is more than `limit` within `windowMs` ({ count, exceeded }).
+ */
+export function createRestartGuard({ windowMs = 60_000, limit = 5, now = () => Date.now() } = {}) {
+  const starts = [];
+  return {
+    windowMs,
+    limit,
+    note() {
+      const at = now();
+      starts.push(at);
+      while (starts.length && at - starts[0] > windowMs) starts.shift();
+      return { count: starts.length, exceeded: starts.length > limit };
+    },
+  };
+}