@reticlehq/server 2.5.0 → 2.6.0

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/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`;
+    }
+}

package/dist/daemon/state-dir.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A sentence naming the problem, or `undefined` when the directory is usable.
+ *
+ * A directory that does not exist yet is NOT a problem: the daemon creates it, and the creation
+ * failing is caught by the same probe on the parent path.
+ */
+export declare function stateDirProblem(dir: string): string | undefined;

package/dist/daemon/state-dir.js

@@ -0,0 +1,59 @@
+/**
+ * Can Reticle write the directory it keeps everything in?
+ *
+ * `~/.reticle` holds the pid files, the daemon logs, the telemetry id and outbox, and every saved
+ * flow. A daemon that cannot write it does not start — and until now said nothing useful about why.
+ *
+ * Measured on 2.6.0 with `chmod 555 ~/.reticle`:
+ *
+ *   the daemon did not come up on :4415 — nothing is listening on :4415 — no daemon is running
+ *   see /…/.reticle/daemon-4415.log
+ *
+ * The first line restates the symptom. The second points at a log **inside the unwritable
+ * directory**, so the one diagnostic offered cannot exist. Someone hitting this — a locked-down home
+ * directory, a container with a read-only mount, a managed corporate profile — has nothing to go on.
+ *
+ * Deliberately a PROBE, not a permission-bit read: `stat` says what the mode claims, and an ACL, a
+ * read-only mount, SELinux or a full disk all produce a writable-looking mode and a failing write.
+ * The only honest test of "can I write here" is writing.
+ */
+import { mkdirSync, existsSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+/** Probe filename. Distinctive so a leftover is obviously ours, and unlinked immediately either way. */
+const PROBE = '.reticle-write-probe';
+/**
+ * A sentence naming the problem, or `undefined` when the directory is usable.
+ *
+ * A directory that does not exist yet is NOT a problem: the daemon creates it, and the creation
+ * failing is caught by the same probe on the parent path.
+ */
+export function stateDirProblem(dir) {
+    if (!existsSync(dir)) {
+        // Not yet created is the ordinary first-run state. Only report if we cannot create it.
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch {
+            return (`Reticle cannot create its state directory at ${dir}. Everything it keeps — the daemon ` +
+                'log, the pid file, saved flows — lives there, so the daemon cannot start. Check the ' +
+                'permissions on the parent directory, or point Reticle elsewhere with HOME.');
+        }
+        return undefined;
+    }
+    const probe = join(dir, PROBE);
+    try {
+        writeFileSync(probe, '', 'utf8');
+    }
+    catch {
+        return (`Reticle cannot write to its state directory at ${dir}. Everything it keeps — the daemon ` +
+            'log, the pid file, saved flows — lives there, so the daemon cannot start. Make it writable ' +
+            '(`chmod u+w`), or point Reticle elsewhere with HOME.');
+    }
+    try {
+        unlinkSync(probe);
+    }
+    catch {
+        /* wrote but could not clean up: the directory IS writable, which is the question asked */
+    }
+    return undefined;
+}

package/dist/daemon/unclean-predecessor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The pid of a daemon that died without exiting, observed at the next start.
+ *
+ * `DaemonExitReason` covers every departure that goes through Node — signal, idle, and the
+ * load-bearing `unknown` for a stray exit or an uncaught throw. It cannot cover SIGKILL, an OOM
+ * kill, or a lost machine: no handler runs, so the log's last word about that daemon is whatever it
+ * happened to be doing. From the report (#123):
+ *
+ *   10:49:05  mcp_daemon_started        port:4400            <- pid 2884
+ *   10:51:29  mcp_daemon_started        port:4400  pid:4900  <- a SECOND daemon binds the SAME port
+ *
+ * pid 2884 died with no exit event at all, and the only evidence was that a second daemon could bind
+ * a port the first one held — something a reader has to notice and interpret.
+ *
+ * The next startup is the only place that death is observable, because it is the only moment
+ * anything looks at the pidfile the dead process left behind. A tidy shutdown unlinks its own, so
+ * finding one whose owner is gone IS the signal.
+ *
+ * Pure, and deliberately conservative: an owner that is still ALIVE is a port conflict, not a death,
+ * and accusing a live sibling of dying would be a new false claim in the log this exists to make
+ * honest.
+ */
+export declare function uncleanPredecessor(owner: number | null, alive: boolean, self: number): number | null;

package/dist/daemon/unclean-predecessor.js

@@ -0,0 +1,27 @@
+/**
+ * The pid of a daemon that died without exiting, observed at the next start.
+ *
+ * `DaemonExitReason` covers every departure that goes through Node — signal, idle, and the
+ * load-bearing `unknown` for a stray exit or an uncaught throw. It cannot cover SIGKILL, an OOM
+ * kill, or a lost machine: no handler runs, so the log's last word about that daemon is whatever it
+ * happened to be doing. From the report (#123):
+ *
+ *   10:49:05  mcp_daemon_started        port:4400            <- pid 2884
+ *   10:51:29  mcp_daemon_started        port:4400  pid:4900  <- a SECOND daemon binds the SAME port
+ *
+ * pid 2884 died with no exit event at all, and the only evidence was that a second daemon could bind
+ * a port the first one held — something a reader has to notice and interpret.
+ *
+ * The next startup is the only place that death is observable, because it is the only moment
+ * anything looks at the pidfile the dead process left behind. A tidy shutdown unlinks its own, so
+ * finding one whose owner is gone IS the signal.
+ *
+ * Pure, and deliberately conservative: an owner that is still ALIVE is a port conflict, not a death,
+ * and accusing a live sibling of dying would be a new false claim in the log this exists to make
+ * honest.
+ */
+export function uncleanPredecessor(owner, alive, self) {
+    if (null === owner || owner === self || alive)
+        return null;
+    return owner;
+}

package/dist/events/predicate-eval.d.ts

@@ -83,6 +83,16 @@ export interface EvalResult {
     inconclusive?: string;
     evidence?: unknown;
     failureReason?: string;
+    /**
+     * The wait ended because the TAB went away, not because the app did anything observable.
+     *
+     * A sibling of `inconclusive` and for the same reason: `pass` is false because nothing was
+     * proven, but nobody could have made it true, so grading it as a defect in the user's app is a
+     * false claim. Without this the verdict rule saw only `pass: false` and answered
+     * `assertion_failed` — "the declared consequence did not hold" — naming the component the agent
+     * had just clicked. See VerifiedReason.OBSERVATION_LOST.
+     */
+    observationLost?: boolean;
     /**
      * The failure, structured — what was seen, what was required, and which oracle judged it.
      *