@reticlehq/server 2.7.0 → 2.9.0

package/dist/tools/snapshot-delta.js

@@ -12,7 +12,152 @@
  * invalidates the prior snapshot (a diff across pages would be meaningless), so the next snapshot
  * returns full — never a misleading cross-page delta.
  */
-import { normalizeLines, diffLines } from '../project/baselines.js';
+/**
+ * Identity for comparison, ref for action.
+ *
+ * The delta path used `normalizeLines` from the baseline layer, which strips the ref marker on
+ * purpose — a ref stored in a baseline would make every later diff noisy. Correct there, wrong here:
+ * every delta line came back as `- button "Row actions"` with no ref, and acting needs a ref, so the
+ * full snapshot had to be taken anyway. The diff call cost tokens and bought nothing. One helper, two
+ * callers, opposite requirements — so this path keeps the ref-stripped line as the KEY and emits the
+ * ORIGINAL line with its ref.
+ *
+ * Focus is stripped from the key too. It rides in the line as `[focused]`, alone or comma-joined with
+ * other states, so a focus move used to surface as one line removed and its twin added — structural
+ * change reported where nothing had been added at all. Focus is a property OF a line, so it gets its
+ * own field. Only focus is exempt: `disabled` moving is a real change and must still show.
+ */
+/** The ref marker, as `formatLine` writes it. Bounded quantifier: `\s*` backtracks polynomially. */
+const REF_MARKER = /\s?\(ref=e\d+\)/;
+/** The state bracket — ` [disabled,checked,expanded,focused]` — and the one state that is not structural. */
+const STATE_BRACKET = /\s\[([a-z,]+)\]$/;
+const FOCUSED_STATE = 'focused';
+/** True when this line carries focus. */
+function isFocused(line) {
+    return true === STATE_BRACKET.exec(line)?.[1]?.split(',').includes(FOCUSED_STATE);
+}
+/** The same line with focus removed — and the bracket dropped when focus was all it held. */
+function withoutFocus(line) {
+    const match = STATE_BRACKET.exec(line);
+    const states = match?.[1];
+    if (null === match || undefined === match || undefined === states)
+        return line;
+    const rest = states.split(',').filter((s) => s !== FOCUSED_STATE);
+    const head = line.slice(0, match.index);
+    return 0 === rest.length ? head : `${head} [${rest.join(',')}]`;
+}
+/** What makes two lines "the same element" for diffing: no ref, no focus, no surrounding space. */
+function deltaKey(line) {
+    return withoutFocus(line.replace(REF_MARKER, '')).trim();
+}
+function deltaLines(tree) {
+    return tree
+        .split('\n')
+        .map((line) => ({ key: deltaKey(line), text: withoutFocus(line).trim() }))
+        .filter((line) => line.key.length > 0);
+}
+/**
+ * Multiset diff on the key, emitting the original text.
+ *
+ * Multiset rather than set because duplicate labels are the norm — twelve identical `Row actions`
+ * 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();
+        for (const line of lines) {
+            const existing = map.get(line.key);
+            if (existing === undefined)
+                map.set(line.key, [line.text]);
+            else
+                existing.push(line.text);
+        }
+        return map;
+    };
+    const before = bucket(prev);
+    const after = bucket(next);
+    const removed = [];
+    const added = [];
+    for (const key of new Set([...before.keys(), ...after.keys()])) {
+        const was = before.get(key) ?? [];
+        const now = after.get(key) ?? [];
+        // Pair the SAME REF first. Twelve identical `Row actions` buttons are one key, and the ref is the
+        // only thing that says which of them left — an end-of-list surplus would name an arbitrary one.
+        const survived = new Set(now);
+        const wentOrChanged = was.filter((text) => !survived.has(text));
+        const arrivedOrChanged = now.filter((text) => !new Set(was).has(text));
+        // Whatever is left over on both sides is the SAME element with a re-minted ref (a re-render, or a
+        // navigation that restarts the sequence). Pairing those off is what stops a ref change reading as
+        // a removal plus an addition; only the count difference is a real structural change.
+        const paired = Math.min(wentOrChanged.length, arrivedOrChanged.length);
+        removed.push(...wentOrChanged.slice(paired));
+        added.push(...arrivedOrChanged.slice(paired));
+    }
+    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.
+ *
+ * These have to be two different things. Comparing the rendered lines said focus had moved whenever
+ * the focused element merely changed — typing into a focused textbox rewrites its `[value=...]`, so
+ * `from` and `to` came back naming the same element with different text. Focus identity is the
+ * ELEMENT, so the comparison is on the ref, and the line is only what gets displayed. Where there is
+ * no ref to compare (a non-interactive line), the ref-stripped key stands in.
+ *
+ * Read from the raw tree so a line the diff filters out cannot silently swallow the focus report.
+ */
+function focusedLine(tree) {
+    const focused = tree.split('\n').find((line) => isFocused(line));
+    if (focused === undefined)
+        return undefined;
+    const text = withoutFocus(focused).trim();
+    return { id: REF_MARKER.exec(focused)?.[0]?.trim() ?? deltaKey(focused), text };
+}
 export const SnapshotDeltaMode = {
     FULL: 'full',
     DELTA: 'delta',
@@ -22,12 +167,32 @@ export const SnapshotDeltaMode = {
 export function snapshotDelta(prevTree, nextTree) {
     if (prevTree === undefined)
         return { mode: SnapshotDeltaMode.FULL };
-    const { added, removed } = diffLines(normalizeLines(prevTree), normalizeLines(nextTree));
-    if (0 === added.length && 0 === removed.length)
-        return { mode: SnapshotDeltaMode.UNCHANGED };
+    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
+    // to remove, and an absent field is how the agent knows nothing happened.
+    const focusChanged = before?.id === now?.id
+        ? undefined
+        : {
+            ...(before === undefined ? {} : { from: before.text }),
+            ...(now === undefined ? {} : { to: now.text }),
+        };
+    const moved = focusChanged === undefined ? {} : { focusChanged };
+    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,
     };
 }
 const DEFAULT_MAX_ENTRIES = 50;
@@ -38,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);
@@ -96,17 +265,33 @@ 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
     // over a prefix is real but not exhaustive either.
     const capped = true === r['truncated'] ? { truncated: true, note: CAPPED_DIFF_NOTE } : {};
+    // Spread onto BOTH branches. A value computed correctly and declared nowhere on the way out is the
+    // defect shape that hit this release five separate times: nothing throws, no test reddens, the
+    // field is simply absent forever.
+    const moved = decision.focusChanged === undefined ? {} : { focusChanged: decision.focusChanged };
     if (decision.mode === SnapshotDeltaMode.UNCHANGED) {
-        return { mode: SnapshotDeltaMode.UNCHANGED, status: r['status'], ...capped };
+        return { mode: SnapshotDeltaMode.UNCHANGED, status: r['status'], ...moved, ...capped };
     }
-    return { mode: SnapshotDeltaMode.DELTA, delta: decision.delta, status: r['status'], ...capped };
+    const { changed, ...structuralDelta } = decision.delta;
+    const changedField = changed.length > 0 ? { changed, changedCount: changed.length } : {};
+    return {
+        mode: SnapshotDeltaMode.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.
  *
@@ -145,6 +177,51 @@ export const CORE_TOOL_NAMES = new Set([
     // because there is nowhere else those two calls are ever named.
     ReticleTool.SESSION,
 ]);
+/**
+ * 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)
@@ -159,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)
@@ -166,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] ?? ''];
@@ -211,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));
 }

package/dist/tools/tools.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { NoSessionAction, QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { withSizeCost } from '../session/output-budget.js';
 import { applySnapshotDelta, SnapshotCache } from './snapshot-delta.js';
@@ -82,6 +82,15 @@ const RAW_TOOLS = [
                 .string()
                 .optional()
                 .describe('Present ONLY when `sessions` is empty: why nothing is connected, and the next action that fixes it. An empty list is never the end of the road — read this before concluding the app cannot be driven.'),
+            next_action: z
+                .object({
+                action: z.nativeEnum(NoSessionAction),
+                command: z.string().optional(),
+                port: z.number().optional(),
+                reason: z.string(),
+            })
+                .optional()
+                .describe("Present ONLY when `sessions` is empty: the same answer as `why`, executable. `command` is the LITERAL command to run, sourced from this project's own package.json scripts and lockfile — it is absent, never guessed, when the project declares no dev script. `action` is one of start_dev_server | run_init | open_app | reopen_app."),
         },
         handler: async (deps) => {
             const provider = deps.realInput;
@@ -97,7 +106,14 @@ const RAW_TOOLS = [
             // rather than only when a later tool fails for want of a session.
             if (0 === sessions.length) {
                 const why = deps.sessions.noSessionHint();
-                return { sessions, ...(why === undefined ? {} : { why }) };
+                // The executable half. `why` is for the human reading the transcript; this is the one the
+                // agent acts on, so it never has to parse a paragraph to find a command inside it.
+                const next = deps.sessions.noSessionNextAction();
+                return {
+                    sessions,
+                    ...(why === undefined ? {} : { why }),
+                    ...(next === undefined ? {} : { next_action: next }),
+                };
             }
             return { sessions };
         },
@@ -126,11 +142,18 @@ const RAW_TOOLS = [
                 .string()
                 .optional()
                 .describe('Indented ARIA tree of every element on the page (or the scoped subtree).'),
-            status: z.object({ route: z.string(), title: z.string().optional() }).optional(),
+            status: z
+                .object({
+                route: z.string(),
+                title: z.string().optional(),
+                visibleDialogs: z.array(z.string()).optional(),
+                overlayHidingPage: z.string().optional(),
+            })
+                .optional(),
             mode: z
                 .string()
                 .optional()
-                .describe('delta | unchanged when diff:true returned a change set.'),
+                .describe('full | delta | unchanged — which kind of diff response this is.'),
             delta: z
                 .object({
                 added: z.array(z.string()),
@@ -140,6 +163,15 @@ const RAW_TOOLS = [
             })
                 .optional()
                 .describe('Only present on a diff:true call that found changes.'),
+            changed: z
+                .array(z.string())
+                .optional()
+                .describe('Elements whose value changed in place (same ref, different content) — not a structural add/remove.'),
+            changedCount: z.number().optional().describe('Number of elements in `changed`.'),
+            reason: z
+                .string()
+                .optional()
+                .describe('Why mode is "full": first snapshot for this route, or route changed.'),
             cost: z
                 .object({ bytes: z.number(), tokens: z.number() })
                 .optional()
@@ -358,16 +390,37 @@ const RAW_TOOLS = [
             })
                 .partial()
                 .optional(),
-            // Theme compliance vs the app's design tokens: { colorToken, backgroundToken (null = off-palette),
-            // offTheme, tokenCount }. Kept as unknown — the structured-content serializer can truncate a
-            // large inspect payload's fields to strings, which a strict shape would reject; the full object
-            // is always present in the text content the agent reads.
+            scroll: z
+                .object({
+                scrollTop: z.number(),
+                scrollHeight: z.number(),
+                clientHeight: z.number(),
+                overflowY: z.string(),
+            })
+                .optional(),
+            // Theme compliance vs the app's design tokens: { colorToken, colorTokens, backgroundToken,
+            // backgroundTokens, offTheme, tokenCount, themeScope }. The plural fields carry EVERY token
+            // matching the resolved colour; the singular ones abstain (null) when several tokens share it,
+            // because returning an arbitrary winner was the defect (#313). `themeScope` names the theme
+            // that was active at capture, so two inspects minutes apart are comparable at all.
+            // Kept as unknown — the structured-content serializer can truncate a large inspect payload's
+            // fields to strings, which a strict shape would reject; the full object is always present in
+            // the text content the agent reads.
             theme: z.unknown().optional(),
             /**
              * Where this element is written, as `file:line`. Present when the app is built with the
              * Reticle build plugin in dev; absent in production builds.
              */
             source: z.string().optional(),
+            /**
+             * Why `source` is missing, when it is.
+             *
+             * Distinguishes "this element has no stamp" from "nothing on this page has one, so the
+             * stamping loader is not running" — the second means `file:line` is unavailable for the
+             * whole session and the fix is a build-config change, which used to be discoverable only by
+             * reading the adapter's own source.
+             */
+            sourceUnavailable: z.string().optional(),
             /**
              * Component identity from the framework adapter (@reticlehq/react).
              *

package/dist/tools/unadvertised-help.js

@@ -1,9 +1,10 @@
 /**
  * What to say when an agent calls a real Reticle tool that this profile does not advertise.
  *
- * The default profile advertises 16 of 46 tools. That is deliberate — every advertised tool's schema
- * is re-sent on every turn, and the trim is most of why `hybrid` is cheap — and the other 30 stay
- * fully callable through `reticle_run`, which `profile-reachability.test.ts` guards.
+ * The default surface advertises 18 of 48 tools, and the extended one 30. That is deliberate — every
+ * advertised tool's schema is re-sent on every turn, and editors budget MCP tools as a COUNT shared
+ * across every connected server — and everything omitted stays fully callable through `reticle_run`,
+ * which `surface-reachability.test.ts` guards.
  *
  * The gap was in the ERROR. The MCP SDK answers `Tool <name> not found`, which is indistinguishable
  * from "this tool does not exist", so an agent that trusts it stops trying. Reported from a real
@@ -14,7 +15,7 @@
  * and the switch that makes it stop being necessary.
  */
 import { ReticleTool } from './tool-names.js';
-import { TOOL_SURFACE, TOOL_PROFILE_ENV } from './tool-surface.js';
+import { ADVERTISE_ALL_ENV } from './tool-surface.js';
 import { mergedNameRedirect, mergedNameMessage } from './merged-name-redirect.js';
 /**
  * Guidance for `name`, or undefined when there is nothing useful to add — the tool IS advertised (so
@@ -34,6 +35,8 @@ export function unadvertisedToolHelp(name, advertised, known) {
         `away. It is NOT missing: invoke it with ` +
         `${ReticleTool.RUN} { tool: "${name}", args: { ... } }. ` +
         `Call ${ReticleTool.TOOLS} { names: ["${name}"] } for its parameters. ` +
-        `If you need it repeatedly, set ${TOOL_PROFILE_ENV}=${TOOL_SURFACE.ALL} to advertise ` +
-        `every tool directly.`);
+        `If you need it repeatedly, start the daemon with ${ADVERTISE_ALL_ENV}=1 for the extended ` +
+        `surface. That is read by the DAEMON at startup, so it takes effect on the next daemon, and it ` +
+        `advertises MORE tools rather than all of them — editors budget MCP tools as a shared count, so ` +
+        `${ReticleTool.RUN} stays the way to reach the rest.`);
 }