@reticlehq/server 2.8.0 → 2.10.0

package/dist/tools/observe-tools.js

@@ -262,7 +262,7 @@ export const OBSERVE_TOOLS = [
             // undocumented here, including `route` — and "did submitting the login form navigate away"
             // is the most common thing an agent wants to assert. A field report reached us from an agent
             // that guessed `urlContains` on route (net's spelling) and got unrecognized_keys.
-            'Predicate to evaluate. Kinds: { signal, name } { net, urlContains|method|status|count } ' +
+            'Predicate to evaluate. Kinds: { signal, name } { net, urlContains|method|status|count|bodyContains } ' +
                 '{ state, path|equals } { route, pathname (exact) | contains (path+query+hash) } ' +
                 '{ element, testid|role|text } { text } { console, level|absent } { animation, name } ' +
                 '{ settled } — combine with { allOf | anyOf | not }. Prefer a signal/net/state consequence ' +
@@ -386,6 +386,10 @@ export const OBSERVE_TOOLS = [
                 .nonnegative()
                 .optional()
                 .describe('Keep only the most recent N matching calls (older are dropped and counted in droppedOldest) — cuts tokens on a wide window. Defaults to 200 when omitted; pass a higher number for more, or scope with since/until.'),
+            bodies: z
+                .boolean()
+                .optional()
+                .describe('Include request/response bodies (default true). Pass false for a body-free listing — method, url, status, timing only — for the common "did POST /x return 200?" read. Bodies dominate the payload, so this cuts the cheap case by a large factor.'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -411,6 +415,8 @@ export const OBSERVE_TOOLS = [
             const status = asNumber(args['status']);
             const ok = 'boolean' === typeof args['ok'] ? args['ok'] : undefined;
             const limit = asNumber(args['limit']);
+            // Default true keeps the current shape; `bodies: false` returns the body-free listing (#401).
+            const bodies = 'boolean' === typeof args['bodies'] ? args['bodies'] : true;
             const buffer = bufferEnvelope(session);
             // Completed calls + unresolved in-flight requests (a hung request shows as pending).
             const allNet = reconcileNet(await session.queryEvents({
@@ -425,14 +431,14 @@ export const OBSERVE_TOOLS = [
             }
             // Default the cap so an omitted `limit` can't dump a whole flooded session (since defaults to 0).
             const { events: budgeted, droppedOldest } = applyEventBudget(matched, limit ?? DEFAULT_QUERY_LIMIT);
-            const calls = budgeted.map(projectNetCall);
+            const calls = budgeted.map((e) => projectNetCall(e, bodies));
             // A zero-match FILTER already reports what did fire (netEmptyHint above). Zero calls at all
             // fell through as a bare `[]`, which is indistinguishable from an observer that is not
             // recording — and those need opposite responses. Say the look happened.
             return withSizeCost(noteEmptyRead({
                 calls,
                 ...(droppedOldest > 0 ? { total: matched.length, droppedOldest } : {}),
-                ...bodiesNotCaptured(calls),
+                ...(bodies ? bodiesNotCaptured(calls) : {}),
                 ...buffer,
             }, 'calls', { noun: 'network calls' }));
         },

package/dist/tools/react-grace.d.ts

@@ -30,6 +30,10 @@ import type { SettleSource } from './settle-in-flight.js';
  * True only for the accusable shape: a SUCCESSFUL MUTATING request settled, and nothing has moved. A
  * read that changed nothing is a prefetch, a failed write is a different finding entirely, and an
  * action that already moved the UI has nothing to wait for — none of them buy a grace period.
+ *
+ * "Mutating" is read from the same constant the accuser uses rather than restated here. Restating it
+ * is how `IPC` came to be absent from this list and present in that one, so on a desktop app every
+ * successful write skipped the grace and a correct app was told it had ignored its own response.
  */
 export declare function awaitsReaction(events: readonly {
     type: string;

package/dist/tools/react-grace.js

@@ -23,7 +23,7 @@
  * Deliberately short. This covers a task-boundary re-render, not a slow app: if nothing has moved
  * within the grace, "ignored" has become an honest description and the finding should stand.
  */
-import { EventType } from '@reticlehq/core';
+import { EventType, MUTATING_METHODS } from '@reticlehq/core';
 /**
  * How long to let the app react. A React commit after a resolved fetch is one or two task hops; this
  * is generous against that and still far too short to paper over an app that genuinely dropped the
@@ -32,7 +32,6 @@ import { EventType } from '@reticlehq/core';
 const REACTION_GRACE_MS = 300;
 /** Poll cadence — the same as the settle wait, for the same reason. */
 const POLL_MS = 50;
-const MUTATING = ['POST', 'PUT', 'PATCH', 'DELETE'];
 /** Movement that would clear `response-ignored`; mirrors `uiAdvanced` in the detector. */
 const MOVEMENT = new Set([
     EventType.DOM_ADDED,
@@ -51,6 +50,10 @@ function moved(events) {
  * True only for the accusable shape: a SUCCESSFUL MUTATING request settled, and nothing has moved. A
  * read that changed nothing is a prefetch, a failed write is a different finding entirely, and an
  * action that already moved the UI has nothing to wait for — none of them buy a grace period.
+ *
+ * "Mutating" is read from the same constant the accuser uses rather than restated here. Restating it
+ * is how `IPC` came to be absent from this list and present in that one, so on a desktop app every
+ * successful write skipped the grace and a correct app was told it had ignored its own response.
  */
 export function awaitsReaction(events) {
     if (moved(events))
@@ -60,7 +63,7 @@ export function awaitsReaction(events) {
             return false;
         const method = 'string' === typeof e.data['method'] ? e.data['method'].toUpperCase() : '';
         const ok = e.data['ok'];
-        return MUTATING.includes(method) && true === ok;
+        return MUTATING_METHODS.includes(method) && true === ok;
     });
 }
 /**

package/dist/tools/read-tools.js

@@ -39,6 +39,15 @@ function unanchoredWarning(count) {
 const HUD_LEVELS = ['info', 'warn', 'error'];
 const HUD_LEVEL_LIST = HUD_LEVELS.join(' | ');
 const hudLevelEnum = z.enum(HUD_LEVELS);
+/**
+ * How deep an unscoped `reticle_state` read goes before collapsing to size markers.
+ *
+ * 3 keeps every store name and every top-level key visible — enough to see what exists and to name a
+ * `path` — while collapsing the collections that make an unscoped read enormous. Measured on the
+ * bench fixture: unbounded 10,119 B, depth 4 1,323 B, depth 3 596 B, depth 2 322 B. Two loses the
+ * per-store keys, which is the orientation the next call needs.
+ */
+const DEFAULT_STATE_DEPTH = 1;
 export const READ_TOOLS = [
     {
         name: ReticleTool.BASELINE_SAVE,
@@ -395,7 +404,44 @@ export const READ_TOOLS = [
                 return { ...root, storeNames: names };
             }
             if (path === undefined && depth === undefined) {
-                return { ...root, storeNames: names }; // unchanged shape, safe storeNames
+                // An unscoped read used to hand back the WHOLE store tree: 10,119 bytes on this repo's own
+                // fixture. A tool result is not paid once — it stays in the conversation and is re-sent on
+                // every later turn, so one such read cost roughly 34,000 tokens across a 16-turn run.
+                //
+                // The VALUES are bounded; the ENVELOPE is not touched. `{ stores, storeNames, component }`
+                // is the documented shape and callers depend on it — a first attempt applied the bound by
+                // routing through the path selector, which silently changed the reply to `{ found, value }`
+                // and took the component projection and the bridge round-trip with it. Capping in place
+                // keeps every store name and the component read exactly where they were; only collections
+                // deeper than the bound collapse to a marker like "[Array(40)]", which still says what is
+                // there and how much of it.
+                //
+                // A default, not a cap: any explicit `depth` is honoured at any value, and `path` reads a
+                // sub-tree at full fidelity. Nothing became unreachable, only cheaper by default.
+                const stores = root.stores;
+                const bounded = 'object' === typeof stores && null !== stores
+                    ? Object.fromEntries(Object.entries(stores).map(([k, v]) => [k, capDepth(v, DEFAULT_STATE_DEPTH)]))
+                    : undefined;
+                // Say that it was bounded, and only when it actually was. A read that quietly hands back
+                // less than it was asked for is the shape of a false green: the agent sees
+                // `deployments: "[Array(40)]"`, concludes it has read the store, and asserts over a summary.
+                // The marker alone is suggestive; this makes it explicit and names the way to the real value.
+                const trimmed = bounded !== undefined && JSON.stringify(bounded) !== JSON.stringify(stores);
+                return {
+                    ...root,
+                    ...(bounded === undefined ? {} : { stores: bounded }),
+                    storeNames: names,
+                    ...(trimmed
+                        ? {
+                            truncation: {
+                                note: `bounded to depth ${String(DEFAULT_STATE_DEPTH)} per store — this is NOT the ` +
+                                    'whole store. Values shown as "[Array(n)]" or "{…n keys}" were collapsed; read ' +
+                                    'one with { store, path } (e.g. { store:"app", path:"deployments.0" }) or pass ' +
+                                    'an explicit `depth` for more.',
+                            },
+                        }
+                        : {}),
+                };
             }
             // Back-compat: an older browser returned the whole store; scope it here (may already be
             // size-truncated in transit for a very large store — that is the limitation this fix removes

package/dist/tools/resolve-target.d.ts

@@ -0,0 +1,33 @@
+/** One candidate the browser returned for a target query. */
+export interface TargetCandidate {
+    ref?: unknown;
+    role?: unknown;
+    name?: unknown;
+    visible?: unknown;
+}
+/** What the resolution produced: a ref to act on, or the reason there isn't one. */
+export type TargetResolution = {
+    readonly kind: 'ref';
+    readonly ref: string;
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+};
+/**
+ * Turn a target QUERY into the single ref an action can be performed on.
+ *
+ * `act_and_wait` took only a `ref`, so every verification cost a `reticle_query` turn first just to
+ * learn one string. The advertised tool surface is re-sent on every turn, so that extra turn was not
+ * a small cost: measured on the wire, a two-turn verification spent 10,756 of its 11,235 tokens on
+ * schema and 479 on the actual answers. Removing the turn removes half the schema bill.
+ *
+ * Ambiguity is an ERROR, never a pick. Choosing "the first match" would let a verification act on a
+ * different element than the author meant and still report success, which is the false green this
+ * product exists to prevent — and the failure is invisible, because the verdict describes the
+ * element it DID act on. The message names the candidates so the caller can narrow rather than guess.
+ *
+ * Invisible matches are filtered before counting: a hidden duplicate is a common way for a
+ * legitimately unambiguous query to look ambiguous, and refusing on it would push callers back to
+ * the two-turn path for no gain.
+ */
+export declare function resolveTargetRef(candidates: readonly unknown[]): TargetResolution;

package/dist/tools/resolve-target.js

@@ -0,0 +1,53 @@
+import { asRecord } from './tools-helpers.js';
+/**
+ * Turn a target QUERY into the single ref an action can be performed on.
+ *
+ * `act_and_wait` took only a `ref`, so every verification cost a `reticle_query` turn first just to
+ * learn one string. The advertised tool surface is re-sent on every turn, so that extra turn was not
+ * a small cost: measured on the wire, a two-turn verification spent 10,756 of its 11,235 tokens on
+ * schema and 479 on the actual answers. Removing the turn removes half the schema bill.
+ *
+ * Ambiguity is an ERROR, never a pick. Choosing "the first match" would let a verification act on a
+ * different element than the author meant and still report success, which is the false green this
+ * product exists to prevent — and the failure is invisible, because the verdict describes the
+ * element it DID act on. The message names the candidates so the caller can narrow rather than guess.
+ *
+ * Invisible matches are filtered before counting: a hidden duplicate is a common way for a
+ * legitimately unambiguous query to look ambiguous, and refusing on it would push callers back to
+ * the two-turn path for no gain.
+ */
+export function resolveTargetRef(candidates) {
+    const all = candidates.map((c) => asRecord(c));
+    const visible = all.filter((c) => c.visible !== false);
+    const usable = visible.length > 0 ? visible : all;
+    if (0 === usable.length) {
+        return {
+            kind: 'error',
+            message: 'target matched no element. Nothing was acted on and no verdict is possible — widen the ' +
+                'query, or take a reticle_snapshot to see what is actually on the page.',
+        };
+    }
+    if (usable.length > 1) {
+        const named = usable
+            .slice(0, 5)
+            .map((c) => {
+            const role = 'string' === typeof c.role ? c.role : '?';
+            const name = 'string' === typeof c.name ? c.name : '';
+            const ref = 'string' === typeof c.ref ? c.ref : '?';
+            return name.length > 0 ? `${ref} (${role} "${name}")` : `${ref} (${role})`;
+        })
+            .join(', ');
+        return {
+            kind: 'error',
+            message: `target matched ${String(usable.length)} elements and an action must not guess between ` +
+                `them: ${named}. Narrow the query (add role/name/testid or a scope), or pass an explicit ` +
+                '`ref` from reticle_query.',
+        };
+    }
+    const only = usable[0];
+    const ref = only === undefined ? undefined : only.ref;
+    if ('string' !== typeof ref || 0 === ref.length) {
+        return { kind: 'error', message: 'target matched an element with no usable ref.' };
+    }
+    return { kind: 'ref', ref };
+}

package/dist/tools/settle-in-flight.d.ts

@@ -62,6 +62,21 @@ export declare function inFlightRequestLabels(events: readonly {
     type: string;
     data: Record<string, unknown>;
 }[]): string[];
+/**
+ * Endpoints called MORE THAN ONCE in this window, busiest first, as "METHOD url ×N".
+ *
+ * The other half of an honest `unsettled`. A retrying query against a dead backend leaves nothing in
+ * flight — every attempt comes back, then the next one fires — so the verdict fell through to "what
+ * kept the page busy was its own churn (a poll, a timer, an animation)", which names three things
+ * and points at none of them. Measured in the field: on an app with a background retry loop
+ * `act_and_wait` could never return a pass, and nothing in the verdict said which endpoint to look
+ * at. This does not judge the repetition — a poll is legitimate — it reports it, which is all an
+ * agent needs to tell "my assertion was wrong" from "this app never quiets".
+ */
+export declare function repeatedRequestLabels(events: readonly {
+    type: string;
+    data: Record<string, unknown>;
+}[]): string[];
 export interface SettleResult {
     /** True when nothing this window started is still outstanding. */
     settled: boolean;

package/dist/tools/settle-in-flight.js

@@ -27,7 +27,16 @@
  *   - still in flight when the budget genuinely runs out → `unsettled`, as before, but now an honest
  *     limit instead of an early exit.
  */
-import { EventType } from '@reticlehq/core';
+import { EventType, isDevToolingUrl } from '@reticlehq/core';
+/**
+ * The dev toolchain talking about ITSELF is not the app finishing its work.
+ *
+ * `evalSettled` and `findContradictions` both drop it already; this file read the raw window, so the
+ * exclusion was cosmetic exactly where it decides a verdict. Reported from a real drive: a
+ * deliberately disabled control — no state change, no storage change, zero application requests —
+ * was graded on the strength of a Next webpack hot-update the same payload printed as ignored.
+ */
+const isDevTooling = (data) => isDevToolingUrl('string' === typeof data['url'] ? data['url'] : undefined);
 /** How often to re-read the buffer. Short enough to return promptly, long enough not to spin. */
 const POLL_MS = 50;
 const idOf = (data) => 'string' === typeof data['id'] ? data['id'] : undefined;
@@ -49,7 +58,7 @@ export function inFlightRequestIds(events) {
     }
     const open = [];
     for (const e of events) {
-        if (e.type !== EventType.NET_PENDING)
+        if (e.type !== EventType.NET_PENDING || isDevTooling(e.data))
             continue;
         const id = idOf(e.data);
         if (id !== undefined && !settled.has(id) && !open.includes(id))
@@ -81,6 +90,37 @@ export function inFlightRequestLabels(events) {
     }
     return labels;
 }
+/** Enough to recognise the loop; a busy dashboard must not spend the verdict on a URL list. */
+const MAX_REPEATED = 3;
+/** One call is traffic. Two to the same endpoint inside one window is a repeat. */
+const MIN_REPEATS = 2;
+/**
+ * Endpoints called MORE THAN ONCE in this window, busiest first, as "METHOD url ×N".
+ *
+ * The other half of an honest `unsettled`. A retrying query against a dead backend leaves nothing in
+ * flight — every attempt comes back, then the next one fires — so the verdict fell through to "what
+ * kept the page busy was its own churn (a poll, a timer, an animation)", which names three things
+ * and points at none of them. Measured in the field: on an app with a background retry loop
+ * `act_and_wait` could never return a pass, and nothing in the verdict said which endpoint to look
+ * at. This does not judge the repetition — a poll is legitimate — it reports it, which is all an
+ * agent needs to tell "my assertion was wrong" from "this app never quiets".
+ */
+export function repeatedRequestLabels(events) {
+    const counts = new Map();
+    for (const e of events) {
+        if (e.type !== EventType.NET_REQUEST || isDevTooling(e.data))
+            continue;
+        const method = 'string' === typeof e.data['method'] ? e.data['method'] : 'request';
+        const url = 'string' === typeof e.data['url'] ? e.data['url'] : 'an unreported url';
+        const key = `${method} ${url}`;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .filter(([, count]) => count >= MIN_REPEATS)
+        .sort(([, a], [, b]) => b - a)
+        .slice(0, MAX_REPEATED)
+        .map(([key, count]) => `${key} ×${String(count)}`);
+}
 /**
  * Wait, bounded by `budgetMs`, for the requests this window started to come back.
  *

package/dist/tools/snapshot-delta.d.ts

@@ -21,6 +21,7 @@ export type SnapshotDeltaMode = (typeof SnapshotDeltaMode)[keyof typeof Snapshot
 interface SnapshotDelta {
     added: string[];
     removed: string[];
+    changed: string[];
     addedCount: number;
     removedCount: number;
 }
@@ -45,6 +46,8 @@ export declare function snapshotDelta(prevTree: string | undefined, nextTree: st
 export declare class SnapshotCache {
     #private;
     constructor(max?: number);
+    /** True when an entry exists for this key (regardless of route match). */
+    has(key: string): boolean;
     /** Last tree for this key IF the route still matches; undefined when absent or route changed. */
     recall(key: string, route: string): string | undefined;
     remember(key: string, route: string, tree: string): void;

package/dist/tools/snapshot-delta.js

@@ -63,6 +63,17 @@ function deltaLines(tree) {
  * buttons — and the count is the only thing that says how many left. Emitting the ORIGINAL text is
  * what finally tells them apart: with refs, "which twelve" has an answer.
  */
+/** Extract the ref marker value from a text line, or undefined if absent. */
+function refOf(text) {
+    return REF_MARKER.exec(text)?.[0]?.trim();
+}
+/** Extract the role (first word after the bullet) from a snapshot line — the structural type that must match. */
+function roleOf(text) {
+    return (text
+        .trimStart()
+        .replace(/^-\s*/, '')
+        .split(/[\s"(]/)[0] ?? '');
+}
 function diffKeyed(prev, next) {
     const bucket = (lines) => {
         const map = new Map();
@@ -96,6 +107,39 @@ function diffKeyed(prev, next) {
     }
     return { removed, added };
 }
+/**
+ * Same ref AND same role in both added and removed = value change, not a structural
+ * arrival/departure. Refs alone are not stable identities — they are re-minted on re-render — so a
+ * removed button and an added textbox sharing a ref must stay in their respective lists.
+ */
+function extractChanged(added, removed) {
+    const addedByRef = new Map();
+    for (const [i, text] of added.entries()) {
+        const ref = refOf(text);
+        if (ref !== undefined)
+            addedByRef.set(ref, { idx: i, text, role: roleOf(text) });
+    }
+    const changedIndicesInAdded = new Set();
+    const changedIndicesInRemoved = new Set();
+    const changed = [];
+    for (const [i, text] of removed.entries()) {
+        const ref = refOf(text);
+        if (ref === undefined)
+            continue;
+        const match = addedByRef.get(ref);
+        if (match !== undefined && match.role === roleOf(text)) {
+            changed.push(match.text);
+            changedIndicesInAdded.add(match.idx);
+            changedIndicesInRemoved.add(i);
+            addedByRef.delete(ref);
+        }
+    }
+    return {
+        added: added.filter((_, i) => !changedIndicesInAdded.has(i)),
+        removed: removed.filter((_, i) => !changedIndicesInRemoved.has(i)),
+        changed,
+    };
+}
 /**
  * Where focus sits now: the line to show, plus the identity to compare it BY.
  *
@@ -123,7 +167,8 @@ export const SnapshotDeltaMode = {
 export function snapshotDelta(prevTree, nextTree) {
     if (prevTree === undefined)
         return { mode: SnapshotDeltaMode.FULL };
-    const { added, removed } = diffKeyed(deltaLines(prevTree), deltaLines(nextTree));
+    const raw = diffKeyed(deltaLines(prevTree), deltaLines(nextTree));
+    const { added, removed, changed } = extractChanged(raw.added, raw.removed);
     const before = focusedLine(prevTree);
     const now = focusedLine(nextTree);
     // Reported only on a MOVE. Repeating "focus is still here" every turn is the noise the delta exists
@@ -135,12 +180,18 @@ export function snapshotDelta(prevTree, nextTree) {
             ...(now === undefined ? {} : { to: now.text }),
         };
     const moved = focusChanged === undefined ? {} : { focusChanged };
-    if (0 === added.length && 0 === removed.length) {
+    if (0 === added.length && 0 === removed.length && 0 === changed.length) {
         return { mode: SnapshotDeltaMode.UNCHANGED, ...moved };
     }
     return {
         mode: SnapshotDeltaMode.DELTA,
-        delta: { added, removed, addedCount: added.length, removedCount: removed.length },
+        delta: {
+            added,
+            removed,
+            changed,
+            addedCount: added.length,
+            removedCount: removed.length,
+        },
         ...moved,
     };
 }
@@ -152,6 +203,10 @@ export class SnapshotCache {
     constructor(max = DEFAULT_MAX_ENTRIES) {
         this.#max = max;
     }
+    /** True when an entry exists for this key (regardless of route match). */
+    has(key) {
+        return this.#map.has(key);
+    }
     /** Last tree for this key IF the route still matches; undefined when absent or route changed. */
     recall(key, route) {
         const entry = this.#map.get(key);
@@ -210,10 +265,13 @@ export function applySnapshotDelta(raw, opts, cache) {
         return raw;
     }
     const prev = cache.recall(key, route);
+    const hadEntry = cache.has(key);
     cache.remember(key, route, tree);
     const decision = snapshotDelta(prev, tree);
-    if (decision.mode === SnapshotDeltaMode.FULL)
-        return raw;
+    if (decision.mode === SnapshotDeltaMode.FULL) {
+        const reason = hadEntry ? 'route changed' : 'first snapshot for this route';
+        return { ...r, mode: SnapshotDeltaMode.FULL, reason };
+    }
     // The walk stops at a node cap and returns a DOCUMENT-ORDER PREFIX, so two capped snapshots of a
     // large page are identical whenever the change happened past the cap — and "unchanged" is then a
     // statement about the cap, not about the page. Carried through on both branches: a delta computed
@@ -226,9 +284,12 @@ export function applySnapshotDelta(raw, opts, cache) {
     if (decision.mode === SnapshotDeltaMode.UNCHANGED) {
         return { mode: SnapshotDeltaMode.UNCHANGED, status: r['status'], ...moved, ...capped };
     }
+    const { changed, ...structuralDelta } = decision.delta;
+    const changedField = changed.length > 0 ? { changed, changedCount: changed.length } : {};
     return {
         mode: SnapshotDeltaMode.DELTA,
-        delta: decision.delta,
+        delta: structuralDelta,
+        ...changedField,
         status: r['status'],
         ...moved,
         ...capped,

package/dist/tools/tool-kit.d.ts

@@ -15,10 +15,18 @@ import type { FlowStore } from '../flows/flows.js';
 import type { ProjectStore } from '../project/project-store.js';
 import type { AnnotationStore } from '../flows/annotation-store.js';
 import type { BrowserPool } from '../pool/browser-pool.js';
-export interface ToolDeps {
+import type { ChromiumProbe } from '../cli/chromium-hint.js';
+export interface ToolDeps<Ext = unknown> {
     sessions: SessionManager;
     /** shared one-browser/N-context pool for headless leases. undefined ⇒ lease tools report unavailable. */
     pool?: BrowserPool;
+    /**
+     * Probe for a launchable Chromium, so the lease path can refuse at the FIRST call with the install
+     * fix rather than failing several calls in with a message that reads as "the app is not running".
+     * Optional: absent ⇒ no preflight — every existing test construction of ToolDeps keeps working, and
+     * the fake-pool lease tests are deliberately runnable without a real Chromium.
+     */
+    browserProbe?: () => Promise<ChromiumProbe>;
     baselines: BaselineStore;
     recordings: RecordingStore;
     /** on-disk anchored-flow store (.reticle/flows/). */
@@ -51,8 +59,23 @@ export interface ToolDeps {
      * ToolDeps keeps working; absent falls back to the default port.
      */
     bridgePort?: number;
+    /**
+     * A consumer's OWN dependencies, carried through untouched.
+     *
+     * Nothing in this package reads it. It exists so a consumer embedding the engine can add tools of
+     * its own — answering out of a store this package has never heard of — without either widening the
+     * fields above with a stranger's vocabulary or forking to get a handle through.
+     *
+     * The type parameter, rather than `unknown`, is what keeps the seam typed: a consumer writes
+     * `ToolDef<TheirExt>` once and their handlers see their own type. Casting out of `unknown` in every
+     * handler is how a typed seam quietly becomes an untyped one.
+     *
+     * Optional, and defaulted to `unknown`, so every existing construction of this bag — and every test
+     * that builds one — is unchanged.
+     */
+    ext?: Ext;
 }
-export interface ToolDef {
+export interface ToolDef<Ext = unknown> {
     name: string;
     description: string;
     inputSchema: z.ZodRawShape;
@@ -78,7 +101,19 @@ export interface ToolDef {
      * example that does not validate is worse than none at all.
      */
     example?: Record<string, unknown>;
-    handler: (deps: ToolDeps, args: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Declared method-style, not as a property, and that is load-bearing rather than stylistic.
+     *
+     * Under `strictFunctionTypes` a property holding a function has CONTRAVARIANT parameters, so
+     * `ToolDef<TheirExt>` and `ToolDef<unknown>` become mutually unassignable and a consumer composing
+     * `[...TOOLS, ...theirTools]` needs a cast — as does every internal helper that then touches the
+     * array. Method-style parameters are checked bivariantly, which collapses all of that.
+     *
+     * The unsoundness bivariance admits is that a handler written against `ToolDeps<TheirExt>` could be
+     * handed a bag carrying no `ext` at all. That costs nothing here, because `ext` is optional by
+     * design: any handler reading it already has to survive `undefined`.
+     */
+    handler(deps: ToolDeps<Ext>, args: Record<string, unknown>): Promise<unknown>;
 }
 export declare const sessionIdShape: {
     sessionId: z.ZodOptional<z.ZodString>;

package/dist/tools/tool-names.d.ts

@@ -46,6 +46,8 @@ export declare const ReticleTool: {
     readonly AFFECTED: "reticle_affected";
     readonly COVERAGE: "reticle_coverage";
     readonly VERIFY_CHANGE: "reticle_verify_change";
+    /** Merged: change/flows/affected/coverage/crawl — "what is proved, and what is not". */
+    readonly VERIFY: "reticle_verify";
     /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
     readonly PROJECT: "reticle_project";
     /** explicitly record a run outcome (the manual companion to auto-recording). */

package/dist/tools/tool-names.js

@@ -47,6 +47,8 @@ export const ReticleTool = {
     AFFECTED: 'reticle_affected',
     COVERAGE: 'reticle_coverage',
     VERIFY_CHANGE: 'reticle_verify_change',
+    /** Merged: change/flows/affected/coverage/crawl — "what is proved, and what is not". */
+    VERIFY: 'reticle_verify',
     /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
     PROJECT: 'reticle_project',
     /** explicitly record a run outcome (the manual companion to auto-recording). */

package/dist/tools/tool-surface.d.ts

@@ -40,6 +40,36 @@ export declare const TOOL_SURFACE: {
     readonly DEFAULT: "default";
     /** Every tool advertised directly, WITH output schemas. A verification switch — see above. */
     readonly ALL: "all";
+    /**
+     * The smallest surface that can still produce a VERDICT. Not a profile — a cost switch.
+     *
+     * Measured on the wire: a verification that names its own target costs one `act_and_wait` call,
+     * and 5,480 of its 5,909 tokens are the advertised surface re-sent for that single turn. The
+     * answers cost 430. So on the path where the caller already knows what to assert, almost the
+     * entire bill is the menu, and the menu is the thing to cut.
+     *
+     * Deliberately NOT the default, and now MEASURED rather than inherited. Run over the same 30-bug
+     * set that the default surface scores 23/27 detection and 2/29 false alarms on:
+     *
+     *   detection      24/28   (held)
+     *   FALSE ALARMS   7/30    (was 2/29 — TRIPLED)
+     *   tokens         113,599 per run (was 179,959 — 37% cheaper)
+     *
+     * The five new false alarms are not scattered. They are `mutation-leak` and
+     * `generate-blast-filter` (state), `kpi-deploys-tamper` (business-logic), `debounce-broken`
+     * (timing) and `route-stuck-deployments` (routing) — precisely the classes whose evidence lives in
+     * `reticle_state`, `reticle_network` and `reticle_observe`, which this surface does not advertise.
+     * Strip the observation tools and the model stops observing: it reaches for the verdict without
+     * the evidence and calls a healthy build broken.
+     *
+     * So the retired `dynamic` finding is confirmed, with a sharper mechanism than "accuracy drops".
+     * 37% of the tokens is not worth trading for the one metric this product actually wins on, and
+     * this must not become the default on the strength of the token number alone.
+     *
+     * It remains correct for a caller who has ALREADY decided what to assert — there the assertion
+     * supplies the evidence the surface would otherwise have to go and find.
+     */
+    readonly VERIFY: "verify";
 };
 export type ToolSurface = (typeof TOOL_SURFACE)[keyof typeof TOOL_SURFACE];
 /**
@@ -49,6 +79,8 @@ export type ToolSurface = (typeof TOOL_SURFACE)[keyof typeof TOOL_SURFACE];
  * users to shop among alternatives that did not meaningfully differ.
  */
 export declare const ADVERTISE_ALL_ENV = "RETICLE_ADVERTISE_ALL_TOOLS";
+/** Opt into the smallest verdict-capable surface. Read by the DAEMON at startup, like the others. */
+export declare const VERIFY_SURFACE_ENV = "RETICLE_VERIFY_SURFACE";
 /**
  * The retired setting, still read so nobody's shell profile breaks.
  *
@@ -58,6 +90,34 @@ export declare const ADVERTISE_ALL_ENV = "RETICLE_ADVERTISE_ALL_TOOLS";
  */
 export declare const TOOL_PROFILE_ENV = "RETICLE_TOOL_PROFILE";
 export declare const CORE_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * The extended surface: what `all` advertises BEYOND the default set.
+ *
+ * `all` used to mean "every tool in the registry", and that is no longer allowed to be true. Cursor
+ * enforces a limit of 40 tools across every connected MCP server COMBINED, so a server advertising
+ * 48 by itself can push a user's other servers out or be dropped wholesale. The budget is a count,
+ * so no amount of trimming parameter prose buys anything back — only advertising fewer names does.
+ *
+ * Everything omitted stays in the registry, stays catalogued by `reticle_tools`, and stays callable
+ * by name through `reticle_run { tool, args }`. The cost is one discovery hop on the cold tail, which
+ * is the same trade the default surface has always made, applied one level further out.
+ *
+ * What it costs that is NOT free: `all` is the only surface that carries `outputSchema`, which is
+ * what makes the MCP layer validate tool OUTPUT — the check that once caught `reticle_verify_change`
+ * returning a payload its own schema rejected. The tools left off this list no longer get that
+ * validation from the wire. That defect class is now uncovered for them, and it is written down here
+ * rather than discovered later.
+ *
+ * Chosen as the capabilities an agent plausibly reaches for once the verify loop is not enough:
+ * orientation, the record/replay flow loop, visual evidence, and the three fault-injection controls.
+ */
+export declare const EXTENDED_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * The verify surface: one acting tool that returns a verdict, plus the two meta-tools that reach
+ * everything else. `act_and_wait` can resolve its own target, so no query tool is needed to name an
+ * element — that round trip was half the token cost of a verification.
+ */
+export declare const VERIFY_TOOL_NAMES: ReadonlySet<string>;
 /**
  * Which surface is live.
  *