@reticlehq/server 2.8.0 → 2.9.0

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';
+import type { ChromiumProbe } from '../cli/chromium-hint.js';
 export interface ToolDeps {
     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/). */

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.
  *

package/dist/tools/tool-surface.js

@@ -40,6 +40,36 @@ export const TOOL_SURFACE = {
     DEFAULT: 'default',
     /** Every tool advertised directly, WITH output schemas. A verification switch — see above. */
     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.
+     */
+    VERIFY: 'verify',
 };
 /**
  * The switch that turns on the full, output-schema-carrying surface. A boolean, not a menu.
@@ -48,6 +78,8 @@ export const TOOL_SURFACE = {
  * users to shop among alternatives that did not meaningfully differ.
  */
 export 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 const VERIFY_SURFACE_ENV = 'RETICLE_VERIFY_SURFACE';
 /**
  * The retired setting, still read so nobody's shell profile breaks.
  *
@@ -144,26 +176,52 @@ export const CORE_TOOL_NAMES = new Set([
     // deleting the instruction from the lease and the pause hint — deletes the handback protocol,
     // because there is nowhere else those two calls are ever named.
     ReticleTool.SESSION,
-    // CAPABILITIES is the highest orientation-per-token tool on the surface: one call returns the app's
-    // whole testable surface — its testids, signals, stores and named flows — and `{fromDisk:true}`
-    // returns the same from a checked-in contract with NO browser attached, so an agent with zero
-    // context starts oriented instead of exploring.
-    //
-    // Same argument as the four above, and it is the fifth time this file has made it: a tool an agent
-    // must already know about, and reach through reticle_run, is a tool that never gets called.
-    //
-    // The cost is real and is NOT the bargain #262 claimed. That issue argued the marginal cost sits
-    // "well below the 274-token average" because the input schema is small; measured, its description
-    // plus schema is closer to 325 tokens, which is above the average rather than below it. This is
-    // also a straight +1 rather than a swap: the tools that write-up proposed demoting (`project`,
-    // `domain`) were never in the default set to begin with.
-    //
-    // So it is a deliberate bet, taken with that correction on the table: that orientation replaces
-    // exploratory snapshots, which are among the most expensive calls an agent makes. The measurement
-    // that settles it is whether sessions calling this early take fewer and cheaper snapshots than
-    // those that do not. If that does not show up, this is the entry to revert.
+]);
+/**
+ * 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 const EXTENDED_TOOL_NAMES = new Set([
+    // Demoted from the default set to make room under the cap. It was added as an explicit bet that
+    // orientation replaces exploratory snapshots, and the measurement that would have settled that
+    // bet was never run — so when the budget became a hard count, the unproven entry is the one that
+    // gives way. Still one `reticle_run` hop from any agent that wants it.
     ReticleTool.CAPABILITIES,
+    ReticleTool.FLOW_SAVE,
+    ReticleTool.FLOW_REPLAY,
+    ReticleTool.FLOW_VERIFY,
+    ReticleTool.RECORD,
+    ReticleTool.SCREENSHOT,
+    ReticleTool.VISUAL_DIFF,
+    ReticleTool.CLOCK,
+    ReticleTool.NETWORK_MOCK,
+    ReticleTool.STORAGE,
+    ReticleTool.VERIFY_CHANGE,
+    ReticleTool.CRAWL,
 ]);
+/**
+ * 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 const VERIFY_TOOL_NAMES = new Set([ReticleTool.ACT_AND_WAIT]);
 /** Is the truthy form of a boolean env var set? `1`, `true`, `yes` — anything else is off. */
 function envFlagOn(raw) {
     if (raw === undefined)
@@ -178,6 +236,8 @@ function envFlagOn(raw) {
  * switch decides, and the retired setting is honoured last so an old shell profile still works.
  */
 export function resolveToolSurface(explicit) {
+    if (explicit === TOOL_SURFACE.VERIFY)
+        return TOOL_SURFACE.VERIFY;
     if (explicit === TOOL_SURFACE.ALL)
         return TOOL_SURFACE.ALL;
     if (explicit === TOOL_SURFACE.DEFAULT)
@@ -185,6 +245,8 @@ export function resolveToolSurface(explicit) {
     const retiredExplicit = explicit === undefined ? undefined : RETIRED_PROFILE_VALUES[explicit];
     if (retiredExplicit !== undefined)
         return retiredExplicit;
+    if (envFlagOn(process.env[VERIFY_SURFACE_ENV]))
+        return TOOL_SURFACE.VERIFY;
     if (envFlagOn(process.env[ADVERTISE_ALL_ENV]))
         return TOOL_SURFACE.ALL;
     const retiredEnv = RETIRED_PROFILE_VALUES[process.env[TOOL_PROFILE_ENV] ?? ''];
@@ -230,7 +292,11 @@ export function describeToolSurface(active, requested) {
 export function filterTools(tools, surface) {
     // CORE_TOOL_NAMES is what it always really was: the set advertised directly. It was never the
     // interesting thing about the `core` PROFILE, whose only distinction was a second name for this.
+    if (surface === TOOL_SURFACE.VERIFY)
+        return tools.filter((t) => VERIFY_TOOL_NAMES.has(t.name));
     if (surface === TOOL_SURFACE.DEFAULT)
         return tools.filter((t) => CORE_TOOL_NAMES.has(t.name));
-    return tools;
+    // `all` is the extended surface, not the whole registry — the cap is a hard budget shared with
+    // every other MCP server the user has connected. surface-sizes.test.ts enforces it.
+    return tools.filter((t) => CORE_TOOL_NAMES.has(t.name) || EXTENDED_TOOL_NAMES.has(t.name));
 }