@reticlehq/server 2.13.1 → 2.14.0

package/SKILL.md

@@ -38,13 +38,9 @@ There are exactly three places you may stop, and none is a question about a pref
 2. **Your host asks the human to approve a command.** That prompt belongs to the host. Never bypass or suppress it, and take a refusal as the answer. `init` writing a pre-approval rule for the `reticle` server is not that: it is a scoped, announced config change the human asked for by running the command, and it covers only Reticle's own tools.
 3. **Only if no agent CLI exists on the machine at all**, the client restart that loads the MCP tools (step 2). If `claude`, `codex`, `cursor-agent` or `gemini` is installed, you do NOT stop. Step 2 shows you how to drive from a child process instead, and that path is measured to be the difference between a verdict and a dead end.
 
-If you do have to stop, the restart ends your turn. This file was fetched into the context that just ended, so nothing carries it across unless you make it. **Before you trigger the restart, write the remaining steps into `RETICLE-SETUP.md` at the repo root**, one line each, with the step you stopped at marked. That file is what you re-read afterwards. Delete it once step 5 has produced a verdict.
-
-Better still, install the on-disk copy first. It survives the restart on its own, and it is the same content:
+**On Claude Code and Codex, do not ask the human to restart at all.** `npx @reticlehq/server init --relaunch` prints the exact resume command for this conversation; run that command yourself rather than handing the person a chore. It refuses when the id has no transcript behind it, because `--resume` on an empty id opens a blank session that looks exactly like success. Everywhere else the restart genuinely is theirs: name the one step for their client and ask for that alone.
 
-```bash
-npx skills add reticlehq/reticle --skill install-and-verify -y
-```
+If you do have to stop, the restart ends your turn. This file was fetched into the context that just ended, so nothing carries it across unless you make it. **Before you trigger the restart, write the remaining steps into `RETICLE-SETUP.md` at the repo root**, one line each, with the step you stopped at marked. That file is what you re-read afterwards. Delete it once step 5 has produced a verdict.
 
 **After the restart, resume at the step you were on.** Do not start over, and do not skip forward.
 
@@ -89,11 +85,7 @@ Read **VERIFY** below when the question is "does this still work?" rather than "
 
 # SETUP
 
-**One command. It does all of it, and it ends with a verdict.**
-
-```bash
-RETICLE_INSTALL_SOURCE=skill_file npx @reticlehq/server@latest init --flow "<the journey worth proving>"
-```
+**One command, the one at the top of this file. It does all of it, and it ends with a verdict.**
 
 `@latest` is deliberate: `npx` caches, and a stale cached CLI is the most common silent setup failure. Never pin a version here.
 
@@ -142,7 +134,7 @@ curl https://docs.reticle.sh/install-manual.md      # register the MCP, wire the
 curl https://docs.reticle.sh/troubleshooting.md     # nothing connected, click did nothing, verdict unknown
 ```
 
-**Vite + React**, **Next.js**, **Remix** and **Astro** are the frameworks with an app and a CI gate behind them, so their wiring is proven rather than assumed. The SDK is framework-agnostic and usually connects elsewhere, but say that honestly rather than reporting a proven install.
+**Vite + React**, **Next.js**, **Remix** and **Astro** are the frameworks with an app and a CI gate behind them, so their wiring is proven rather than assumed. **TanStack Start** is detected and given a client-only recipe, but nothing in CI proves it. The SDK is framework-agnostic and usually connects elsewhere, but say that honestly rather than reporting a proven install.
 
 Do not reconstruct it from memory. Three things decide whether it works, and all three get skipped:
 
@@ -198,18 +190,18 @@ Work down this list and stop at the first row that fits. Do not hand-drive a flo
 
 | The question | The call | Calls |
 | --- | --- | --- |
-| "Did my edit break anything?" | `reticle_run({ tool: "reticle_verify", args: { action: "change", files: ["src/App.tsx"] } })` | 1 |
+| "Did my edit break anything?" | `reticle_verify({ action: "change", files: ["src/App.tsx"] })` | 1 |
 | "Does this known journey still work?" | `reticle_run({ tool: "reticle_flow_replay", args: { flowName: "login" } })` | 1 |
 | "Does this new behaviour work?" | `reticle_act_sequence` for the setup, then ONE `reticle_act_and_wait` | 2 |
 | No MCP available at all | `npx @reticlehq/server verify <url>` in the shell | 1, no MCP |
 
-`reticle_verify` and `reticle_flow_replay` are **not on the advertised tool list**: they are reached through `reticle_run` exactly as written above. That is the supported call shape, not a workaround, and it is why you have to be told they exist at all.
+`reticle_verify` IS on the advertised tool list, so call it directly. `reticle_flow_replay` is not: it is reached through `reticle_run` exactly as written above. That is the supported call shape, not a workaround, and it is why you have to be told it exists at all.
 
 `reticle_verify {action:"change"}` answers `unknown` when no saved flow covers the files you changed. That is the honest answer and not a failure. Nothing ran, so nothing was proved. It is also the signal to record one. Never read it as a pass.
 
 ## Two more you have to be told about
 
-Same story as `reticle_verify`: extended surface, so they are not in the tool list you were handed, and reached through `reticle_run`.
+Extended surface, so they are not in the tool list you were handed, and reached through `reticle_run`.
 
 **Context compacted, a turn starting, or a sub-agent taking over?** Ask what this run already established, instead of re-snapshotting to rediscover what you already knew:
 
@@ -263,11 +255,9 @@ reticle_act_and_wait({ sessionId, ref, action: "click", until: { kind: "allOf",
 
 Prefer `reticle_act_and_wait({ ref, action, until })`. It names the expected consequence **before** the action, which is the difference between a check and a rationalisation.
 
-A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown. `verified: "no-fault"` is not a pass either. It means the page settled and no channel reported a problem, but nothing was declared to prove, so assert a consequence the action CHANGES. **Never weaken a check to make it pass.**
-
 Then report what you drove, what it produced, and the `file:line` for anything broken.
 
-The surface is deliberately small: `default` 18, `all` 30. Editors budget tools across every MCP server you have connected (Cursor allows 40 in total), so the count is capped rather than allowed to grow. `reticle_tools` loads the argument grammar for the rest on demand, and `reticle_run` invokes any of them by name. Nothing is unreachable; the cold tail just costs one discovery hop.
+The surface is deliberately small: `default` 19, `all` 30. Editors budget tools across every MCP server you have connected (Cursor allows 40 in total), so the count is capped rather than allowed to grow. `reticle_tools` loads the argument grammar for the rest on demand, and `reticle_run` invokes any of them by name. Nothing is unreachable; the cold tail just costs one discovery hop.
 
 - Batching, regression suites, reading a verdict: `https://docs.reticle.sh/agent-cheatsheet.md`
 - Every predicate and action: `https://docs.reticle.sh/predicates.md`, `https://docs.reticle.sh/actions.md`

package/bin/reticle.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from '../dist/cli.js';
+main();

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

@@ -26,7 +26,18 @@ const NO_TOKEN = 'authentication failed: no pairing token on the page';
 /** 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, helloToken) {
-    if (helloProject !== undefined && 0 < servedProjects.size && !servedProjects.has(helloProject)) {
+    // ONE served project, not merely some. A daemon that has accepted sessions from SEVERAL projects
+    // is demonstrably not owned by any one of them, so "that daemon is not yours, stop it" is the
+    // wrong story — and its advice is actively harmful there, because stopping it breaks the projects
+    // that are working. This is the normal shape for a globally-registered daemon, which several
+    // editors start from the user's home directory and point at everything.
+    //
+    // With one served project the inference holds and is worth making: the daemon belongs to that
+    // project and this HELLO is somebody else's. With several, the token is the suspect, and the plain
+    // reason says so without prescribing a recovery that costs other people their sessions.
+    if (helloProject !== undefined &&
+        1 === servedProjects.size &&
+        !servedProjects.has(helloProject)) {
         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/bridge-security.d.ts

@@ -1,9 +1,17 @@
 import type { StartOptions } from '../index.js';
+import { pairingTokenSource } from './pairing-token.js';
 /** The security contract the bridge/daemon enforce: bind host, pairing token, and WS origin allow-list. */
 interface BridgeSecurity {
     host?: string;
     token?: string;
     allowedOrigins?: string[];
+    /**
+     * Which source supplied `token`, decided HERE because this is the only place that knows.
+     * By the time the Bridge sees it, an auto-provisioned token and one passed by a caller are the
+     * same field — so computing it downstream would report `explicit` for every daemon and describe
+     * nothing. See pairingTokenSource for why a refusal needs this at all.
+     */
+    tokenSource?: ReturnType<typeof pairingTokenSource>;
 }
 /**
  * Resolve the bridge's security options from explicit options first, then the environment. Shared by

package/dist/bridge/bridge-security.js

@@ -1,5 +1,5 @@
 import { ReticleEnv } from '@reticlehq/core';
-import { defaultPairingTokenDir, nodePairingTokenDeps, readOrCreatePairingToken, } from './pairing-token.js';
+import { defaultPairingTokenDir, nodePairingTokenDeps, readOrCreatePairingToken, pairingTokenSource, } from './pairing-token.js';
 import { log } from '../log.js';
 /**
  * Resolve the bridge's security options from explicit options first, then the environment. Shared by
@@ -7,6 +7,10 @@ import { log } from '../log.js';
  * every entrypoint — a past divergence let daemon mode silently run with auth disabled.
  */
 export function resolveBridgeSecurity(options) {
+    const tokenSource = pairingTokenSource({
+        explicit: options.token !== undefined && 0 < options.token.length,
+        env: process.env,
+    });
     const envToken = process.env[ReticleEnv.TOKEN];
     const envOrigins = process.env[ReticleEnv.ALLOWED_ORIGINS];
     const host = options.host ?? process.env[ReticleEnv.HOST];
@@ -20,6 +24,7 @@ export function resolveBridgeSecurity(options) {
         ...(host === undefined ? {} : { host }),
         ...(token === undefined ? {} : { token }),
         ...(allowedOrigins === undefined ? {} : { allowedOrigins }),
+        tokenSource,
     };
 }
 /**

package/dist/bridge/bridge.d.ts

@@ -1,5 +1,6 @@
 import * as http from 'node:http';
 import { Session, SessionManager } from '../session/session.js';
+import { pairingTokenSource } from './pairing-token.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. */
@@ -41,6 +42,8 @@ interface BridgeOptions {
     port: number;
     host?: string;
     token?: string;
+    /** Which source supplied `token`. Set by resolveBridgeSecurity; logged on a refusal, never sent. */
+    tokenSource?: ReturnType<typeof pairingTokenSource>;
     allowedOrigins?: string[];
     maxMessagesPerSecond?: number;
     maxSessions?: number;

package/dist/bridge/bridge.js

@@ -5,8 +5,10 @@ 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, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
 import { Session, SessionManager } from '../session/session.js';
 import { tokensMatch } from './token-auth.js';
+import { pairingTokenSource } from './pairing-token.js';
 import { log } from '../log.js';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
+import { sessionReplacedReason } from '../session/session-replaced.js';
 import { describeSkew, sdkFix, SkewPair } from '../version/version-skew.js';
 import { noteVersionSkew } from '../version/version-nudge.js';
 import { protocolSkewReason } from './protocol-skew.js';
@@ -174,6 +176,8 @@ export class Bridge {
     #wss;
     #clock;
     #token;
+    /** Which source supplied #token — logged on a refusal so a mismatch names its own cause. */
+    #tokenSource;
     /**
      * 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
@@ -223,6 +227,15 @@ export class Bridge {
         this.#clock = options.clock ?? (() => Date.now());
         this.#token =
             options.token !== undefined && options.token.length > 0 ? options.token : undefined;
+        // Supplied by resolveBridgeSecurity, which is the only place that can tell an auto-provisioned
+        // token from one a caller passed — both arrive here as options.token. Defaulted rather than
+        // required so a directly-constructed Bridge (tests, embedders) still logs something true.
+        this.#tokenSource =
+            options.tokenSource ??
+                pairingTokenSource({
+                    explicit: options.token !== undefined && 0 < options.token.length,
+                    env: process.env,
+                });
         // An entry that fails to normalize — typically a scheme-less `myapp.test` — used to be
         // filtered out with no trace: the allow-list LOOKED configured, every dial from that origin
         // was refused at the gate, and the refusal read as a scheme mismatch in the page rather than
@@ -446,10 +459,16 @@ export class Bridge {
                         // 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, parsed.token);
+                        // The token SOURCE, never the token. A refusal here has no other witness: the value is
+                        // machine-level on both sides, so the daemon's cwd cannot explain a mismatch (#685) and
+                        // the only thing that can is the environment the two processes were started in — which
+                        // differs exactly when an IDE spawns the MCP server globally instead of from the shell
+                        // that launched the dev server.
                         log('authentication_failed', {
                             served: [...this.#servedProjects],
                             ...(parsed.projectId === undefined ? {} : { helloProject: parsed.projectId }),
                             presented: parsed.token !== undefined && 0 < parsed.token.length,
+                            tokenSource: this.#tokenSource,
                         });
                         this.sessions.noteClosure(WS_CLOSE_REASON.AUTH_FAILED, this.#clock());
                         socket.close(WS_CLOSE.AUTH_FAILED[0], reason);
@@ -509,7 +528,7 @@ export class Bridge {
                         // the old handle can finish against the live connection instead of returning an error whose
                         // only answer is to go and rediscover an id that has not changed. See Session.succeededBy.
                         replaced.succeededBy(session);
-                        replaced.disconnect(`session replaced by a newer connection claiming the same id (${session.id}) from ${session.url}`, true);
+                        replaced.disconnect(sessionReplacedReason(session.id, session.url), true);
                     }
                     // 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
@@ -520,6 +539,9 @@ export class Bridge {
                         contract: parsed.contract,
                         fix: this.#sdkFix(),
                     }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
+                    // Kept so a remedy can check whether it applies to THIS page — see body-capture-remedy.
+                    session.sdkVersion = parsed.sdkVersion;
+                    session.captureBodies = parsed.captureBodies;
                     if (skew !== undefined) {
                         log('version_skew', {
                             sessionId: session.id,

package/dist/bridge/bridge.test-harness.d.ts

@@ -27,10 +27,19 @@ export declare class FakeBrowser {
         name: string;
         args: Record<string, unknown>;
     }[];
-    /** The snapshot tree to return. Mutable so tests can vary the page between calls. */
+    /**
+     * The snapshot tree to return. Mutable so tests can vary the page between calls.
+     *
+     * The counters are optional because the fields they stand for are: the browser omits `nodes`-
+     * adjacent diagnostics on a page that has nothing to report, and a test asserting on one has to be
+     * able to send a payload shaped like the real thing.
+     */
     snapshotResult: {
         tree: string;
         status: Record<string, unknown>;
+        nodes?: number;
+        hiddenSkipped?: number;
+        leanSkipped?: number;
     };
     constructor(port: number, sessionId: string, hasCapabilities?: boolean);
     open(): Promise<void>;

package/dist/bridge/bridge.test-harness.js

@@ -34,7 +34,13 @@ export class FakeBrowser {
     queryResolves = true;
     /** Records every command the bridge sent (for replay assertions). */
     received = [];
-    /** The snapshot tree to return. Mutable so tests can vary the page between calls. */
+    /**
+     * The snapshot tree to return. Mutable so tests can vary the page between calls.
+     *
+     * The counters are optional because the fields they stand for are: the browser omits `nodes`-
+     * adjacent diagnostics on a page that has nothing to report, and a test asserting on one has to be
+     * able to send a payload shaped like the real thing.
+     */
     snapshotResult = {
         tree: '- button "Pay" (ref=e7)\n- dialog "Order confirmed" (ref=e12)',
         status: { route: '/checkout' },

package/dist/bridge/pairing-token.d.ts

@@ -16,6 +16,23 @@ export interface PairingTokenDeps {
 export declare const PAIRING_TOKEN_DIR_ENV: "RETICLE_PAIRING_TOKEN_DIR";
 /** The default directory that holds the token — the per-user ~/.reticle so it's shared across projects. */
 export declare function defaultPairingTokenDir(): string;
+/**
+ * Which of the three sources supplied the token this process is using.
+ *
+ * The SOURCE, never the secret. #685 reports a globally-registered daemon refusing an app that
+ * `doctor` calls correctly wired, and blames the daemon's cwd — but cwd cannot reach this value:
+ * resolution is options.token, then RETICLE_TOKEN, then the file under ~/.reticle, and the Vite
+ * plugin reads that same file. What CAN diverge is the ENVIRONMENT, because an IDE spawning a global
+ * MCP server does not inherit the shell that started the dev server. Either variable then moves one
+ * side and not the other, and neither is visible in anything we print — so the refusal is a mystery
+ * with no witness, which is how this report has stayed open on a guessed cause.
+ *
+ * Pure, and takes its env, so the order can be pinned by tests rather than by reading two files.
+ */
+export declare function pairingTokenSource(input: {
+    explicit: boolean;
+    env: NodeJS.ProcessEnv;
+}): 'explicit' | 'env:RETICLE_TOKEN' | 'env:RETICLE_PAIRING_TOKEN_DIR' | 'default';
 export declare function pairingTokenPath(dir: string): string;
 /** Production IO adapter: 0600 file + 0700 dir so only the owner can read the secret. */
 export declare function nodePairingTokenDeps(): PairingTokenDeps;

package/dist/bridge/pairing-token.js

@@ -15,6 +15,32 @@ export function defaultPairingTokenDir() {
         return override;
     return join(homedir(), ReticleDir.ROOT);
 }
+/**
+ * Which of the three sources supplied the token this process is using.
+ *
+ * The SOURCE, never the secret. #685 reports a globally-registered daemon refusing an app that
+ * `doctor` calls correctly wired, and blames the daemon's cwd — but cwd cannot reach this value:
+ * resolution is options.token, then RETICLE_TOKEN, then the file under ~/.reticle, and the Vite
+ * plugin reads that same file. What CAN diverge is the ENVIRONMENT, because an IDE spawning a global
+ * MCP server does not inherit the shell that started the dev server. Either variable then moves one
+ * side and not the other, and neither is visible in anything we print — so the refusal is a mystery
+ * with no witness, which is how this report has stayed open on a guessed cause.
+ *
+ * Pure, and takes its env, so the order can be pinned by tests rather than by reading two files.
+ */
+export function pairingTokenSource(input) {
+    // Same precedence the resolver applies, deliberately: a source that did not decide the value is a
+    // misdirection, and this exists to stop one.
+    if (input.explicit)
+        return 'explicit';
+    const token = input.env[ReticleEnv.TOKEN];
+    if (token !== undefined && 0 < token.length)
+        return `env:${ReticleEnv.TOKEN}`;
+    const dir = input.env[PAIRING_TOKEN_DIR_ENV];
+    if (dir !== undefined && 0 < dir.length)
+        return `env:${PAIRING_TOKEN_DIR_ENV}`;
+    return 'default';
+}
 export function pairingTokenPath(dir) {
     return join(dir, ReticleDir.PAIRING_TOKEN_FILE);
 }

package/dist/bridge/token-auth.d.ts

@@ -1,4 +1,11 @@
 import type { IncomingMessage } from 'node:http';
+/**
+ * The query parameter a client may present its pairing token in.
+ *
+ * Exported because the CLI now presents the same token when it attaches to a running daemon over the
+ * MCP HTTP transport, and a second spelling of this string is a second way for auth to fail.
+ */
+export declare const TOKEN_QUERY_PARAM = "token";
 /**
  * Timing-safe pairing-token comparison. Length-guards first because `timingSafeEqual` throws on a
  * length mismatch — and the guard itself is not a timing oracle (length is not the secret).

package/dist/bridge/token-auth.js

@@ -2,7 +2,13 @@ import { timingSafeEqual } from 'node:crypto';
 import { isLoopbackHostname } from '@reticlehq/core';
 /** `Authorization: Bearer <token>` prefix and the query-param fallback for clients that can't set headers. */
 const BEARER_PREFIX = 'Bearer ';
-const TOKEN_QUERY_PARAM = 'token';
+/**
+ * The query parameter a client may present its pairing token in.
+ *
+ * Exported because the CLI now presents the same token when it attaches to a running daemon over the
+ * MCP HTTP transport, and a second spelling of this string is a second way for auth to fail.
+ */
+export const TOKEN_QUERY_PARAM = 'token';
 /** Node reports IPv4 loopback over a dual-stack socket as this mapped form; strip it before classifying. */
 const IPV4_MAPPED_PREFIX = /^::ffff:/i;
 /**

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

@@ -31,19 +31,19 @@ declare const CapsuleSchema: z.ZodObject<{
     /** Minimal steps to reproduce (prefix-trimmed). */
     steps: z.ZodArray<z.ZodType<FlowStep, z.ZodTypeDef, FlowStep>, "many">;
 }, "strip", z.ZodTypeAny, {
+    origin: string;
+    expected: string;
     id: string;
     version: 1;
-    expected: string;
-    origin: string;
     steps: FlowStep[];
     observed: string;
     createdAt: number;
     flow?: string | undefined;
 }, {
+    origin: string;
+    expected: string;
     id: string;
     version: 1;
-    expected: string;
-    origin: string;
     steps: FlowStep[];
     observed: string;
     createdAt: number;

package/dist/capsule/capsule.d.ts

@@ -15,4 +15,4 @@ export interface DivergenceCapsule {
     blastRadius: string[];
 }
 /** Compose the full capsule from the declared chain and the observed (attributed) event window. */
-export declare function buildDivergenceCapsule(expected: readonly ExpectedLink[], observed: readonly ReticleEvent[]): DivergenceCapsule;
+export declare function buildDivergenceCapsule(expected: readonly ExpectedLink[], observed: readonly ReticleEvent[], truncated?: boolean): DivergenceCapsule;

package/dist/capsule/capsule.js

@@ -26,10 +26,10 @@ function blastRadius(expected, observed) {
     return radius;
 }
 /** Compose the full capsule from the declared chain and the observed (attributed) event window. */
-export function buildDivergenceCapsule(expected, observed) {
+export function buildDivergenceCapsule(expected, observed, truncated = false) {
     return {
-        summary: causalSummary(observed),
-        firstDivergence: firstDivergence(expected, observed),
+        summary: causalSummary(observed, { truncated }),
+        firstDivergence: firstDivergence(expected, observed, truncated),
         blastRadius: blastRadius(expected, observed),
     };
 }

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

@@ -76,10 +76,30 @@ export interface CausalSummary {
      * `stateSettleMs` and `elided` follow.
      */
     stateUnwatched?: true;
+    /**
+     * TRUE when the ring buffer evicted events belonging to this window, so every count and list here
+     * is a FLOOR, not a total — `net.total: 0` means "none survived", never "none happened".
+     *
+     * The same distinction `stateUnwatched` draws, from the other cause, and it was the more expensive
+     * one. A field app rewrote one localStorage key thousands of times a minute; the no-op writes
+     * starved the buffer (`held: 2000, dropped: 70482`), and the verdict for that window reported
+     * `net.total: 0`, `stateDiffs: []` and "state never changed" — while a POST that had returned 200
+     * in that exact window carried the entire root cause in its body. The agent read the zero and was
+     * about to report "clicking Accept fires no network request", which points a developer at the
+     * click handler instead of at the payload the server rejected.
+     *
+     * `honesty.integrity.losses` already said `buffer_loss`. It was not enough: the headline fields an
+     * agent reads to form a verdict are these, and a bare `0` several levels above a nested integrity
+     * flag reads as a fact. The absolute and the caveat must not be separable, so the caveat rides on
+     * the summary that carries the absolutes.
+     */
+    truncated?: true;
 }
 /** What only the SESSION knows — level facts the event window cannot contain. See `stateUnwatched`. */
-export interface SummaryContext {
+interface SummaryContext {
     stateUnwatched?: boolean;
+    /** Did the buffer drop events from this window — see `CausalSummary.truncated`. */
+    truncated?: boolean;
 }
 /**
  * THE INVARIANT: every field of this summary has a bounded size that does not depend on how much the

package/dist/capsule/causal-summary.js

@@ -1,5 +1,5 @@
 import { EventType, PerfMetric, isDevToolingUrl } from '@reticlehq/core';
-import { routePathOf } from '../events/predicate-route.js';
+import { routeOfEvent } from '../events/predicate-route.js';
 /**
  * THE INVARIANT: every field of this summary has a bounded size that does not depend on how much the
  * app did. A verdict travels in the same payload as its evidence, so an unbounded evidence field is
@@ -119,14 +119,15 @@ export function causalSummary(events, context = {}) {
                 }
                 break;
             }
-            case EventType.ROUTE_CHANGE:
+            case EventType.ROUTE_CHANGE: {
                 // The ROUTER's path. Reporting the document pathname left `route: "/"` on every action of a
                 // hash-routed app — the same reading that made a route predicate unsatisfiable there, and an
-                // agent reasoning off this field would conclude the route never changed. See routePathOf.
-                if ('string' === typeof data['pathname']) {
-                    route = routePathOf(data['pathname'], 'string' === typeof data['hash'] ? data['hash'] : '');
-                }
+                // agent reasoning off this field would conclude the route never changed. See routeOfEvent.
+                const routed = routeOfEvent(data);
+                if (routed !== undefined)
+                    route = routed.routePath;
                 break;
+            }
             case EventType.SIGNAL:
                 pushUnique(signals, data['name']);
                 break;
@@ -166,5 +167,6 @@ export function causalSummary(events, context = {}) {
         ...(layoutShift === undefined ? {} : { layoutShift }),
         longTasks,
         ...(true === context.stateUnwatched ? { stateUnwatched: true } : {}),
+        ...(true === context.truncated ? { truncated: true } : {}),
     };
 }

package/dist/capsule/divergence.d.ts

@@ -32,4 +32,4 @@ export interface Divergence {
  * Walk the declared chain in order; return the first link not satisfied by the observed events (with a
  * side-by-side of what happened instead), or null when the whole chain held.
  */
-export declare function firstDivergence(expected: readonly ExpectedLink[], observed: readonly ReticleEvent[]): Divergence | null;
+export declare function firstDivergence(expected: readonly ExpectedLink[], observed: readonly ReticleEvent[], truncated?: boolean): Divergence | null;

package/dist/capsule/divergence.js

@@ -20,26 +20,42 @@ function satisfies(link, events) {
                 (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) {
+/**
+ * Describe what WAS observed for a link that failed — the closest attempt, for a side-by-side.
+ *
+ * `truncated` says the buffer dropped events belonging to this window, which turns every sentence
+ * below from a claim about the app into a claim about a partial reading. It is the difference
+ * between "the request was never made" and "no surviving event shows the request", and a field
+ * session proved they are not interchangeable: a POST that returned 200 inside the window carried
+ * the whole root cause, and the capsule for that same window said `state "cad" never changed`. The
+ * agent believed the absolute — the strongest, most specific, and most wrong thing this tool can
+ * say. Absence of evidence must never be typed as evidence of absence.
+ */
+function observedFor(link, events, truncated) {
     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 (match !== undefined) {
+            return `${link.urlContains} responded ${String(match.data['status'])} (expected ${String(link.status)})`;
+        }
+        return truncated
+            ? `no surviving event shows a request to ${link.urlContains} — capture truncated, so this is not evidence there was none`
+            : `no request to ${link.urlContains}`;
     }
-    if (ConsequenceKind.SIGNAL === link.kind)
-        return `signal "${link.name}" never fired`;
-    return `state "${link.name}" never changed`;
+    const subject = ConsequenceKind.SIGNAL === link.kind ? `signal "${link.name}"` : `state "${link.name}"`;
+    if (truncated)
+        return `${subject} was not observed — capture truncated, so absence is unproven`;
+    return ConsequenceKind.SIGNAL === link.kind
+        ? `${subject} never fired`
+        : `${subject} never changed`;
 }
 /**
  * Walk the declared chain in order; return the first link not satisfied by the observed events (with a
  * side-by-side of what happened instead), or null when the whole chain held.
  */
-export function firstDivergence(expected, observed) {
+export function firstDivergence(expected, observed, truncated = false) {
     for (const link of expected) {
         if (!satisfies(link, observed)) {
-            return { expected: link, observed: observedFor(link, observed) };
+            return { expected: link, observed: observedFor(link, observed, truncated) };
         }
     }
     return null;

package/dist/chromium-launch-options.d.ts

@@ -17,7 +17,7 @@
  */
 export declare const CHROMIUM_ANTI_THROTTLING_ARGS: readonly ["--disable-background-timer-throttling", "--disable-backgrounding-occluded-windows", "--disable-renderer-backgrounding"];
 /** The options object handed to `chromium.launch` at both launch sites. */
-export interface ChromiumLaunchOptions {
+interface ChromiumLaunchOptions {
     headless: boolean;
     args: string[];
 }
@@ -26,3 +26,4 @@ export interface ChromiumLaunchOptions {
  * each call so no caller can mutate the constant behind everyone else's back.
  */
 export declare function chromiumLaunchOptions(headless: boolean): ChromiumLaunchOptions;
+export {};

package/dist/cli/adhoc-verdict.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A verdict from the CLI, against the daemon that is already running.
+ *
+ * THE DEAD END THIS REMOVES. The largest single cluster in the field feedback is not a defect in any
+ * tool — it is that the tools were not loaded in the client, and there was no supported way to reach
+ * a verdict from that state. The shape was always the same: the app is instrumented, the daemon is
+ * healthy, `doctor` shows a live connected page, and the client (Codex, Cursor Cloud, Antigravity,
+ * Gemini CLI, or a Claude Code session whose MCP link dropped) exposes no `reticle_*` tools, because
+ * they load only at client startup. The documented CLI fallback then refused, because the daemon
+ * already owned the port — precisely the state a successful install leaves you in. The other CLI
+ * verdict paths need saved flows, and a first-install project has none. And our own guidance says
+ * never to stop the daemon, because that kills the agent's MCP link.
+ *
+ * So an agent held a live, correctly-wired app and no path to a verdict short of a human restarting
+ * their editor. Several reporters fell back to Playwright or to their own client and said honestly
+ * that Reticle could not produce a verdict.
+ *
+ * HOW, AND WHY IT ADDS NO NEW SURFACE. One reporter found the answer themselves: they drove the full
+ * tool surface over the daemon's HTTP/SSE transport with a hand-written client, and it worked. That
+ * transport is not opt-in — `start()` calls `attachMcp` unconditionally, so every daemon has it. So
+ * this asks the running daemon the same questions an agent would, over the same transport, using the
+ * MCP client the SDK already ships. Nothing new is exposed and nothing is bound: the daemon keeps
+ * the port, the agent keeps its link, and there is nothing to stop.
+ *
+ * It is deliberately the CLI equivalent of ONE `act_and_wait`: navigate, then assert. A CLI that
+ * grew its own scripting language would be a second way to express a journey, competing with flows
+ * and drifting from them.
+ */
+/** What a one-shot verdict reports back to the caller. */
+export interface AdhocVerdict {
+    /** Process exit code: 0 only when the predicate was PROVED. */
+    code: number;
+    /** Lines to print, in order. */
+    lines: string[];
+}
+export interface AdhocVerdictOptions {
+    port: number;
+    /** Navigated to first when given; omitted to assert against wherever the session already is. */
+    url?: string;
+    /** The predicate, already parsed from the caller's JSON. */
+    predicate: unknown;
+    token?: string;
+    /** Injected so a test does not need a live daemon. */
+    connect?: (endpoint: URL) => Promise<ToolCaller>;
+}
+/** The narrow slice of an MCP client this needs — one call, then close. */
+export interface ToolCaller {
+    call(name: string, args: Record<string, unknown>): Promise<unknown>;
+    close(): Promise<void>;
+}
+/**
+ * Navigate (optionally) and assert, against the daemon already on this port.
+ *
+ * Exit code 0 ONLY for `verified: "yes"`. `unknown` exits non-zero on purpose: it means Reticle could
+ * not tell what happened, and a CI step that treats "could not tell" as success is the false green
+ * this whole product exists to prevent.
+ */
+export declare function runAdhocVerdict(options: AdhocVerdictOptions): Promise<AdhocVerdict>;