@reticlehq/server 2.11.0 → 2.13.0

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

@@ -5,30 +5,232 @@
  * 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`), resolved
+ * through `realpath` so symlinks cannot escape it. 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 } from '@reticlehq/core';
-import { isPointerAction } from '../input/real-input.js';
+import { ActionType, InputModeReason, ReticleCommand, TRANSPORT_LIMITS } from '@reticlehq/core';
+import { boxCenter, isPointerAction } from '../input/real-input.js';
 import { assertDragNotDestructive, assertNotDestructive } from './act-danger.js';
 import { NATIVE_INPUT_ARG } from '@reticlehq/core';
 import { asString, asRecord } from './tools-helpers.js';
 import { commandOrThrow } from './tool-kit.js';
 import { asBox } from './act-helpers.js';
+import { isAbsolute, join, relative, extname, basename } from 'node:path';
+/**
+ * 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);
+/**
+ * Resolve and validate a caller-supplied upload path.
+ *
+ * 1. 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.
+ * 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) {
+    const abs = isAbsolute(rawPath) ? rawPath : join(projectRoot, rawPath);
+    // 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 rel = relative(projectRoot, real);
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw new Error(`upload path '${rawPath}' resolves to '${real}', which is outside the project root ` +
+            `'${projectRoot}' — only files within the project directory may be uploaded. ` +
+            'Use a path relative to the project root, or an absolute path inside it.');
+    }
+    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) {
+    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 = join(deps.reticleRoot, '..');
+    // Blocker 4 fix: stat FIRST, before allocating read buffer, so a huge file fails fast.
+    const realPath = await resolveUploadPath(rawPath, projectRoot, deps.fs);
+    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
@@ -45,6 +247,12 @@ export async function tryRealInput(deps, session, ref, action, args) {
     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 });
@@ -83,6 +291,8 @@ export async function tryRealInput(deps, session, ref, action, args) {
         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,

package/dist/tools/reconcile-tools.js

@@ -1,11 +1,13 @@
 import { z } from 'zod';
-import { EventType, ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { EventType, ReticleCommand, SnapshotMode, urlForMatch } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
+import { cursorSchema } from './numeric-bounds.js';
 import { reconcile } from '../events/reconcile.js';
 import { salvageJson } from '../events/json-salvage.js';
 import { withControl } from '../session/control-envelope.js';
 import { asNumber, asString } from './tools-helpers.js';
 import { sessionIdShape, commandOrThrow } from './tool-kit.js';
+import { readCompleteTree } from './complete-snapshot.js';
 /**
  * Does the screen agree with the data the app was given?
  *
@@ -28,7 +30,7 @@ async function capturedBodies(session, since, urlContains) {
     for (const event of events) {
         if (event.type !== EventType.NET_REQUEST)
             continue;
-        const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
+        const url = urlForMatch(event.data);
         if (urlContains !== undefined && !url.includes(urlContains))
             continue;
         total += 1;
@@ -54,8 +56,7 @@ export const RECONCILE_TOOLS = [
         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: z
-                .number()
+            since: cursorSchema
                 .optional()
                 .describe('Cursor from a prior act — scopes to responses received after it. Default: 0.'),
             urlContains: z
@@ -88,11 +89,24 @@ export const RECONCILE_TOOLS = [
                         : `${String(total)} response(s) matched but NONE carried a recorded body, so nothing was compared. Enable it where your app calls connect(): \`reticle.connect({ captureNetworkBodies: true })\`, then re-run`,
                 });
             }
-            const snapshot = await commandOrThrow(deps, session.id, ReticleCommand.SNAPSHOT, {
+            // 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,
-            });
-            const tree = snapshot.tree;
-            const mismatches = reconcile(bodies, 'string' === typeof tree ? tree : '');
+                ...(scope === undefined ? {} : { scope, includeRoot: true }),
+            }));
+            const mismatches = reconcile(bodies, page.tree);
+            // 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.
+            if (0 === mismatches.length && !page.complete) {
+                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.

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

@@ -1,10 +1,3 @@
-/** 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';

package/dist/tools/sdk-marker-probe.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Did the document this app served carry any Reticle at all?
+ *
+ * `LeaseEvidence.sdkMarker` was read in two places and set by nothing, so the clause that
+ * distinguishes "installed but not connecting" from "never installed" could never fire. That
+ * distinction is the whole difference between the diagnosis a new user needs and the four causes
+ * they were getting, every one of which presupposes the SDK is already there.
+ *
+ * The probe is a plain GET of the page that was just loaded, so it costs one localhost round trip on
+ * a path that has already failed and is about to print a paragraph.
+ *
+ * ## Every uncertainty resolves to silence, on purpose
+ *
+ * `true` requires the EXACT marker the Vite plugin injects into `<head>` of every served document —
+ * a constant this repo already owns, so there is no new contract and no guessing.
+ *
+ * `false` requires the served document to contain no `reticle` anywhere, in any case. That is the
+ * only evidence strong enough to say "this app ships no SDK", and it is deliberately harder to earn
+ * than `true` is: a false `false` accuses a working install, and a false `true` SUPPRESSES the one
+ * instruction an uninstrumented user needs. Both are worse than saying nothing.
+ *
+ * Anything else — a fetch that failed, a timeout, a document that mentions Reticle without the
+ * marker (a Next or Babel install, where the SDK arrives through a module and never touches the
+ * HTML) — returns `undefined`, and the hint says nothing about markers at all.
+ */
+/** Pure: the verdict for a document body we managed to read. Exported so the rule is testable. */
+export declare function readSdkMarker(body: string): boolean | undefined;
+/** Never throws, never hangs. A probe that can break the diagnosis is worse than no probe. */
+export declare function probeSdkMarker(url: string): Promise<boolean | undefined>;

package/dist/tools/sdk-marker-probe.js

@@ -0,0 +1,57 @@
+/**
+ * Did the document this app served carry any Reticle at all?
+ *
+ * `LeaseEvidence.sdkMarker` was read in two places and set by nothing, so the clause that
+ * distinguishes "installed but not connecting" from "never installed" could never fire. That
+ * distinction is the whole difference between the diagnosis a new user needs and the four causes
+ * they were getting, every one of which presupposes the SDK is already there.
+ *
+ * The probe is a plain GET of the page that was just loaded, so it costs one localhost round trip on
+ * a path that has already failed and is about to print a paragraph.
+ *
+ * ## Every uncertainty resolves to silence, on purpose
+ *
+ * `true` requires the EXACT marker the Vite plugin injects into `<head>` of every served document —
+ * a constant this repo already owns, so there is no new contract and no guessing.
+ *
+ * `false` requires the served document to contain no `reticle` anywhere, in any case. That is the
+ * only evidence strong enough to say "this app ships no SDK", and it is deliberately harder to earn
+ * than `true` is: a false `false` accuses a working install, and a false `true` SUPPRESSES the one
+ * instruction an uninstrumented user needs. Both are worse than saying nothing.
+ *
+ * Anything else — a fetch that failed, a timeout, a document that mentions Reticle without the
+ * marker (a Next or Babel install, where the SDK arrives through a module and never touches the
+ * HTML) — returns `undefined`, and the hint says nothing about markers at all.
+ */
+import { RETICLE_RENDER_PREHOOK } from '@reticlehq/core';
+/** A page that has not answered in this long is not going to inform a diagnosis. */
+const PROBE_TIMEOUT_MS = 1_500;
+/** Enough of the document to carry a head-prepended script; a whole SPA bundle is not wanted. */
+const PROBE_MAX_BYTES = 200_000;
+/** Pure: the verdict for a document body we managed to read. Exported so the rule is testable. */
+export function readSdkMarker(body) {
+    if (body.includes(RETICLE_RENDER_PREHOOK))
+        return true;
+    // Case-insensitive and deliberately broad: ANY mention is enough to withhold the accusation.
+    if (!/reticle/i.test(body))
+        return false;
+    return undefined;
+}
+/** Never throws, never hangs. A probe that can break the diagnosis is worse than no probe. */
+export async function probeSdkMarker(url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.text()).slice(0, PROBE_MAX_BYTES);
+        return readSdkMarker(body);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

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

@@ -26,7 +26,7 @@ interface SnapshotDelta {
     removedCount: number;
 }
 /** Where focus moved, when it moved. Absent fields mean nothing held focus on that side. */
-export interface FocusChange {
+interface FocusChange {
     from?: string;
     to?: string;
 }

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

@@ -56,6 +56,18 @@ export interface ToolDeps<Ext = unknown> {
      * exactly today's behaviour.
      */
     artifactRootFor?: (projectId: string | undefined) => ArtifactRoot;
+    /**
+     * A verification run just landed — wake cloud sync instead of waiting for its next tick.
+     *
+     * The run itself is pushed immediately on this path, but everything AROUND it — the impact
+     * counters, the flows it exercised, flake and intent — moves only on the timer. That is what
+     * produced a dashboard showing a fresh run beside stale numbers, which reads as a sync bug and is
+     * really just two different clocks. Waking the loop here makes the run and its context arrive
+     * together.
+     *
+     * Optional: absent ⇒ the timer alone, which is exactly today's behaviour.
+     */
+    onRunPersisted?: () => void;
     /**
      * This daemon's OWN project id, derived from the directory it was started in.
      *
@@ -130,6 +142,18 @@ export interface ToolDef<Ext = unknown> {
      */
     handler(deps: ToolDeps<Ext>, args: Record<string, unknown>): Promise<unknown>;
 }
+/**
+ * The optional inline intent, on every tool that draws a verdict.
+ *
+ * One field, carrying either prose or the id of an intent already declared, because the surface is
+ * the scarce thing and a second field for the reference case would double the cost of the idea to
+ * make one of its two uses marginally more explicit. Told apart by the ledger — see
+ * `intent/inline-intent.ts`.
+ *
+ * The first sentence is what a lean surface advertises, so it carries both readings; the rest is for
+ * the profiles that send the whole description.
+ */
+export declare const intentArg: z.ZodOptional<z.ZodString>;
 export declare const sessionIdShape: {
     sessionId: z.ZodOptional<z.ZodString>;
 };

package/dist/tools/tool-kit.js

@@ -7,6 +7,27 @@
 import { z } from 'zod';
 import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
 import { normalizeLines } from '../project/baselines.js';
+/**
+ * The optional inline intent, on every tool that draws a verdict.
+ *
+ * One field, carrying either prose or the id of an intent already declared, because the surface is
+ * the scarce thing and a second field for the reference case would double the cost of the idea to
+ * make one of its two uses marginally more explicit. Told apart by the ledger — see
+ * `intent/inline-intent.ts`.
+ *
+ * The first sentence is what a lean surface advertises, so it carries both readings; the rest is for
+ * the profiles that send the whole description.
+ */
+export const intentArg = z
+    .string()
+    .optional()
+    .describe('What this change is meant to make true — as a durable statement ABOUT THE PRODUCT, or the id of an intent you already declared. ' +
+    'Write it so a teammate who was not here understands it in six months: name the behaviour, not this run. ' +
+    'GOOD: "a filtered issue queue is a shareable link — the filter is in the URL". ' +
+    'BAD: "P1 step 5", "drive 2 of 2", "same as before the fix", "the board renders cleanly" — these name a session, ' +
+    'a step number or nothing checkable, and the person reading them later has none of that context. ' +
+    'This is shared memory: it is pooled per project and later agents read it back to avoid re-deriving what you just established. ' +
+    'Recorded in .reticle/intent.json, the same ledger reticle_intent writes, and marked proved by this verdict if it passes.');
 export const sessionIdShape = {
     sessionId: z
         .string()

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

@@ -47,9 +47,14 @@ export declare const ReticleTool: {
     readonly COVERAGE: "reticle_coverage";
     readonly VERIFY_CHANGE: "reticle_verify_change";
     /** Merged: change/flows/affected/coverage/crawl — "what is proved, and what is not". */
+    readonly INTENT: "reticle_intent";
+    /** what THIS run has established, proved, and not yet discharged — pulled when memory is gone. */
+    readonly CONTEXT: "reticle_context";
     readonly VERIFY: "reticle_verify";
     /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
     readonly PROJECT: "reticle_project";
+    /** The team's shared memory, read on demand — see memory/memory-tools.ts. */
+    readonly MEMORY: "reticle_memory";
     /** explicitly record a run outcome (the manual companion to auto-recording). */
     readonly RUN_RECORD: "reticle_run_record";
     /** capture a pixel screenshot (CDP/driven browser) →.reticle/visual/<name>.png. */

package/dist/tools/tool-names.js

@@ -48,9 +48,14 @@ export const ReticleTool = {
     COVERAGE: 'reticle_coverage',
     VERIFY_CHANGE: 'reticle_verify_change',
     /** Merged: change/flows/affected/coverage/crawl — "what is proved, and what is not". */
+    INTENT: 'reticle_intent',
+    /** what THIS run has established, proved, and not yet discharged — pulled when memory is gone. */
+    CONTEXT: 'reticle_context',
     VERIFY: 'reticle_verify',
     /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
     PROJECT: 'reticle_project',
+    /** The team's shared memory, read on demand — see memory/memory-tools.ts. */
+    MEMORY: 'reticle_memory',
     /** explicitly record a run outcome (the manual companion to auto-recording). */
     RUN_RECORD: 'reticle_run_record',
     /** capture a pixel screenshot (CDP/driven browser) →.reticle/visual/<name>.png. */

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

@@ -70,6 +70,45 @@ export declare const TOOL_SURFACE: {
      * supplies the evidence the surface would otherwise have to go and find.
      */
     readonly VERIFY: "verify";
+    /**
+     * EXPERIMENTAL, opt-in, and UNDER MEASUREMENT. Not a recommendation, and not on a path to becoming
+     * the default until it has a number of its own.
+     *
+     * It exists because of the finding recorded on VERIFY above, read forwards instead of backwards.
+     * That surface cut the bill 37% and TRIPLED false alarms, and the five new false alarms were not
+     * scattered: every one of them was a defect whose evidence lives in `reticle_state`,
+     * `reticle_network` or `reticle_observe`. So the token saving and the accuracy loss came from two
+     * different cuts, and only one of them has to be paid for. `lean` keeps every observation tool and
+     * cuts the rest.
+     *
+     * What stays, and why each one is not a candidate for removal:
+     *   SNAPSHOT / QUERY   look. Without them the agent cannot name an element it did not already know.
+     *   STATE / NETWORK / CONSOLE / OBSERVE   the four evidence tools. Dropping these is the MEASURED
+     *                      cause of the tripled false-alarm rate. They are the point of the profile.
+     *   ACT_AND_WAIT       the only tool that acts AND returns a verdict. Omitting `until` makes it
+     *                      act-then-settle, which is what `reticle_act` does, so `act` is redundant here.
+     *   ASSERT             the only way to get a verdict WITHOUT acting. `act_and_wait` requires an
+     *                      `action`, so this is a capability it genuinely cannot express, not a synonym.
+     *
+     * What goes, and what it costs (one `reticle_run` hop each — `unadvertisedToolHelp` hands the agent
+     * the exact call, so a dropped name never comes back as "not found"):
+     *   ACT                subsumed: `act_and_wait` with `until` omitted is act-then-settle.
+     *   WAIT_FOR           subsumed: `act_and_wait { until }` takes the same PredicateSchema.
+     *   ACT_SEQUENCE       batching is a cost optimisation on top of a surface built to be cheap.
+     *   NAVIGATE           once per run, not once per turn — the wrong thing to pay for every turn.
+     *   SESSIONS           the CLI answers this (`reticle status`) without spending any turn budget.
+     *   INSPECT            fix-side, not verdict-side: it is called once a bug is FOUND, so its hop is
+     *                      paid once per finding rather than once per turn. Nothing else maps a node to
+     *                      a source file, which is why it is a hop and not a deletion.
+     *   SESSION            the lease block and the pause hint name it in prose, which is what made it
+     *                      load-bearing on the default surface. Under a trimmed surface the
+     *                      unadvertised-tool help turns that into a working `reticle_run` call.
+     *   FEEDBACK           the one drop with a KNOWN CEILING: an unadvertised feedback channel collects
+     *                      little to nothing, so a long-lived profile must not ship without it. Acceptable
+     *                      only because this profile is opt-in and short-lived by construction; if it
+     *                      ever stops being an experiment, feedback comes back first.
+     */
+    readonly LEAN: "lean";
 };
 export type ToolSurface = (typeof TOOL_SURFACE)[keyof typeof TOOL_SURFACE];
 /**
@@ -79,8 +118,6 @@ 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.
  *
@@ -98,6 +135,17 @@ export declare const CORE_TOOL_NAMES: ReadonlySet<string>;
  * 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.
  *
+ * That is true of the COUNT cap and false of everything else, which is worth separating here before
+ * somebody reads it as "prose is free". Measured against two competitor MCP servers on the same
+ * agent loop: this server advertises the FEWEST tools of the three and ships the HEAVIEST schema
+ * block, and 83% of that weight is parameter descriptions, not tool descriptions. The block is
+ * re-sent every turn, so it is multiplied by turn count before one byte of evidence is counted, and
+ * it was most of the gap in that run.
+ *
+ * Which does NOT license trimming by eye. Those descriptions are what make a tool get called
+ * correctly, and one malformed call costs a whole extra turn — more than the bytes saved. The
+ * outcome to measure is turn count and error rate, not size.
+ *
  * 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.
@@ -113,11 +161,42 @@ export declare const CORE_TOOL_NAMES: ReadonlySet<string>;
  */
 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.
+ * The lean surface: look, observe, act-with-a-verdict, assert. Pinned by lean-surface.test.ts,
+ * because an experiment whose independent variable drifts mid-flight measures nothing. Every
+ * inclusion and every exclusion is argued at TOOL_SURFACE.LEAN.
+ *
+ * ## MEASURED: it is cheaper and less correct. Do not promote it to the default.
+ *
+ * Run as its own arm of the fix-and-verify benchmark — same five bugs, same model, same budget, the
+ * full surface as its control:
+ *
+ * | | full surface | lean |
+ * |---|---|---|
+ * | bugs fixed | **5/5** | **3/5** |
+ * | FALSE GREENS | **0** | **1** |
+ *
+ * The false green is the finding, and it is the first this benchmark has ever produced. On
+ * `broken-form-validation` the lean agent finished in SIX turns and 62k tokens — the cheapest cell
+ * of the whole run, a fifth of what the full surface spent — edited the file, took one snapshot,
+ * and ended with a hypothetical walkthrough: "Enter spaces + valid name -> spaces are trimmed,
+ * valid part is used. VERDICT: FIXED". The submit button was still enabled for a whitespace-only
+ * service. It reasoned about what its own code would now do instead of driving it, which is exactly
+ * the failure this product exists to catch, produced by our own surface.
+ *
+ * The other loss has the same root from the other side. On `cross-component-regression` the agent
+ * called `reticle_tools` three times and `reticle_run` eight, saying "since Reticle isn't
+ * connecting, let me see what reticle_tools offers" — it spent the run hunting for capabilities
+ * this surface does not advertise instead of using them, and never fixed the bug.
+ *
+ * That is the same result the `verify` surface already recorded — dropping the observation tools
+ * TRIPLED false alarms — arriving from the other direction: strip the surface and the agent stops
+ * verifying, then claims anyway. The known ceiling written here was that `reticle_feedback` goes
+ * uncollected. This is a bigger one and it was not predicted.
+ *
+ * It stays opt-in and it stays measured. The one thing it genuinely bought — the ceiling-bound cell
+ * halved, 30 turns to 14 — is not worth a verdict that lies, because the product is the verdict.
  */
-export declare const VERIFY_TOOL_NAMES: ReadonlySet<string>;
+export declare const LEAN_TOOL_NAMES: ReadonlySet<string>;
 /**
  * Which surface is live.
  *