@reticlehq/server 2.14.0 → 3.2.0

package/dist/surface/tools/real-input-attempt.js

@@ -0,0 +1,360 @@
+/**
+ * The native-input attempt — everything that decides whether a pointer action is driven through a
+ * real input provider or falls back to the occlusion-honest synthetic path, and WHY.
+ *
+ * Split out of act-tools.ts along its natural seam: the act tools care only about the outcome
+ * (`result` defined = it went native), never about provider availability, box resolution,
+ * drag-target inspection or the reason taxonomy.
+ *
+ * Also hosts `rewriteUploadArgs` — the daemon-side path that lets an agent name a file on disk
+ * and have its REAL bytes reach the browser's `<input type="file">`. The browser SDK cannot read
+ * the filesystem; the daemon can. The rewrite happens here, before the ACT command crosses the
+ * bridge, so the browser side sees a normal `{ content, name, type }` call and `assertUploadArgs`
+ * keeps its invariant (no fabricated bytes, no silently-dropped keys).
+ *
+ * Trust boundary: scoped to the project root (one level above `deps.reticleRoot`) plus any
+ * opt-in `uploadRoots` declared in `.reticle.json`, resolved through `realpath` so symlinks
+ * cannot escape an allowed root. Sensitive files (.env*, .git/, *.pem, id_*, .npmrc) are denied
+ * with a message that says why. The cap is derived from the bridge's own MAX_MESSAGE_BYTES with
+ * the base64 4/3 inflation factor applied, so the encoded payload always fits in one WebSocket
+ * frame.
+ */
+import { ActionType, InputModeReason, ReticleCommand, TRANSPORT_LIMITS } from '@reticlehq/core';
+import { boxCenter, isPointerAction } from '../../portal/input/real-input.js';
+import { assertDragNotDestructive, assertNotDestructive } from './act/act-danger.js';
+import { NATIVE_INPUT_ARG } from '@reticlehq/core';
+import { asRecord, asString } from '@reticlehq/core';
+import { commandOrThrow } from './tool-kit.js';
+import { asBox } from './act/act-helpers.js';
+import { isAbsolute, join, relative, extname, basename, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { RETICLE_CONFIG_BASENAME } from '../../command/cli/ports/resolve/cli-port.js';
+/**
+ * Minimal extension → MIME-type table for the file types agents most commonly upload.
+ * Falls back to `application/octet-stream` for anything not listed here — the browser and
+ * the receiving server both sniff the real type from the bytes anyway.
+ */
+const MIME_BY_EXT = {
+    '.pdf': 'application/pdf',
+    '.csv': 'text/csv',
+    '.txt': 'text/plain',
+    '.json': 'application/json',
+    '.xml': 'application/xml',
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.zip': 'application/zip',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.xls': 'application/vnd.ms-excel',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.doc': 'application/msword',
+    '.mp4': 'video/mp4',
+    '.mp3': 'audio/mpeg',
+};
+function mimeFromPath(filePath) {
+    return MIME_BY_EXT[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
+}
+/**
+ * Sensitive path patterns that are refused even inside the project root.
+ *
+ * The project root is the right scope for fixture files. It also contains secrets that live
+ * inside a repo: .env*, .git/config, *.pem, id_rsa, .npmrc. An agent whose context includes
+ * text it just read off the page can be prompted to "verify the importer — upload your .env".
+ * The deny-list keeps fixtures/foo.pdf working while closing that path.
+ *
+ * Patterns are matched against the resolved basename (after realpath, so no symlink aliasing).
+ */
+const DENIED_PATTERNS = [
+    /^\.env(\.|$)/i, // .env, .env.local, .env.production …
+    /^\.git$/i, // .git directory itself
+    /\.pem$/i, // TLS private keys
+    /^id_/i, // SSH private keys: id_rsa, id_ed25519 …
+    /^\.npmrc$/i, // npm auth tokens
+    /^\.netrc$/i, // generic credential store
+    /^\.aws$/i, // AWS credentials directory
+];
+function isDeniedPath(resolvedPath) {
+    // Check every segment of the path, not just the basename, so .git/config is caught too.
+    const segments = resolvedPath.split(/[/\\]/);
+    return segments.some((seg) => DENIED_PATTERNS.some((re) => re.test(seg)));
+}
+/**
+ * Maximum raw bytes the daemon will read for an upload.
+ *
+ * The bridge serialises bytes as base64 inside a JSON WebSocket frame; base64 inflates by 4/3.
+ * The frame must fit within MAX_MESSAGE_BYTES (the maxPayload applied to BOTH bridge sockets).
+ * We leave ~25% headroom for the JSON envelope (action type, ref, other fields).
+ *
+ * Previously hardcoded at 10 MiB, which is 13× the 1 MiB frame limit — any enterprise PDF
+ * would have been rejected by the socket, not by this guard. Now derived from the same constant
+ * that configures the socket so they can never drift.
+ */
+const UPLOAD_MAX_BYTES = Math.floor((TRANSPORT_LIMITS.MAX_MESSAGE_BYTES / (4 / 3)) * 0.75);
+/**
+ * Expand a leading `~` against the caller's home directory. Absolute and relative paths pass
+ * through unchanged. `home` is injected so unit tests do not depend on the machine's real home.
+ */
+export function expandUserPath(rawPath, home) {
+    if ('~' === rawPath)
+        return home;
+    if (rawPath.startsWith('~/') || rawPath.startsWith('~\\'))
+        return join(home, rawPath.slice(2));
+    return rawPath;
+}
+/** True when `real` is inside `root` after both have been realpath'd / resolved. */
+function isInsideRoot(real, root) {
+    const rel = relative(root, real);
+    return !rel.startsWith('..') && !isAbsolute(rel);
+}
+/**
+ * Opt-in extra upload directories from `.reticle.json` (`uploadRoots`). Absent, empty, or unreadable
+ * config means project-root only — the previous default, kept on purpose.
+ */
+async function readUploadRoots(projectRoot, fs, home) {
+    const configPath = join(projectRoot, RETICLE_CONFIG_BASENAME);
+    let raw;
+    try {
+        raw = await fs.readFile(configPath);
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed))
+        return [];
+    const listed = parsed['uploadRoots'];
+    if (!Array.isArray(listed))
+        return [];
+    const roots = [];
+    for (const entry of listed) {
+        if ('string' !== typeof entry || 0 === entry.trim().length)
+            continue;
+        roots.push(resolve(expandUserPath(entry.trim(), home)));
+    }
+    return roots;
+}
+/**
+ * Resolve and validate a caller-supplied upload path.
+ *
+ * 1. Expand a leading `~`, then resolve to absolute (join against project root for relative paths).
+ * 2. Call `realpath` to follow symlinks — `relative()` is lexical and a symlink inside the tree
+ *    can point outside it; realpath is the only reliable check.
+ * 3. Confirm the real path is within the project root or an opt-in `uploadRoots` entry.
+ * 4. Confirm the path does not match the sensitive-file deny-list.
+ *
+ * Returns the resolved real path on success. Throws with a user-readable message on any violation.
+ */
+async function resolveUploadPath(rawPath, projectRoot, fs, uploadRoots, home) {
+    const expanded = expandUserPath(rawPath, home);
+    const abs = isAbsolute(expanded) ? expanded : join(projectRoot, expanded);
+    // realpath resolves symlinks; it also rejects ENOENT, so we get a clear missing-file error.
+    const real = await fs.realpath(abs).catch(() => {
+        throw new Error(`upload path '${rawPath}' could not be read: file not found or not accessible.`);
+    });
+    const allowed = [projectRoot, ...uploadRoots];
+    if (!allowed.some((root) => isInsideRoot(real, root))) {
+        const listed = allowed.map((r) => `'${r}'`).join(', ');
+        throw new Error(`upload path '${rawPath}' resolves to '${real}', which is outside every allowed upload root ` +
+            `(${listed}). Paths must sit under the project directory or an entry in ` +
+            `\`.reticle.json\`'s \`uploadRoots\` (e.g. ["~/Downloads"]).`);
+    }
+    if (isDeniedPath(real)) {
+        throw new Error(`upload path '${rawPath}' matches a sensitive-file pattern and cannot be read by the daemon. ` +
+            'Fixture files for upload tests should live in a dedicated directory (e.g. fixtures/).');
+    }
+    return real;
+}
+/**
+ * If the action is `upload` AND the inner args carry `path`, read the file from disk and rewrite
+ * the args to `{ content, name, type, __base64: true }` before the ACT command reaches the browser.
+ *
+ * Returns the (possibly rewritten) args object. All other actions are returned unchanged.
+ *
+ * This is the SINGLE interception point — called from session.command() so flow replay, crawl,
+ * and every other ACT dispatch site are covered without per-site wiring.
+ */
+export async function rewriteUploadArgs(deps, action, innerArgs, 
+/** Injected for tests; production uses the process home directory. */
+home = homedir()) {
+    if (action !== ActionType.UPLOAD)
+        return innerArgs;
+    const rawPath = asString(innerArgs['path']);
+    if (rawPath === undefined)
+        return innerArgs; // no path → browser handles as inline upload
+    // Project root is one level above .reticle/
+    const projectRoot = resolve(join(deps.reticleRoot, '..'));
+    const uploadRoots = await readUploadRoots(projectRoot, deps.fs, home);
+    // Blocker 4 fix: stat FIRST, before allocating read buffer, so a huge file fails fast.
+    const realPath = await resolveUploadPath(rawPath, projectRoot, deps.fs, uploadRoots, home);
+    const fileStat = await deps.fs.stat(realPath).catch(() => {
+        throw new Error(`upload path '${rawPath}' could not be read: file not found or not accessible.`);
+    });
+    // Blocker 2 fix: cap is now derived from TRANSPORT_LIMITS so it can never exceed the socket limit.
+    if (fileStat.size > UPLOAD_MAX_BYTES) {
+        throw new Error(`upload path '${rawPath}' is ${fileStat.size} bytes, which exceeds the ` +
+            `${UPLOAD_MAX_BYTES} byte upload limit (bridge frame cap). ` +
+            'Split the file or pass its bytes as args.content directly.');
+    }
+    const bytes = await deps.fs.readFileBytes(realPath).catch(() => {
+        throw new Error(`upload path '${rawPath}' could not be read: file not found or not accessible.`);
+    });
+    // Encode as base-64 so the bytes survive JSON serialisation across the bridge.
+    const content = Buffer.from(bytes).toString('base64');
+    // Infer MIME type from the file extension; fall back to octet-stream if unknown.
+    const callerType = asString(innerArgs['type']);
+    const type = callerType ?? mimeFromPath(realPath);
+    // Default filename to the basename of the REAL path (post-symlink-resolution).
+    const callerName = asString(innerArgs['name']);
+    const name = callerName ?? basename(realPath);
+    // Strip 'path' — the browser does not know it; assertUploadArgs would refuse it.
+    // __base64: true tells the browser-side dispatch to decode content before File construction.
+    const { path: _dropped, name: _n, type: _t, ...rest } = innerArgs;
+    return { ...rest, content, name, type, __base64: true };
+}
+/** Synthetic outcome with a diagnostic reason (provider configured but native input skipped). */
+function synthetic(reason) {
+    return reason === undefined
+        ? { result: undefined, settled: false }
+        : { result: undefined, settled: false, reason };
+}
+/**
+ * Hover without a native pointer is a false success: synthetic mouseover reports dispatched and
+ * settled while CSS `:hover` never applies. Same refusal shape as contenteditable — name the gap
+ * rather than pretend the action ran.
+ */
+export const HOVER_NEEDS_POINTER_MSG = 'cannot hover without a real pointer — CSS :hover only applies to a native mouse move, never to a synthetic mouseover';
+function hoverSucceeded(center) {
+    return { result: { performed: true, center, action: ActionType.HOVER }, settled: true };
+}
+/**
+ * Drive hover through a real pointer (CDP provider, then a leased Playwright page), or refuse.
+ *
+ * A leased tab already owns Chromium — the pool can move the mouse even when `reticle drive` /
+ * `RETICLE_CDP_URL` never configured a provider. Falling through to synthetic dispatch is the
+ * bug: the tool reports done and the styles never ran.
+ */
+async function hoverForReal(deps, session, ref, inner, provider) {
+    const providerReady = provider !== undefined && (await provider.isAvailableFor(session.url));
+    if (!providerReady && deps.pool === undefined) {
+        throw new Error(HOVER_NEEDS_POINTER_MSG);
+    }
+    const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
+    assertNotDestructive(ActionType.HOVER, inner, inspected);
+    const box = asBox(inspected);
+    if (box === undefined) {
+        throw new Error(HOVER_NEEDS_POINTER_MSG);
+    }
+    if (providerReady && provider !== undefined) {
+        try {
+            const performed = await provider.perform(session.url, ActionType.HOVER, box, {});
+            if (performed.performed)
+                return hoverSucceeded(performed.center);
+        }
+        catch {
+            // A provider error used to fall back to synthetic dispatch. For hover that is a lie.
+        }
+    }
+    const { cx, cy } = boxCenter(box);
+    if (true === (await deps.pool?.hoverLease(session.id, cx, cy))) {
+        return hoverSucceeded({ cx, cy });
+    }
+    throw new Error(HOVER_NEEDS_POINTER_MSG);
+}
+/**
+ * Attempt to drive a pointer action via native input. Returns a synthetic outcome (with a
+ * `reason` when a provider is configured) whenever the synthetic path should run — no matching
+ * page, unresolvable box, declined, etc. A throw inside the provider becomes a synthetic fallback
+ * flagged with `fellBack`. `result` is defined only on a real success.
+ *
+ * Hover is the exception: it never returns synthetic. CSS `:hover` is not applied by
+ * `dispatchEvent`, so a synthetic success is the defect. The call either drives a real pointer
+ * or throws.
+ */
+export async function tryRealInput(deps, session, ref, action, args) {
+    const provider = deps.realInput;
+    const inner = asRecord(args['args']);
+    const askedForNative = true === inner[NATIVE_INPUT_ARG];
+    if (action === ActionType.HOVER) {
+        return hoverForReal(deps, session, ref, inner, provider);
+    }
+    if (provider === undefined) {
+        // Silent by default: with no provider EVERY action is synthetic, and a reason on all of them is
+        // noise on the most-used tool in the product. But an agent that passed native:true asked a
+        // question and got the opposite answer — reported from the field as a silent downgrade that cost
+        // real debugging time, because the tool description promises a reason is "never silent".
+        return askedForNative ? synthetic(InputModeReason.NOT_CONFIGURED) : synthetic();
+    }
+    if (!isPointerAction(action))
+        return synthetic(InputModeReason.NOT_POINTER); // fill/type stay synthetic
+    // "Don't click, run the code": a click/dblclick runs the occlusion-honest SYNTHETIC path by default
+    // even with a provider configured — no coordinate gesture to be intercepted by the HUD or missed
+    // off-screen. Opt into a trusted native click with args.native:true (file pickers, clipboard,
+    // isTrusted-gated handlers). hover/drag genuinely need native pointer state, so they stay real.
+    if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) && !askedForNative) {
+        return synthetic(InputModeReason.SYNTHETIC_CLICK_PREFERRED);
+    }
+    // Under version skew CDP is unusable while DOM tools still work (#688). Surface the skew sentence
+    // rather than "page not correlated" / a silent provider-error fallback — those send the agent
+    // hunting a dead context that is not dead.
+    if (session.versionSkew !== undefined) {
+        throw new Error(session.versionSkew);
+    }
+    if (!(await provider.isAvailableFor(session.url)))
+        return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
+    const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
+    assertNotDestructive(action, inner, inspected);
+    const box = asBox(inspected);
+    if (box === undefined)
+        return synthetic(InputModeReason.ELEMENT_NOT_LOCATABLE);
+    let toBox;
+    if (action === ActionType.DRAG) {
+        const toRef = asString(inner['toRef']);
+        if (toRef === undefined)
+            return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
+        const targetInspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, {
+            ref: toRef,
+        });
+        // A drag is judged on BOTH ends: dropping onto "Trash" is destructive however innocent the
+        // thing being dragged looks.
+        assertDragNotDestructive(inner, inspected, targetInspected);
+        toBox = asBox(targetInspected);
+        if (toBox === undefined)
+            return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
+    }
+    const performArgs = {};
+    const value = asString(inner['value']);
+    if (value !== undefined)
+        performArgs.value = value;
+    const text = asString(inner['text']);
+    if (text !== undefined)
+        performArgs.text = text;
+    if (toBox !== undefined)
+        performArgs.toBox = toBox;
+    try {
+        const performed = await provider.perform(session.url, action, box, performArgs);
+        if (!performed.performed)
+            return synthetic(InputModeReason.PROVIDER_DECLINED);
+        return { result: { performed: true, center: performed.center, action }, settled: true };
+    }
+    catch {
+        if (session.versionSkew !== undefined)
+            throw new Error(session.versionSkew);
+        return {
+            result: undefined,
+            settled: false,
+            fellBack: true,
+            reason: InputModeReason.PROVIDER_ERROR,
+        };
+    }
+}

package/dist/surface/tools/reconcile-tools.js

@@ -0,0 +1,211 @@
+import { bodyCaptureRemedy } from '@reticlehq/engine/evidence/body-capture-remedy.js';
+import { z } from 'zod';
+import { witnessDisagreement, WitnessOutcome, } from '@reticlehq/engine/disagreement/witness-disagreement.js';
+/** How long to wait on the outside observer. Short: it is a read model, not the app under test. */
+const WITNESS_MS = 5_000;
+import { EventType, ReticleCommand, SnapshotMode, urlForMatch } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { cursorSchema } from './args/numeric-bounds.js';
+import { reconcile } from '@reticlehq/engine/disagreement/reconcile.js';
+import { salvageJson } from '@reticlehq/engine/window/json-salvage.js';
+import { withControl } from '../../portal/session/control-envelope.js';
+import { asNumber, asString } from '@reticlehq/core';
+import { sessionIdShape, commandOrThrow } from './tool-kit.js';
+import { readCompleteTree } from './read/complete-snapshot.js';
+import { HttpWitness } from '../../portal/realm/http-witness.js';
+/**
+ * Does the screen agree with the data the app was given?
+ *
+ * A separate tool rather than a passive contradiction rule, because it needs the rendered page as
+ * well as the events — a comparison, not an observation. Passive rules stay pure and run on every
+ * window; this one costs a snapshot, so the agent asks for it.
+ *
+ * It exists because the misses that mattered on a real payments dashboard were all this shape: a USD
+ * amount rendered with a rupee sign, a settlement the API calls `on_hold` rendered as "pending". No
+ * request fails, no assertion fails, and the numbers on screen match the numbers in the payload. The
+ * only thing that disagrees is the meaning.
+ */
+/** Response bodies captured in the window, newest last. Only JSON is worth comparing. */
+async function capturedBodies(session, since, urlContains) {
+    const events = (await session.queryEvents({ since }));
+    const bodies = [];
+    let withBody = 0;
+    let total = 0;
+    let truncated = 0;
+    for (const event of events) {
+        if (event.type !== EventType.NET_REQUEST)
+            continue;
+        const url = urlForMatch(event.data);
+        if (urlContains !== undefined && !url.includes(urlContains))
+            continue;
+        total += 1;
+        const raw = event.data['responseBody'];
+        if (typeof raw !== 'string' || 0 === raw.length)
+            continue;
+        // A capped body is not an absent one. Recover the records that closed before the cut rather than
+        // reporting nothing about the page with the most data on it.
+        const salvaged = salvageJson(raw);
+        if (0 === salvaged.values.length)
+            continue;
+        bodies.push(...salvaged.values);
+        withBody += 1;
+        if (salvaged.partial)
+            truncated += 1;
+    }
+    return { bodies, withBody, total, truncated };
+}
+export const RECONCILE_TOOLS = [
+    {
+        name: ReticleTool.RECONCILE,
+        example: { urlContains: '/api/v1/settlements' },
+        description: 'Compare what the API returned against what the page RENDERS. Catches the class no status code and no assertion can: a USD amount shown with a ₹ sign, a record the API calls `on_hold` displayed as "pending". Needs response bodies — enable `captureNetworkBodies` — and says so when they are missing rather than reporting a clean result over data it never read.',
+        inputSchema: {
+            ...sessionIdShape,
+            since: cursorSchema
+                .optional()
+                .describe('Cursor from a prior act — scopes to responses received after it. Default: 0.'),
+            urlContains: z
+                .string()
+                .optional()
+                .describe('Only compare responses from URLs containing this, e.g. "/api/v1/settlements".'),
+            witness: z
+                .object({
+                url: z.string().url(),
+                expect: z.string().optional(),
+            })
+                .optional()
+                .describe('An observer OUTSIDE the app — a read-only endpoint that reports what really happened (a row count, a mail sink, an admin read model). Everything else this tool compares is the app describing itself, so an app that lies to itself repeats the lie on every channel. This is the one reading it cannot author. GET the url; `expect` is a substring the response must contain for the effect to count as SEEN. Unreachable is reported as inconclusive and NEVER as agreement.'),
+        },
+        outputSchema: {
+            mismatches: z
+                .array(z.object({ entity: z.string(), field: z.string(), api: z.string() }).passthrough())
+                .describe('Fields whose rendering disagrees with the data the app was given.'),
+            compared: z.number().describe('How many responses carried a body that could be compared.'),
+            note: z
+                .string()
+                .optional()
+                .describe('Present when nothing could be compared — never silent about an empty check.'),
+            witness: z
+                .object({ kind: z.string(), because: z.string(), inconclusive: z.boolean().optional() })
+                .optional()
+                .describe('Present only when a `witness` was supplied AND it disagreed with the app, or could not be reached. Two independent observers disagreeing is a fact, not an inference — it is the strongest finding this tool can produce.'),
+        },
+        handler: async (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const since = asNumber(args['since']) ?? 0;
+            const { bodies, withBody, total, truncated } = await capturedBodies(session, since, asString(args['urlContains']));
+            // An empty result over data that was never read is the exact false green this tool exists to
+            // prevent, so the two cases are reported differently and neither is silent.
+            if (0 === bodies.length) {
+                return withControl(session, {
+                    mismatches: [],
+                    compared: 0,
+                    note: 0 === total
+                        ? 'no responses in this window matched — nothing was compared'
+                        : `${String(total)} response(s) matched but NONE carried a recorded body, so nothing was compared. ${bodyCaptureRemedy(session.sdkVersion)}`,
+                });
+            }
+            // The whole page, INCLUDING whatever the snapshot's node cap cut off. A comparison against a
+            // prefix of the page can miss the row that disagrees and can invent one that does not — the
+            // value it was looking for may simply sit past the cut.
+            const page = await readCompleteTree((scope) => commandOrThrow(deps, session.id, ReticleCommand.SNAPSHOT, {
+                mode: SnapshotMode.FULL,
+                ...(scope === undefined ? {} : { scope, includeRoot: true }),
+            }));
+            const mismatches = reconcile(bodies, page.tree);
+            /*
+             * Consult the observer outside the app, when one was named.
+             *
+             * Everything above is the app describing itself — its own responses against its own page — so
+             * an app that lies to itself repeats the lie consistently and no amount of it settles
+             * anything. This is the one reading the subject cannot author.
+             *
+             * Consulted BEFORE the completeness refusal below, for the reason that refusal itself gives:
+             * a finding FOUND in a partial page is still found. The witness was last, so a page that could
+             * not be read fully threw before the outside observer was ever contacted — discarding the
+             * strongest evidence available at exactly the moment the app's own evidence is unreadable.
+             *
+             * "The app claims" is taken as: it returned a body worth comparing and nothing on screen
+             * contradicts it. That is the strongest self-report available here, and it is exactly the
+             * claim a witness is for checking.
+             */
+            const witnessArg = args['witness'];
+            let witness;
+            if (witnessArg !== null && 'object' === typeof witnessArg) {
+                const { url, expect: needle } = witnessArg;
+                const appClaims = withBody > 0 && 0 === mismatches.length;
+                /*
+                 * Through `HttpWitness`, not a bare `fetch` — this used to be its own inline request, so the
+                 * protocol's reference witness had no production caller and the class that IS bound to the
+                 * `Witness` SPI could drift from the behaviour that actually ships without anything going
+                 * red. Two implementations of "look from outside and say what you saw" is one more than the
+                 * evidence is worth.
+                 *
+                 * A non-2xx answer is raised here rather than inside the witness, because a witness that
+                 * could not look must report a blind spot and not an observation: `witnessDisagreement`
+                 * reads "observed nothing, nothing hidden" as the world contradicting the app, which would
+                 * turn a 404 on the observer's own endpoint into an accusation against somebody else's code.
+                 */
+                const observer = new HttpWitness({
+                    url,
+                    fetch: async (target) => {
+                        const res = await fetch(target, {
+                            method: 'GET',
+                            signal: AbortSignal.timeout(WITNESS_MS),
+                        });
+                        if (!res.ok)
+                            throw new Error(`the observer answered ${String(res.status)}`);
+                        return res;
+                    },
+                    now: () => Date.now(),
+                });
+                const witnessWindow = observer.openWindow(WITNESS_MS);
+                const seen = await observer.observe(witnessWindow);
+                const unreachable = (await observer.coverage(witnessWindow)).blindSpots[0]?.detail;
+                const saw = unreachable !== undefined
+                    ? undefined
+                    : needle === undefined
+                        ? seen.length > 0
+                        : seen.some((o) => String(o.value).includes(needle));
+                witness = witnessDisagreement({
+                    appClaims,
+                    witnessSaw: saw,
+                    ...(unreachable === undefined ? {} : { unreachable }),
+                });
+            }
+            // ASYMMETRIC on purpose. A mismatch FOUND in a partial page is still found — one witness proves
+            // presence, and withholding it because the rest of the page was unread helps nobody. An EMPTY
+            // result is the universal claim "nothing anywhere disagrees", and a partial page cannot support
+            // it. So the positive keeps working and only the negative is refused.
+            /*
+             * A DISAGREEMENT outranks the completeness refusal, by the same asymmetry stated above: two
+             * independent observers disagreeing is a fact about the app, and a partial page cannot make it
+             * less of one. Only the universal claim "nothing anywhere disagrees" needs a whole page.
+             */
+            if (0 === mismatches.length && !page.complete && witness?.kind !== WitnessOutcome.DISAGREES) {
+                throw new Error(`the page could not be read completely — ${page.incompleteBecause ?? 'the snapshot was cut'}. ` +
+                    'Nothing was found to disagree with the API, but that is not the same as nothing disagreeing: ' +
+                    'the record that does could be in the part that was never read. Narrow the page (close overlays, ' +
+                    'navigate to the view holding these records) and re-run.');
+            }
+            // A truncated body is declared whether or not anything was found in it: "no mismatches" over a
+            // partially-read payload is a weaker statement than over a whole one, and the difference is
+            // exactly the kind of omission this layer exists to refuse.
+            const partial = truncated > 0
+                ? {
+                    note: `${String(truncated)} of ${String(withBody)} response(s) exceeded the body cap and were read only up to the cut — records after it were not compared`,
+                }
+                : 0 === mismatches.length
+                    ? {
+                        note: `compared ${String(withBody)} response(s); nothing on screen contradicts them`,
+                    }
+                    : {};
+            return withControl(session, {
+                mismatches,
+                compared: withBody,
+                ...partial,
+                ...(witness === undefined ? {} : { witness }),
+            });
+        },
+    },
+];

package/dist/surface/tools/tool-hit-rate.js

@@ -0,0 +1,90 @@
+import { CORE_TOOL_NAMES, EXTENDED_TOOL_NAMES } from './tool-surface.js';
+/**
+ * Which tools this session called, and how reachable each one was.
+ *
+ * The generalisation of the capture ledger: it recorded a short list of read tools to answer one
+ * feature's disproof, and the question that followed is the same question asked of the whole table —
+ * most of the surface has never been observed being called at all, and a decision about what to cut
+ * or consolidate is about to be made. This is the instrument for that decision, and nothing else.
+ *
+ * ## Why the count alone is not enough
+ *
+ * A tool that goes uncalled because nobody was told it exists and a tool that goes uncalled because
+ * nobody wants it look identical in a call count. They are opposite conclusions. So every count is
+ * reported beside the tool's REACHABILITY — advertised on the default surface, advertised only on
+ * the extended one, or reachable solely by naming it to `reticle_run` — and the interesting cell is
+ * the one where an agent found a run-only tool anyway.
+ *
+ * ## The tiers are derived, never restated
+ *
+ * `tierOfTool` reads `CORE_TOOL_NAMES` and `EXTENDED_TOOL_NAMES` directly. A tool promoted or
+ * demoted between surfaces changes tier here with nothing edited. A local copy of either list would
+ * go stale on the first move and would then be wrong about the exact axis this exists to measure —
+ * and it would be wrong silently, in a report used to justify deleting things.
+ *
+ * ## What these numbers do NOT establish
+ *
+ *  - **One session is not a hit rate.** This is evidence about ONE run by ONE agent against ONE app.
+ *    A hit rate is a distribution over many sessions; a single session quoted as one is an anecdote
+ *    with a denominator drawn on it.
+ *  - **Never-called is not useless.** A tool one team reaches for once a month in an emergency and a
+ *    tool nobody has ever called are the same zero here. Frequency alone cannot separate them, so a
+ *    cut decided on frequency alone will delete the wrong things.
+ *  - **Absent is not zero.** A session with no ledger reports `observed: false`. It has not
+ *    established that no tools were called; it has established that nothing was watching.
+ *  - The tools that ran BEFORE this instrument existed in the process, or against a session this
+ *    daemon adopted after the fact, are simply missing rather than counted low.
+ */
+/** How an agent could have reached a tool. Derived from the surface sets — see above. */
+export const ToolTier = {
+    /** Advertised directly on the surface every user gets. */
+    DEFAULT: 'default',
+    /** Advertised only when the full schema-carrying surface is switched on. */
+    EXTENDED: 'extended',
+    /** Advertised nowhere: reachable only by naming it to `reticle_run`. */
+    RUN_ONLY: 'run-only',
+};
+/** Which surface would have put this tool in front of an agent, read off that surface's own set. */
+export function tierOfTool(tool) {
+    if (CORE_TOOL_NAMES.has(tool))
+        return ToolTier.DEFAULT;
+    if (EXTENDED_TOOL_NAMES.has(tool))
+        return ToolTier.EXTENDED;
+    return ToolTier.RUN_ONLY;
+}
+function tally(tools) {
+    return {
+        default: tools.filter((tier) => ToolTier.DEFAULT === tier).length,
+        extended: tools.filter((tier) => ToolTier.EXTENDED === tier).length,
+        runOnly: tools.filter((tier) => ToolTier.RUN_ONLY === tier).length,
+    };
+}
+/**
+ * Cross one session's per-tool counts with the tool table.
+ *
+ * `allTools` is the DISPATCHABLE table — the names `reticle_run` will accept — passed in rather than
+ * imported, because the table is assembled in the module that owns this tool and importing it back
+ * would close a cycle. A tool counted but absent from the table still appears, so a name the table
+ * lost is visible rather than dropped.
+ */
+export function foldToolHitRate(input) {
+    const { calls } = input;
+    if (calls === undefined)
+        return { observed: false };
+    const called = [...calls]
+        .map(([tool, count]) => ({ tool, tier: tierOfTool(tool), calls: count }))
+        .sort((a, b) => b.calls - a.calls || a.tool.localeCompare(b.tool));
+    const neverCalled = input.allTools
+        .filter((tool) => !calls.has(tool))
+        .map((tool) => ({ tool, tier: tierOfTool(tool) }))
+        .sort((a, b) => a.tool.localeCompare(b.tool));
+    return {
+        observed: true,
+        cells: {
+            called: tally(called.map((entry) => entry.tier)),
+            neverCalled: tally(neverCalled.map((entry) => entry.tier)),
+        },
+        called,
+        neverCalled,
+    };
+}