@reticlehq/server 3.8.2 → 3.10.0

package/dist/command/daemon/daemon.js

@@ -1,10 +1,11 @@
 import { join } from 'node:path';
-import { homedir } from 'node:os';
+import { homedir, uptime } from 'node:os';
 import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, openSync, closeSync, readdirSync, statSync, renameSync, writeSync, } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { daemonRegistryFileName, DaemonSpawnMethod, ReticleEnv, } from '@reticlehq/core';
 import { log } from '../../log.js';
 import { uncleanPredecessor } from './lifetime/unclean-predecessor.js';
+import { deathCauseFromLog, readLogTail } from './lifetime/death-cause.js';
 import { reportDaemonDiedUnclean } from '../../telemetry/proxy-telemetry.js';
 import { MAX_DAEMON_LOG_BYTES, pruneOldDaemonLogs } from './lifetime/log-cap.js';
 import { escapeJobViaWmi } from './win32-escape.js';
@@ -59,13 +60,18 @@ export function readPid(port, home = reticleStateHome()) {
     const n = parseInt(readFileSync(path, 'utf8').trim(), 10);
     return isNaN(n) ? null : n;
 }
+/**
+ * Whether a process with this pid exists. `EPERM` means it exists and this process may not signal
+ * it, which a daemon that WMI started can answer on Windows; only `ESRCH` means it is gone. Reading
+ * every throw as "dead" reclaimed a live daemon and started a second one on its port.
+ */
 export function isAlive(pid) {
     try {
         process.kill(pid, 0);
         return true;
     }
-    catch {
-        return false;
+    catch (err) {
+        return err instanceof Error && 'code' in err && 'EPERM' === err.code;
     }
 }
 export function writePid(port) {
@@ -149,13 +155,42 @@ export function discoverDaemonPort() {
     }
     return found;
 }
+/**
+ * When the machine last booted, in epoch ms. A pidfile written before it names no daemon: every
+ * process from before the boot is gone, and its pid may now belong to anything.
+ */
+function lastBootMs() {
+    // The clock is read at this I/O boundary, as the other timestamps in this file are.
+    return Date.now() - uptime() * 1000;
+}
+/**
+ * Does this pidfile name a daemon that is still running?
+ *
+ * The pid must be alive AND the file must be newer than the last boot. A pid alone is not enough:
+ * the OS reuses pids, and after a reboot a pidfile named an unrelated Bluetooth service on Windows.
+ * The port was free, but serve skipped the start because that pid was alive, and the daemon never
+ * came up. A file whose age cannot be read is judged by its pid alone, as before.
+ */
+export function pidFileIsLive(path, pid, pidAlive, bootMs = lastBootMs) {
+    if (!pidAlive(pid)) {
+        return false;
+    }
+    let writtenMs;
+    try {
+        writtenMs = statSync(path).mtimeMs;
+    }
+    catch {
+        return true;
+    }
+    return writtenMs >= bootMs();
+}
 /**
  * Sweep ~/.reticle for daemon-<port>.pid files whose process is no longer alive and delete them, so a
  * crashed daemon never leaves a stale pidfile that confuses discovery or makes a port look "taken".
  * Returns the ports reclaimed. `home` and `pidAlive` are injectable for testing (default to the real
  * ~/.reticle and the process.kill(pid,0) liveness probe).
  */
-export function reclaimStaleDaemons(home = reticleStateHome(), pidAlive = isAlive) {
+export function reclaimStaleDaemons(home = reticleStateHome(), pidAlive = isAlive, bootMs = lastBootMs) {
     const reclaimed = [];
     let files;
     try {
@@ -178,7 +213,7 @@ export function reclaimStaleDaemons(home = reticleStateHome(), pidAlive = isAliv
         catch {
             pid = null; // unreadable pidfile counts as stale
         }
-        if (null === pid || !pidAlive(pid)) {
+        if (null === pid || !pidFileIsLive(path, pid, pidAlive, bootMs)) {
             try {
                 unlinkSync(path);
                 removeDaemonRegistry(Number(match[1])); // drop the sidecar discovery entry too
@@ -206,17 +241,22 @@ function defaultSpawnDaemonDeps() {
         pidAlive: isAlive,
         platform: process.platform,
         escapeJob: escapeJobViaWmi,
-        onUncleanDeath: (ageMs) => void reportDaemonDiedUnclean(ageMs),
+        onUncleanDeath: (ageMs, cause) => void reportDaemonDiedUnclean(ageMs, cause),
     };
 }
 /**
  * Report a dead predecessor, aged from its pidfile: the parent writes that file at spawn time.
  * Read before the unlink, because after it nothing is left to age. A report must never stop a start.
  */
-function reportUncleanAge(pidFilePath, deps) {
+function reportUncleanAge(pidFilePath, logFilePath, deps) {
     try {
         // The clock is read at this I/O boundary, the same as the log timestamps in this file.
-        deps.onUncleanDeath?.(Math.max(0, Date.now() - statSync(pidFilePath).mtimeMs));
+        const now = Date.now();
+        const startedMs = statSync(pidFilePath).mtimeMs;
+        // Read before `rotateDaemonLog`, which renames the file this daemon wrote.
+        const tail = readLogTail(logFilePath);
+        const cause = tail === undefined ? undefined : deathCauseFromLog(tail, startedMs, now);
+        deps.onUncleanDeath?.(Math.max(0, now - startedMs), cause);
     }
     catch {
         // An unreadable pidfile has no age to report.
@@ -276,14 +316,16 @@ export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpaw
     }
     catch {
         const existing = readPid(port, deps.home);
-        if (existing !== null && deps.pidAlive(existing))
+        if (existing !== null &&
+            pidFileIsLive(pidFilePath, existing, (pid) => deps.pidAlive(pid), deps.bootTimeMs)) {
             return false;
+        }
         // This branch IS the crash detection — its own comment has always said so ("a stale pidfile from
         // a crashed daemon is reclaimed"), it just never said it out loud. Captured before the unlink,
         // because after it there is no trace left that the previous daemon died at all.
         orphanPid = uncleanPredecessor(existing, false, process.pid);
         if (null !== orphanPid) {
-            reportUncleanAge(pidFilePath, deps);
+            reportUncleanAge(pidFilePath, logFilePath, deps);
         }
         try {
             unlinkSync(pidFilePath);

package/dist/command/daemon/lifetime/daemon-exit.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The daemon's exit, with a bound (#1937).
+ *
+ * The exit used to await the telemetry summary and then `server.close()`, with no limit on the
+ * close. The close waits for the browser pool, the cloud sync flush and every open HTTP connection.
+ * When one of them never settled, the process stayed alive with its port held, and every tool call
+ * found a daemon that did not answer.
+ */
+export declare const ExitCode: {
+    readonly CLEAN: 0;
+    readonly FAILED: 1;
+};
+export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
+/**
+ * The most the summary and the close get together. The summary send has its own 2s bound, and the
+ * pool needs a few seconds to close its browsers.
+ */
+export declare const DAEMON_EXIT_BUDGET_MS = 10000;
+/** Send the summary, close, and resolve to the exit code. Never takes longer than `budgetMs`. */
+export declare function exitAfterClose(steps: {
+    summary: () => Promise<void>;
+    close: () => Promise<void>;
+    budgetMs?: number;
+}): Promise<ExitCode>;

package/dist/command/daemon/lifetime/daemon-exit.js

@@ -0,0 +1,39 @@
+/**
+ * The daemon's exit, with a bound (#1937).
+ *
+ * The exit used to await the telemetry summary and then `server.close()`, with no limit on the
+ * close. The close waits for the browser pool, the cloud sync flush and every open HTTP connection.
+ * When one of them never settled, the process stayed alive with its port held, and every tool call
+ * found a daemon that did not answer.
+ */
+import { log } from '../../../log.js';
+export const ExitCode = {
+    CLEAN: 0,
+    FAILED: 1,
+};
+/**
+ * The most the summary and the close get together. The summary send has its own 2s bound, and the
+ * pool needs a few seconds to close its browsers.
+ */
+export const DAEMON_EXIT_BUDGET_MS = 10_000;
+/** Send the summary, close, and resolve to the exit code. Never takes longer than `budgetMs`. */
+export async function exitAfterClose(steps) {
+    const budgetMs = steps.budgetMs ?? DAEMON_EXIT_BUDGET_MS;
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`the daemon did not finish its shutdown within ${String(budgetMs)}ms`));
+        }, budgetMs);
+    });
+    try {
+        await Promise.race([steps.summary().then(steps.close), deadline]);
+        return ExitCode.CLEAN;
+    }
+    catch (err) {
+        log('reticle_daemon_close_error', { error: err instanceof Error ? err.message : String(err) });
+        return ExitCode.FAILED;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/command/daemon/lifetime/death-cause.d.ts

@@ -0,0 +1,15 @@
+import { DaemonEnd, type DaemonDeath } from '@reticlehq/core';
+/** What the log says about the dead daemon. `ageMs` is the caller's to add. */
+export type DeathCause = Omit<DaemonDeath, 'ageMs'> & {
+    end: DaemonEnd;
+};
+/**
+ * Read the cause of death of the daemon that started at `startedMs`.
+ *
+ * The log is append-only across launches, so only lines at or after `startedMs` count. A daemon
+ * that crashed before it wrote any line leaves only a raw Node stack, after the last line of the
+ * daemon before it; the error code is read from there.
+ */
+export declare function deathCauseFromLog(text: string, startedMs: number, nowMs: number): DeathCause;
+/** The last part of the log at `path`, or undefined when it cannot be read. Never throws. */
+export declare function readLogTail(path: string): string | undefined;

package/dist/command/daemon/lifetime/death-cause.js

@@ -0,0 +1,149 @@
+/**
+ * Why a daemon died, read from its own log by the start that finds it dead.
+ *
+ * The daemon log already says how a daemon ended: a heartbeat every 30 s, a line for a signal, a
+ * line for an exit, and a line for a failed start (see heartbeat.ts). Nobody uploads that file, so
+ * `daemon_died_unclean` carried only the age, and a reboot, a killed process tree, an out-of-memory
+ * kill and a crash at startup sent the same event. The next start reads the log before it rotates
+ * it, and sends the cause with the event.
+ *
+ * Only facts that are names or numbers leave this module: an end, a signal name, a Node error code,
+ * counts. Never a message, because a message can carry the user's paths.
+ */
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+import { DaemonEnd, DaemonStartupError, NODE_ERROR_CODE } from '@reticlehq/core';
+import { DAEMON_HEARTBEAT_EVENT, classifyDaemonLife } from './heartbeat.js';
+import { DAEMON_START_FAILED_EVENT } from './startup-failure.js';
+/**
+ * A Node error code where Node writes one: `[ERR_MODULE_NOT_FOUND]`, `code: 'EADDRINUSE'`, or
+ * `listen EADDRINUSE:`. A bare upper-case word elsewhere is not a code.
+ */
+const ERROR_CODE_IN_TEXT = /\b(E[A-Z]{3,30}|ERR_[A-Z0-9_]{2,60})(?=\]|'|"|:)/g;
+/** Upper-case words that sit before a colon and are not codes. */
+const NOT_A_CODE = new Set(['ERROR', 'EXIT', 'ENV']);
+function parse(raw) {
+    let record;
+    try {
+        record = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if ('object' !== typeof record || null === record) {
+        return undefined;
+    }
+    const r = record;
+    const t = 'string' === typeof r['t'] ? Date.parse(r['t']) : Number.NaN;
+    if (!Number.isFinite(t) || 'string' !== typeof r['event']) {
+        return undefined;
+    }
+    return { ...r, t, event: r['event'] };
+}
+/** The last Node error code in `text`, or undefined. Only the code, never the text around it. */
+function lastErrorCode(text) {
+    const codes = [...text.matchAll(ERROR_CODE_IN_TEXT)].map((m) => m[1]);
+    const code = codes.filter((c) => c !== undefined && !NOT_A_CODE.has(c)).at(-1);
+    return code !== undefined && NODE_ERROR_CODE.test(code) ? code : undefined;
+}
+/** The stage of a failed start, only when it is a member of the closed list. */
+function startupStage(v) {
+    return Object.values(DaemonStartupError).find((stage) => stage === v);
+}
+/** The code field of a failed start, only when it has the shape of a Node error code. */
+function codeField(v) {
+    return 'string' === typeof v && NODE_ERROR_CODE.test(v) ? v : undefined;
+}
+const count = (v) => 'number' === typeof v && Number.isInteger(v) && 0 <= v ? v : undefined;
+/**
+ * Read the cause of death of the daemon that started at `startedMs`.
+ *
+ * The log is append-only across launches, so only lines at or after `startedMs` count. A daemon
+ * that crashed before it wrote any line leaves only a raw Node stack, after the last line of the
+ * daemon before it; the error code is read from there.
+ */
+export function deathCauseFromLog(text, startedMs, nowMs) {
+    const ours = [];
+    const rawAfterLastLine = [];
+    const rawInOurs = [];
+    for (const raw of text.split('\n')) {
+        const trimmed = raw.trim();
+        if (0 === trimmed.length) {
+            continue;
+        }
+        const parsed = parse(trimmed);
+        if (parsed === undefined) {
+            (0 < ours.length ? rawInOurs : rawAfterLastLine).push(trimmed);
+            continue;
+        }
+        if (parsed.t >= startedMs) {
+            ours.push(parsed);
+        }
+        else {
+            rawAfterLastLine.length = 0;
+        }
+    }
+    const life = classifyDaemonLife(ours, nowMs);
+    const cause = { end: life.end };
+    if (life.silentForMs !== undefined) {
+        cause.silentMs = Math.max(0, Math.round(life.silentForMs));
+    }
+    if (life.signal !== undefined && /^SIG[A-Z0-9]{1,12}$/.test(life.signal)) {
+        cause.signal = life.signal;
+    }
+    const lastBeat = ours.findLast((l) => l.event === DAEMON_HEARTBEAT_EVENT);
+    if (lastBeat !== undefined) {
+        const sessions = count(lastBeat['sessions']);
+        const rssMb = count(lastBeat['rssMb']);
+        if (sessions !== undefined) {
+            cause.sessions = sessions;
+        }
+        if ('boolean' === typeof lastBeat['served']) {
+            cause.served = lastBeat['served'];
+        }
+        if (rssMb !== undefined) {
+            cause.rssMb = rssMb;
+        }
+    }
+    const failed = ours.findLast((l) => l.event === DAEMON_START_FAILED_EVENT);
+    const stage = startupStage(failed?.['stage']);
+    if (stage !== undefined) {
+        cause.startupError = stage;
+    }
+    const error = codeField(failed?.['code']) ??
+        ('string' === typeof failed?.['error'] ? lastErrorCode(failed['error']) : undefined) ??
+        // Raw lines before this daemon's first line belong to the daemon before it, unless this one
+        // wrote no line at all, which is a crash before its first log line.
+        lastErrorCode((0 < ours.length ? rawInOurs : rawAfterLastLine).join('\n'));
+    if (error !== undefined) {
+        cause.error = error;
+    }
+    // No line of its own, and a Node error after the last line of the daemon before it: Node stopped
+    // this daemon before its code could write anything, for example on a module that did not load.
+    if (0 === ours.length && error !== undefined) {
+        cause.end = DaemonEnd.START_FAILED;
+        cause.startupError = DaemonStartupError.BEFORE_LOG;
+    }
+    return cause;
+}
+/** How much of the end of a daemon log the next start reads. The last beats and a stack fit. */
+const LOG_TAIL_BYTES = 256 * 1024;
+/** The last part of the log at `path`, or undefined when it cannot be read. Never throws. */
+export function readLogTail(path) {
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+        const size = fstatSync(fd).size;
+        const length = Math.min(size, LOG_TAIL_BYTES);
+        const buffer = Buffer.alloc(length);
+        readSync(fd, buffer, 0, length, size - length);
+        return buffer.toString('utf8');
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            closeSync(fd);
+        }
+    }
+}

package/dist/command/daemon/lifetime/heartbeat.d.ts

@@ -17,6 +17,7 @@
  *
  * A heartbeat nobody interprets is just log volume.
  */
+import { DaemonEnd } from '@reticlehq/core';
 /** The event name a beat carries. One `grep` separates liveness from everything else in the file. */
 export declare const DAEMON_HEARTBEAT_EVENT = "reticle_daemon_alive";
 /**
@@ -43,6 +44,11 @@ interface HeartbeatFacts {
      * and make a long-lived daemon look freshly idle.
      */
     served: boolean;
+    /**
+     * Resident memory in MB. Optional, so a caller that cannot read it sends no number rather than
+     * a guess. The next start reports it when this daemon dies, which separates a memory death.
+     */
+    rssMb?: number;
 }
 interface DaemonHeartbeatOptions {
     log: (event: string, fields: Record<string, unknown>) => void;
@@ -74,20 +80,7 @@ export declare class DaemonHeartbeat {
     start(): void;
     stop(): void;
 }
-/** How a daemon's life ended, as far as its own log can say. */
-export declare const DaemonEnd: {
-    /** Still beating within tolerance. */
-    readonly ALIVE: "alive";
-    /** Logged its own exit, with no signal before it. */
-    readonly CLEAN: "clean";
-    /** A signal arrived — the cause an exit line with `code: 0` does not carry. */
-    readonly SIGNALLED: "signalled";
-    /** The beat simply stopped. No exit, no signal: killed, crashed, or swept. */
-    readonly DIED_SILENTLY: "died_silently";
-    /** No beat was ever emitted, so this log cannot answer the question. */
-    readonly UNKNOWN: "unknown";
-};
-export type DaemonEnd = (typeof DaemonEnd)[keyof typeof DaemonEnd];
+export { DaemonEnd };
 /**
  * One parsed line of a daemon log. The index signature is not laziness: these lines carry whatever
  * their event needed (`code`, `port`, `pid`, `reason`, …), and a reader that refused unknown keys
@@ -116,4 +109,3 @@ export interface DaemonLife {
  * signal we never sent is the same confident-wrong this module replaces.
  */
 export declare function classifyDaemonLife(lines: readonly LogLine[], nowMs: number): DaemonLife;
-export {};

package/dist/command/daemon/lifetime/heartbeat.js

@@ -17,7 +17,9 @@
  *
  * A heartbeat nobody interprets is just log volume.
  */
+import { DaemonEnd } from '@reticlehq/core';
 import { DAEMON_LOG_TRUNCATED_EVENT, guardDaemonLog } from './log-cap.js';
+import { DAEMON_START_FAILED_EVENT } from './startup-failure.js';
 /** The event name a beat carries. One `grep` separates liveness from everything else in the file. */
 export const DAEMON_HEARTBEAT_EVENT = 'reticle_daemon_alive';
 /** Written by installExitTrace when the process exits through Node. */
@@ -90,6 +92,7 @@ export class DaemonHeartbeat {
             everyMs: this.#intervalMs,
             sessions: facts.sessions,
             served: facts.served,
+            ...(facts.rssMb === undefined ? {} : { rssMb: facts.rssMb }),
         });
     }
     start() {
@@ -106,19 +109,8 @@ export class DaemonHeartbeat {
         this.#timer = undefined;
     }
 }
-/** How a daemon's life ended, as far as its own log can say. */
-export const DaemonEnd = {
-    /** Still beating within tolerance. */
-    ALIVE: 'alive',
-    /** Logged its own exit, with no signal before it. */
-    CLEAN: 'clean',
-    /** A signal arrived — the cause an exit line with `code: 0` does not carry. */
-    SIGNALLED: 'signalled',
-    /** The beat simply stopped. No exit, no signal: killed, crashed, or swept. */
-    DIED_SILENTLY: 'died_silently',
-    /** No beat was ever emitted, so this log cannot answer the question. */
-    UNKNOWN: 'unknown',
-};
+// The vocabulary lives in core, because `daemon_died_unclean` reports it too.
+export { DaemonEnd };
 /**
  * Read a daemon log back and say how it ended.
  *
@@ -141,8 +133,12 @@ export function classifyDaemonLife(lines, nowMs) {
             };
     }
     const last = beats.at(-1);
-    if (last === undefined)
-        return { end: DaemonEnd.UNKNOWN };
+    if (last === undefined) {
+        // A daemon that logged a failed start never beat. Without this branch its death was `unknown`,
+        // which said "no evidence" about a log that held the cause (#2043).
+        const failed = lines.some((l) => l.event === DAEMON_START_FAILED_EVENT);
+        return { end: failed ? DaemonEnd.START_FAILED : DaemonEnd.UNKNOWN };
+    }
     const everyMs = 'number' === typeof last.everyMs ? last.everyMs : DAEMON_HEARTBEAT_MS;
     const silentForMs = nowMs - last.t;
     return silentForMs > everyMs * MISSED_BEATS_TOLERATED

package/dist/command/daemon/lifetime/startup-failure.d.ts

@@ -1,5 +1,33 @@
+import { DaemonStartupError } from '@reticlehq/core';
 /** The structured log event emitted when the daemon child cannot start. */
 export declare const DAEMON_START_FAILED_EVENT = "reticle_daemon_start_failed";
+type LogFn = (event: string, fields: Record<string, unknown>) => void;
+/**
+ * Write a failed start to the daemon log, before the process exits (#2043).
+ *
+ * The line has three fields. `error` is the message, for the person who reads the log and for
+ * `readDaemonStartupCause`. `code` is the Node error code, read from the error and not from the
+ * message. `stage` is where the start failed: a failed bind is always `listen`, whatever the caller
+ * gave. The next start reads `code` and `stage` into `daemon_died_unclean`. The message stays here.
+ */
+export declare function recordStartupFailure(log: LogFn, error: unknown, stage: DaemonStartupError): void;
+/** The parts of `process` that the startup trap uses. */
+export interface StartupTrapTarget {
+    prependListener(event: 'uncaughtException' | 'unhandledRejection', handler: (value: unknown) => void): void;
+    off(event: 'uncaughtException' | 'unhandledRejection', handler: (value: unknown) => void): void;
+}
+/**
+ * Write a throw or a rejection that stops the start to the daemon log.
+ *
+ * Before the daemon is ready, the process crash guard owns these two events. It writes one sentence
+ * to stderr and exits, and that sentence has no event name and no code. So a daemon that died in
+ * its first 100 ms left a log that no reader could classify. This trap runs FIRST (it is prepended)
+ * and writes one structured line. It does not exit: the crash guard still does that.
+ *
+ * Returns a disposer. Call it when the daemon is ready, because from then on the daemon's own
+ * resilience handlers own these events, and a crash is no longer a failed start.
+ */
+export declare function installStartupTrap(proc: StartupTrapTarget, log: LogFn): () => void;
 /**
  * Return the most recent startup cause written by this launch attempt.
  *
@@ -9,3 +37,4 @@ export declare const DAEMON_START_FAILED_EVENT = "reticle_daemon_start_failed";
  * unavailable logs are best-effort misses; the caller still has its generic fallback diagnosis.
  */
 export declare function readDaemonStartupCause(path: string, sinceMs: number): string | undefined;
+export {};

package/dist/command/daemon/lifetime/startup-failure.js

@@ -1,6 +1,68 @@
 import { readFileSync } from 'node:fs';
+import { DaemonStartupError, NODE_ERROR_CODE } from '@reticlehq/core';
 /** The structured log event emitted when the daemon child cannot start. */
 export const DAEMON_START_FAILED_EVENT = 'reticle_daemon_start_failed';
+/** The `syscall` that Node puts on the error of a failed bind. */
+const LISTEN_SYSCALL = 'listen';
+/** The Node error code on `error`, or undefined. Only a value that has the shape of a code. */
+function nodeErrorCode(error) {
+    if ('object' !== typeof error || null === error) {
+        return undefined;
+    }
+    const code = error.code;
+    return 'string' === typeof code && NODE_ERROR_CODE.test(code) ? code : undefined;
+}
+function isListenError(error) {
+    if ('object' !== typeof error || null === error) {
+        return false;
+    }
+    return LISTEN_SYSCALL === error.syscall;
+}
+/**
+ * Write a failed start to the daemon log, before the process exits (#2043).
+ *
+ * The line has three fields. `error` is the message, for the person who reads the log and for
+ * `readDaemonStartupCause`. `code` is the Node error code, read from the error and not from the
+ * message. `stage` is where the start failed: a failed bind is always `listen`, whatever the caller
+ * gave. The next start reads `code` and `stage` into `daemon_died_unclean`. The message stays here.
+ */
+export function recordStartupFailure(log, error, stage) {
+    const code = nodeErrorCode(error);
+    log(DAEMON_START_FAILED_EVENT, {
+        stage: isListenError(error) ? DaemonStartupError.LISTEN : stage,
+        ...(code === undefined ? {} : { code }),
+        error: error instanceof Error ? error.message : String(error),
+    });
+}
+/**
+ * Write a throw or a rejection that stops the start to the daemon log.
+ *
+ * Before the daemon is ready, the process crash guard owns these two events. It writes one sentence
+ * to stderr and exits, and that sentence has no event name and no code. So a daemon that died in
+ * its first 100 ms left a log that no reader could classify. This trap runs FIRST (it is prepended)
+ * and writes one structured line. It does not exit: the crash guard still does that.
+ *
+ * Returns a disposer. Call it when the daemon is ready, because from then on the daemon's own
+ * resilience handlers own these events, and a crash is no longer a failed start.
+ */
+export function installStartupTrap(proc, log) {
+    let written = false;
+    const trap = (stage) => (value) => {
+        if (written) {
+            return;
+        }
+        written = true;
+        recordStartupFailure(log, value, stage);
+    };
+    const onException = trap(DaemonStartupError.UNCAUGHT_EXCEPTION);
+    const onRejection = trap(DaemonStartupError.UNHANDLED_REJECTION);
+    proc.prependListener('uncaughtException', onException);
+    proc.prependListener('unhandledRejection', onRejection);
+    return () => {
+        proc.off('uncaughtException', onException);
+        proc.off('unhandledRejection', onRejection);
+    };
+}
 /**
  * Return the most recent startup cause written by this launch attempt.
  *

package/dist/command/daemon/port-state.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What holds the bridge port, said the same way by every surface (#1937).
+ *
+ * A Reticle daemon stuck in its exit held the port and answered nothing. `status` called the port
+ * free, the MCP proxy called the holder "not a Reticle daemon", and `restart` refused to stop it.
+ * The pid file did not name it, because the next start had replaced that file. Its command line
+ * still did.
+ */
+import { type PortHolder } from '../cli/ports/port-holder.js';
+import { PortPresence } from './binding/port-presence.js';
+/** The listener on `port`, and whether its command line is a Reticle daemon's. */
+export declare function identifyPortHolder(port: number, exec: (command: string, args: readonly string[]) => string | null): PortHolder | null;
+/** The sentence for the state of `port`, with the holder named when something holds it. */
+export declare function describePortState(presence: PortPresence, port: number): string;

package/dist/command/daemon/port-state.js

@@ -0,0 +1,31 @@
+/**
+ * What holds the bridge port, said the same way by every surface (#1937).
+ *
+ * A Reticle daemon stuck in its exit held the port and answered nothing. `status` called the port
+ * free, the MCP proxy called the holder "not a Reticle daemon", and `restart` refused to stop it.
+ * The pid file did not name it, because the next start had replaced that file. Its command line
+ * still did.
+ */
+import { captureLookup, describeForeignHolder, findPortHolder, } from '../cli/ports/port-holder.js';
+import { describePresence, PortPresence } from './binding/port-presence.js';
+import { isReticleDaemonCommand } from './daemon-argv.js';
+import { readPid } from './daemon.js';
+/** The listener on `port`, and whether its command line is a Reticle daemon's. */
+export function identifyPortHolder(port, exec) {
+    const holder = findPortHolder(port, exec);
+    if (null === holder) {
+        return null;
+    }
+    const commandLine = exec('ps', ['-o', 'command=', '-p', String(holder.pid)]);
+    return {
+        ...holder,
+        reticleDaemon: null !== commandLine && isReticleDaemonCommand(commandLine),
+    };
+}
+/** The sentence for the state of `port`, with the holder named when something holds it. */
+export function describePortState(presence, port) {
+    if (PortPresence.FOREIGN !== presence) {
+        return describePresence(presence, port);
+    }
+    return describeForeignHolder(port, identifyPortHolder(port, captureLookup), readPid(port));
+}

package/dist/command/setup/agent-configs.d.ts

@@ -82,6 +82,8 @@ interface AgentPlanInput {
     readonly platform: keyof PlatformPaths;
     readonly exists: (path: string) => boolean;
     readonly readFile: (path: string) => string;
+    /** The installed bin to register (`InitHost.mcpLauncher`). Absent: the pinned npx command. */
+    readonly launcher?: string | undefined;
 }
 /**
  * Join for the platform the CALLER named, never the one this process happens to run on.