@reticlehq/server 2.7.0 → 2.9.0

package/dist/bridge/bridge.d.ts

@@ -15,7 +15,30 @@ type SessionReadyHandler = (session: Session) => void;
 export declare const WS_CLOSE_REASON: {
     readonly PROTOCOL_MISMATCH: "protocol version mismatch — upgrade @reticlehq/browser";
     readonly AUTH_FAILED: "authentication failed — reload the page to pick up the current pairing token";
+    /**
+     * The pool of half-open handshakes was full, so this dial was turned away before it could say
+     * anything. Every other refusal here records why and this one did not — it closed the socket and
+     * returned — so an app that was running, instrumented and actively dialling looked exactly like an
+     * app nobody had started, and the diagnosis went hunting a stopped dev server.
+     *
+     * Names the cause and the fact that it is transient, because the remedy differs from every other
+     * refusal on this path: nothing about the app is wrong and retrying is the correct response.
+     */
+    readonly HANDSHAKE_POOL_FULL: string;
 };
+/**
+ * A dial turned away at the ORIGIN gate, in words the reader can act on.
+ *
+ * This is the refusal that used to leave no trace anywhere. It happens before any HELLO, so it
+ * produced no `noteClosure`, no `session_disconnected`, nothing but an `origin_rejected` log line —
+ * and the daemon log is the file nobody opens until they have already lost the afternoon. Reported
+ * from a multi-tenant app resolving its tenant from the `Host` header: on a hosts-file alias every
+ * dial was refused here, `doctor` reported every check green, and the lease hint blamed the port.
+ *
+ * The origin is IN the message because it is the fix: it is either the alias to allow-list, or the
+ * proof that the page is not being served from where the developer thinks it is.
+ */
+export declare function originRejectedReason(origin: string | undefined): string;
 interface BridgeOptions {
     port: number;
     host?: string;

package/dist/bridge/bridge.js

@@ -1,5 +1,6 @@
 import * as http from 'node:http';
 import { authFailureReason } from './auth-failure-reason.js';
+import { impactSnapshot, recordImpact } from '../impact/impact-recorder.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, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
 import { Session, SessionManager } from '../session/session.js';
@@ -38,7 +39,39 @@ function refreshIdentity(session, hello) {
 export const WS_CLOSE_REASON = {
     PROTOCOL_MISMATCH: 'protocol version mismatch — upgrade @reticlehq/browser',
     AUTH_FAILED: 'authentication failed — reload the page to pick up the current pairing token',
+    /**
+     * The pool of half-open handshakes was full, so this dial was turned away before it could say
+     * anything. Every other refusal here records why and this one did not — it closed the socket and
+     * returned — so an app that was running, instrumented and actively dialling looked exactly like an
+     * app nobody had started, and the diagnosis went hunting a stopped dev server.
+     *
+     * Names the cause and the fact that it is transient, because the remedy differs from every other
+     * refusal on this path: nothing about the app is wrong and retrying is the correct response.
+     */
+    HANDSHAKE_POOL_FULL: 'refused at the handshake pool — too many connections were mid-handshake on this daemon, so ' +
+        'this dial never got to identify itself. Nothing is wrong with the app; the pool drains on its ' +
+        'own and reloading the page reconnects. If it persists, something else on this machine is ' +
+        'opening sockets to this port.',
 };
+/**
+ * A dial turned away at the ORIGIN gate, in words the reader can act on.
+ *
+ * This is the refusal that used to leave no trace anywhere. It happens before any HELLO, so it
+ * produced no `noteClosure`, no `session_disconnected`, nothing but an `origin_rejected` log line —
+ * and the daemon log is the file nobody opens until they have already lost the afternoon. Reported
+ * from a multi-tenant app resolving its tenant from the `Host` header: on a hosts-file alias every
+ * dial was refused here, `doctor` reported every check green, and the lease hint blamed the port.
+ *
+ * The origin is IN the message because it is the fix: it is either the alias to allow-list, or the
+ * proof that the page is not being served from where the developer thinks it is.
+ */
+export function originRejectedReason(origin) {
+    const named = origin === undefined || 0 === origin.length ? 'a page sending no Origin' : origin;
+    return (`a browser dialled this daemon and was REFUSED at the origin gate: ${named} is not allowed. ` +
+        'Off localhost the SDK needs BOTH `allowNonLocalhost: true` AND a pairing token, and the ' +
+        'daemon needs that origin allow-listed (RETICLE_ALLOWED_ORIGINS). The app is running and ' +
+        'instrumented — it was turned away, so do not go looking for a stopped dev server.');
+}
 /** WS close codes + reasons the bridge sends to the SDK (1008 = policy violation, 1013 = try again later). */
 const WS_CLOSE = {
     TOO_MANY_HANDSHAKES: [1013, 'too many pending handshakes'],
@@ -135,6 +168,8 @@ export class Bridge {
      * authFailureReason.
      */
     #servedProjects = new Set();
+    /** Session ids already counted in the impact record - a reconnect is not a new session. */
+    #countedSessions = new Set();
     #allowedOrigins;
     #maxMessagesPerSecond;
     #maxSessions;
@@ -198,7 +233,7 @@ export class Bridge {
                 verifyClient: ({ origin }, done) => {
                     const allowed = this.#originAllowed(origin);
                     if (!allowed)
-                        log('origin_rejected', { origin: origin ?? 'missing' });
+                        this.#noteOriginRejected(origin);
                     done(allowed, 403, 'Forbidden');
                 },
             });
@@ -229,7 +264,7 @@ export class Bridge {
                 verifyClient: ({ origin }, done) => {
                     const allowed = this.#originAllowed(origin);
                     if (!allowed)
-                        log('origin_rejected', { origin: origin ?? 'missing' });
+                        this.#noteOriginRejected(origin);
                     done(allowed, 403, 'Forbidden');
                 },
             });
@@ -244,12 +279,27 @@ export class Bridge {
                 });
             });
         }
+        // A PERMANENT 'error' listener, on top of the one `ready` installs and then removes.
+        //
+        // `ws` re-emits every 'error' from the server it is attached to, and both `ready` branches above
+        // drop their listener the moment the port is bound. From then on the emitter is bare, and an
+        // EventEmitter that emits 'error' with no listener THROWS — which in the daemon is an
+        // uncaughtException, which is an exit, which takes every agent and every session on this port
+        // with it. Logging one is all it takes; the transport itself needs no other reaction.
+        this.#wss.on('error', (err) => {
+            log('bridge_ws_error', { error: err.message });
+        });
         this.#wss.on('connection', (socket) => {
             this.#onConnection(socket);
         });
     }
     #onConnection(socket) {
         if (this.#pendingConnections >= this.#maxPendingConnections) {
+            // On the channel the no-session diagnosis reads, not only into the log. This refusal happens
+            // before any HELLO, so without it the dial leaves no trace at all — the same hole the origin
+            // gate had, and the same fix.
+            this.sessions.noteClosure(WS_CLOSE_REASON.HANDSHAKE_POOL_FULL, this.#clock());
+            log('bridge_handshake_pool_full', { pending: this.#pendingConnections });
             socket.close(...WS_CLOSE.TOO_MANY_HANDSHAKES);
             return;
         }
@@ -362,6 +412,16 @@ export class Bridge {
                 if (parsed.projectId !== undefined)
                     this.#servedProjects.add(parsed.projectId);
                 this.#onSessionCreate?.(session); // attach the durable journal before any events stream in
+                // A tab that has just connected has no impact record yet, so the report would read "nothing
+                // recorded" over a file with a month of history in it. Push what is already on disk as soon
+                // as there is somewhere to push it to; a session is also a thing that HAPPENED, so it counts.
+                // A reconnecting tab keeps its id, so counting every connect made a page reload look like
+                // a fresh session - the number climbed while nothing new happened.
+                if (!this.#countedSessions.has(session.id)) {
+                    this.#countedSessions.add(session.id);
+                    recordImpact({ sessions: 1 });
+                }
+                session.pushImpact(impactSnapshot, true);
                 const replaced = this.sessions.add(session);
                 if (replaced !== undefined) {
                     // Name the newcomer. A field report had a live session vanish during `reticle_lease` and the
@@ -374,6 +434,10 @@ export class Bridge {
                         byUrl: session.url,
                         previousUrl: replaced.url,
                     });
+                    // Hand the displaced session its replacement BEFORE ending it, so a tool call still holding
+                    // 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}`);
                 }
                 // The daemon is the single judge of skew, and HELLO is where the page announces itself.
@@ -448,6 +512,20 @@ export class Bridge {
             log('socket_error', { error: err.message });
         });
     }
+    /**
+     * Record a refused dial where something OTHER than the daemon log can read it.
+     *
+     * The log line stays — it is the forensic record — but a line in `~/.reticle/daemon-<port>.log` is
+     * invisible to the agent that is, at that exact moment, being told "no browser session connected"
+     * with no reason attached. `noteClosure` is the channel the no-session diagnosis already reads, so
+     * the refusal now travels the same route as an auth failure and a protocol mismatch, and the loop
+     * (the reason is only in the page console; the console needs a session; the refusal prevents one)
+     * is broken from the daemon side.
+     */
+    #noteOriginRejected(origin) {
+        log('origin_rejected', { origin: origin ?? 'missing' });
+        this.sessions.noteClosure(originRejectedReason(origin), this.#clock());
+    }
     #originAllowed(origin) {
         // A real browser SDK connection always carries an Origin. A missing Origin means a non-browser
         // local process (another app, a malicious npm postinstall, an extension's native host) — untrusted

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

@@ -25,6 +25,11 @@ export declare class FakeBrowser {
         name: string;
         args: Record<string, unknown>;
     }[];
+    /** The snapshot tree to return. Mutable so tests can vary the page between calls. */
+    snapshotResult: {
+        tree: string;
+        status: Record<string, unknown>;
+    };
     constructor(port: number, sessionId: string, hasCapabilities?: boolean);
     open(): Promise<void>;
     /** Re-send the HELLO on the live socket, the way the SDK does when capabilities register late. */

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

@@ -32,6 +32,11 @@ 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. */
+    snapshotResult = {
+        tree: '- button "Pay" (ref=e7)\n- dialog "Order confirmed" (ref=e12)',
+        status: { route: '/checkout' },
+    };
     constructor(port, sessionId, hasCapabilities = false) {
         this.sessionId = sessionId;
         this.hasCapabilities = hasCapabilities;
@@ -147,10 +152,7 @@ export class FakeBrowser {
             };
         }
         else if (name === ReticleCommand.SNAPSHOT) {
-            result = {
-                tree: '- button "Pay" (ref=e7)\n- dialog "Order confirmed" (ref=e12)',
-                status: { route: '/checkout' },
-            };
+            result = this.snapshotResult;
         }
         else if (name === ReticleCommand.CAPABILITIES) {
             if (!this.handlesCapabilities) {

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

@@ -56,9 +56,44 @@ 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;
+    /**
+     * TRUE when no store was subscribed, so `statePathsChanged`/`stateDiffs` are empty because nothing
+     * was watching — not because the app changed nothing.
+     *
+     * The two readings are the same empty list, and the wrong one is the one an agent takes: "state
+     * did not change" is a claim about the app, and this codebase would rather say "I could not see"
+     * than say something confident and wrong. Present only when the channel is dark, so a wired app
+     * pays nothing and the field's PRESENCE is what carries the meaning — the same rule
+     * `stateSettleMs` and `elided` follow.
+     */
+    stateUnwatched?: true;
+}
+/** What only the SESSION knows — level facts the event window cannot contain. See `stateUnwatched`. */
+export interface SummaryContext {
+    stateUnwatched?: boolean;
 }
-export declare function causalSummary(events: readonly ReticleEvent[]): CausalSummary;
+/**
+ * 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[], context?: SummaryContext): 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);
@@ -37,7 +56,7 @@ function stateSettle(diffs) {
     const spread = Math.max(...times) - Math.min(...times);
     return spread > 0 ? { stateSettleMs: spread } : {};
 }
-export function causalSummary(events) {
+export function causalSummary(events, context = {}) {
     let netTotal = 0;
     let netErrors = 0;
     let ignoredDevTooling = 0;
@@ -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,14 +150,16 @@ 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,
+        ...(true === context.stateUnwatched ? { stateUnwatched: true } : {}),
     };
 }

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