@reticlehq/server 2.7.0 → 2.8.0

package/README.md

@@ -3,16 +3,25 @@
 The [Reticle](https://github.com/reticlehq/reticle) bridge + MCP server. It hosts a localhost WebSocket endpoint your app's `@reticlehq/browser` SDK connects to, and exposes MCP tools your coding agent uses to look at, act on, observe, and assert against the live app.
 
 ```bash
-npx @reticlehq/server        # bridge on ws://localhost:4400, MCP over stdio
+npx @reticlehq/server init   # wire the project: SDK + build plugin + MCP registration
+npx @reticlehq/server mcp    # MCP over stdio; auto-starts the bridge on ws://localhost:4400
 ```
 
-Point your agent at it (e.g. Claude Code `.mcp.json`):
+The package installs a `reticle` bin, so inside a project `reticle mcp` and `npx @reticlehq/server mcp` are the same command. `reticle` is not a package name on npm.
 
-```jsonc
-{ "mcpServers": { "reticle": { "command": "npx", "args": ["@reticlehq/server", "mcp"] } } }
+Point your agent at it. On Claude Code, register it at user scope:
+
+```bash
+claude mcp add reticle -s user -- npx @reticlehq/server mcp
 ```
 
-Tools: `reticle_snapshot`, `reticle_query`, `reticle_inspect`, `reticle_act`, `reticle_act_sequence`, `reticle_act_and_wait`, `reticle_observe`, `reticle_wait_for`, `reticle_assert`, `reticle_network`, `reticle_console`, `reticle_animations`, `reticle_baseline`, `reticle_visual_diff`, `reticle_record`, `reticle_flow`, `reticle_explore`, `reticle_sessions`.
+Default tools (18):
+
+`reticle_sessions`, `reticle_snapshot`, `reticle_query`, `reticle_inspect`, `reticle_navigate`, `reticle_act`, `reticle_act_sequence`, `reticle_act_and_wait`, `reticle_observe`, `reticle_wait_for`, `reticle_assert`, `reticle_network`, `reticle_console`, `reticle_state`, `reticle_feedback`, `reticle_session`, `reticle_tools`, `reticle_run`.
+
+Only `reticle_act_and_wait` and `reticle_assert` return a verdict; everything else moves or reads the app.
+
+Another 30 tools ship but are not advertised, to keep the per-turn tool payload small: screenshots and visual diff, saved flows, recording, baselines, clock control, viewport, crawl, coverage, network mocking, leases and more. Reach any of them by name with `reticle_run`, list them with `reticle_tools`, or advertise the whole surface with `RETICLE_ADVERTISE_ALL_TOOLS=1` (this roughly doubles the per-turn tool payload).
 
 See the [main README](https://github.com/reticlehq/reticle).
 

package/SKILL.md

@@ -7,9 +7,22 @@
 > **The moment something is wrong, missing, awkward, or slower than it should be, file it — one call, then carry on with the task.** A step in this document that did not match reality, an install that needed a manual fix, a tool that returned nonsense, something you wished existed, something that works but takes five calls where it should take one. Nothing is too minor; the minor things are exactly what never gets reported and therefore never gets fixed.
 >
 > - Tools available: `reticle_feedback { kind, text, need?, impact?, currentApproach?, model?, trace? }` where `kind` is `bug` | `gap` | `ambiguity` | `feature_request` | `improvement`.
-> - Not set up yet, or the daemon will not start (which is most of setup): `reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"` — it needs nothing running.
+> - Not set up yet, or the daemon will not start (which is most of setup): `npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"` — it needs nothing running.
 > - Report defects in **Reticle**. A bug you find in the app under test is Reticle working; that one goes to the user. Never put app source, secrets, or user data in a report.
 
+> ## Do not re-read this file to look something up
+>
+> This document is large, and a fetch of it may well have been truncated or summarised before it reached you. Everything in it also exists at `https://docs.reticle.sh`, one page at a time, and **appending `.md` to any page URL returns its source with no site chrome**:
+>
+> ```bash
+> curl https://docs.reticle.sh/llms.txt               # every page title and URL; read this first
+> curl https://docs.reticle.sh/cli/doctor.md          # one command: flags, real output, exit codes
+> curl https://docs.reticle.sh/tools-act-and-wait.md  # one tool: arguments, and what its verdict means
+> curl https://docs.reticle.sh/troubleshooting.md     # the failures people actually hit
+> ```
+>
+> Pull the one page that answers the question rather than the whole document. Every page arrives with the rules that matter prepended, so a single fetch orients you without a second call.
+
 Start by detecting which mode to run:
 
 ```bash
@@ -57,7 +70,7 @@ The one thing you may not do is stop early and call it done.
 ## Step 1 — Run `init`. Ask the user nothing.
 
 ```bash
-npx @reticlehq/server init
+RETICLE_INSTALL_SOURCE=skill_file npx @reticlehq/server init
 ```
 
 That is the setup. It takes a few seconds and it does the whole job: detects the framework, package manager and UI library; registers the MCP server globally with whichever agents are installed; writes the agent verification rule **and the `/reticle` slash command**; installs the SDK pinned to the CLI's version; writes `.reticle.json`; wires the build config — the Vite plugin, or all three Next.js files (`next.config`, the root layout, and the `ReticleDev` component); and generates a **capabilities scaffold** pre-filled with the `data-testid` values it found and the state library it detected.
@@ -79,14 +92,15 @@ Reticle **attaches** to whatever is already running; it never starts or manages
 
 Then read the report. Each line is marked:
 
-| Mark | Meaning                  | What you do                                         |
-| ---- | ------------------------ | --------------------------------------------------- |
-| `✓`  | applied                  | nothing                                             |
-| `·`  | already wired            | nothing                                             |
-| `–`  | skipped by a flag        | nothing                                             |
-| `⚠`  | needs a human/agent edit | **only these** — the line carries the exact snippet |
+| Mark | Meaning | What you do |
+| --- | --- | --- |
+| `✓` | applied | nothing |
+| `·` | already wired | nothing |
+| `–` | skipped by a flag | nothing |
+| `ℹ` | done, but incomplete in a way that matters | **read it** — the step ran and something about the result still stops a session appearing |
+| `⚠` | needs a human/agent edit | **only these** — the line carries the exact snippet |
 
-**If every line is `✓`, `·` or `–`, go to Step 1c.** The manual sections below exist for the `⚠` lines only.
+**If every line is `✓`, `·` or `–`, go to Step 1c.** The manual sections below exist for the `⚠` and `ℹ` lines. `ℹ` is the one people skim past, because the step did not fail.
 
 **`init` exits non-zero when a `⚠` lands on a step that makes the app CONNECT** (the Vite plugin, the `ReticleDev` component, the connect snippet). Nothing else applies that step, so the app will never dial the daemon and every tool will answer "no browser session connected" until you paste it in. A non-zero exit is therefore a to-do list for you, not a failed install — apply the snippet on that line, then validate. Other `⚠` lines (MCP registration, the agent rule) exit 0.
 
@@ -120,7 +134,7 @@ Register once globally so Reticle is available in every project:
 claude mcp add reticle -s user -- npx @reticlehq/server mcp
 ```
 
-Confirm with `claude mcp list` — `reticle` should appear. **After adding, restart Claude Code** (or run `/mcp` to refresh) so it picks up the server.
+Confirm with `claude mcp list` — `reticle` should appear. **After adding, restart Claude Code** so it picks up the server. `/mcp` will not do it: that panel manages servers already loaded and never re-reads the config.
 
 **If the `claude` CLI is unavailable**, fall back to merging `"reticle"` into `mcpServers` in `~/.claude.json` — Claude Code's user-scope config, and the same file `claude mcp add` writes. It is a large stateful file, so merge one key; never rewrite it:
 
@@ -239,25 +253,28 @@ Only add this if the user explicitly asks for the daemon to stop between turns:
 
 ---
 
-## Step 1c — The `reticle_*` tools do not exist yet. Get them.
+## Step 1c — Do you already have the `reticle_*` tools? Usually yes.
+
+**Check first. It costs one call, and most of the time it ends this step.**
 
-`init` registered the MCP server, but **your client read its tool list when it started and has not read it again.** So `reticle_*` is not callable in this session yet, however successful the install was. An agent that skips straight to driving here gets "unknown tool" and misdiagnoses it as a broken install.
+- **`reticle_sessions` is callable → you have the tools. Skip straight to Step 4.**
+- Not callable → read on.
 
-**Check first — it costs one call:**
+`reticle init` registers the MCP server **globally, once per machine** (Claude Code user scope, `~/.cursor/mcp.json` for Cursor). So this step bites on the **first Reticle install on this machine and no other**. Every project after that starts with the tools already there — do not put a reload in front of a user who does not need one.
 
-- If `reticle_sessions` is callable, you already have the tools. Skip this step.
-- If it is not, the tools have not loaded, and no amount of retrying will load them.
+If they are not callable: your client read its server list when it started and has not read it again, so `reticle_*` is not callable in this session however successful the install was. **No amount of retrying loads it, and no slash command re-reads the config.** An agent that keeps calling `reticle_*` here gets "unknown tool" and misdiagnoses it as a broken install.
 
-**Then tell the user, in one line, to reload the tools.** This is the only point in setup where you genuinely need them, and it takes them five seconds:
+**Tell the user, in one line, to restart the client.** It takes them five seconds:
 
-| Client            | What they do                                                               |
-| ----------------- | -------------------------------------------------------------------------- |
-| Claude Code       | run `/mcp` to refresh — or restart Claude Code if that does not pick it up |
-| Cursor / Windsurf | reopen the window (Cmd/Ctrl-Shift-P → "Reload Window")                     |
-| VS Code (Copilot) | reload the window                                                          |
-| anything else     | restart the client                                                         |
+| Client | What they do |
+| --- | --- |
+| Claude Code | **restart Claude Code.** `/mcp` does _not_ re-read the config — it only manages servers already loaded, so it cannot pick up a newly registered one |
+| Cursor | reopen the window (Cmd/Ctrl-Shift-P → "Reload Window"). The MCP refresh button was removed in 1.0; the toggle in Settings → MCP sometimes works, the reload always does |
+| VS Code (Copilot) | **no window reload needed** — open `.vscode/mcp.json` and hit the `Start` code lens, or Cmd/Ctrl-Shift-P → `MCP: List Servers` → Start. (Setting `chat.mcp.autostart` makes VS Code do this itself on config change.) |
+| Windsurf / Zed | reopen the window |
+| anything else | restart the client |
 
-Say exactly this and nothing more: **"Reticle is installed. Reload your MCP tools (`/mcp` in Claude Code, or reload the window) and tell me when they're back — then I'll verify a flow in your app."**
+Say exactly this and nothing more: **"Reticle is installed — this is a one-time step for this machine. Restart your client so it picks up the new MCP server (VS Code: just hit Start in `.vscode/mcp.json`), and tell me when the tools are back — then I'll verify a flow in your app."**
 
 Then **wait for them, and continue where you left off.** Do not declare setup finished here: nothing has been verified yet, and this is the single most likely place for a user to walk away believing they are done. When the tools return, go to Step 4.
 
@@ -462,7 +479,18 @@ export default withReticle(nextConfig);
 
 It configures **both** Turbopack and webpack, so it is correct on Next 16 (Turbopack by default) and on Next 15 and earlier. If `next dev` on Next 16 dies with _"This build is using Turbopack, with a webpack config and no turbopack config"_, you are on an old `@reticlehq/next` — upgrade it rather than dropping `withReticle`.
 
-**Other frameworks** — call `reticle.connect()` and `install()` inside a dev guard. Vanilla / HTML: use a dynamic `import('@reticlehq/react')` inside `if (location.hostname === 'localhost')`.
+**Other frameworks** — call `reticle.connect()` and `install()` inside the framework's own dev guard (`import.meta.env.DEV`, `import.meta.dev`, `process.env.NODE_ENV !== 'production'`). Do NOT guard on the hostname; see Step 4's checklist for why that one silently loses the whole setup.
+
+**A page with NO build step** (plain HTML, or a Python/Ruby/PHP app serving templates) — you do not need npm, a bundler, or a `package.json`. Import the SDK from a URL, in a template you only serve in development:
+
+```html
+<script type="module">
+  import { reticle } from 'https://cdn.jsdelivr.net/npm/@reticlehq/browser@2.8.0/+esm';
+  reticle.connect({ token: '<contents of ~/.reticle/pairing-token>' });
+</script>
+```
+
+The `token` is required: without it the bridge closes the socket with "authentication failed" and no session ever appears. Pin the version to the daemon's (`npx @reticlehq/server version`), because a floating import upgrades the page SDK underneath a daemon that did not move. Serving on something other than localhost? Add `allowNonLocalhost: true`.
 
 ---
 
@@ -534,6 +562,11 @@ Most no-connect cases are one of these. Fastest signal first:
 3. Walk it with `reticle_act_and_wait`, narrating each step before you take it.
 4. `reticle_assert` after each step — that the effect happened, not just that the click dispatched.
 5. `reticle_console` + `reticle_network` at the end, for what the DOM does not show.
+6. **`reticle_state` — and read what comes back.** This is the one check that proves the generated `reticle-dev` file is actually doing something. `init` writes it and registers every store it could prove from your source; the ones it could not (Jotai atoms, an XState actor, a TanStack `queryClient` — all need an argument only reading the code supplies) are left commented, and a file that registers nothing looks exactly like a working one from the outside.
+   - **State came back with your keys → done.** The agent can now check what the app BELIEVES, not only what it rendered.
+   - **State came back empty, or `hasCapabilities` is false → say so, in one line, and offer to finish it.** You have the codebase open; completing that file is a minute's work and it is the single highest-value thing left. What you may not do is report a clean install over an empty state read — `init` reported `✓` for writing the file, which is not the same as the file working.
+
+This is a check, not a prerequisite: **an empty state read never blocks the flow you just drove.** Everything else — DOM, network, console, source pointers — works without it. Reporting it accurately is the requirement; treating it as a gate that must be cleared before you show the user anything is how a two-minute setup becomes an afternoon.
 
 Then report what you drove and what it produced, with `file:line` for anything broken.
 
@@ -612,7 +645,7 @@ Two more worth knowing, because nothing else answers these:
 - **`reticle_scroll_to`** — the only way to reach a row that a virtualised list has not mounted. A `query` that misses it is not evidence the row is absent.
 - **`reticle_storage`** — what the app persisted (auth tokens, session ids). The difference between "logged in" and "looks logged in".
 
-> **There is one tool surface, and nothing to pick.** The verify loop is advertised directly (navigate / snapshot / query / act / act_sequence / act_and_wait / observe / network / console / wait_for / assert / state / inspect / sessions / session / feedback). Everything else the skill names — `reticle_capabilities`, the flow and record tools — is one hop away through two meta-tools: `reticle_run({ tool, args })` invokes any tool by name, `reticle_tools` lists them (pass `names:[…]` for full params). `reticle_run` takes `sessionId` at the top level and forwards it, so you do not have to nest it in `args`. Advertised counts, checked by a gate (`surface-sizes.test.ts`): `default` 18, `all` 48.
+> **There is one tool surface, and nothing to pick.** The verify loop is advertised directly (navigate / snapshot / query / act / act_sequence / act_and_wait / observe / network / console / wait_for / assert / state / inspect / capabilities / sessions / session / feedback). Everything else the skill names — the flow and record tools — is one hop away through two meta-tools: `reticle_run({ tool, args })` invokes any tool by name, `reticle_tools` lists them (pass `names:[…]` for full params). `reticle_run` takes `sessionId` at the top level and forwards it, so you do not have to nest it in `args`. Advertised counts, checked by a gate (`surface-sizes.test.ts`): `default` 19, `all` 48.
 >
 > `all` is a verification switch, not a mode to drive agents in: `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises every tool **with its output schema**, at several times the per-turn cost. It is read by the DAEMON at startup, never by your client — exporting it while a daemon is already running changes nothing, so run `npx @reticlehq/server stop` first.
 
@@ -763,7 +796,7 @@ For flows worth re-checking forever — the actual test suite — record them, t
 Reticle's edge over a DOM/screenshot tool is **efficiency and robustness**, not that it sees things nothing else can. A capable browser-automation agent _can_ reach app state by running JS in the page (e.g. walking the React fiber via `browser_evaluate`) — but that's fragile (breaks on minified prod builds, non-React stores, framework-internals changes) and costs ~10× the tool-calls/tokens/time. Reticle reads the same truth with **one typed call**, stably:
 
 - **UI-vs-state desync** (the UI shows one value, the store holds another — e.g. a count that didn't refresh, or a value corrupted in the store but rendered in no view): `reticle_state({ sessionId, store, path })` returns it directly. A pure snapshot can't see it; an agent spelunking framework internals can, but at far higher cost — measured head-to-head, Reticle-MCP caught a never-rendered store tamper in **4 tool calls / 45s** where a Playwright-MCP agent needed **45 calls / ~9min** reverse-engineering the React fiber.
-- **Present-but-unusable / off-theme controls**: `reticle_inspect` returns `occluded` (covered by an overlay), `styles.cursor`/`opacity`, `box` (0×0), and `theme.offTheme` (color off the design-token palette) — the "is it actually usable / on-brand?" read, in one call.
+- **Present-but-unusable / off-theme controls**: `reticle_inspect` returns `occluded` (covered by an overlay), `styles.cursor`/`opacity`, `box` (0×0), and `theme.offTheme` (color matches no design token; `theme.colorTokens` lists every token that does, and `theme.themeScope` says which theme it was measured under) — the "is it actually usable / on-brand?" read, in one call.
 
 ### Consume the human's bug reports (`reticle_session {action:"review"}`)
 
@@ -843,7 +876,7 @@ Use `npx @reticlehq/server status` to see which daemons are running and which se
 
 ### No Chromium / Playwright needed for standard use
 
-Reticle does NOT download Chromium for normal agent workflows. The browser SDK runs inside the user's own browser — the agent sees the DOM, network, console, and state through the WebSocket bridge. Playwright is only installed if you explicitly call `reticle serve --drive <url>` or `reticle verify`, which launch an autonomous browser for unattended automation.
+Reticle does NOT download Chromium for normal agent workflows. The browser SDK runs inside the user's own browser — the agent sees the DOM, network, console, and state through the WebSocket bridge. Playwright is only installed if you explicitly call `npx @reticlehq/server serve --drive <url>` or `npx @reticlehq/server verify`, which launch an autonomous browser for unattended automation.
 
 To attach to a browser the user already has open (zero download, zero extra process):
 
@@ -867,7 +900,7 @@ npx --yes @reticlehq/server@latest version   # force-resolves latest and prints
 npx @reticlehq/server stop                    # stop any daemon running the old version
 ```
 
-Then reload Claude Code (`/mcp`) so the new version is picked up on next connection.
+Then restart Claude Code so the new version is picked up on next connection. `/mcp` does not respawn the stdio proxy — only a restart does.
 
 **Second common cause: the Stop hook is killing the daemon between turns.** If `~/.claude/settings.json` has a Stop hook running `reticle stop --quiet`, remove it. The daemon must stay alive across turns — killing it forces a cold-boot spawn on every reconnect, and if that spawn takes longer than 10 seconds (cold npx cache, slow disk, first install), the proxy times out and exits with code 1. See Step 1b above.
 
@@ -884,7 +917,9 @@ Then reload Claude Code (`/mcp`) so the new version is picked up on next connect
 
 2. **Check for the Stop hook:** `cat ~/.claude/settings.json | grep reticle` If present, delete that hook entry, then repeat step 1.
 
-3. **If -32000 persists**, the daemon may be crashing on startup. Check the log: `cat ~/.reticle/daemon-4400.log | tail -30` Look for `reticle_daemon_start_failed` or `reticle_mcp_daemon_unavailable`. If the port is taken by another process: `lsof -i :4400` to identify it, then kill it and retry.
+3. **If -32000 persists**, the daemon may be crashing on startup. Check the log: `cat ~/.reticle/daemon-4400.log | tail -30` Look for `reticle_daemon_start_failed` or `reticle_mcp_daemon_unavailable`. If the port is taken: run `npx @reticlehq/server doctor`, which names the holder, then `npx @reticlehq/server kill` to free it and retry.
+
+   **Do not reach for `lsof -i :4400` and kill what it lists.** That matches every process on the port, and one of them is the agent's own MCP proxy holding a client socket, so the command that was supposed to fix your connection is the one that takes it away. It is the single most common cause of "the MCP went down". `reticle kill` signals only the listener. If you have no CLI to hand, the safe shell form is `lsof -nP -iTCP:4400 -sTCP:LISTEN -t | xargs kill -9`.
 
 4. **Confirm the MCP config is user-level** (not project-level) and has no pinned version:
 

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

@@ -56,9 +56,29 @@ export interface CausalSummary {
     stateSettleMs?: number;
     /** Before→after for each changed storage key. Values capped. */
     storageDiffs: StorageDiff[];
+    /**
+     * How many entries each list dropped to stay within MAX_SUMMARY_ENTRIES. Present only when
+     * something was dropped, so a trim is never silent — the same rule `ignoredDevTooling` follows.
+     */
+    elided?: Partial<Record<CappedList, number>>;
     route?: string;
     signals: string[];
     layoutShift?: number;
     longTasks: number;
 }
+/**
+ * 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
+ * an unbounded chance that the verdict is the part a client truncates — and an agent that cannot read
+ * the verdict has run the verification and got nothing, which is indistinguishable from not running
+ * it. Measured: one click on a page with a registered TanStack Query store returned ~363KB, because
+ * `capValue` bounded each diff and nothing bounded the COUNT of them.
+ *
+ * 20 keeps the signal that is actually read — the first paths to move, and the settle window over all
+ * of them — while the full names of everything that changed stay one `reticle_state` call away.
+ */
+export declare const MAX_SUMMARY_ENTRIES = 20;
+/** The lists that are capped, named so `elided` can say which one lost entries. */
+type CappedList = 'statePathsChanged' | 'storageKeysChanged' | 'stateDiffs' | 'storageDiffs' | 'signals';
 export declare function causalSummary(events: readonly ReticleEvent[]): CausalSummary;
+export {};

package/dist/capsule/causal-summary.js

@@ -1,4 +1,23 @@
 import { EventType, PerfMetric, isDevToolingUrl } from '@reticlehq/core';
+/**
+ * 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
+ * an unbounded chance that the verdict is the part a client truncates — and an agent that cannot read
+ * the verdict has run the verification and got nothing, which is indistinguishable from not running
+ * it. Measured: one click on a page with a registered TanStack Query store returned ~363KB, because
+ * `capValue` bounded each diff and nothing bounded the COUNT of them.
+ *
+ * 20 keeps the signal that is actually read — the first paths to move, and the settle window over all
+ * of them — while the full names of everything that changed stay one `reticle_state` call away.
+ */
+export const MAX_SUMMARY_ENTRIES = 20;
+/** Trim one list to the cap and report the loss. Order is arrival order, so the head is the earliest. */
+function cap(list, name, elided) {
+    if (list.length <= MAX_SUMMARY_ENTRIES)
+        return list;
+    elided[name] = list.length - MAX_SUMMARY_ENTRIES;
+    return list.slice(0, MAX_SUMMARY_ENTRIES);
+}
 function pushUnique(list, value) {
     if ('string' === typeof value && value.length > 0 && !list.includes(value))
         list.push(value);
@@ -118,6 +137,11 @@ export function causalSummary(events) {
                 break;
         }
     }
+    const elided = {};
+    // `stateSettleMs` is computed over EVERY diff, before the cap: the interval is a fact about the
+    // store, and shrinking it because the evidence was trimmed would make the transient window read as
+    // narrower than it was — the one number here that must survive the trim intact.
+    const settle = stateSettle(stateDiffs);
     return {
         net: {
             total: netTotal,
@@ -126,13 +150,14 @@ export function causalSummary(events) {
             ...(headline === undefined ? {} : { headline }),
         },
         consoleErrors,
-        statePathsChanged,
-        storageKeysChanged,
-        stateDiffs,
-        ...stateSettle(stateDiffs),
-        storageDiffs,
+        statePathsChanged: cap(statePathsChanged, 'statePathsChanged', elided),
+        storageKeysChanged: cap(storageKeysChanged, 'storageKeysChanged', elided),
+        stateDiffs: cap(stateDiffs, 'stateDiffs', elided),
+        ...settle,
+        storageDiffs: cap(storageDiffs, 'storageDiffs', elided),
         ...(route === undefined ? {} : { route }),
-        signals,
+        signals: cap(signals, 'signals', elided),
+        ...(0 === Object.keys(elided).length ? {} : { elided }),
         ...(layoutShift === undefined ? {} : { layoutShift }),
         longTasks,
     };

package/dist/capsule/divergence.js

@@ -7,7 +7,13 @@ function satisfies(link, events) {
         case ConsequenceKind.SIGNAL:
             return events.some((e) => e.type === EventType.SIGNAL && e.data['name'] === link.name);
         case ConsequenceKind.STATE:
-            return events.some((e) => e.type === EventType.STATE_CHANGE && e.data['name'] === link.name);
+            // Matched against the store name OR the changed path, because the link carries whichever half
+            // the predicate gave: `store` when it named one, and `path` otherwise (predicateToExpectedLinks).
+            // The event carries both. Comparing only the store meant every assertion written by path
+            // reported "never changed" however the app behaved — a false claim printed beside a `stateDiffs`
+            // entry showing that exact path changing.
+            return events.some((e) => e.type === EventType.STATE_CHANGE &&
+                (e.data['name'] === link.name || e.data['path'] === link.name));
         case ConsequenceKind.NET:
             return net(events).some((e) => 'string' === typeof e.data['url'] &&
                 e.data['url'].includes(link.urlContains) &&

package/dist/cli/chromium-hint.d.ts

@@ -7,9 +7,18 @@
  * says missing afterwards. Reported from the field by an agent whose machine already had five
  * chromium builds, none of them the wanted one, with no way to learn which one was wanted.
  *
- * Two things fix it, and they are the same two things any unsatisfiable check needs: pin the command
- * to the version doing the asking, and say what was probed. A check that reports only its verdict
- * cannot be argued with — the reader has no way to tell a missing browser from a bad lookup.
+ * The same reporter came back, because pinning the command fixes only half of it. Their five builds
+ * sat in the standard Windows browsers root and the line still read a flat `missing`, which leaves
+ * two readings — "the check is broken" and "none of these count" — and no way to choose. Present at
+ * the wrong revision and absent entirely are different problems: one is a single pinned download,
+ * the other means the lookup is aimed at a root nothing was ever installed into. Collapsing them is
+ * what made the loop unbreakable.
+ *
+ * Three things fix it, and they are what any unsatisfiable check needs: pin the command to the
+ * version doing the asking, say what was probed, and separate the verdicts that have different
+ * fixes. The wanted revision and the browsers root are both read back off the path Playwright itself
+ * resolves, so `PLAYWRIGHT_BROWSERS_PATH` and every platform default are honoured by construction
+ * rather than by a table of roots this file would have to keep in step with Playwright's.
  */
 /** What the check found, gathered by the caller so this stays pure and testable. */
 export interface ChromiumProbe {
@@ -19,6 +28,12 @@ export interface ChromiumProbe {
     exists: boolean;
     /** Version of the playwright the DAEMON bundles — not whatever `npx` would fetch. */
     playwrightVersion?: string | undefined;
+    /** The revision that path names, e.g. `chromium-1223`. Undefined if the path has no revision in it. */
+    wantedRevision?: string | undefined;
+    /** The browsers root the lookup used, wherever `PLAYWRIGHT_BROWSERS_PATH` and the platform put it. */
+    browsersRoot?: string | undefined;
+    /** Chromium revisions actually sitting in that root, wanted or not. */
+    installedRevisions?: readonly string[] | undefined;
 }
 /**
  * The install command, pinned when we know what to pin to.
@@ -27,11 +42,24 @@ export interface ChromiumProbe {
  * at all is a worse one.
  */
 export declare function chromiumInstallCommand(playwrightVersion?: string): string;
+/**
+ * Split a resolved executable path into the browsers root and the revision under it, or null.
+ *
+ * Reading them back off Playwright's own answer is the point. The alternative is reconstructing the
+ * root from `PLAYWRIGHT_BROWSERS_PATH` plus a per-platform default, which is a copy of Playwright's
+ * resolution rules that drifts the first time they change one — and getting it wrong here means
+ * telling a user their browsers are missing while looking in the wrong directory, which is the exact
+ * failure this file exists to stop.
+ */
+export declare function parseChromiumRevision(executablePath: string): {
+    revision: string;
+    root: string;
+} | null;
 /**
  * Ask the playwright THIS process would use, not the one `npx` would fetch.
  *
- * Both halves matter: `executablePath()` resolves the revision the daemon will actually launch, and
- * the bundled package version is what makes the suggested command install that same revision.
+ * `executablePath()` resolves the revision the daemon will actually launch AND the root it will look
+ * in, which is why the probe never reads `PLAYWRIGHT_BROWSERS_PATH` itself.
  */
 export declare function probeChromium(): Promise<ChromiumProbe>;
 /** The bundled playwright's version, or undefined if it cannot be read (the hint then goes unpinned). */

package/dist/cli/chromium-hint.js

@@ -7,12 +7,31 @@
  * says missing afterwards. Reported from the field by an agent whose machine already had five
  * chromium builds, none of them the wanted one, with no way to learn which one was wanted.
  *
- * Two things fix it, and they are the same two things any unsatisfiable check needs: pin the command
- * to the version doing the asking, and say what was probed. A check that reports only its verdict
- * cannot be argued with — the reader has no way to tell a missing browser from a bad lookup.
+ * The same reporter came back, because pinning the command fixes only half of it. Their five builds
+ * sat in the standard Windows browsers root and the line still read a flat `missing`, which leaves
+ * two readings — "the check is broken" and "none of these count" — and no way to choose. Present at
+ * the wrong revision and absent entirely are different problems: one is a single pinned download,
+ * the other means the lookup is aimed at a root nothing was ever installed into. Collapsing them is
+ * what made the loop unbreakable.
+ *
+ * Three things fix it, and they are what any unsatisfiable check needs: pin the command to the
+ * version doing the asking, say what was probed, and separate the verdicts that have different
+ * fixes. The wanted revision and the browsers root are both read back off the path Playwright itself
+ * resolves, so `PLAYWRIGHT_BROWSERS_PATH` and every platform default are honoured by construction
+ * rather than by a table of roots this file would have to keep in step with Playwright's.
  */
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
+/**
+ * A browsers-root entry that is a chromium build.
+ *
+ * Deliberately not matching `chromium_headless_shell-*`: it lives beside the full build and is a
+ * different artifact, so counting it would let a root holding only headless shells report the full
+ * browser as present-but-mismatched.
+ */
+const CHROMIUM_DIR = /^chromium-\d+$/;
+/** The same directory name as a path segment, on either separator, so Windows paths split too. */
+const CHROMIUM_SEGMENT = /[\\/](chromium-\d+)[\\/]/;
 /**
  * The install command, pinned when we know what to pin to.
  *
@@ -23,20 +42,58 @@ export function chromiumInstallCommand(playwrightVersion) {
     const pin = playwrightVersion === undefined ? 'playwright' : `playwright@${playwrightVersion}`;
     return `npx ${pin} install chromium`;
 }
+/**
+ * Split a resolved executable path into the browsers root and the revision under it, or null.
+ *
+ * Reading them back off Playwright's own answer is the point. The alternative is reconstructing the
+ * root from `PLAYWRIGHT_BROWSERS_PATH` plus a per-platform default, which is a copy of Playwright's
+ * resolution rules that drifts the first time they change one — and getting it wrong here means
+ * telling a user their browsers are missing while looking in the wrong directory, which is the exact
+ * failure this file exists to stop.
+ */
+export function parseChromiumRevision(executablePath) {
+    const match = CHROMIUM_SEGMENT.exec(executablePath);
+    if (null === match)
+        return null;
+    const revision = match[1];
+    if (revision === undefined)
+        return null;
+    return { revision, root: executablePath.slice(0, match.index) };
+}
+/** Chromium revisions present in a browsers root. Empty on an unreadable or absent root. */
+function installedRevisions(root) {
+    try {
+        return readdirSync(root)
+            .filter((entry) => CHROMIUM_DIR.test(entry))
+            .sort();
+    }
+    catch {
+        // No root at all is the commonest case here and is not an error: it means nothing was installed.
+        return [];
+    }
+}
 /**
  * Ask the playwright THIS process would use, not the one `npx` would fetch.
  *
- * Both halves matter: `executablePath()` resolves the revision the daemon will actually launch, and
- * the bundled package version is what makes the suggested command install that same revision.
+ * `executablePath()` resolves the revision the daemon will actually launch AND the root it will look
+ * in, which is why the probe never reads `PLAYWRIGHT_BROWSERS_PATH` itself.
  */
 export async function probeChromium() {
     try {
         const { chromium } = await import('playwright');
         const executablePath = chromium.executablePath();
+        const parsed = parseChromiumRevision(executablePath);
         return {
             executablePath,
             exists: existsSync(executablePath),
             playwrightVersion: bundledPlaywrightVersion(),
+            ...(null === parsed
+                ? {}
+                : {
+                    wantedRevision: parsed.revision,
+                    browsersRoot: parsed.root,
+                    installedRevisions: installedRevisions(parsed.root),
+                }),
         };
     }
     catch {
@@ -62,14 +119,27 @@ export function bundledPlaywrightVersion() {
 }
 /** The doctor line for the Chromium check — verdict, what was probed, and how to satisfy it. */
 export function chromiumHint(probe) {
-    if (probe.exists)
-        return '✓ installed';
+    if (probe.exists) {
+        // Naming the revision on the happy line too: it is the number the mismatch line talks about, and
+        // a reader comparing two machines has nothing to compare without it.
+        return probe.wantedRevision === undefined
+            ? '✓ installed'
+            : `✓ installed (${probe.wantedRevision})`;
+    }
     const command = chromiumInstallCommand(probe.playwrightVersion);
+    if (probe.executablePath === undefined) {
+        return `✗ the playwright package is not installed; run: ${command}`;
+    }
+    const present = probe.installedRevisions ?? [];
+    if (present.length > 0 && probe.wantedRevision !== undefined) {
+        // The reported machine. Every fact here is one the reader could not otherwise get: what is
+        // wanted, what is there, and where "there" is. `npx playwright install chromium` unpinned adds
+        // a build to this list and changes nothing, which is what happened.
+        return (`✗ wrong revision — the bundled playwright wants ${probe.wantedRevision}; ` +
+            `${probe.browsersRoot ?? ''} holds ${present.join(', ')}. run: ${command}`);
+    }
     // Naming the path is what turns "missing" from a verdict into evidence: a reader with browsers on
     // disk can see immediately whether this is a missing install or a lookup pointed somewhere else
     // (PLAYWRIGHT_BROWSERS_PATH, a different browsers root, a revision bump).
-    const probed = probe.executablePath === undefined
-        ? 'the playwright package is not installed'
-        : `looked for ${probe.executablePath}`;
-    return `✗ missing — ${probed}; run: ${command}`;
+    return `✗ missing — looked for ${probe.executablePath}; run: ${command}`;
 }