@reticlehq/server 2.5.0 → 2.7.0

package/dist/daemon/daemon.js

@@ -1,9 +1,10 @@
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, openSync, closeSync, readdirSync, statSync, renameSync, } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync, openSync, closeSync, readdirSync, statSync, renameSync, writeSync, } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { daemonRegistryFileName, ReticleEnv } from '@reticlehq/core';
 import { log } from '../log.js';
+import { uncleanPredecessor } from './unclean-predecessor.js';
 /** Env override for the whole state directory — see ReticleEnv.STATE_DIR. */
 export const STATE_DIR_ENV = ReticleEnv.STATE_DIR;
 /**
@@ -233,6 +234,8 @@ export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpaw
     // O_EXCL spawn-lock: only the FIRST racer to create the pidfile spawns. A concurrent second gets
     // EEXIST — if a LIVE daemon owns the port it skips (no duplicate detached daemon, no clobbered pid);
     // a stale pidfile from a crashed daemon is reclaimed. Returns false when it did not spawn.
+    /** Set when this start reclaimed a pidfile whose owner is gone — see unclean-predecessor.ts. */
+    let orphanPid = null;
     let lockFd;
     try {
         lockFd = deps.openFile(pidFilePath, 'wx');
@@ -241,6 +244,10 @@ export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpaw
         const existing = readPid(port, deps.home);
         if (existing !== null && deps.pidAlive(existing))
             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);
         try {
             unlinkSync(pidFilePath);
             lockFd = deps.openFile(pidFilePath, 'wx');
@@ -267,6 +274,24 @@ export function spawnDaemon(nodeExec, scriptPath, args, port, deps = defaultSpaw
         }
         return false;
     }
+    // Into the daemon log itself, not the parent's stdout: `doctor` points the reader at this file, and
+    // a death recorded anywhere else is a death they will not find. Written through the fd the child is
+    // about to inherit, so it lands immediately before that child's first line — exactly where a reader
+    // comparing two `mcp_daemon_started` entries is already looking.
+    if (null !== orphanPid) {
+        try {
+            writeSync(logFd, `${JSON.stringify({
+                // Same convention as log(): the clock is read at the I/O boundary, not injected.
+                t: new Date().toISOString(),
+                event: 'reticle_daemon_previous_died_unclean',
+                port,
+                pid: orphanPid,
+            })}\n`);
+        }
+        catch {
+            // A log we cannot write is not a reason to refuse to start the daemon.
+        }
+    }
     let child;
     try {
         child = deps.spawnChild(nodeExec, [scriptPath, ...args], {

package/dist/daemon/heartbeat.d.ts

@@ -0,0 +1,115 @@
+/**
+ * A regular beat, so SILENCE in the daemon log becomes evidence.
+ *
+ * `installExitTrace` hooks `'exit'`, which a SIGKILL never fires. So a daemon that is killed —
+ * crashed, OOM-ed, swept by another project, `kill -9`'d by the recipe in every troubleshooting
+ * thread — leaves no trace at all, and the last line before its port goes dark is whatever it
+ * happened to be doing. Worse, a daemon that DID exit logs `code: 0`, so a tidy shutdown and a
+ * violent death are the same shape to anyone reading the file.
+ *
+ * Measured cost of that: a correct SvelteKit install was written up as an install failure, because
+ * the daemon had died 21 seconds earlier and nothing in the log said so. The fixture was named in the
+ * report; the daemon was not.
+ *
+ * Two halves, and the second is what makes the first worth having:
+ *   - DaemonHeartbeat emits `reticle_daemon_alive` on a fixed cadence, unconditionally.
+ *   - classifyDaemonLife reads a log back and says which way the daemon ended.
+ *
+ * A heartbeat nobody interprets is just log volume.
+ */
+/** 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";
+/** Written by installExitTrace when the process exits through Node. */
+export declare const DAEMON_EXIT_EVENT = "reticle_daemon_exiting";
+/** Written by installExitTrace when a signal arrives, which is a CAUSE the exit line does not carry. */
+export declare const DAEMON_SIGNAL_EVENT = "reticle_daemon_signalled";
+/**
+ * How often a live daemon says so.
+ *
+ * The median daemon lives 28 minutes, so at 30s that is ~56 lines — readable, and small against a log
+ * that already rotates. Shorter would make the gap sharper and the file noisier; the gap only needs
+ * to be legible against a connect window, which is measured in seconds.
+ */
+export declare const DAEMON_HEARTBEAT_MS = 30000;
+/**
+ * The cadence, from the environment. Same shape as `resolveIdleCheckMs`: a bad value falls back
+ * rather than throwing, and 0 or negative is not a legal cadence — it would spin.
+ */
+export declare function resolveHeartbeatMs(raw: string | undefined): number;
+interface HeartbeatFacts {
+    /** Browser sessions connected right now. */
+    sessions: number;
+    /**
+     * Has this daemon EVER served a tool call? A lifetime fact, not a window count.
+     *
+     * It is the difference between a death that cost somebody work and one that cost nothing — the
+     * same distinction `isUselessDaemon` already draws. A windowed count would reset under the reader
+     * and make a long-lived daemon look freshly idle.
+     */
+    served: boolean;
+}
+interface DaemonHeartbeatOptions {
+    log: (event: string, fields: Record<string, unknown>) => void;
+    /** Read at each beat, never cached — the point is to describe the daemon NOW. */
+    facts: () => HeartbeatFacts;
+    intervalMs?: number;
+    /** Injected, per the repo rule: never call Date.now() inside logic. */
+    clock?: () => number;
+}
+export declare class DaemonHeartbeat {
+    #private;
+    constructor(opts: DaemonHeartbeatOptions);
+    /**
+     * One beat. Exposed so a test can drive it with an injected clock rather than waiting.
+     *
+     * Unconditional on purpose. Skipping the beat when nothing happened is the obvious optimisation and
+     * it destroys the signal: silence would then mean "idle" OR "dead", which is precisely the
+     * ambiguity this exists to remove.
+     */
+    beat(): void;
+    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];
+/**
+ * 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
+ * would reject the very file it exists to read.
+ */
+interface LogLine {
+    t: number;
+    event: string;
+    signal?: unknown;
+    everyMs?: unknown;
+    [field: string]: unknown;
+}
+export interface DaemonLife {
+    end: DaemonEnd;
+    /** When the last beat landed, or undefined if there was never one. */
+    lastBeatMs?: number;
+    /** How long the log has been silent, when that is the finding. */
+    silentForMs?: number;
+    signal?: string;
+}
+/**
+ * Read a daemon log back and say how it ended.
+ *
+ * UNKNOWN rather than ALIVE when there is no heartbeat at all — every log written before this
+ * existed, and any file the reader was pointed at by mistake. Inferring health from the absence of a
+ * 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/daemon/heartbeat.js

@@ -0,0 +1,141 @@
+/**
+ * A regular beat, so SILENCE in the daemon log becomes evidence.
+ *
+ * `installExitTrace` hooks `'exit'`, which a SIGKILL never fires. So a daemon that is killed —
+ * crashed, OOM-ed, swept by another project, `kill -9`'d by the recipe in every troubleshooting
+ * thread — leaves no trace at all, and the last line before its port goes dark is whatever it
+ * happened to be doing. Worse, a daemon that DID exit logs `code: 0`, so a tidy shutdown and a
+ * violent death are the same shape to anyone reading the file.
+ *
+ * Measured cost of that: a correct SvelteKit install was written up as an install failure, because
+ * the daemon had died 21 seconds earlier and nothing in the log said so. The fixture was named in the
+ * report; the daemon was not.
+ *
+ * Two halves, and the second is what makes the first worth having:
+ *   - DaemonHeartbeat emits `reticle_daemon_alive` on a fixed cadence, unconditionally.
+ *   - classifyDaemonLife reads a log back and says which way the daemon ended.
+ *
+ * A heartbeat nobody interprets is just log volume.
+ */
+/** 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. */
+export const DAEMON_EXIT_EVENT = 'reticle_daemon_exiting';
+/** Written by installExitTrace when a signal arrives, which is a CAUSE the exit line does not carry. */
+export const DAEMON_SIGNAL_EVENT = 'reticle_daemon_signalled';
+/**
+ * How often a live daemon says so.
+ *
+ * The median daemon lives 28 minutes, so at 30s that is ~56 lines — readable, and small against a log
+ * that already rotates. Shorter would make the gap sharper and the file noisier; the gap only needs
+ * to be legible against a connect window, which is measured in seconds.
+ */
+export const DAEMON_HEARTBEAT_MS = 30_000;
+/**
+ * How many beats may be missed before a reader calls it dead.
+ *
+ * Timers slip under load — the battery boots three servers and a browser — and a reader that cries
+ * death on one late beat is a reader people learn to ignore. Two intervals plus a margin.
+ */
+const MISSED_BEATS_TOLERATED = 2;
+/**
+ * The cadence, from the environment. Same shape as `resolveIdleCheckMs`: a bad value falls back
+ * rather than throwing, and 0 or negative is not a legal cadence — it would spin.
+ */
+export function resolveHeartbeatMs(raw) {
+    if (raw === undefined || '' === raw.trim())
+        return DAEMON_HEARTBEAT_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return DAEMON_HEARTBEAT_MS;
+    return Math.floor(n);
+}
+export class DaemonHeartbeat {
+    #log;
+    #facts;
+    #intervalMs;
+    #clock;
+    #startedAt;
+    #timer;
+    constructor(opts) {
+        this.#log = opts.log;
+        this.#facts = opts.facts;
+        this.#intervalMs = opts.intervalMs ?? DAEMON_HEARTBEAT_MS;
+        this.#clock = opts.clock ?? (() => Date.now());
+        this.#startedAt = this.#clock();
+    }
+    /**
+     * One beat. Exposed so a test can drive it with an injected clock rather than waiting.
+     *
+     * Unconditional on purpose. Skipping the beat when nothing happened is the obvious optimisation and
+     * it destroys the signal: silence would then mean "idle" OR "dead", which is precisely the
+     * ambiguity this exists to remove.
+     */
+    beat() {
+        const facts = this.#facts();
+        this.#log(DAEMON_HEARTBEAT_EVENT, {
+            uptimeMs: this.#clock() - this.#startedAt,
+            // The cadence travels WITH the beat so a reader never hard-codes it. Hard-coding is how the
+            // reader and the emitter drift apart the first time the interval is tuned.
+            everyMs: this.#intervalMs,
+            sessions: facts.sessions,
+            served: facts.served,
+        });
+    }
+    start() {
+        if (this.#timer !== undefined)
+            return;
+        this.#timer = setInterval(() => this.beat(), this.#intervalMs);
+        // Never the reason a process stays alive — this is a diagnostic, not a workload.
+        this.#timer.unref();
+    }
+    stop() {
+        if (this.#timer === undefined)
+            return;
+        clearInterval(this.#timer);
+        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',
+};
+/**
+ * Read a daemon log back and say how it ended.
+ *
+ * UNKNOWN rather than ALIVE when there is no heartbeat at all — every log written before this
+ * existed, and any file the reader was pointed at by mistake. Inferring health from the absence of a
+ * signal we never sent is the same confident-wrong this module replaces.
+ */
+export function classifyDaemonLife(lines, nowMs) {
+    const beats = lines.filter((l) => l.event === DAEMON_HEARTBEAT_EVENT);
+    const exit = lines.findLast((l) => l.event === DAEMON_EXIT_EVENT);
+    const signal = lines.findLast((l) => l.event === DAEMON_SIGNAL_EVENT);
+    if (exit !== undefined) {
+        // A signal is the CAUSE; the exit line only says it happened. Reporting `clean` for a SIGTERMed
+        // daemon is how "shut down tidily" and "the bridge every app needs is gone" became one sentence.
+        return signal === undefined
+            ? { end: DaemonEnd.CLEAN }
+            : {
+                end: DaemonEnd.SIGNALLED,
+                ...('string' === typeof signal.signal ? { signal: signal.signal } : {}),
+            };
+    }
+    const last = beats.at(-1);
+    if (last === undefined)
+        return { end: DaemonEnd.UNKNOWN };
+    const everyMs = 'number' === typeof last.everyMs ? last.everyMs : DAEMON_HEARTBEAT_MS;
+    const silentForMs = nowMs - last.t;
+    return silentForMs > everyMs * MISSED_BEATS_TOLERATED
+        ? { end: DaemonEnd.DIED_SILENTLY, lastBeatMs: last.t, silentForMs }
+        : { end: DaemonEnd.ALIVE, lastBeatMs: last.t };
+}

package/dist/daemon/idle-shutdown.d.ts

@@ -35,12 +35,20 @@ export declare class IdleShutdown {
     stop(): void;
 }
 /**
- * Resolve the idle-shutdown grace from `RETICLE_IDLE_SHUTDOWN_MS`: a non-negative integer of milliseconds,
- * `0` to disable. Anything missing/invalid falls back to the default. Pure.
+ * The idle re-check cadence, from the environment. Same shape as the grace resolver, with one
+ * deliberate difference: `0` is not a legal cadence here (it would spin), so `<= 0` falls back to
+ * the default rather than meaning anything.
  */
+export declare function resolveIdleCheckMs(raw: string | undefined): number;
 /**
- * The idle re-check cadence, from the environment. Same shape as the grace resolver: a bad value
- * falls back rather than throwing, and 0/negative is not a legal cadence (it would spin).
+ * Resolve the idle-shutdown grace from `RETICLE_IDLE_SHUTDOWN_MS`: a non-negative integer of
+ * milliseconds, `0` to disable. Anything missing or invalid falls back to the default. Pure.
+ *
+ * The disable is NOT implemented here — 0 is passed through as 0, and `IdleShutdown` treats
+ * `graceMs <= 0` as "never self-shut-down" in both `start()` and `check()`. Said out loud because
+ * this docblock had drifted onto the function above it, leaving this one undocumented next to a
+ * bare `Math.floor`: a reviewer driving 2.5.0 read it as a documented option with no branch
+ * implementing it and filed the gate that depends on it as inverted. The behaviour was correct in
+ * every build; only the code was readable as broken.
  */
-export declare function resolveIdleCheckMs(raw: string | undefined): number;
 export declare function resolveIdleShutdownMs(raw: string | undefined): number;

package/dist/daemon/idle-shutdown.js

@@ -65,12 +65,9 @@ export class IdleShutdown {
     }
 }
 /**
- * Resolve the idle-shutdown grace from `RETICLE_IDLE_SHUTDOWN_MS`: a non-negative integer of milliseconds,
- * `0` to disable. Anything missing/invalid falls back to the default. Pure.
- */
-/**
- * The idle re-check cadence, from the environment. Same shape as the grace resolver: a bad value
- * falls back rather than throwing, and 0/negative is not a legal cadence (it would spin).
+ * The idle re-check cadence, from the environment. Same shape as the grace resolver, with one
+ * deliberate difference: `0` is not a legal cadence here (it would spin), so `<= 0` falls back to
+ * the default rather than meaning anything.
  */
 export function resolveIdleCheckMs(raw) {
     if (raw === undefined || '' === raw.trim())
@@ -80,6 +77,17 @@ export function resolveIdleCheckMs(raw) {
         return SESSION_LIFECYCLE.DAEMON_IDLE_CHECK_MS;
     return Math.floor(n);
 }
+/**
+ * Resolve the idle-shutdown grace from `RETICLE_IDLE_SHUTDOWN_MS`: a non-negative integer of
+ * milliseconds, `0` to disable. Anything missing or invalid falls back to the default. Pure.
+ *
+ * The disable is NOT implemented here — 0 is passed through as 0, and `IdleShutdown` treats
+ * `graceMs <= 0` as "never self-shut-down" in both `start()` and `check()`. Said out loud because
+ * this docblock had drifted onto the function above it, leaving this one undocumented next to a
+ * bare `Math.floor`: a reviewer driving 2.5.0 read it as a documented option with no branch
+ * implementing it and filed the gate that depends on it as inverted. The behaviour was correct in
+ * every build; only the code was readable as broken.
+ */
 export function resolveIdleShutdownMs(raw) {
     if (raw === undefined || '' === raw.trim())
         return SESSION_LIFECYCLE.DAEMON_IDLE_SHUTDOWN_MS;

package/dist/daemon/loopback-alias.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Serve the IPv4-bound daemon on IPv6 loopback too, so `localhost` reaches it on every platform.
+ *
+ * The daemon binds `127.0.0.1` — deliberately, because Reticle must never be reachable off-host. But
+ * `localhost` is a NAME, and on Windows Chrome resolves it to `::1` before `127.0.0.1`. The SDK's
+ * default bridge URL says `localhost`. So on the platform that is most of our installs, and the
+ * browser that is most of that, the documented default cannot connect — and the error text names the
+ * daemon, containers and WSL, none of which is the cause.
+ *
+ * This is a byte forwarder rather than a second `http.Server` on purpose. The daemon speaks HTTP,
+ * WebSocket upgrades and SSE on one port; copying request/upgrade wiring onto a second server means a
+ * second place to keep in sync, and the first handler anybody forgets to mirror becomes a bug that
+ * only Windows sees. A TCP pipe carries all three and cannot drift from what it forwards.
+ *
+ * Best-effort by contract: a machine with IPv6 disabled, or something already holding `[::1]:port`,
+ * leaves the daemon exactly as it was before. Never fatal — this widens reachability, it is not a
+ * precondition for serving.
+ */
+/** IPv6 loopback. The other half of what `localhost` can mean. */
+export declare const IPV6_LOOPBACK = "::1";
+export interface LoopbackAlias {
+    /** False when the alias could not be bound — the daemon still serves IPv4 as before. */
+    opened: boolean;
+    close: () => Promise<void>;
+}
+/**
+ * Accept on `[::1]:port` and pipe each connection to `127.0.0.1:port`.
+ *
+ * Both ends are loopback, so a forwarded peer is still a loopback peer and the bridge's loopback
+ * trust holds — the alias does not widen who may connect, only which address they may name.
+ */
+export declare function openLoopbackAlias(port: number): Promise<LoopbackAlias>;

package/dist/daemon/loopback-alias.js

@@ -0,0 +1,80 @@
+/**
+ * Serve the IPv4-bound daemon on IPv6 loopback too, so `localhost` reaches it on every platform.
+ *
+ * The daemon binds `127.0.0.1` — deliberately, because Reticle must never be reachable off-host. But
+ * `localhost` is a NAME, and on Windows Chrome resolves it to `::1` before `127.0.0.1`. The SDK's
+ * default bridge URL says `localhost`. So on the platform that is most of our installs, and the
+ * browser that is most of that, the documented default cannot connect — and the error text names the
+ * daemon, containers and WSL, none of which is the cause.
+ *
+ * This is a byte forwarder rather than a second `http.Server` on purpose. The daemon speaks HTTP,
+ * WebSocket upgrades and SSE on one port; copying request/upgrade wiring onto a second server means a
+ * second place to keep in sync, and the first handler anybody forgets to mirror becomes a bug that
+ * only Windows sees. A TCP pipe carries all three and cannot drift from what it forwards.
+ *
+ * Best-effort by contract: a machine with IPv6 disabled, or something already holding `[::1]:port`,
+ * leaves the daemon exactly as it was before. Never fatal — this widens reachability, it is not a
+ * precondition for serving.
+ */
+import net from 'node:net';
+import { LOOPBACK_HOST } from '@reticlehq/core';
+/** IPv6 loopback. The other half of what `localhost` can mean. */
+export const IPV6_LOOPBACK = '::1';
+/**
+ * Accept on `[::1]:port` and pipe each connection to `127.0.0.1:port`.
+ *
+ * Both ends are loopback, so a forwarded peer is still a loopback peer and the bridge's loopback
+ * trust holds — the alias does not widen who may connect, only which address they may name.
+ */
+export function openLoopbackAlias(port) {
+    /** Every socket this alias has open, so shutdown can end them instead of waiting them out. */
+    const live = new Set();
+    const server = net.createServer((inbound) => {
+        const outbound = net.connect(port, LOOPBACK_HOST);
+        live.add(inbound).add(outbound);
+        const drop = (socket) => {
+            live.delete(socket);
+        };
+        inbound.on('close', () => drop(inbound));
+        outbound.on('close', () => drop(outbound));
+        // A dead peer on either side must tear down the pair, not surface as an unhandled 'error'
+        // event — which in Node terminates the daemon this alias exists to make reachable.
+        inbound.on('error', () => outbound.destroy());
+        outbound.on('error', () => inbound.destroy());
+        inbound.pipe(outbound);
+        outbound.pipe(inbound);
+    });
+    return new Promise((resolve) => {
+        /**
+         * Stop listening and END EVERYTHING, rather than draining.
+         *
+         * `server.close()` fires its callback only once every existing connection has gone, so a single
+         * held-open socket — a keep-alive, an SSE stream, exactly what this daemon serves — means the
+         * callback never fires. The daemon's shutdown chain awaits this, so an un-drained alias silently
+         * became a daemon that ignores SIGTERM: `reticle stop` timed out, the process stayed alive, and
+         * the port stayed held. Caught by the heartbeat spec, which is the one gate that watches a
+         * daemon actually die.
+         *
+         * A best-effort side listener must never be able to hold up the shutdown of the thing it exists
+         * to make reachable. We are exiting; ending these sockets is the correct outcome, not a
+         * compromise.
+         */
+        const close = () => new Promise((done) => {
+            server.close(() => done());
+            for (const socket of live)
+                socket.destroy();
+            live.clear();
+        });
+        server.once('error', () => {
+            // Nothing was bound, so there is nothing to close — but the caller still gets a close it can
+            // call unconditionally, rather than a shape it has to branch on.
+            resolve({ opened: false, close: () => Promise.resolve() });
+        });
+        server.listen(port, IPV6_LOOPBACK, () => {
+            // Never the reason the process stays up: if the daemon is otherwise done, this must not be
+            // what keeps the event loop alive.
+            server.unref();
+            resolve({ opened: true, close });
+        });
+    });
+}

package/dist/daemon/port-presence.d.ts

@@ -0,0 +1,76 @@
+/**
+ * What is actually on the bridge port — three states, because two produced a lie.
+ *
+ * `isRunning` reads the pid file and never the port. So "a stranger holds 4400" and "nothing holds
+ * 4400" both answer `running: false`, and every surface built on it inherits that:
+ *
+ *   $ reticle serve
+ *   {"event":"reticle_daemon_spawned","port":4400}        <- exit 0
+ *   $ reticle status
+ *   {"event":"reticle_status","port":4400,"running":false}
+ *   $ tail -1 ~/.reticle/daemon-4400.log
+ *   {"event":"reticle_daemon_start_failed","error":"listen EADDRINUSE: ... 127.0.0.1:4400"}
+ *
+ * The daemon knew exactly what was wrong and wrote it where nobody looks. The true sentence — *port
+ * 4400 is held by another process* — was never said by anything a person sees.
+ *
+ * Deliberately probe-based rather than lsof-based: two questions (does TCP connect, does `/status`
+ * answer) separate all three states with no platform-specific code, and they work on Windows, where
+ * every `lsof` recipe in this repo does not. Naming the holding process is a nicer message and a
+ * strictly harder problem; it is not needed to stop lying.
+ */
+export declare const PortPresence: {
+    /** A Reticle daemon answered `/status`. The only usable state. */
+    readonly DAEMON: "daemon";
+    /**
+     * Something accepts connections here and does not serve Reticle's status endpoint.
+     *
+     * A foreign process, or one of our own daemons wedged mid-start — and those are the same fact for
+     * every caller: this port cannot be bound and cannot be used.
+     */
+    readonly FOREIGN: "foreign";
+    /** Nothing is listening. */
+    readonly FREE: "free";
+};
+export type PortPresence = (typeof PortPresence)[keyof typeof PortPresence];
+interface PortFacts {
+    /** A TCP connection to the port was accepted. */
+    tcpOpen: boolean;
+    /** An HTTP GET of `/status` returned a Reticle status payload. */
+    statusAnswered: boolean;
+}
+/**
+ * Pure. The probes live at the call sites (`probeDaemon`, `fetchStatus`) so this stays testable
+ * without a socket, and so a probe that starts lying is a separate failure from a rule that does.
+ */
+export declare function classifyPort(facts: PortFacts): PortPresence;
+/** True only for a daemon that answered. Anything else must not be treated as "running". */
+export declare function presenceIsUsable(presence: PortPresence): boolean;
+/**
+ * Ask the port both questions and classify the answers.
+ *
+ * The TCP probe is first and cheap; `/status` is only asked when something accepted, which keeps the
+ * common "nothing there" case to one failed connect. Impure by necessity — the rule above is where
+ * the behaviour lives, and it is tested without a socket.
+ */
+export declare function probePresence(port: number, probes: {
+    tcpOpen: (port: number) => Promise<boolean>;
+    status: (port: number) => Promise<unknown>;
+}): Promise<PortPresence>;
+/**
+ * Who is holding the port, when we can tell.
+ *
+ * `FOREIGN` covers two situations that need the same answer to "can I bind this?" and OPPOSITE
+ * answers to "what do I do?": a stranger's process, and one of our own daemons wedged. Passing
+ * these lets the sentence tell them apart when — and only when — the recorded pid for the port
+ * matches the process actually holding it.
+ */
+export interface PortHolder {
+    /** The pid we recorded for this port, from the daemon pid file. `null` when there is none. */
+    ourPid: number | null;
+    /** The pid actually holding the port, when the caller could determine it. */
+    holderPid: number | undefined;
+}
+/** One sentence a human can act on, for each state. Exhaustive by switch, so a new state must add one. */
+export declare function describePresence(presence: PortPresence, port: number, holder?: PortHolder): string;
+export {};

package/dist/daemon/port-presence.js

@@ -0,0 +1,93 @@
+/**
+ * What is actually on the bridge port — three states, because two produced a lie.
+ *
+ * `isRunning` reads the pid file and never the port. So "a stranger holds 4400" and "nothing holds
+ * 4400" both answer `running: false`, and every surface built on it inherits that:
+ *
+ *   $ reticle serve
+ *   {"event":"reticle_daemon_spawned","port":4400}        <- exit 0
+ *   $ reticle status
+ *   {"event":"reticle_status","port":4400,"running":false}
+ *   $ tail -1 ~/.reticle/daemon-4400.log
+ *   {"event":"reticle_daemon_start_failed","error":"listen EADDRINUSE: ... 127.0.0.1:4400"}
+ *
+ * The daemon knew exactly what was wrong and wrote it where nobody looks. The true sentence — *port
+ * 4400 is held by another process* — was never said by anything a person sees.
+ *
+ * Deliberately probe-based rather than lsof-based: two questions (does TCP connect, does `/status`
+ * answer) separate all three states with no platform-specific code, and they work on Windows, where
+ * every `lsof` recipe in this repo does not. Naming the holding process is a nicer message and a
+ * strictly harder problem; it is not needed to stop lying.
+ */
+export const PortPresence = {
+    /** A Reticle daemon answered `/status`. The only usable state. */
+    DAEMON: 'daemon',
+    /**
+     * Something accepts connections here and does not serve Reticle's status endpoint.
+     *
+     * A foreign process, or one of our own daemons wedged mid-start — and those are the same fact for
+     * every caller: this port cannot be bound and cannot be used.
+     */
+    FOREIGN: 'foreign',
+    /** Nothing is listening. */
+    FREE: 'free',
+};
+/**
+ * Pure. The probes live at the call sites (`probeDaemon`, `fetchStatus`) so this stays testable
+ * without a socket, and so a probe that starts lying is a separate failure from a rule that does.
+ */
+export function classifyPort(facts) {
+    if (facts.statusAnswered) {
+        if (!facts.tcpOpen) {
+            // Not reachable from a real pair of probes. Folding it into DAEMON would mean a broken TCP
+            // probe reports a healthy daemon — the exact shape of confident-wrong this module exists to
+            // remove — so it is an error rather than a guess.
+            throw new Error('a port cannot answer /status without accepting a TCP connection; one of the probes is wrong');
+        }
+        return PortPresence.DAEMON;
+    }
+    return facts.tcpOpen ? PortPresence.FOREIGN : PortPresence.FREE;
+}
+/** True only for a daemon that answered. Anything else must not be treated as "running". */
+export function presenceIsUsable(presence) {
+    return presence === PortPresence.DAEMON;
+}
+/**
+ * Ask the port both questions and classify the answers.
+ *
+ * The TCP probe is first and cheap; `/status` is only asked when something accepted, which keeps the
+ * common "nothing there" case to one failed connect. Impure by necessity — the rule above is where
+ * the behaviour lives, and it is tested without a socket.
+ */
+export async function probePresence(port, probes) {
+    const tcpOpen = await probes.tcpOpen(port);
+    if (!tcpOpen)
+        return PortPresence.FREE;
+    const status = await probes.status(port);
+    return classifyPort({ tcpOpen, statusAnswered: status !== undefined });
+}
+/** One sentence a human can act on, for each state. Exhaustive by switch, so a new state must add one. */
+export function describePresence(presence, port, holder) {
+    switch (presence) {
+        case PortPresence.DAEMON:
+            return `a Reticle daemon is serving :${String(port)}`;
+        case PortPresence.FOREIGN:
+            // Our own daemon, wedged: it accepts TCP and never answers `/status`, so it classifies as
+            // FOREIGN — correct for binding, and a lie in prose. Found by SIGSTOPping a daemon: doctor
+            // said "which is not a Reticle daemon" about a pid its own pid file named, and sent the
+            // reader hunting a stranger while never mentioning the fix that works.
+            if (holder?.ourPid !== null &&
+                holder?.ourPid !== undefined &&
+                holder.ourPid === holder.holderPid) {
+                return (`port ${String(port)} is held by YOUR Reticle daemon (pid ${String(holder.ourPid)}), ` +
+                    'and it is not responding — it is running but wedged, so nothing can use it and nothing ' +
+                    'else can bind the port. Stop it (`reticle stop`) and the next tool call starts a fresh ' +
+                    'one.');
+            }
+            return (`port ${String(port)} is held by another process that is not a Reticle daemon — ` +
+                'a daemon cannot bind it. Stop that process, or run Reticle on a different port ' +
+                '(`--port`), then retry.');
+        case PortPresence.FREE:
+            return `nothing is listening on :${String(port)} — no daemon is running`;
+    }
+}