@reticlehq/server 2.4.0 → 2.6.0

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

@@ -0,0 +1,32 @@
+/**
+ * How long an idle daemon is given before it shuts itself down.
+ *
+ * It used to be one number for every case, and at 5 minutes that number killed live runs: 187
+ * `reticle_daemon_idle_shutdown` lines on one user's machine, with their editor's Reticle
+ * disconnecting each time; and in the fixtures gate it fired during long dependency installs, so apps
+ * that booted afterwards hit ERR_CONNECTION_REFUSED and were scored as install failures when nothing
+ * was wrong with their install.
+ *
+ * Reverting is not an option. Daemons used to sit idle a median of 28 minutes at a 0.04% duty cycle
+ * because "an agent is attached" alone kept one alive for a whole editor session, and the widened
+ * rule is what fixed that.
+ *
+ * The distinction is TIME, not state. Mid-install an attached daemon is state-identical to one in an
+ * empty directory — nothing has been asked of either. What differs is how long it is reasonable to
+ * wait: quiet with a client attached means the human is thinking or the install is slow; the same
+ * quiet with nobody attached means the daemon is unwanted. Both still exit.
+ */
+/**
+ * An attached daemon waits this many times the base grace. Six is chosen against the two measurements
+ * that matter: the default base is 5 minutes, so an attached daemon survives 30 — comfortably past
+ * the slow installs that were killing runs, and comfortably short of the 28-minute median idle the
+ * shorter rule was introduced to end.
+ */
+export declare const ATTACHED_GRACE_MULTIPLIER = 6;
+/**
+ * @param overrideMs an explicit attached grace (RETICLE_IDLE_ATTACHED_MS). Derived from the base when
+ * absent — but the derived value is arithmetic on a number the caller also controls, and a test that
+ * has to reason about both is a test that breaks for the wrong reason. Configuring it directly is
+ * what lets the e2e spec assert the BEHAVIOUR (an attached daemon exits) without racing a product.
+ */
+export declare function idleGraceMs(baseMs: number, agentAttached: boolean, overrideMs?: number): number;

package/dist/daemon/idle-grace.js

@@ -0,0 +1,41 @@
+/**
+ * How long an idle daemon is given before it shuts itself down.
+ *
+ * It used to be one number for every case, and at 5 minutes that number killed live runs: 187
+ * `reticle_daemon_idle_shutdown` lines on one user's machine, with their editor's Reticle
+ * disconnecting each time; and in the fixtures gate it fired during long dependency installs, so apps
+ * that booted afterwards hit ERR_CONNECTION_REFUSED and were scored as install failures when nothing
+ * was wrong with their install.
+ *
+ * Reverting is not an option. Daemons used to sit idle a median of 28 minutes at a 0.04% duty cycle
+ * because "an agent is attached" alone kept one alive for a whole editor session, and the widened
+ * rule is what fixed that.
+ *
+ * The distinction is TIME, not state. Mid-install an attached daemon is state-identical to one in an
+ * empty directory — nothing has been asked of either. What differs is how long it is reasonable to
+ * wait: quiet with a client attached means the human is thinking or the install is slow; the same
+ * quiet with nobody attached means the daemon is unwanted. Both still exit.
+ */
+/**
+ * An attached daemon waits this many times the base grace. Six is chosen against the two measurements
+ * that matter: the default base is 5 minutes, so an attached daemon survives 30 — comfortably past
+ * the slow installs that were killing runs, and comfortably short of the 28-minute median idle the
+ * shorter rule was introduced to end.
+ */
+export const ATTACHED_GRACE_MULTIPLIER = 6;
+/**
+ * @param overrideMs an explicit attached grace (RETICLE_IDLE_ATTACHED_MS). Derived from the base when
+ * absent — but the derived value is arithmetic on a number the caller also controls, and a test that
+ * has to reason about both is a test that breaks for the wrong reason. Configuring it directly is
+ * what lets the e2e spec assert the BEHAVIOUR (an attached daemon exits) without racing a product.
+ */
+export function idleGraceMs(baseMs, agentAttached, overrideMs) {
+    // A non-positive base means the watcher is disabled; multiplying must not resurrect it.
+    if (baseMs <= 0)
+        return baseMs;
+    if (!agentAttached)
+        return baseMs;
+    return overrideMs !== undefined && overrideMs > 0
+        ? overrideMs
+        : baseMs * ATTACHED_GRACE_MULTIPLIER;
+}

package/dist/{idle-shutdown.d.ts → daemon/idle-shutdown.d.ts}

@@ -5,6 +5,14 @@ export interface IdleShutdownOptions {
     onShutdown: () => void;
     /** Continuous-idle window before shutdown. `0` (or negative) disables the watcher entirely. */
     graceMs: number;
+    /**
+     * Is an agent's MCP client attached right now? An attached daemon gets a much longer grace — quiet
+     * with a client present means a slow install or a thinking human, not an unwanted daemon. It still
+     * exits. See idle-grace.
+     */
+    agentAttached?: () => boolean;
+    /** Explicit attached grace (RETICLE_IDLE_ATTACHED_MS); derived from graceMs when absent. */
+    attachedGraceMs?: number;
     /** How often to re-check idleness. */
     checkIntervalMs?: number;
     /** Injected clock — never read wall-clock time in logic (repo rule). */
@@ -27,7 +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;
+/**
+ * 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 resolveIdleShutdownMs(raw: string | undefined): number;

package/dist/{idle-shutdown.js → daemon/idle-shutdown.js}

@@ -1,5 +1,6 @@
 import { SESSION_LIFECYCLE } from '@reticlehq/core';
-import { log } from './log.js';
+import { idleGraceMs } from './idle-grace.js';
+import { log } from '../log.js';
 /**
  * Self-terminates an idle daemon so Reticle never lingers eating a user's resources (the daemon process,
  * any headless Chromium the pool launched, and the bound port) after the editor closes. The `reticle mcp`
@@ -15,12 +16,16 @@ export class IdleShutdown {
     #isIdle;
     #onShutdown;
     #graceMs;
+    #agentAttached;
+    #attachedGraceMs;
     #checkMs;
     #clock;
     constructor(opts) {
         this.#isIdle = opts.isIdle;
         this.#onShutdown = opts.onShutdown;
         this.#graceMs = opts.graceMs;
+        this.#agentAttached = opts.agentAttached;
+        this.#attachedGraceMs = opts.attachedGraceMs;
         this.#checkMs = opts.checkIntervalMs ?? SESSION_LIFECYCLE.DAEMON_IDLE_CHECK_MS;
         this.#clock = opts.clock ?? (() => Date.now());
     }
@@ -34,9 +39,15 @@ export class IdleShutdown {
         }
         const now = this.#clock();
         this.#idleSince ??= now;
-        if (now - this.#idleSince >= this.#graceMs) {
+        // Read per CHECK, not at construction: a client attaches and detaches during a daemon's life, and
+        // the question "how long should this quiet be tolerated" is only answerable now. See idle-grace.
+        const grace = idleGraceMs(this.#graceMs, this.#agentAttached?.() ?? false, this.#attachedGraceMs);
+        if (now - this.#idleSince >= grace) {
             this.#fired = true;
-            log('reticle_daemon_idle_shutdown', { idleMs: now - this.#idleSince });
+            log('reticle_daemon_idle_shutdown', {
+                idleMs: now - this.#idleSince,
+                attached: this.#agentAttached?.() ?? false,
+            });
             this.#onShutdown();
         }
     }
@@ -54,11 +65,31 @@ 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, 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())
+        return SESSION_LIFECYCLE.DAEMON_IDLE_CHECK_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        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() === '')
+    if (raw === undefined || '' === raw.trim())
         return SESSION_LIFECYCLE.DAEMON_IDLE_SHUTDOWN_MS;
     const n = Number(raw);
     if (!Number.isFinite(n) || n < 0)

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/domain/domain-model.js

@@ -107,11 +107,11 @@ export function buildDomainModel(flows, contract, runs = []) {
     };
 }
 function buildSummary(flowCount, coverage, gaps, topRisk) {
-    if (flowCount === 0) {
+    if (0 === flowCount) {
         return 'No saved flows yet — record the critical journeys (reticle_record{action:"start"}) so the agent learns the app.';
     }
     const parts = [
-        `${String(flowCount)} flow${flowCount === 1 ? '' : 's'}: ${String(coverage.asserted)} asserted, ${String(coverage.presenceOnly)} presence-only, ${String(coverage.assertionFree)} assertion-free`,
+        `${String(flowCount)} flow${1 === flowCount ? '' : 's'}: ${String(coverage.asserted)} asserted, ${String(coverage.presenceOnly)} presence-only, ${String(coverage.assertionFree)} assertion-free`,
     ];
     if (topRisk !== undefined) {
         parts.push(`test first: ${topRisk.name} (${topRisk.reason})`);

package/dist/events/body-failures.js

@@ -25,19 +25,19 @@ const ERROR_KEYS = ['error', 'errors', 'errorMessage', 'failureReason'];
 /** Arrays worth walking for per-item outcomes. Bulk APIs converge on a handful of names. */
 const ITEM_KEYS = ['results', 'items', 'data', 'records', 'responses'];
 function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
+    return 'object' === typeof value && value !== null && !Array.isArray(value);
 }
 /** Whether one object reports a failure of its own. */
 function reportsFailure(item) {
     if (!isRecord(item))
         return false;
     for (const flag of FAILURE_FLAGS) {
-        if (item[flag] === false)
+        if (false === item[flag])
             return true;
     }
     for (const key of ERROR_KEYS) {
         const value = item[key];
-        if (value === undefined || value === null)
+        if (value === undefined || null === value)
             continue;
         if (Array.isArray(value)) {
             if (value.length > 0)
@@ -45,7 +45,7 @@ function reportsFailure(item) {
             continue;
         }
         // An empty string or an explicit null is an API saying "no error", not an error.
-        if (typeof value === 'string' && value.length === 0)
+        if ('string' === typeof value && 0 === value.length)
             continue;
         return true;
     }
@@ -55,7 +55,7 @@ function reportsFailure(item) {
 function itemOutcomes(body) {
     for (const key of ITEM_KEYS) {
         const list = body[key];
-        if (!Array.isArray(list) || list.length === 0)
+        if (!Array.isArray(list) || 0 === list.length)
             continue;
         const failed = list.filter(reportsFailure).length;
         return { failed, total: list.length };
@@ -63,7 +63,7 @@ function itemOutcomes(body) {
     return { failed: 0, total: 0 };
 }
 function parse(raw) {
-    if (typeof raw !== 'string' || raw.length === 0)
+    if (typeof raw !== 'string' || 0 === raw.length)
         return undefined;
     try {
         const parsed = JSON.parse(raw);
@@ -87,8 +87,8 @@ export function findBodyFailures(events) {
         const body = parse(event.data['responseBody']);
         if (body === undefined)
             continue;
-        const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
-        const method = typeof event.data['method'] === 'string' ? event.data['method'] : '';
+        const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
+        const method = 'string' === typeof event.data['method'] ? event.data['method'] : '';
         const where = `${method} ${url} → ${String(status)}`;
         const { failed, total } = itemOutcomes(body);
         if (failed > 0) {

package/dist/events/contradictions.d.ts

@@ -50,4 +50,4 @@ export interface ContradictionOptions {
      */
     mutatedWithin?: number | undefined;
 }
-export declare function findContradictions(events: readonly ReticleEvent[], options?: ContradictionOptions): Contradiction[];
+export declare function findContradictions(allEvents: readonly ReticleEvent[], options?: ContradictionOptions): Contradiction[];