@reticlehq/server 2.4.0 → 2.6.0

package/dist/bridge/auth-failure-reason.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Why the bridge refused a HELLO — the specific reason when there is one.
+ *
+ * A daemon left running by one project answers the next project's app and rejects it on token, and
+ * the SDK printed `bridge refused the connection: authentication failed`. That sends someone to
+ * check a token which is perfectly correct — it is simply a DIFFERENT project's token. The two cases
+ * need opposite fixes: "your token is wrong" versus "that daemon is not yours, stop it".
+ *
+ * The discriminator is EVIDENCE, not derivation. The daemon and the SDK derive project ids by
+ * different schemes (the SDK from its Vite root, the daemon from its own cwd), so comparing those
+ * would report "different project" on every auth failure — the same confidently-wrong diagnostic
+ * this exists to replace. What the daemon knows for certain is which projects it has ALREADY
+ * accepted a session from; if it has served X and a HELLO arrives for Y, it demonstrably belongs to
+ * someone else.
+ *
+ * With no evidence — a fresh daemon, or a HELLO naming no project — nothing is inferred and the
+ * plain reason stands.
+ */
+export declare function authFailureReason(servedProjects: ReadonlySet<string>, helloProject: string | undefined): string;

package/dist/bridge/auth-failure-reason.js

@@ -0,0 +1,29 @@
+/**
+ * Why the bridge refused a HELLO — the specific reason when there is one.
+ *
+ * A daemon left running by one project answers the next project's app and rejects it on token, and
+ * the SDK printed `bridge refused the connection: authentication failed`. That sends someone to
+ * check a token which is perfectly correct — it is simply a DIFFERENT project's token. The two cases
+ * need opposite fixes: "your token is wrong" versus "that daemon is not yours, stop it".
+ *
+ * The discriminator is EVIDENCE, not derivation. The daemon and the SDK derive project ids by
+ * different schemes (the SDK from its Vite root, the daemon from its own cwd), so comparing those
+ * would report "different project" on every auth failure — the same confidently-wrong diagnostic
+ * this exists to replace. What the daemon knows for certain is which projects it has ALREADY
+ * accepted a session from; if it has served X and a HELLO arrives for Y, it demonstrably belongs to
+ * someone else.
+ *
+ * With no evidence — a fresh daemon, or a HELLO naming no project — nothing is inferred and the
+ * plain reason stands.
+ */
+const PLAIN = 'authentication failed';
+/** WebSocket close reasons are capped at 123 bytes; a longer one throws and closes with nothing. */
+const MAX_REASON_BYTES = 123;
+export function authFailureReason(servedProjects, helloProject) {
+    if (helloProject === undefined || 0 === servedProjects.size)
+        return PLAIN;
+    if (servedProjects.has(helloProject))
+        return PLAIN;
+    const reason = `this daemon serves a different project — run \`reticle stop\` and retry`;
+    return Buffer.byteLength(reason, 'utf8') <= MAX_REASON_BYTES ? reason : PLAIN;
+}

package/dist/{bridge-security.d.ts → bridge/bridge-security.d.ts}

@@ -1,4 +1,4 @@
-import type { StartOptions } from './index.js';
+import type { StartOptions } from '../index.js';
 /** The security contract the bridge/daemon enforce: bind host, pairing token, and WS origin allow-list. */
 interface BridgeSecurity {
     host?: string;

package/dist/{bridge-security.js → bridge/bridge-security.js}

@@ -1,6 +1,6 @@
 import { ReticleEnv } from '@reticlehq/core';
 import { defaultPairingTokenDir, nodePairingTokenDeps, readOrCreatePairingToken, } from './pairing-token.js';
-import { log } from './log.js';
+import { log } from '../log.js';
 /**
  * Resolve the bridge's security options from explicit options first, then the environment. Shared by
  * both `start` and `startDaemon` so the token/host/origin contract is enforced identically on

package/dist/{bridge.d.ts → bridge/bridge.d.ts}

@@ -1,9 +1,21 @@
 import * as http from 'node:http';
-import { Session, SessionManager } from './session/session.js';
+import { Session, SessionManager } from '../session/session.js';
 /** A human clicked ▶ on a saved flow in the panel — replay it with no agent. Wired by the daemon. */
 type ReplayRequestHandler = (sessionId: string, flowName: string) => void;
 /** Called once a browser session connects, so the daemon can push it the replayable-flow list. */
 type SessionReadyHandler = (session: Session) => void;
+/**
+ * The close reasons worth telling an AGENT about, not just the SDK.
+ *
+ * The SDK prints these and stops retrying. The agent then calls a tool and is told "no browser
+ * session connected" — which is indistinguishable from an app nobody started. An outdated SDK and a
+ * stale pairing token were both invisible for that reason; these two carry their own remedy, so
+ * surfacing them is strictly better than the generic answer.
+ */
+export declare const WS_CLOSE_REASON: {
+    readonly PROTOCOL_MISMATCH: "protocol version mismatch — upgrade @reticlehq/browser";
+    readonly AUTH_FAILED: "authentication failed — reload the page to pick up the current pairing token";
+};
 interface BridgeOptions {
     port: number;
     host?: string;

package/dist/{bridge.js → bridge/bridge.js}

@@ -1,9 +1,14 @@
 import * as http from 'node:http';
+import { authFailureReason } from './auth-failure-reason.js';
 import { WebSocketServer } from 'ws';
-import { EventType, HumanControlKind, RETICLE_WS_PATH, ReticleMessageSchema, LOOPBACK_HOST, MessageKind, ReticleEnv, RETICLE_PROTOCOL_VERSION, TRANSPORT_LIMITS, isLocalPage, isLoopbackHostname, isOpaqueOrigin, OPAQUE_ORIGIN, isHighValueEvent, RATE_CAP_HIGH_VALUE_RESERVE_RATIO, } from '@reticlehq/core';
-import { Session, SessionManager } from './session/session.js';
+import { EventType, HumanControlKind, RETICLE_WS_PATH, ReticleMessageSchema, LOOPBACK_HOST, MessageKind, ReticleEnv, RETICLE_PROTOCOL_VERSION, TRANSPORT_LIMITS, isLocalPage, isLoopbackHostname, isOpaqueOrigin, OPAQUE_ORIGIN, isHighValueEvent, RATE_CAP_HIGH_VALUE_RESERVE_RATIO, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
+import { Session, SessionManager } from '../session/session.js';
 import { tokensMatch } from './token-auth.js';
-import { log } from './log.js';
+import { log } from '../log.js';
+import { getSessionMetrics } from '../telemetry/session-metrics.js';
+import { describeSkew, sdkFix, SkewPair } from '../version/version-skew.js';
+import { noteVersionSkew } from '../version/version-nudge.js';
+import { SERVER_VERSION } from '../version/server-version.js';
 /**
  * Take the mutable half of a session's identity from a repeat HELLO.
  *
@@ -22,15 +27,31 @@ function refreshIdentity(session, hello) {
     session.adapters = hello.adapters;
     session.hasCapabilities = hello.hasCapabilities ?? false;
 }
+/**
+ * The close reasons worth telling an AGENT about, not just the SDK.
+ *
+ * The SDK prints these and stops retrying. The agent then calls a tool and is told "no browser
+ * session connected" — which is indistinguishable from an app nobody started. An outdated SDK and a
+ * stale pairing token were both invisible for that reason; these two carry their own remedy, so
+ * surfacing them is strictly better than the generic answer.
+ */
+export const WS_CLOSE_REASON = {
+    PROTOCOL_MISMATCH: 'protocol version mismatch — upgrade @reticlehq/browser',
+    AUTH_FAILED: 'authentication failed — reload the page to pick up the current pairing token',
+};
 /** WS close codes + reasons the bridge sends to the SDK (1008 = policy violation, 1013 = try again later). */
 const WS_CLOSE = {
     TOO_MANY_HANDSHAKES: [1013, 'too many pending handshakes'],
     HELLO_TIMEOUT: [1008, 'hello timeout'],
     INVALID_MESSAGE: [1008, 'invalid message'],
     HELLO_DUPLICATE: [1008, 'hello already received'],
-    AUTH_FAILED: [1008, 'authentication failed'],
+    // Names the recovery, because the SDK prints this reason and then stops retrying — so it is the
+    // last thing the developer sees. The common cause is a page served before the daemon existed,
+    // which carries no token; a reload re-fetches the connect module and picks the current one up.
+    // Kept under the 123-byte WebSocket close-reason limit.
+    AUTH_FAILED: [1008, WS_CLOSE_REASON.AUTH_FAILED],
     SESSION_LIMIT: [1013, 'session limit reached'],
-    PROTOCOL_MISMATCH: [1008, 'protocol version mismatch — upgrade @reticlehq/browser'],
+    PROTOCOL_MISMATCH: [1008, WS_CLOSE_REASON.PROTOCOL_MISMATCH],
 };
 /** Parse a positive integer env override; anything else (unset, zero, junk) falls through to the default. */
 function positiveIntFromEnv(raw) {
@@ -46,7 +67,7 @@ function replayRequest(event) {
     if (event.data['kind'] !== HumanControlKind.REPLAY)
         return undefined;
     const name = event.data['text'];
-    return typeof name === 'string' && name.length > 0 ? name : undefined;
+    return 'string' === typeof name && name.length > 0 ? name : undefined;
 }
 /**
  * Canonical comparable form of a WS `Origin`. Web origins collapse to scheme://host[:port]. An
@@ -76,7 +97,7 @@ function helloProtocolMismatch(text) {
     try {
         const json = JSON.parse(text);
         if (json.kind === MessageKind.HELLO &&
-            typeof json.protocolVersion === 'number' &&
+            'number' === typeof json.protocolVersion &&
             json.protocolVersion !== RETICLE_PROTOCOL_VERSION) {
             return json.protocolVersion;
         }
@@ -88,7 +109,7 @@ function helloProtocolMismatch(text) {
 }
 /** Normalize ws RawData (string | Buffer | Buffer[] | ArrayBuffer) into a UTF-8 string. */
 function rawToString(raw) {
-    if (typeof raw === 'string')
+    if ('string' === typeof raw)
         return raw;
     if (Array.isArray(raw))
         return Buffer.concat(raw).toString('utf8');
@@ -108,6 +129,12 @@ export class Bridge {
     #wss;
     #clock;
     #token;
+    /**
+     * Projects this daemon has ACCEPTED a session from. Evidence, not derivation: it is what lets a
+     * leaked daemon say "I belong to another project" instead of "authentication failed". See
+     * authFailureReason.
+     */
+    #servedProjects = new Set();
     #allowedOrigins;
     #maxMessagesPerSecond;
     #maxSessions;
@@ -124,7 +151,7 @@ export class Bridge {
         if ((options.token?.length ?? 0) > TRANSPORT_LIMITS.MAX_TOKEN_LENGTH) {
             throw new Error(`Reticle pairing token exceeds ${String(TRANSPORT_LIMITS.MAX_TOKEN_LENGTH)} characters`);
         }
-        if (!isLoopbackHostname(host) && (options.token === undefined || options.token.length === 0)) {
+        if (!isLoopbackHostname(host) && (options.token === undefined || 0 === options.token.length)) {
             throw new Error('a pairing token is required when the Reticle bridge binds beyond localhost');
         }
         this.#clock = options.clock ?? (() => Date.now());
@@ -136,7 +163,7 @@ export class Bridge {
         // Binding beyond localhost means the browser dials in from a non-loopback Origin. With no
         // allow-list, #originAllowed rejects every such Origin at the WS handshake, so the bridge comes
         // up but accepts nothing — a silent, fail-closed footgun. Refuse to start with a clear message.
-        if (!isLoopbackHostname(host) && this.#allowedOrigins.size === 0) {
+        if (!isLoopbackHostname(host) && 0 === this.#allowedOrigins.size) {
             throw new Error(`${ReticleEnv.ALLOWED_ORIGINS} must list the app origin(s) when the Reticle bridge binds ` +
                 'beyond localhost — otherwise every non-loopback browser is rejected at the WebSocket ' +
                 'origin check and no connection can be established.');
@@ -247,10 +274,14 @@ export class Bridge {
             const overRate = messagesInWindow > this.#maxMessagesPerSecond;
             const text = rawToString(raw);
             const parsed = this.#parse(text);
-            if (parsed === null) {
+            if (null === parsed) {
                 const got = helloProtocolMismatch(text);
                 if (got !== null) {
                     log('protocol_version_mismatch', { got, expected: RETICLE_PROTOCOL_VERSION });
+                    // Told to the AGENT too, not only to the SDK that is about to stop retrying. Without this
+                    // the next tool call answers "no browser session connected", which reads as "no app is
+                    // running" — so an SDK too old to connect is invisible.
+                    this.sessions.noteClosure(WS_CLOSE_REASON.PROTOCOL_MISMATCH, this.#clock());
                     socket.close(...WS_CLOSE.PROTOCOL_MISMATCH);
                     return;
                 }
@@ -297,8 +328,16 @@ export class Bridge {
                     return;
                 }
                 if (this.#token !== undefined && !tokensMatch(this.#token, parsed.token)) {
-                    log('authentication_failed', {});
-                    socket.close(...WS_CLOSE.AUTH_FAILED);
+                    // A daemon left running by ANOTHER project answers this app and rejects it on token. The
+                    // token is not wrong, it is somebody else's — and "authentication failed" sends the user to
+                    // check the one thing that is fine. See auth-failure-reason.
+                    const reason = authFailureReason(this.#servedProjects, parsed.projectId);
+                    log('authentication_failed', {
+                        served: [...this.#servedProjects],
+                        ...(parsed.projectId === undefined ? {} : { helloProject: parsed.projectId }),
+                    });
+                    this.sessions.noteClosure(WS_CLOSE_REASON.AUTH_FAILED, this.#clock());
+                    socket.close(WS_CLOSE.AUTH_FAILED[0], reason);
                     return;
                 }
                 const existing = this.sessions.get(parsed.sessionId);
@@ -309,10 +348,51 @@ export class Bridge {
                 clearTimeout(helloTimer);
                 releasePending();
                 session = new Session(parsed, socket, this.#clock);
+                // Recorded on ACCEPTANCE, so it is evidence of what this daemon really serves.
+                if (parsed.projectId !== undefined)
+                    this.#servedProjects.add(parsed.projectId);
                 this.#onSessionCreate?.(session); // attach the durable journal before any events stream in
                 const replaced = this.sessions.add(session);
-                replaced?.disconnect('session replaced by a newer connection');
+                if (replaced !== undefined) {
+                    // Name the newcomer. A field report had a live session vanish during `reticle_lease` and the
+                    // only evidence was "session replaced by a newer connection" in the page console — which
+                    // says a replacement happened but not BY WHAT, so the cause had to be inferred. A session
+                    // is only ever replaced by one carrying the SAME id, and knowing which URL claimed it is
+                    // the difference between a diagnosis and a guess.
+                    log('session_replaced', {
+                        sessionId: session.id,
+                        byUrl: session.url,
+                        previousUrl: replaced.url,
+                    });
+                    replaced.disconnect(`session replaced by a newer connection claiming the same id (${session.id}) from ${session.url}`);
+                }
+                // The daemon is the single judge of skew, and HELLO is where the page announces itself.
+                // Reported on the session (reticle_sessions) AND queued for the next tool result, because an
+                // agent driving a flow never calls reticle_sessions and would never learn.
+                const skew = describeSkew({
+                    what: 'the page',
+                    version: parsed.sdkVersion,
+                    contract: parsed.contract,
+                    fix: sdkFix(SERVER_VERSION),
+                }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
+                if (skew !== undefined) {
+                    log('version_skew', {
+                        sessionId: session.id,
+                        sdk: parsed.sdkVersion,
+                        daemon: SERVER_VERSION,
+                    });
+                    session.versionSkew = skew;
+                    noteVersionSkew(SkewPair.SDK, skew);
+                }
                 log('session_connected', { sessionId: session.id, url: session.url });
+                // The one fact that separates a broken install from an unused one. Best-effort and wrapped:
+                // a metric must never affect whether an app can connect. See SessionSummary.appConnects.
+                try {
+                    getSessionMetrics().recordAppConnected();
+                }
+                catch {
+                    /* never let a counter interfere with an app connecting */
+                }
                 this.#onSessionReady?.(session); // daemon pushes the replayable-flow list to the panel
                 return;
             }
@@ -357,7 +437,7 @@ export class Bridge {
         if (origin === undefined)
             return this.#token !== undefined;
         const normalized = normalizeOrigin(origin);
-        if (normalized === null)
+        if (null === normalized)
             return false;
         if (this.#allowedOrigins.has(normalized))
             return true;

package/dist/{bridge.test-harness.d.ts → bridge/bridge.test-harness.d.ts}

@@ -1,16 +1,6 @@
 import { type ElementQuery } from '@reticlehq/core';
 import type { Bridge } from './bridge.js';
-import { type ToolDeps } from './tools/tools.js';
-/** The app-advertised testable surface a FakeBrowser reports for an reticle_capabilities round-trip. */
-export declare const FAKE_CAPABILITIES: {
-    testids: string[];
-    signals: string[];
-    stores: string[];
-    flows: {
-        name: string;
-        steps: string[];
-    }[];
-};
+import { type ToolDeps } from '../tools/tools.js';
 /** A stand-in for the real @reticlehq/browser SDK: replies to commands and emits events. */
 export declare class FakeBrowser {
     #private;
@@ -45,6 +35,14 @@ export declare class FakeBrowser {
     emit(type: string, data: Record<string, unknown>, ref?: string): void;
     close(): void;
 }
+/**
+ * Poll until `cond` holds.
+ *
+ * The default was 2000ms and the fifty-browser test blew it on the Windows runner at 5155ms — a
+ * statement about the machine, not about the bridge. Raising it is safe in a way that raising a
+ * fixed sleep would not be: this POLLS every 10ms and resolves the instant the condition holds, so
+ * a passing test is not slowed by one millisecond and only a genuinely failing one waits longer.
+ */
 export declare function waitUntil(cond: () => boolean, timeoutMs?: number): Promise<void>;
 export declare const callTool: (deps: ToolDeps, name: string, args?: Record<string, unknown>) => Promise<unknown>;
 /** Builds the ToolDeps wired to a running bridge, with a frozen clock for deterministic tests. */

package/dist/{bridge.test-harness.js → bridge/bridge.test-harness.js}

@@ -1,14 +1,14 @@
 import { WebSocket } from 'ws';
 import { RETICLE_WS_PATH, ReticleCommand, LOOPBACK_HOST, MessageKind, } from '@reticlehq/core';
-import { BaselineStore } from './project/baselines.js';
-import { createNodeFileSystem } from './project/fs-port.js';
-import { RecordingStore } from './flows/recordings.js';
-import { FlowStore } from './flows/flows.js';
-import { ProjectStore } from './project/project-store.js';
-import { AnnotationStore } from './flows/annotation-store.js';
-import { TOOLS } from './tools/tools.js';
+import { BaselineStore } from '../project/baselines.js';
+import { createNodeFileSystem } from '../project/fs-port.js';
+import { RecordingStore } from '../flows/recordings.js';
+import { FlowStore } from '../flows/flows.js';
+import { ProjectStore } from '../project/project-store.js';
+import { AnnotationStore } from '../flows/annotation-store.js';
+import { TOOLS } from '../tools/tools.js';
 /** The app-advertised testable surface a FakeBrowser reports for an reticle_capabilities round-trip. */
-export const FAKE_CAPABILITIES = {
+const FAKE_CAPABILITIES = {
     testids: ['toast'],
     signals: ['webhook:received'],
     stores: ['cart'],
@@ -141,7 +141,7 @@ export class FakeBrowser {
         }
         else if (name === ReticleCommand.STATE_READ) {
             result = {
-                stores: { workspace: { tab: args['store'] === 'workspace' ? 'open' : 'all' } },
+                stores: { workspace: { tab: 'workspace' === args['store'] ? 'open' : 'all' } },
                 storeNames: ['workspace'],
                 component: args['ref'] !== undefined ? { component: 'PayButton', hooks: [0] } : undefined,
             };
@@ -170,7 +170,15 @@ export class FakeBrowser {
         this.#ws.send(JSON.stringify(obj));
     }
 }
-export function waitUntil(cond, timeoutMs = 2000) {
+/**
+ * Poll until `cond` holds.
+ *
+ * The default was 2000ms and the fifty-browser test blew it on the Windows runner at 5155ms — a
+ * statement about the machine, not about the bridge. Raising it is safe in a way that raising a
+ * fixed sleep would not be: this POLLS every 10ms and resolves the instant the condition holds, so
+ * a passing test is not slowed by one millisecond and only a genuinely failing one waits longer.
+ */
+export function waitUntil(cond, timeoutMs = 15_000) {
     return new Promise((resolve, reject) => {
         const start = Date.now();
         const tick = () => {

package/dist/{pairing-token.js → bridge/pairing-token.js}

@@ -49,7 +49,7 @@ export async function readOrCreatePairingToken(dir, deps) {
     }
     try {
         const token = deps.randomToken().trim();
-        if (token.length === 0)
+        if (0 === token.length)
             return undefined;
         await deps.mkdir(dir);
         await deps.writeFile(path, token);

package/dist/capsule/capsule-store.d.ts

@@ -10,6 +10,12 @@ import type { FileSystemPort } from '../project/fs-port.js';
  * fix lands, it is exactly a regression flow. Capsules are ordinary flow files plus evidence, so they
  * replay through the existing machinery rather than needing a second runner.
  */
+/**
+ * The capsule file-format version. Declared ABOVE the schema so the schema, the writer and this
+ * constant cannot disagree: the number was previously written as a bare `1` in three places — here,
+ * in the schema literal, and in act-capsule's writer — with the named one used by nobody.
+ */
+export declare const CAPSULE_VERSION = 1;
 export declare const CapsuleSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     id: z.ZodString;
@@ -29,8 +35,8 @@ export declare const CapsuleSchema: z.ZodObject<{
     version: 1;
     id: string;
     expected: string;
-    steps: FlowStep[];
     observed: string;
+    steps: FlowStep[];
     createdAt: number;
     flow?: string | undefined;
 }, {
@@ -38,13 +44,12 @@ export declare const CapsuleSchema: z.ZodObject<{
     version: 1;
     id: string;
     expected: string;
-    steps: FlowStep[];
     observed: string;
+    steps: FlowStep[];
     createdAt: number;
     flow?: string | undefined;
 }>;
 export type Capsule = z.infer<typeof CapsuleSchema>;
-export declare const CAPSULE_VERSION = 1;
 /** Capsule ids are filenames — refuse anything that could escape the capsules directory. */
 export declare function isValidCapsuleId(id: string): boolean;
 export declare class CapsuleStore {

package/dist/capsule/capsule-store.js

@@ -11,8 +11,14 @@ import { reticleDirPaths } from '../project/reticle-dir.js';
  * fix lands, it is exactly a regression flow. Capsules are ordinary flow files plus evidence, so they
  * replay through the existing machinery rather than needing a second runner.
  */
+/**
+ * The capsule file-format version. Declared ABOVE the schema so the schema, the writer and this
+ * constant cannot disagree: the number was previously written as a bare `1` in three places — here,
+ * in the schema literal, and in act-capsule's writer — with the named one used by nobody.
+ */
+export const CAPSULE_VERSION = 1;
 export const CapsuleSchema = z.object({
-    version: z.literal(1),
+    version: z.literal(CAPSULE_VERSION),
     id: z.string(),
     /** The flow the failure happened in, when it came from one (a bare assert has no flow). */
     flow: z.string().optional(),
@@ -26,7 +32,6 @@ export const CapsuleSchema = z.object({
     /** Minimal steps to reproduce (prefix-trimmed). */
     steps: z.array(FlowStepSchema),
 });
-export const CAPSULE_VERSION = 1;
 /** Capsule ids are filenames — refuse anything that could escape the capsules directory. */
 export function isValidCapsuleId(id) {
     return /^[a-zA-Z0-9._-]+$/.test(id) && id !== '.' && id !== '..' && id.length <= 128;

package/dist/capsule/capsule.js

@@ -1,13 +1,13 @@
-import { EventType } from '@reticlehq/core';
+import { ConsequenceKind, EventType } from '@reticlehq/core';
 import { causalSummary } from './causal-summary.js';
 import { firstDivergence } from './divergence.js';
 /** Observed signal/state changes the flow never declared — the side effects. */
 function blastRadius(expected, observed) {
     const declaredSignals = new Set(expected
-        .filter((l) => l.kind === 'signal')
+        .filter((l) => ConsequenceKind.SIGNAL === l.kind)
         .map((l) => l.name));
     const declaredStates = new Set(expected
-        .filter((l) => l.kind === 'state')
+        .filter((l) => ConsequenceKind.STATE === l.kind)
         .map((l) => l.name));
     const radius = [];
     const add = (value) => {

package/dist/capsule/causal-summary.d.ts

@@ -26,9 +26,17 @@ export interface StorageDiff {
     to?: unknown;
 }
 export interface CausalSummary {
+    /**
+     * `total`/`errors` describe the APP's traffic. `ignoredDevTooling` is the count of calls the dev
+     * toolchain made about itself (Next's error overlay, HMR, the Vite client — see
+     * `DevToolingChannel`), which Reticle deliberately leaves out of the settle decision and out of
+     * contradiction hunting. Present only when there were any: a trim is never silent, so an agent can
+     * always see that something was ignored and go read it in the timeline.
+     */
     net: {
         total: number;
         errors: number;
+        ignoredDevTooling?: number;
         headline?: string;
     };
     consoleErrors: number;

package/dist/capsule/causal-summary.js

@@ -1,6 +1,6 @@
-import { EventType, PerfMetric } from '@reticlehq/core';
+import { EventType, PerfMetric, isDevToolingUrl } from '@reticlehq/core';
 function pushUnique(list, value) {
-    if (typeof value === 'string' && value.length > 0 && !list.includes(value))
+    if ('string' === typeof value && value.length > 0 && !list.includes(value))
         list.push(value);
 }
 /** Keep a diff value bounded so the per-act summary never bloats: primitives capped to a short string. */
@@ -10,11 +10,11 @@ function truncate(text) {
     return text.length > MAX_DIFF_LEN ? `${text.slice(0, MAX_DIFF_LEN - 1)}…` : text;
 }
 function capValue(value) {
-    if (value === undefined || value === null)
+    if (value === undefined || null === value)
         return value;
-    if (typeof value === 'string')
+    if ('string' === typeof value)
         return truncate(value);
-    if (typeof value === 'number' || typeof value === 'boolean')
+    if ('number' === typeof value || 'boolean' === typeof value)
         return value;
     // Objects/arrays: a shallow, length-capped JSON repr (never a deep dump on the hot path).
     try {
@@ -40,6 +40,7 @@ function stateSettle(diffs) {
 export function causalSummary(events) {
     let netTotal = 0;
     let netErrors = 0;
+    let ignoredDevTooling = 0;
     let headline;
     let consoleErrors = 0;
     const statePathsChanged = [];
@@ -54,9 +55,13 @@ export function causalSummary(events) {
         const data = event.data;
         switch (event.type) {
             case EventType.NET_REQUEST: {
+                if (isDevToolingUrl('string' === typeof data['url'] ? data['url'] : undefined)) {
+                    ignoredDevTooling += 1;
+                    break;
+                }
                 netTotal += 1;
                 const status = data['status'];
-                const failed = data['ok'] === false || (typeof status === 'number' && status >= 400);
+                const failed = false === data['ok'] || ('number' === typeof status && status >= 400);
                 if (failed) {
                     netErrors += 1;
                     // Headline is the first failing request — the thing most worth the agent's eye.
@@ -73,9 +78,9 @@ export function causalSummary(events) {
                 // The subscribed-store observer emits { name, path, value, old } — `value` is the AFTER side
                 // (`new` is accepted too for any producer that uses it). Presence of either makes it a real
                 // before→after diff rather than a bare reading.
-                const path = typeof data['path'] === 'string' ? data['path'] : data['name'];
+                const path = 'string' === typeof data['path'] ? data['path'] : data['name'];
                 const hasAfter = 'value' in data || 'new' in data;
-                if (typeof path === 'string' && path.length > 0 && ('old' in data || hasAfter)) {
+                if ('string' === typeof path && path.length > 0 && ('old' in data || hasAfter)) {
                     const after = 'value' in data ? data['value'] : data['new'];
                     stateDiffs.push({
                         path,
@@ -89,20 +94,20 @@ export function causalSummary(events) {
             case EventType.STORAGE_CHANGE: {
                 pushUnique(storageKeysChanged, data['key']);
                 const key = data['key'];
-                if (typeof key === 'string' && key.length > 0) {
+                if ('string' === typeof key && key.length > 0) {
                     storageDiffs.push({ key, from: capValue(data['old']), to: capValue(data['new']) });
                 }
                 break;
             }
             case EventType.ROUTE_CHANGE:
-                if (typeof data['pathname'] === 'string')
+                if ('string' === typeof data['pathname'])
                     route = data['pathname'];
                 break;
             case EventType.SIGNAL:
                 pushUnique(signals, data['name']);
                 break;
             case EventType.PERF:
-                if (data['metric'] === PerfMetric.CLS && typeof data['value'] === 'number') {
+                if (data['metric'] === PerfMetric.CLS && 'number' === typeof data['value']) {
                     layoutShift = Math.max(layoutShift ?? 0, data['value']);
                 }
                 else if (data['metric'] === PerfMetric.LONGTASK) {
@@ -114,7 +119,12 @@ export function causalSummary(events) {
         }
     }
     return {
-        net: { total: netTotal, errors: netErrors, ...(headline === undefined ? {} : { headline }) },
+        net: {
+            total: netTotal,
+            errors: netErrors,
+            ...(0 === ignoredDevTooling ? {} : { ignoredDevTooling }),
+            ...(headline === undefined ? {} : { headline }),
+        },
         consoleErrors,
         statePathsChanged,
         storageKeysChanged,

package/dist/capsule/divergence.d.ts

@@ -1,4 +1,4 @@
-import { type ReticleEvent } from '@reticlehq/core';
+import { ConsequenceKind, type ReticleEvent } from '@reticlehq/core';
 /**
  * First-divergence — the brain of the divergence capsule (Tier 2). Given the chain the flow DECLARED
  * should happen (its mustHold, as ordered expected links) and what was OBSERVED, walk the declaration and
@@ -6,15 +6,20 @@ import { type ReticleEvent } from '@reticlehq/core';
  * fault lives — the agent fixes it without re-exploring. Pure; the acceptance bar is that for every
  * hidden-500 / hung-request fixture it names the correct link.
  */
+/**
+ * The links a capsule can walk. Exactly core's ConsequenceKind — a link is a thing the app provably
+ * DID, which is the same set signal/net/state names everywhere else. Spelled through the shared
+ * constant so the two can never drift apart.
+ */
 export type ExpectedLink = {
-    kind: 'signal';
+    kind: typeof ConsequenceKind.SIGNAL;
     name: string;
 } | {
-    kind: 'net';
+    kind: typeof ConsequenceKind.NET;
     urlContains: string;
     status?: number;
 } | {
-    kind: 'state';
+    kind: typeof ConsequenceKind.STATE;
     name: string;
 };
 export interface Divergence {