@reticlehq/server 2.13.1 → 2.14.0

package/dist/cloud/cloud-sync.d.ts

@@ -9,7 +9,7 @@
  * cloud copy is an enhancement, so a push error is logged and swallowed.
  */
 import { z } from 'zod';
-import type { FlowFile, ReticleVerificationRun, RunRecord } from '@reticlehq/core';
+import { type FlowFile, type ReticleVerificationRun, type RunRecord, type VerifyProgressEvent } from '@reticlehq/core';
 /** Env var names — the presence of BOTH is what "logged in" means for cloud sync. */
 export declare const CloudEnv: {
     readonly URL: "RETICLE_CLOUD_URL";
@@ -115,21 +115,21 @@ declare const ServerVerificationSchema: z.ZodObject<{
     }>, "many">;
     summary: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    verificationId: string;
     verdict: string | null;
     flows: {
         status: string;
         name: string;
     }[];
     summary: string;
-    verificationId: string;
 }, {
+    verificationId: string;
     verdict: string | null;
     flows: {
         status: string;
         name: string;
     }[];
     summary: string;
-    verificationId: string;
 }>;
 export type ServerVerification = z.infer<typeof ServerVerificationSchema>;
 /**
@@ -144,4 +144,47 @@ export declare function submitServerVerification(body: {
     flows: string[];
     source: string;
 }, config: CloudConfig | null, fetchImpl: FetchPostJsonLike): Promise<ServerVerification | null>;
+/**
+ * Narrate a run in flight to the dashboard.
+ *
+ * ## Why this exists
+ *
+ * Everything else here syncs a FINISHED artifact. That is the right shape for evidence and the wrong
+ * shape for the minutes a verification is actually running: a browser launches, flows replay one at
+ * a time, and until the run ends the dashboard has nothing to show but a spinner. A run that is
+ * working and a run that has died are indistinguishable for the whole of its duration, and somebody
+ * watching sat on exactly that ambiguity for fifteen minutes.
+ *
+ * ## Why it is batched
+ *
+ * One request per flow is one request per flow. A fifty-flow suite would open a hundred connections
+ * to say things that are only interesting in aggregate, so events accumulate and go out on a timer.
+ * Two seconds is well under the time a person waits before deciding a page is broken, and well over
+ * the time a fast flow takes — so a burst of quick replays becomes one request, not twenty.
+ *
+ * ## Why it can never matter
+ *
+ * Opt-in like every other cloud call (no credentials → no-op, nothing leaves the machine), and
+ * best-effort at every layer: a failed flush is dropped, never retried and never surfaced. This is
+ * narration. The run artifact is the record, it syncs separately, and nothing here is graded or
+ * allowed to influence a verdict or an exit code.
+ */
+export declare function syncProgressToCloud(runId: string, events: readonly VerifyProgressEvent[], config: CloudConfig | null, fetchImpl: FetchLike): Promise<SyncResult>;
+/** How long events accumulate before a flush. See the batching note above. */
+export declare const PROGRESS_FLUSH_MS = 2000;
+/**
+ * A listener that buffers progress and ships it on a timer.
+ *
+ * Returned with its own `flush` and `stop` so the caller can push the last events out when the run
+ * ends — otherwise the most interesting event of all, the one saying it finished, waits for a timer
+ * that is about to be cleared.
+ *
+ * The timer is `unref`'d where the runtime supports it: a narration timer must never be the reason a
+ * CLI process stays alive after its work is done.
+ */
+export declare function createProgressReporter(runId: string, config: CloudConfig | null, fetchImpl: FetchLike, flushMs?: number): {
+    onProgress: (event: VerifyProgressEvent) => void;
+    flush: () => Promise<void>;
+    stop: () => void;
+};
 export {};

package/dist/cloud/cloud-sync.js

@@ -9,6 +9,7 @@
  * cloud copy is an enhancement, so a push error is logged and swallowed.
  */
 import { z } from 'zod';
+import { VERIFY_PROGRESS_MAX_EVENTS, } from '@reticlehq/core';
 /** Env var names — the presence of BOTH is what "logged in" means for cloud sync. */
 export const CloudEnv = {
     URL: 'RETICLE_CLOUD_URL',
@@ -20,6 +21,7 @@ const CLOUD_RUNS_PATH = '/v1/runs';
 const CLOUD_PROJECT_RUNS_PATH = '/v1/project/runs';
 const CLOUD_PROJECT_REGRESSION_PATH = '/v1/project/regression';
 const CLOUD_VERIFICATIONS_PATH = '/v1/verifications';
+const CLOUD_PROGRESS_PATH = '/v1/connect/progress';
 /** Resolve cloud credentials from the environment, or null when not logged in (sync disabled). */
 export function resolveCloudConfig(env) {
     const url = env[CloudEnv.URL];
@@ -236,3 +238,117 @@ export async function submitServerVerification(body, config, fetchImpl) {
         return null;
     }
 }
+/**
+ * Narrate a run in flight to the dashboard.
+ *
+ * ## Why this exists
+ *
+ * Everything else here syncs a FINISHED artifact. That is the right shape for evidence and the wrong
+ * shape for the minutes a verification is actually running: a browser launches, flows replay one at
+ * a time, and until the run ends the dashboard has nothing to show but a spinner. A run that is
+ * working and a run that has died are indistinguishable for the whole of its duration, and somebody
+ * watching sat on exactly that ambiguity for fifteen minutes.
+ *
+ * ## Why it is batched
+ *
+ * One request per flow is one request per flow. A fifty-flow suite would open a hundred connections
+ * to say things that are only interesting in aggregate, so events accumulate and go out on a timer.
+ * Two seconds is well under the time a person waits before deciding a page is broken, and well over
+ * the time a fast flow takes — so a burst of quick replays becomes one request, not twenty.
+ *
+ * ## Why it can never matter
+ *
+ * Opt-in like every other cloud call (no credentials → no-op, nothing leaves the machine), and
+ * best-effort at every layer: a failed flush is dropped, never retried and never surfaced. This is
+ * narration. The run artifact is the record, it syncs separately, and nothing here is graded or
+ * allowed to influence a verdict or an exit code.
+ */
+export async function syncProgressToCloud(runId, events, config, fetchImpl) {
+    if (null === config)
+        return { outcome: SyncOutcome.SKIPPED };
+    if (0 === events.length)
+        return { outcome: SyncOutcome.SKIPPED };
+    try {
+        const res = await fetchImpl(`${config.url}${CLOUD_PROGRESS_PATH}`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${config.apiKey}`,
+            },
+            // Bounded on the way OUT as well as in the schema: a receiver that rejects an oversized batch
+            // would drop the whole window, and the newest events are the ones somebody is waiting on.
+            body: JSON.stringify({ runId, events: events.slice(-VERIFY_PROGRESS_MAX_EVENTS) }),
+        });
+        return res.ok
+            ? { outcome: SyncOutcome.SYNCED, status: res.status }
+            : { outcome: SyncOutcome.FAILED, status: res.status };
+    }
+    catch (err) {
+        return { outcome: SyncOutcome.FAILED, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** How long events accumulate before a flush. See the batching note above. */
+export const PROGRESS_FLUSH_MS = 2_000;
+/**
+ * A listener that buffers progress and ships it on a timer.
+ *
+ * Returned with its own `flush` and `stop` so the caller can push the last events out when the run
+ * ends — otherwise the most interesting event of all, the one saying it finished, waits for a timer
+ * that is about to be cleared.
+ *
+ * The timer is `unref`'d where the runtime supports it: a narration timer must never be the reason a
+ * CLI process stays alive after its work is done.
+ */
+export function createProgressReporter(runId, config, fetchImpl, flushMs = PROGRESS_FLUSH_MS) {
+    /*
+     * The WHOLE window, re-sent each flush — not the events since the last one.
+     *
+     * The receiver REPLACES the row it keeps for a project rather than appending, because one row per
+     * project is what stops narration accumulating into a second, ungraded history of the run. A
+     * client that sent deltas against that would destroy its own story: each flush would overwrite the
+     * row with only the handful of events since the previous one, and a finished run would be
+     * represented by whatever its last two seconds happened to contain.
+     *
+     * Found by running a real verification and watching the dashboard freeze on flow 2 of 3.
+     *
+     * Re-sending is cheap and idempotent: the window is bounded, the events are tiny, and a replace is
+     * the same operation however many times it arrives. `dirty` keeps an unchanged window off the
+     * wire, so a run that has gone quiet stops posting rather than resending forever.
+     */
+    /* Named `accumulated`, not `window`: this is Node, and shadowing the global reads badly. */
+    const accumulated = [];
+    let dirty = false;
+    let timer = null;
+    const flush = async () => {
+        if (!dirty || 0 === accumulated.length)
+            return;
+        // Cleared BEFORE the await so a slow flush does not let the next tick send the same window
+        // again; a genuinely new event during the send re-sets it and the next tick picks it up.
+        dirty = false;
+        await syncProgressToCloud(runId, [...accumulated], config, fetchImpl).catch(() => undefined);
+    };
+    const start = () => {
+        if (null !== timer || null === config)
+            return;
+        timer = setInterval(() => void flush(), flushMs);
+        timer.unref?.();
+    };
+    return {
+        onProgress: (event) => {
+            if (null === config)
+                return; // not logged in: nothing is buffered and nothing is sent
+            // Bounded, keeping the NEWEST: they are the ones somebody is waiting on.
+            if (accumulated.length >= VERIFY_PROGRESS_MAX_EVENTS)
+                accumulated.shift();
+            accumulated.push(event);
+            dirty = true;
+            start();
+        },
+        flush,
+        stop: () => {
+            if (null !== timer)
+                clearInterval(timer);
+            timer = null;
+        },
+    };
+}

package/dist/cloud/sync-cycle.d.ts

@@ -4,7 +4,7 @@
  * A list rather than three hand-written blocks so adding a fourth is one line and cannot be
  * half-done — the bundle, the hashing and the reporting all walk this.
  */
-export declare const DERIVED_RECORDS: readonly [{
+declare const DERIVED_RECORDS: readonly [{
     readonly kind: "impact";
     readonly file: "impact.json";
 }, {
@@ -14,7 +14,7 @@ export declare const DERIVED_RECORDS: readonly [{
     readonly kind: "intent";
     readonly file: "intent.json";
 }];
-export type DerivedKind = (typeof DERIVED_RECORDS)[number]['kind'];
+type DerivedKind = (typeof DERIVED_RECORDS)[number]['kind'];
 /** What the machine reads from disk. Injected so a cycle is testable with no filesystem at all. */
 export interface SyncSource {
     /** Every run artifact currently on disk. */
@@ -35,7 +35,7 @@ export interface SyncSink {
     writeState: (state: CloudSyncState) => void;
 }
 /** A decision a human made on the dashboard, as the machine stores it. */
-export interface PulledIssue {
+interface PulledIssue {
     status: string;
     flowName: string | null;
     title: string;
@@ -82,7 +82,7 @@ export interface SyncReport {
     /** Set when the cycle could not complete. The local record is untouched either way. */
     error?: string;
 }
-export interface SyncDeps {
+interface SyncDeps {
     config: {
         url: string;
         apiKey: string;
@@ -108,3 +108,4 @@ export interface SyncDeps {
 export declare function runSyncCycle(deps: SyncDeps): Promise<SyncReport>;
 /** One line a human can read, for the CLI and the daemon log. */
 export declare function describeSync(report: SyncReport): string;
+export {};

package/dist/cloud/sync-cycle.js

@@ -42,7 +42,7 @@ const SYNC_PULL_PATH = '/v1/sync/pull';
  * A list rather than three hand-written blocks so adding a fourth is one line and cannot be
  * half-done — the bundle, the hashing and the reporting all walk this.
  */
-export const DERIVED_RECORDS = [
+const DERIVED_RECORDS = [
     { kind: 'impact', file: ReticleDir.IMPACT_FILE },
     { kind: 'flake', file: ReticleDir.FLAKE_FILE },
     { kind: 'intent', file: ReticleDir.INTENT_FILE },

package/dist/cloud/sync-daemon.d.ts

@@ -1,23 +1,6 @@
 import { type SyncReport } from './sync-cycle.js';
 import type { ProjectCloud } from './cloud-config.js';
-/** How often the daemon cycles. See the note above on why this is a constant and not a curve. */
-export declare const DAEMON_SYNC_INTERVAL_MS = 60000;
-/**
- * The cadence while something is actually happening.
- *
- * A fixed minute is the wrong shape for both states it has to cover. During a drive the ledger
- * changes on every tool call and a minute of lag is what makes a dashboard feel dead; idle, a minute
- * is already more often than nothing has changed deserves.
- *
- * So the interval follows the work: a cycle that MOVED something earns the fast rate, a cycle that
- * moved nothing backs off to the slow one. No session plumbing and no new configuration — activity
- * is inferred from what the last cycle actually sent, which is the only honest evidence available.
- *
- * Deliberately not per-tool-call. A push in the tool path would put the network in the agent's inner
- * loop, and verification working with the network down is a promise this product makes.
- */
-export declare const DAEMON_SYNC_ACTIVE_INTERVAL_MS = 5000;
-export interface SyncDaemonDeps {
+interface SyncDaemonDeps {
     reticleRoot: string;
     /** Resolved per tick, not once: a repo linked while the daemon is alive starts syncing itself. */
     cloud: () => Promise<ProjectCloud>;
@@ -46,7 +29,7 @@ export interface SyncDaemonDeps {
         text: string;
     }>;
 }
-export interface SyncDaemon {
+interface SyncDaemon {
     /** Run one cycle now, whatever the timer is doing. Returns undefined when not linked. */
     syncNow: () => Promise<SyncReport | undefined>;
     /**
@@ -67,3 +50,4 @@ export interface SyncDaemon {
  * nothing until one appears, which is what lets `reticle link` take effect without a restart.
  */
 export declare function startSyncDaemon(deps: SyncDaemonDeps): SyncDaemon;
+export {};

package/dist/cloud/sync-daemon.js

@@ -25,7 +25,7 @@ import { log } from '../log.js';
 import { describeSync, runSyncCycle } from './sync-cycle.js';
 import { diskSink, diskSource, readCloudState } from './sync-disk.js';
 /** How often the daemon cycles. See the note above on why this is a constant and not a curve. */
-export const DAEMON_SYNC_INTERVAL_MS = 60_000;
+const DAEMON_SYNC_INTERVAL_MS = 60_000;
 /**
  * The cadence while something is actually happening.
  *
@@ -40,7 +40,7 @@ export const DAEMON_SYNC_INTERVAL_MS = 60_000;
  * Deliberately not per-tool-call. A push in the tool path would put the network in the agent's inner
  * loop, and verification working with the network down is a promise this product makes.
  */
-export const DAEMON_SYNC_ACTIVE_INTERVAL_MS = 5_000;
+const DAEMON_SYNC_ACTIVE_INTERVAL_MS = 5_000;
 /** Given to the first cycle so a freshly-started daemon does not race the session that woke it. */
 const FIRST_CYCLE_DELAY_MS = 5_000;
 /**

package/dist/crawl/crawl-tools.js

@@ -51,7 +51,7 @@ export const CRAWL_TOOLS = [
                 source: z
                     .string()
                     .optional()
-                    .describe('Where the control is written, as `file:line` — open this to fix it.'),
+                    .describe('Where the fault is written, as `file:line`; console errors prefer their own stack and fall back to the clicked control.'),
             })),
             counts: z.record(z.number()),
             visited: z.array(z.string()).describe('The controls actually clicked, in order.'),

package/dist/crawl/crawl.d.ts

@@ -45,12 +45,12 @@ export interface CrawlAnomaly {
     desc: string;
     detail: string;
     /**
-     * Where the control is written, as `file:line`.
+     * Where the fault is written, as `file:line`.
      *
-     * A crawl reports problems across a whole app, so it is the output most likely to be read as a
-     * work list — and "e42 does nothing" is a work list item that starts with a search. The location
-     * comes free: the crawl already clicks each control, and an act result carries the source captured
-     * alongside its anchor. Absent in production builds and apps without the build plugin.
+     * Console faults prefer their own component/error stack. The clicked control stays in `ref` and
+     * `desc`, and its source is only the fallback: a navigation link explains what exposed a render
+     * crash, while the crashing component explains what to fix. Other anomaly kinds still use the
+     * control source captured alongside the action. Absent when neither source can be localized.
      */
     source?: string;
 }

package/dist/crawl/crawl.js

@@ -2,6 +2,7 @@ import { span } from '../trace.js';
 import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, DANGEROUS_ACTION_CONFIRM_ARG, EventType, ReticleCommand, } from '@reticlehq/core';
 import { crawlEmptyNote } from './crawl-empty.js';
 import { parseInteractive, asRecord, asNumber, asString, sourceOf, } from '../tools/tools-helpers.js';
+import { isSessionReplacedError } from '../session/session-replaced.js';
 import { ReticleTool } from '../tools/tool-names.js';
 import { findContradictions } from '../events/contradictions.js';
 /** Said out loud when the page was larger than one snapshot, so a clean sweep cannot mean "all clear". */
@@ -38,6 +39,115 @@ function isActivity(e) {
 function isConsoleError(e) {
     return e.type === EventType.CONSOLE_ERROR || e.type === EventType.ERROR_UNCAUGHT;
 }
+const SOURCE_FRAME = /^(.*):(\d+):(\d+)$/;
+const COMPONENT_STACK_FIELDS = ['componentStack', 'message'];
+const URL_SOURCE_PROTOCOLS = new Set([
+    'http:',
+    'https:',
+    'file:',
+    'webpack:',
+    'webpack-internal:',
+]);
+/** Turn a browser/dev-server frame URL into the file-shaped pointer the rest of Reticle emits. */
+function sourceFile(raw) {
+    let file = raw.trim();
+    if (0 === file.length)
+        return undefined;
+    try {
+        const parsed = new URL(file);
+        if (URL_SOURCE_PROTOCOLS.has(parsed.protocol))
+            file = decodeURIComponent(parsed.pathname);
+    }
+    catch {
+        // A repo-relative or Windows path is already the more useful form; keep it as-is.
+    }
+    file = file.replace(/[?#].*$/, '').replace(/\\/g, '/');
+    const bundledPrefix = file.lastIndexOf('/./');
+    if (-1 !== bundledPrefix)
+        file = file.slice(bundledPrefix + 3);
+    if (file.startsWith('/@fs/'))
+        file = file.slice('/@fs/'.length);
+    if (/^\/[A-Za-z]:\//.test(file))
+        file = file.slice(1);
+    else
+        file = file.replace(/^\/+/, '');
+    if (file.startsWith('./'))
+        file = file.slice(2);
+    return 0 === file.length ? undefined : file;
+}
+/** The location part of a Chrome/React or Firefox stack frame. */
+function frameLocation(line) {
+    let frame = line.trim();
+    if (frame.startsWith('at '))
+        frame = frame.slice(3).trim();
+    else {
+        const firefoxSeparator = frame.lastIndexOf('@');
+        if (-1 === firefoxSeparator)
+            return undefined;
+        frame = frame.slice(firefoxSeparator + 1);
+    }
+    const opening = frame.lastIndexOf('(');
+    if (-1 !== opening && frame.endsWith(')'))
+        return frame.slice(opening + 1, -1);
+    return frame;
+}
+function isFrameworkSource(file) {
+    const normalized = `/${file.toLowerCase().replace(/^\/+/, '')}`;
+    return normalized.includes('/node_modules/') || normalized.startsWith('/node:');
+}
+/** First editable app frame in a component/error stack, excluding framework internals. */
+function sourceFromStack(stack) {
+    for (const line of stack.split('\n')) {
+        const location = frameLocation(line);
+        if (location === undefined)
+            continue;
+        const match = SOURCE_FRAME.exec(location);
+        if (null === match)
+            continue;
+        const [, rawFile, rawLine] = match;
+        if (rawFile === undefined || rawLine === undefined)
+            continue;
+        const file = sourceFile(rawFile);
+        const lineNumber = Number(rawLine);
+        if (file === undefined ||
+            isFrameworkSource(file) ||
+            !Number.isSafeInteger(lineNumber) ||
+            lineNumber <= 0) {
+            continue;
+        }
+        return `${file}:${String(lineNumber)}`;
+    }
+    return undefined;
+}
+/** Prefer where a console fault occurred over the control whose click merely exposed it. */
+function sourceFromConsoleError(event) {
+    // React currently passes its component stack as a console.error string argument, so the browser
+    // observer carries it inside `message`; richer producers can send `componentStack` directly.
+    for (const field of COMPONENT_STACK_FIELDS) {
+        const componentStack = asString(event.data[field]);
+        if (componentStack === undefined)
+            continue;
+        const componentSource = sourceFromStack(componentStack);
+        if (componentSource !== undefined)
+            return componentSource;
+    }
+    // The ordinary error stack can also identify a component better than ErrorEvent.filename (for
+    // example, a bundle or click-handler frame), so try app frames before the structured fallback.
+    const stack = asString(event.data['stack']);
+    if (stack !== undefined) {
+        const stackSource = sourceFromStack(stack);
+        if (stackSource !== undefined)
+            return stackSource;
+    }
+    const directFile = asString(event.data['source']);
+    const directLine = asNumber(event.data['line']);
+    if (directFile === undefined || directLine === undefined || directLine <= 0)
+        return undefined;
+    const file = sourceFile(directFile);
+    return file === undefined || isFrameworkSource(file)
+        ? undefined
+        : `${file}:${String(directLine)}`;
+}
 function failedRequests(events, floor) {
     return events.filter((e) => {
         if (e.type !== EventType.NET_REQUEST)
@@ -163,6 +273,18 @@ export async function crawl(session, opts, sleep) {
         const since = session.elapsed();
         session.beginAction?.(ReticleTool.CRAWL, { ref: item.ref, action: ActionType.CLICK });
         let act;
+        /*
+         * A full page load reconnects the SDK, which rejects whatever command was in flight.
+         *
+         * On a server-rendered app that is what following a link DOES — every navigation replaces the
+         * session — so the rejection is evidence the click worked, not that it failed. Crawl used to let
+         * it propagate and died on link one of every Django, Rails or plain-HTML app.
+         *
+         * Recorded as a navigation rather than swallowed: a control that took the page somewhere is the
+         * opposite of a dead one, and reporting it as dead would be the false negative crawl exists to
+         * find.
+         */
+        let navigatedAway = false;
         try {
             // One span per control clicked, so a slow crawl names the control rather than reporting a
             // single multi-second total. The settle sleep below is INSIDE it deliberately: it is part of
@@ -177,6 +299,11 @@ export async function crawl(session, opts, sleep) {
                 return clicked;
             });
         }
+        catch (err) {
+            if (!isSessionReplacedError(err))
+                throw err;
+            navigatedAway = true;
+        }
         finally {
             // Close on every exit so a throw cannot leak the window onto the next control's events.
             session.finishAction?.();
@@ -184,16 +311,18 @@ export async function crawl(session, opts, sleep) {
         const events = session.eventsSince(since);
         // Captured at act time, so it survives a click that unmounts its own control.
         const src = sourceOf(asRecord(act?.result)['source']);
-        const source = src === undefined ? {} : { source: `${src.file}:${String(src.line)}` };
+        const controlSource = src === undefined ? undefined : `${src.file}:${String(src.line)}`;
+        const source = controlSource === undefined ? {} : { source: controlSource };
         const errs = events.filter(isConsoleError);
         for (const e of errs) {
             counts.consoleErrors += 1;
+            const errorSource = sourceFromConsoleError(e) ?? controlSource;
             anomalies.push({
                 kind: CrawlAnomalyKind.CONSOLE_ERROR,
                 ref: item.ref,
                 desc: item.desc,
                 detail: asString(e.data['message']) ?? e.type,
-                ...source,
+                ...(errorSource === undefined ? {} : { source: errorSource }),
             });
         }
         for (const e of failedRequests(events, CRAWL_DEFAULTS.FAILED_STATUS)) {
@@ -242,8 +371,13 @@ export async function crawl(session, opts, sleep) {
         // Deliberately NOT fixed by counting focus as activity: focus moving is not the app reacting, and
         // treating it as such would make a genuinely dead button that takes focus look alive — trading
         // noise for the false negative this check exists to catch.
-        const dispatched = asRecord(act.result)['dispatched'] !== false && act.ok;
-        if (dispatched &&
+        const dispatched = asRecord(act?.result)['dispatched'] !== false && true === act?.ok;
+        if (
+        // A control that took the page somewhere is the OPPOSITE of a dead one. Without this, every
+        // link on a server-rendered app would be reported as an anomaly by the check that exists to
+        // find controls which do nothing.
+        !navigatedAway &&
+            dispatched &&
             0 === errs.length &&
             !events.some(isActivity) &&
             !legitimatelyInert(item.desc)) {

package/dist/daemon/daemon-resilience.d.ts

@@ -67,7 +67,8 @@ export declare function installDaemonResilience(proc: ProcessLike, log: LogFn, o
  * dormant paths). A crashed-but-serving proxy answers the handshake and `tools/list` from cache; a
  * dead one answers nothing and needs a human.
  *
- * `onCrash` is for reporting only — it must not end the process.
+ * `onCrash` is for reporting only — it must not end the process. `onGone` is the ONE exception, and
+ * it is the subject of DISCONNECT_STORM below.
  */
-export declare function installProxyResilience(proc: ProcessLike, log: LogFn, onCrash?: (kind: CrashKind, cause: unknown) => void): void;
+export declare function installProxyResilience(proc: ProcessLike, log: LogFn, onCrash?: (kind: CrashKind, cause: unknown) => void, onGone?: () => void): void;
 export {};

package/dist/daemon/daemon-resilience.js

@@ -53,6 +53,24 @@ const DISCONNECT_CODES = new Set([
  * `connect_error` on `mcp_connection_lost`, which is the metric that can actually act on it.
  */
 const UNREACHABLE_CODES = new Set(['ECONNREFUSED']);
+/**
+ * How many absorbed client disconnects mean the client is GONE rather than between reconnects.
+ *
+ * Absorbing a disconnect and continuing is right for one: the client closed a socket, the proxy
+ * rebuilds it. It is catastrophic for a stream of them, because the write that failed is retried
+ * immediately, fails identically, and is absorbed again — a tight loop with no backoff and no exit.
+ *
+ * Measured in the field: one proxy ran four days after its editor closed, at 97-98% of a core, with
+ * 1473 minutes of CPU time and ~930 MB/hour of identical log lines, every entry stamped to the same
+ * millisecond. Nothing in Reticle's own output showed it — the daemon beside it reported healthy,
+ * `sessions: 0` — so it was findable only by running `ps` by hand, and thirteen more idle pairs from
+ * earlier sessions were still resident behind it.
+ *
+ * Chosen well above the handful a genuine reconnect produces and far below a runaway. The proxy's
+ * whole purpose is to be the stdio server its editor launched; once that editor is gone there is
+ * nobody left to serve, and the correct thing is to leave rather than to burn a core proving it.
+ */
+const DISCONNECT_STORM = 20;
 /** The expected-failure code this value carries, and which class it belongs to. */
 function expectedCode(value) {
     const raw = value?.code;
@@ -253,22 +271,43 @@ export function installDaemonResilience(proc, log, onFatal) {
  * dormant paths). A crashed-but-serving proxy answers the handshake and `tools/list` from cache; a
  * dead one answers nothing and needs a human.
  *
- * `onCrash` is for reporting only — it must not end the process.
+ * `onCrash` is for reporting only — it must not end the process. `onGone` is the ONE exception, and
+ * it is the subject of DISCONNECT_STORM below.
  */
-export function installProxyResilience(proc, log, onCrash = reportCrash) {
+export function installProxyResilience(proc, log, onCrash = reportCrash, onGone = () => process.exit(0)) {
     const expected = {
         disconnected: 'reticle_mcp_proxy_client_disconnected',
         unreachable: 'reticle_mcp_proxy_daemon_unreachable',
     };
+    // "Absorb the disconnect and keep serving" is right for ONE disconnect and catastrophic for a
+    // stream of them — see DISCONNECT_STORM.
+    let disconnects = 0;
+    let gone = false;
+    const absorb = (value) => {
+        if (!absorbExpected(value, log, expected))
+            return false;
+        if (false === expectedCode(value)?.unreachable) {
+            disconnects += 1;
+            if (disconnects >= DISCONNECT_STORM && !gone) {
+                gone = true;
+                log('reticle_mcp_proxy_client_gone', {
+                    disconnects,
+                    note: 'the client end is gone for good, not between reconnects — exiting instead of retrying forever',
+                });
+                onGone();
+            }
+        }
+        return true;
+    };
     proc.on('unhandledRejection', (reason) => {
-        if (absorbExpected(reason, log, expected))
+        if (absorb(reason))
             return;
         log('reticle_mcp_proxy_unhandled_rejection', { reason: describe(reason) });
         onCrash(CrashKind.UNHANDLED_REJECTION, reason);
     });
     proc.on('uncaughtException', (err) => {
         // The client closing its end of stdio is how this process is SUPPOSED to end its day.
-        if (absorbExpected(err, log, expected))
+        if (absorb(err))
             return;
         log('reticle_mcp_proxy_uncaught_exception', {
             error: describe(err),

package/dist/daemon/daemon-resolve.d.ts

@@ -16,15 +16,6 @@
  * This module is the one answer both sides now use. It is pure and injectable: no process spawning,
  * no port binding, nothing that needs a real `~/.reticle` to test.
  */
-import { type DaemonRegistryEntry } from '@reticlehq/core';
-/**
- * Every well-formed registry entry in `home`.
- *
- * A corrupt or half-written entry is skipped rather than thrown on: the registry is written by other
- * processes that can be killed mid-write, and one bad file must not make a machine's daemons
- * undiscoverable. Validated through core's schema so a shape change cannot silently pass here.
- */
-export declare function readDaemonRegistry(home: string): DaemonRegistryEntry[];
 /**
  * The port of the live daemon serving `projectId`, or undefined when this project has none.
  *

package/dist/daemon/daemon-resolve.js

@@ -18,7 +18,7 @@
  */
 import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { DaemonRegistryEntrySchema, daemonRegistryPort, pickDaemonPort, } from '@reticlehq/core';
+import { DaemonRegistryEntrySchema, daemonRegistryPort, pickDaemonPort, } from '@reticlehq/core/artifacts';
 /**
  * Every well-formed registry entry in `home`.
  *
@@ -26,7 +26,7 @@ import { DaemonRegistryEntrySchema, daemonRegistryPort, pickDaemonPort, } from '
  * processes that can be killed mid-write, and one bad file must not make a machine's daemons
  * undiscoverable. Validated through core's schema so a shape change cannot silently pass here.
  */
-export function readDaemonRegistry(home) {
+function readDaemonRegistry(home) {
     let files;
     try {
         files = readdirSync(home);