@reticlehq/server 2.4.0 → 2.5.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,5 +1,5 @@
 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. */

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

@@ -1,9 +1,13 @@
 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 { 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.
  *
@@ -46,7 +50,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 +80,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 +92,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 +112,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 +134,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 +146,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,7 +257,7 @@ 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 });
@@ -297,8 +307,15 @@ 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 }),
+                    });
+                    socket.close(WS_CLOSE.AUTH_FAILED[0], reason);
                     return;
                 }
                 const existing = this.sessions.get(parsed.sessionId);
@@ -309,9 +326,42 @@ 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 });
                 this.#onSessionReady?.(session); // daemon pushes the replayable-flow list to the panel
                 return;
@@ -357,7 +407,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;

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,
             };

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 {

package/dist/capsule/divergence.js

@@ -1,28 +1,28 @@
-import { EventType } from '@reticlehq/core';
+import { ConsequenceKind, EventType } from '@reticlehq/core';
 function net(events) {
     return events.filter((e) => e.type === EventType.NET_REQUEST);
 }
 function satisfies(link, events) {
     switch (link.kind) {
-        case 'signal':
+        case ConsequenceKind.SIGNAL:
             return events.some((e) => e.type === EventType.SIGNAL && e.data['name'] === link.name);
-        case 'state':
+        case ConsequenceKind.STATE:
             return events.some((e) => e.type === EventType.STATE_CHANGE && e.data['name'] === link.name);
-        case 'net':
-            return net(events).some((e) => typeof e.data['url'] === 'string' &&
+        case ConsequenceKind.NET:
+            return net(events).some((e) => 'string' === typeof e.data['url'] &&
                 e.data['url'].includes(link.urlContains) &&
                 (link.status === undefined || e.data['status'] === link.status));
     }
 }
 /** Describe what WAS observed for a link that failed — the closest attempt, for a side-by-side. */
 function observedFor(link, events) {
-    if (link.kind === 'net') {
-        const match = net(events).find((e) => typeof e.data['url'] === 'string' && e.data['url'].includes(link.urlContains));
+    if (ConsequenceKind.NET === link.kind) {
+        const match = net(events).find((e) => 'string' === typeof e.data['url'] && e.data['url'].includes(link.urlContains));
         if (match === undefined)
             return `no request to ${link.urlContains}`;
         return `${link.urlContains} responded ${String(match.data['status'])} (expected ${String(link.status)})`;
     }
-    if (link.kind === 'signal')
+    if (ConsequenceKind.SIGNAL === link.kind)
         return `signal "${link.name}" never fired`;
     return `state "${link.name}" never changed`;
 }

package/dist/capsule/predicate-to-links.js

@@ -1,3 +1,4 @@
+import { ConsequenceKind, PredicateKind } from '@reticlehq/core';
 /**
  * Convert a mustHold predicate into the ordered ExpectedLinks the divergence capsule walks. Only the
  * consequence kinds (signal/net/state) become links — a presence check (element/text) can't diverge in a
@@ -5,24 +6,26 @@
  */
 export function predicateToExpectedLinks(predicate) {
     switch (predicate.kind) {
-        case 'signal':
-            return predicate.name === undefined ? [] : [{ kind: 'signal', name: predicate.name }];
-        case 'net':
+        case PredicateKind.SIGNAL:
+            return predicate.name === undefined
+                ? []
+                : [{ kind: ConsequenceKind.SIGNAL, name: predicate.name }];
+        case PredicateKind.NET:
             return predicate.urlContains === undefined
                 ? []
                 : [
                     {
-                        kind: 'net',
+                        kind: ConsequenceKind.NET,
                         urlContains: predicate.urlContains,
                         ...(predicate.status === undefined ? {} : { status: predicate.status }),
                     },
                 ];
-        case 'state': {
+        case PredicateKind.STATE: {
             const name = predicate.store ?? predicate.path;
-            return [{ kind: 'state', name }];
+            return [{ kind: ConsequenceKind.STATE, name }];
         }
-        case 'allOf':
-        case 'anyOf':
+        case PredicateKind.ALL_OF:
+        case PredicateKind.ANY_OF:
             return predicate.predicates.flatMap(predicateToExpectedLinks);
         default:
             return [];

package/dist/{cli-doctor.js → cli/cli-doctor.js}

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { readPid, isAlive } from './daemon.js';
-import { diagnoseDesktop, isDesktopProject } from './init/desktop-doctor.js';
+import { ReticleEnv } from '@reticlehq/core';
+import { readPid, isAlive, reticleStateHome } from '../daemon/daemon.js';
+import { diagnoseDesktop, isDesktopProject } from '../init/desktop-doctor.js';
 /**
  * `reticle doctor` — collapse the ~6 independent first-run failure modes into one command. Checks the
  * Chromium install (the #1 silent failure), whether a daemon is up on the resolved bridge port, and
@@ -31,6 +32,12 @@ export async function handleDoctor(port) {
         line(`  daemon       ✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`);
     }
     line(`  bridge port  ${port}  (your app must dial THIS port — not your dev-server port)`);
+    // Where to LOOK when something is wrong. The daemon has always written a structured log here and
+    // nothing ever said so, so the first move in every investigation was reading source instead of
+    // reading the log. `RETICLE_TRACE=1` turns the same stream into a per-stage trace — see
+    // docs/debugging.md.
+    line(`  daemon log   ${join(reticleStateHome(), `daemon-${String(port)}.log`)}`);
+    line(`  tracing      ${ReticleEnv.TRACE}=1 on the daemon for per-stage timings in that log`);
     // Desktop setup RCA. Every one of these fails SILENTLY — a Tauri app with the default CSP runs
     // perfectly and never connects; an Electron app without the preload line reports zero network
     // activity forever, which reads as "makes no backend calls" rather than "you are blind to them".

package/dist/{cli-flow-commands.d.ts → cli/cli-flow-commands.d.ts}

@@ -5,8 +5,8 @@
  * opens first. These five functions form one cohesive group: they all read the flow store and report on
  * verification state, and none of them touch daemon lifecycle, which is what the rest of cli.ts does.
  */
-import { type FileSystemPort } from './project/fs-port.js';
-import { type NamedFlow } from './flows/flow-sources.js';
+import { type FileSystemPort } from '../project/fs-port.js';
+import { type NamedFlow } from '../flows/flow-sources.js';
 /** Load the {name, steps} of every saved flow for the active project. */
 /** Explicit files plus, when --since is given, the git-changed files since that ref. */
 export declare function resolveChangedFiles(files: string[], since: string | undefined): Promise<string[]>;