@reticlehq/server 3.3.0 → 3.4.0

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

@@ -13,7 +13,7 @@ export const BROWSER_TOOLS = [
     {
         name: ReticleTool.NAVIGATE,
         example: { url: '/settings' },
-        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). `ok` means the navigation was DISPATCHED — the SDK is torn down by the navigation, so the page itself cannot report on it. The daemon then waits up to `timeout_ms` (default 5000) for the SDK to reconnect: `confirmed:true` with a new `sessionId` means the page arrived and you can act immediately. `confirmed:false` means it did not arrive within that window (reported as `waitedMs`) — the page may be slow, uninstrumented, or not there. A slow SPA can take 30-60s to reattach: raise `timeout_ms` rather than polling reticle_sessions.',
+        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). `ok` means the navigation was DISPATCHED — the SDK is torn down by the navigation, so the old page cannot report on it. The daemon then waits up to `timeout_ms` (default 5000) for the SDK to reconnect. `confirmed:true` with a `sessionId` means the requested page arrived and you can act immediately. `confirmed:false` with `landedOn` means the navigation arrived but the app landed at another URL, such as an authentication or route-guard redirect; use `landedOn` to understand where the browser actually ended up. `confirmed:false` without `landedOn` means the target was not observed within the wait window; a slow app may still be on its way, so increase `timeout_ms` when appropriate.',
         inputSchema: {
             url: z.string().optional().describe('The URL to navigate to. Omit when using reload.'),
             reload: z
@@ -38,6 +38,10 @@ export const BROWSER_TOOLS = [
             confirmed: z.boolean().optional(),
             /** The session the SDK reconnected as, when arrival was confirmed — it is a NEW id. */
             sessionId: z.string().optional(),
+            /**
+             * The URL where the navigated document landed when it differs from the requested target.
+             */
+            landedOn: z.string().optional(),
             /**
              * On confirmed:false — the budget (ms) that expired without the page coming back. Says which
              * of "Reticle stopped waiting" and "the page never came back" you are looking at.
@@ -58,6 +62,7 @@ export const BROWSER_TOOLS = [
                 // back past this point. Reported from the field as an assertion whose clauses all passed
                 // coming back `contradicted` by hundreds of 500s against resources that were already gone.
                 before.lastAct.markNavigated(before.elapsed());
+                deps.recordings.markNavigated();
                 await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
                     hard: true === args['hard'],
                 });
@@ -96,6 +101,7 @@ export const BROWSER_TOOLS = [
             // document just as thoroughly. `beginAction` attributes events to this action; it does not move
             // the window a later assert judges over, and those are two different jobs.
             session.lastAct.markNavigated(session.elapsed());
+            deps.recordings.markNavigated();
             try {
                 const result = (await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.NAVIGATE, { url }));
                 // `ok` is the browser accepting the instruction, not the page arriving — see navigate-result.
@@ -104,7 +110,13 @@ export const BROWSER_TOOLS = [
                 // reticle_sessions itself. A refusal skips the wait: there is nothing to wait FOR.
                 const timeoutMs = asNumber(args['timeout_ms']) ?? ARRIVAL_TIMEOUT_MS;
                 const arrival = true === result.ok
-                    ? await awaitArrival(deps.sessions, target, { navigatedId: session.id, priorIds }, timeoutMs)
+                    ? await awaitArrival(deps.sessions, target, {
+                        // Keep the original Session object and URL so arrival detection can distinguish
+                        // an in-progress navigation from a document that arrived somewhere else.
+                        navigatedSession: session,
+                        navigatedFrom: session.url,
+                        priorIds,
+                    }, timeoutMs)
                     : null;
                 return navigateResult(result, arrival, timeoutMs);
             }

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

@@ -10,6 +10,7 @@ import { ReticleTool } from '@reticlehq/core';
 import { asString } from '@reticlehq/core';
 import { exercisedCount } from './gaps/coverage-identity.js';
 import { commandOrThrow, sessionIdShape } from './tool-kit.js';
+import { foldAppCoverage } from '../../features/exhaust/app-coverage.js';
 /**
  * `reticle_coverage` — which interactive controls this session has driven, and which it has not.
  *
@@ -69,8 +70,17 @@ export function buildCoverageTools(toolNames) {
             name: ReticleTool.COVERAGE,
             description: 'Which interactive controls you have driven this session, and which you have NOT. Returns { total, exercised, untouched:[{ref,label}], alsoDroveGone? } over the controls currently on the page. Use it to decide whether verification is finished: an untouched list that still holds the controls your change affects means you are not done. This is about what you did not TOUCH — distinct from the `coverage` field on an action result, which reports what the layer could not SEE.',
             example: {},
-            inputSchema: { ...sessionIdShape },
+            inputSchema: {
+                app: z
+                    .boolean()
+                    .optional()
+                    .describe('Also fold into the app-wide ledger; returns `app.levels`.'),
+                ...sessionIdShape,
+            },
             outputSchema: {
+                // The app-wide ledger — see features/exhaust/ledger.ts. Loose: run-only, and the levels
+                // carry their own shape.
+                app: z.record(z.unknown()).optional(),
                 total: z.number(),
                 exercised: z.number(),
                 untouched: z.array(z.object({ ref: z.string(), label: z.string() })),
@@ -171,6 +181,22 @@ export function buildCoverageTools(toolNames) {
                     ...(regressed === undefined ? {} : { observabilityRegressed: regressed }),
                     featureUse,
                     toolHitRate,
+                    ...(true === args['app']
+                        ? {
+                            app: await foldAppCoverage({
+                                fs: deps.fs,
+                                reticleRoot: sessionRoot(deps, sessionId),
+                                seen: parseControls(tree).map((c) => c.label),
+                                session,
+                                now: deps.now,
+                                ...(deps.realInput?.takeCodeCoverage === undefined
+                                    ? {}
+                                    : {
+                                        takeCode: (url) => deps.realInput?.takeCodeCoverage?.(url) ?? Promise.resolve(undefined),
+                                    }),
+                            }),
+                        }
+                        : {}),
                 };
             },
         },

package/dist/surface/tools/error-recovery.js

@@ -67,7 +67,7 @@ export const RECOVERY = {
     UNKNOWN_SESSION: 'That sessionId is not connected. Call reticle_sessions for the current ids and retry with a valid one.',
     THROTTLED: 'The target tab is backgrounded/throttled, so actions may silently no-op. Ask the human to bring ' +
         'the tab to the front, or acquire a guaranteed scriptable context yourself with ' +
-        '`reticle_run { tool: "reticle_lease", action: "acquire", url }` (a human can equivalently run ' +
+        '`reticle_run { tool: "reticle_lease", args: { action: "acquire", url } }` (a human can equivalently run ' +
         '`reticle drive <url>`).',
     MISSING_BASELINE: 'That baseline does not exist yet. Call reticle_baseline { action: "list" } to see saved names, or ' +
         'reticle_baseline { action: "save", name } to capture one before diffing against it.',
@@ -159,7 +159,7 @@ export const RECOVERY = {
         'assert on the result instead of typing it. Known gap, already reported: no need to file it.',
     HOVER_NEEDS_POINTER: 'Hover needs a real pointer: a synthetic mouseover does not apply CSS :hover, and Reticle ' +
         'refuses rather than reporting the styles as applied. Acquire a tab with ' +
-        'reticle_run { tool: "reticle_lease", action: "acquire", url } — reticle_lease is not ' +
+        'reticle_run { tool: "reticle_lease", args: { action: "acquire", url } } — reticle_lease is not ' +
         'advertised under the default profile, so it is reached through reticle_run, not called ' +
         'directly — or ask the human to drive with `reticle drive` / RETICLE_CDP_URL. This is a ' +
         'deliberate refusal, not a defect: there is nothing to report.',
@@ -182,7 +182,7 @@ export const RECOVERY = {
     COMMAND_TIMEOUT: 'The page did not answer within the command window. That is a fact about the page, not a Reticle ' +
         'failure: check reticle_sessions for `throttled`/`stale` on this session — a backgrounded tab is ' +
         'throttled and may never answer, so ask the human to bring it to the front or drive your own ' +
-        'browser with reticle_run { tool: "reticle_lease", action: "acquire", url } — reticle_lease is ' +
+        'browser with reticle_run { tool: "reticle_lease", args: { action: "acquire", url } } — reticle_lease is ' +
         'not advertised under the default profile, so it is reached through reticle_run, not called ' +
         'directly. If the tab is in front, the page is busy or blocked (a long ' +
         'synchronous task, an alert/confirm dialog); reticle_console usually shows what it hit. Retry ' +
@@ -495,7 +495,7 @@ const INVALID_NAME_REJECTION = /^invalid (?:[a-z]+ )*name: /i;
  * us nothing new.
  */
 export const FEEDBACK_ASK = 'This error is not one Reticle recognizes, which means it may be a defect in Reticle rather than in ' +
-    'the app. If you believe Reticle misbehaved, call reticle_feedback with a root-cause analysis and ' +
+    'the app. If you believe Reticle misbehaved, call reticle_session { action: "feedback" } with a root-cause analysis and ' +
     'the call trace before moving on — that report is the only way this gets fixed.';
 /**
  * Build the tool-error payload spliced at the MCP boundary. `recovery` is added when the error is

package/dist/surface/tools/feedback-invite.js

@@ -36,12 +36,14 @@ export const FrictionKind = {
  * a run of three is where a deliberate retry becomes a loop.
  */
 const REPEAT_INVITE_AT = 3;
+/** The call that files feedback. The old `reticle_feedback` name only answers with a redirect. */
+const FEEDBACK_CALL = 'reticle_session { action: "feedback" }';
 const LINES = {
-    [FrictionKind.UNKNOWN_TOOL]: 'no such tool — reticle_feedback tells us what you expected it to do, which is how it gets built',
-    [FrictionKind.UNKNOWN_VERDICT]: 'Reticle could not tell what happened here. If you expected otherwise, reticle_feedback. An ' +
+    [FrictionKind.UNKNOWN_TOOL]: `no such tool — ${FEEDBACK_CALL} tells us what you expected it to do, which is how it gets built`,
+    [FrictionKind.UNKNOWN_VERDICT]: `Reticle could not tell what happened here. If you expected otherwise, ${FEEDBACK_CALL}. An ` +
         'unknown verdict is our defect, not yours',
-    [FrictionKind.REPEATING]: 'stuck on the same call? reticle_feedback — say what you were trying to do and it gets fixed',
-    [FrictionKind.REFUSED]: 'if that diagnosis was wrong or unhelpful, reticle_feedback — error messages are a product ' +
+    [FrictionKind.REPEATING]: `stuck on the same call? ${FEEDBACK_CALL} — say what you were trying to do and it gets fixed`,
+    [FrictionKind.REFUSED]: `if that diagnosis was wrong or unhelpful, ${FEEDBACK_CALL} — error messages are a product ` +
         'surface and we fix the ones that fail',
 };
 /**

package/dist/surface/tools/harness-explore.d.ts

@@ -98,8 +98,9 @@ export declare const MSG_NO_OPENAI_KEY: string;
  *
  * Resolved into the env rather than threaded through four call sites: the drivers and the
  * preference lookup all read an env record, and giving them a completed one leaves each of them
- * exactly as simple as it was. An EXPLICIT variable still wins — someone who exported a key meant
- * that key, and CI has no linked project to read.
+ * exactly as simple as it was. The key precedence is the resolver's, the same as sync's and the
+ * CLI's: the stored key for the link's host, else the exported one (which is how CI, with no
+ * keystore, gets here). An explicitly exported HOST still wins, so a proxy is not overridden.
  *
  * The credential arrives through `deps.linkedCloud`, a port, because resolving it here would make
  * the tool surface reach into `memory/cloud` — a reach the directory guard refused, correctly.

package/dist/surface/tools/harness-explore.js

@@ -7,7 +7,7 @@
  * nothing grades) but the flows that now exist on disk, because every future run replays those
  * deterministically with no model in the loop at all.
  */
-import { ReticleEnv, ReticleTool, apiKeyFrom, asRecord } from '@reticlehq/core';
+import { ReticleEnv, ReticleTool, cloudUrlFrom, asRecord } from '@reticlehq/core';
 import { projectForRoot } from '../../memory/project/project-for-root.js';
 import { harnessDriver, harnessOptionsFromEnv, } from '../../features/harness/driver.js';
 import { fillValues } from '../../features/harness/fill-values.js';
@@ -22,6 +22,7 @@ import { openAiDriver, openAiOptionsFromEnv } from '../../features/harness/opena
 import { fetchPlatformConfig } from '../../features/harness/platform-config.js';
 import { DEFAULT_MAX_STEPS, runHarness, } from '../../features/harness/harness.js';
 import { reticleToolset } from './harness-toolset.js';
+import { secretEnvKey } from '../../language/flows/flows.js';
 /**
  * Why the harness is unavailable, phrased as the way to make it available.
  *
@@ -53,15 +54,14 @@ const msgUnknownDriver = (asked) => `Unknown harness driver \`${asked}\`. Known
  *
  * Resolved into the env rather than threaded through four call sites: the drivers and the
  * preference lookup all read an env record, and giving them a completed one leaves each of them
- * exactly as simple as it was. An EXPLICIT variable still wins — someone who exported a key meant
- * that key, and CI has no linked project to read.
+ * exactly as simple as it was. The key precedence is the resolver's, the same as sync's and the
+ * CLI's: the stored key for the link's host, else the exported one (which is how CI, with no
+ * keystore, gets here). An explicitly exported HOST still wins, so a proxy is not overridden.
  *
  * The credential arrives through `deps.linkedCloud`, a port, because resolving it here would make
  * the tool surface reach into `memory/cloud` — a reach the directory guard refused, correctly.
  */
 export async function withLinkedCredential(deps, env) {
-    if (apiKeyFrom(env) !== undefined)
-        return env;
     try {
         const linked = await deps.linkedCloud?.();
         if (linked === undefined || null === linked)
@@ -69,7 +69,7 @@ export async function withLinkedCredential(deps, env) {
         return {
             ...env,
             [ReticleEnv.API_KEY]: linked.apiKey,
-            [ReticleEnv.CLOUD_URL]: env[ReticleEnv.CLOUD_URL] ?? linked.url,
+            [ReticleEnv.CLOUD_URL]: cloudUrlFrom(env) ?? linked.url,
         };
     }
     catch {
@@ -412,6 +412,7 @@ function buildDriver(env, maxSteps, plan, requested, fills) {
          * With no such key the label heuristic answers, exactly as it did before this existed.
          */
         fillValue: fillValues({
+            secret: (label) => env[secretEnvKey(label)],
             ...(fills === undefined ? {} : { cache: fills }),
             ...(harnessOptionsFromEnv(env) === undefined
                 ? {}

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

@@ -21,7 +21,7 @@ import { hasAnyAppConnectedBefore } from '../../memory/recall/prior/connection-m
 import { AGENT_DRIVING_ELSEWHERE, AGENT_DRIVING_HERE_AGAIN, watchersToNotify, } from '../../portal/session/lease-visibility.js';
 import { reticleStateHome } from '../../command/daemon/daemon.js';
 import { LeaseNotReadyReason, REDACTED_VALUE, RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT, ReticleCommand, SeedStorageSchema, scrubKnownSecrets, } from '@reticlehq/core';
-import { ReticleTool } from '@reticlehq/core';
+import { ReticleTool, SESSION_HEALTH } from '@reticlehq/core';
 import { asString } from '@reticlehq/core';
 import { chromiumHint } from '../../command/cli/doctor/browser/chromium-hint.js';
 /**
@@ -165,6 +165,10 @@ export function scrubSeedFromError(text, seed) {
     }
     return out;
 }
+/** True for a Playwright `storageState()` export (`{ origins: [...] }`), not our seed shape. */
+function looksLikeStorageStateExport(seed) {
+    return Array.isArray(seed?.origins);
+}
 /**
  * Turn a raw navigation failure (Playwright's `page.goto: net::ERR_… at <url>\nCall log:…`, often
  * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
@@ -494,8 +498,13 @@ export const LEASE_ACQUIRE_TOOL = {
         if (seedStorageArg !== undefined) {
             const parsed = SeedStorageSchema.safeParse(seedStorageArg);
             if (!parsed.success) {
-                const issuesMsg = scrubSeedFromError(parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join(', '), seedStorageArg);
-                throw new Error(`reticle_lease{action:"acquire"} seedStorage is invalid: ${issuesMsg}`);
+                const msg = scrubSeedFromError(parsed.error.issues
+                    .map((i) => (i.path.length > 0 ? `${i.path.join('.')}: ${i.message}` : i.message))
+                    .join(', '), seedStorageArg);
+                const hint = looksLikeStorageStateExport(seedStorageArg)
+                    ? 'This looks like a Playwright storageState() export ({ origins, cookies }); seedStorage takes { local?, session?, cookies? } (map origins[].localStorage into `local`).'
+                    : 'Expected { local?, session?, cookies? }.';
+                throw new Error(`reticle_lease{action:"acquire"} seedStorage is invalid: ${msg}. ${hint}`);
             }
             validatedSeed = parsed.data;
         }
@@ -699,9 +708,7 @@ const PREFER_EXISTING_NOTE = 'a non-leased tab for this app was already connecte
  * is the right trade for a broadcast and the wrong one here, where a single `[0]` is handed back as
  * "drive this instead". With `projectId` undefined — and it is an OPTIONAL argument that an
  * acquiring agent has no reason to pass — every non-leased session qualified and the answer was
- * whichever the map yielded first. Measured against a real daemon: leasing `localhost:4312`
- * recommended a Phanpy tab on `:5173`, so an agent that complied would have driven a different
- * application and reported a verdict about it.
+ * whichever the map yielded first: leasing `localhost:4312` recommended a tab on `:5173`, another app.
  *
  * So this narrows by the one thing a lease always knows: the ORIGIN it is being taken against.
  * `projectId` still narrows further when given. Nothing is recommended when nothing matches, which
@@ -718,6 +725,8 @@ function liveTabFor(deps, projectId, url) {
         const candidates = deps.sessions
             .all()
             .filter((session) => session.url !== undefined && originOf(session.url) === wanted)
+            // Nor a tab gone silent: one last heard from 105s earlier was named here and answered nothing.
+            .filter((session) => (session.lastSeenMs?.() ?? 0) <= SESSION_HEALTH.STALE_THRESHOLD_MS)
             .map((session) => ({ id: session.id, projectId: session.projectId }));
         return watchersToNotify(candidates, pool.leasedSessionIds(), projectId)[0];
     }

package/dist/surface/tools/live-call-text.js

@@ -38,7 +38,10 @@ const NO_TOOL_EQUIVALENT = [
         // \u2014 so the optional group could not match, the clause survived, and the replacement landed
         // inside the original quoting. What an agent read was the human-equivalent clause twice over,
         // with backticks nested three deep.
-        pattern: /`?reticle_run\s*\{\s*tool:\s*\\?"reticle_lease\\?"[^}]*\}`?(\s*\([^)]*\))?(\s*[-\u2014]+\s*reticle_lease is[^.]*\.)?/g,
+        // The body allows ONE nested object, because the call is `{ tool, args: { action, url } }`: the
+        // hint used to put `action` and `url` beside `tool`, which reticle_run refuses, and a `[^}]*\}`
+        // body stopped at the inner brace and left ` }` behind once the hint was corrected.
+        pattern: /`?reticle_run\s*\{\s*tool:\s*\\?"reticle_lease\\?"(?:[^{}]|\{[^{}]*\})*\}`?(\s*\([^)]*\))?(\s*[-\u2014]+\s*reticle_lease is[^.]*\.)?/g,
         instead: 'the CLI: `reticle open <url>` (a human can equivalently run `reticle drive <url>`)',
     },
     {

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

@@ -33,6 +33,7 @@ import { withControl } from '../../portal/session/control-envelope.js';
 import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { intentArg, sessionIdShape, commandOrThrow } from './tool-kit.js';
 import { gradeOfPredicate } from './assert/assert-grade.js';
+import { captureAssertion } from '../../language/flows/replay.js';
 /**
  * Evidence-completeness block: present on observe/network/console only when the ring buffer has
  * evicted events, so a "no such event" answer is distinguishable from "I dropped it" (issue #27).
@@ -302,7 +303,7 @@ export const OBSERVE_TOOLS = [
                 '{ net, urlContains|method|status|count|bodyMatches|bodyContains|requestBodyContains|requestBodyMatches } ' +
                 '{ state, path|equals } { route, pathname (exact) | contains (path+query+hash) } ' +
                 '{ element, testid|role|text } { text } { console, level|contains|absent } { animation, name } ' +
-                '{ settled } — combine with { allOf | anyOf | not }. Prefer a signal/net/state consequence ' +
+                '{ settled } { compare, left, right } — combine with { allOf | anyOf | not }. Prefer a signal/net/state consequence ' +
                 'over element/text presence.'),
             until: PredicateSchema.optional().describe("Alias for `predicate` (act_and_wait's name)."),
             timeout_ms: timeoutMsSchema
@@ -446,6 +447,13 @@ export const OBSERVE_TOOLS = [
             // destroys — see runs/run-context.ts. Recorded WITHOUT an attribution window: this tool drives
             // nothing, so no event it observed was caused by it.
             session.recordAction(ReticleTool.ASSERT, asRecord(args), verdictEffect);
+            // A passing check over the default window (since the last act) is proof of that act, so it
+            // joins that step in the recording — otherwise "act, then assert" saves a bare click. An
+            // explicit `since` may reach back past the last step, where replay would not find it. The
+            // store itself refuses when a navigation came after that step: see RecordingStore.markNavigated.
+            if (Verified.YES === decision['verified'] && args['since'] === undefined) {
+                captureAssertion(deps.recordings, predicate);
+            }
             return withControl(session, {
                 ...decision,
                 ...annotateStarvedFailure(session, verdict),

package/dist/surface/tools/tools.js

@@ -236,6 +236,10 @@ export const RAW_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('True when the page exceeded the snapshot cap. The tree is then a document-order PREFIX: an element being absent from it does NOT mean it is absent from the page.'),
+            // The refs a capped read never entered — re-read one with `scope`. Undeclared, a validating
+            // client stripped it, and a truncated tree arrived with no way to finish reading it.
+            unread: z.array(z.string()).optional(),
+            unreadOverflow: z.boolean().optional(),
             note: z
                 .string()
                 .optional()

package/dist/telemetry/argument-shape.d.ts

@@ -19,8 +19,6 @@
  * never quietly start forwarding free text.
  */
 export declare const OTHER_VALUE = "other";
-/** True for anything we are willing to report a value for. */
-export declare function isSafeEnumParam(name: string): boolean;
 /**
  * The reportable form of one parameter: `name` on its own, or `name:value` when the parameter is a
  * known enum. Never the raw value of anything else.

package/dist/telemetry/argument-shape.js

@@ -41,10 +41,6 @@ const SAFE_ENUM_PARAMS = new Map([
     ['level', new Set(['error', 'warn', 'info', 'log', 'debug'])],
 ]);
 export const OTHER_VALUE = 'other';
-/** True for anything we are willing to report a value for. */
-export function isSafeEnumParam(name) {
-    return SAFE_ENUM_PARAMS.has(name);
-}
 /**
  * The reportable form of one parameter: `name` on its own, or `name:value` when the parameter is a
  * known enum. Never the raw value of anything else.

package/dist/telemetry/error-class.d.ts

@@ -2,9 +2,8 @@
  * Whose defect was that tool error?
  *
  * `toolErrors` was one number covering three failures with three different fixes, so the top-line
- * count could be acted on only by unpacking `errors[]` by hand and reading the prose. Measured over
- * 2026-08-10/11: 60 `state`, 22 `refusal`, 20 `schema` (serialized zod arrays) and 20 stale refs.
- * Read as "126 tool errors" that hides the sixth of them where OUR schema failed to explain itself —
+ * count could be acted on only by unpacking `errors[]` by hand and reading the prose. Read as one
+ * number, it hides the share where OUR schema failed to explain itself (serialized zod arrays),
  * which is the only bucket we can fix by writing better descriptions.
  *
  * Classified from the message SHAPE, never stored raw: this returns a bucket, and the caller keeps

package/dist/telemetry/error-class.js

@@ -2,9 +2,8 @@
  * Whose defect was that tool error?
  *
  * `toolErrors` was one number covering three failures with three different fixes, so the top-line
- * count could be acted on only by unpacking `errors[]` by hand and reading the prose. Measured over
- * 2026-08-10/11: 60 `state`, 22 `refusal`, 20 `schema` (serialized zod arrays) and 20 stale refs.
- * Read as "126 tool errors" that hides the sixth of them where OUR schema failed to explain itself —
+ * count could be acted on only by unpacking `errors[]` by hand and reading the prose. Read as one
+ * number, it hides the share where OUR schema failed to explain itself (serialized zod arrays),
  * which is the only bucket we can fix by writing better descriptions.
  *
  * Classified from the message SHAPE, never stored raw: this returns a bucket, and the caller keeps

package/dist/telemetry/harness-drive.d.ts

@@ -2,5 +2,3 @@
 export declare function withHarnessDrive<T>(drive: () => Promise<T>): Promise<T>;
 /** True while a harness drive is in progress. */
 export declare function harnessDriving(): boolean;
-/** Tests only — a leaked span would mis-attribute every verdict after it. */
-export declare function resetHarnessDrive(): void;

package/dist/telemetry/harness-drive.js

@@ -33,7 +33,3 @@ export async function withHarnessDrive(drive) {
 export function harnessDriving() {
     return depth > 0;
 }
-/** Tests only — a leaked span would mis-attribute every verdict after it. */
-export function resetHarnessDrive() {
-    depth = 0;
-}

package/dist/wire-journal.d.ts

@@ -1,5 +1,6 @@
 import { Bridge } from './portal/bridge/bridge.js';
 import { FlowStore } from './language/flows/flows.js';
+import type { FlowFile } from '@reticlehq/core';
 import type { FileSystemPort } from './memory/project/fs/fs-port.js';
 import type { TapeStep } from './memory/journal/drive-flow.js';
 import type { OnboardingStep } from '@reticlehq/core/telemetry';
@@ -26,6 +27,8 @@ export declare function attachJournal(bridge: Bridge, deps: {
     /** Tell cloud sync a run landed, so it cycles instead of waiting for its timer. */
     onRunPersisted?: () => void;
     flows?: FlowStore;
+    /** Who is driving, stamped on each flow teardown saves. */
+    author?: () => FlowFile['author'];
     /** What this project is willing to keep — the `retain` block of its `.reticle.json`. */
     retain?: PruneWorkspaceOptions;
 }): void;

package/dist/wire-journal.js

@@ -65,6 +65,10 @@ export function attachJournal(bridge, deps) {
     // Teardown: flush the journal tail to disk + persist what this session learned.
     bridge.attachSessionEnd(makeSessionEnd({
         ...deps,
+        // A drive is saved in the session's own project, where replay will look for it.
+        ...(deps.flows === undefined
+            ? {}
+            : { flowsAt: (root) => new FlowStore(deps.fs, root, { now: Date.now }) }),
         ...(deps.retain === undefined ? {} : { retain: deps.retain }),
         // Retention runs from teardown, and it must not delete the journal of a session that is still
         // being written. The registry is the only thing that knows which those are.

package/dist/workspace-packages.d.ts

@@ -18,5 +18,3 @@
  * allowed to depend on anything, which is what makes them useful as fixtures.
  */
 export declare function publishedPackageDirs(): string[];
-/** The same list, as the last part of each path: `core`, `server`, `dom`, and so on. */
-export declare function publishedPackageNames(): string[];

package/dist/workspace-packages.js

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { basename, join } from 'node:path';
+import { join } from 'node:path';
 import { workspaceGlobs } from '../../scripts/check-boundaries.mjs';
 import { REPO_ROOT } from './machine/repo-root.js';
 /**
@@ -47,11 +47,3 @@ function collect(dir, levels, into) {
             collect(join(dir, entry.name), levels - 1, into);
     }
 }
-/** The same list, as the last part of each path: `core`, `server`, `dom`, and so on. */
-export function publishedPackageNames() {
-    // `basename`, not `split('/')`: these directories are built with `join`, so on Windows they hold
-    // backslashes and contain no forward slash at all — the split then returns the WHOLE ABSOLUTE
-    // PATH as the package name. Every caller comparing a name against a real one silently stops
-    // matching, which is the same defect that reported fourteen packages as uncovered.
-    return publishedPackageDirs().map((dir) => basename(dir));
-}

package/docs/README.md

@@ -13,8 +13,9 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | Page | What it answers |
 | --- | --- |
 | [quickstart.mdx](quickstart.mdx) | five minutes to a real verdict; every response on it was captured live |
-| [what-is-reticle.mdx](what-is-reticle.mdx) | the definition, what Reticle is NOT, and what it needs to run |
-| [why-reticle.mdx](why-reticle.mdx) | the false-green problem, the measured case, and where we lose |
+| [what-is-reticle.mdx](what-is-reticle.mdx) | the definition, where it fits beside other tools, and what it needs to run |
+| [why-reticle.mdx](why-reticle.mdx) | the false-green problem, the measured case, and what pairs well with it |
+| [use-cases.mdx](use-cases.mdx) | what people verify with it: agent-built changes, security behaviour, accessibility, performance, SEO basics, personas |
 | [install-agentic.mdx](install-agentic.mdx) | what `npx @reticlehq/server init` writes, and how to read its marks |
 | [install-manual.mdx](install-manual.mdx) | wiring the MCP server and SDK by hand, per agent and framework |
 | [skill-setup.md](skill-setup.md) | the setup half of SKILL.md: what to pass `init`, reading its report, and what to do when it cannot finish |
@@ -24,6 +25,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [capabilities.mdx](capabilities.mdx) | coverage, storage, fake clocks, crawl, visual diff, network mocking |
 | [recipes.mdx](recipes.mdx) | worked examples for real situations, with the response each returned |
 | [actions.mdx](actions.mdx) | every action and its arguments, including `press` and its history |
+| [environment.mdx](environment.mdx) | every environment variable Reticle reads, what it changes, and which process reads it |
 | [faq.mdx](faq.mdx) | production, frameworks, comparisons, and the honest limits |
 | [tools/overview.mdx](tools/overview.mdx) | the 18 advertised tools, the 30 in the cold tail, and why |
 | [tools/snapshot.mdx](tools/snapshot.mdx) | `reticle_look { action: "page" }`: three modes, from full tree to a 25-token route check |

package/docs/actions.mdx

@@ -5,7 +5,7 @@ description: Every action reticle_act and reticle_act_and_wait can perform, with
 icon: hand-pointer
 ---
 
-Every action Reticle can perform takes the same shape: a `ref` from [`reticle_snapshot`](/tools/snapshot) or [`reticle_query`](/tools/query), an `action` name, and an optional `args` object. The same seventeen actions are available on [`reticle_act`](/tools/act), which proves nothing, and on [`reticle_act_and_wait`](/tools/act-and-wait), which returns a verdict.
+Every action Reticle can perform takes the same shape: a `ref` from [`reticle_look { action: "page" }`](/tools/snapshot) or [`reticle_look { action: "find" }`](/tools/query), an `action` name, and an optional `args` object. The same seventeen actions are available on [`reticle_act`](/tools/act), which proves nothing, and on [`reticle_act_and_wait`](/tools/act-and-wait), which returns a verdict.
 
 ```json
 { "ref": "e104", "action": "fill", "args": { "value": "reticle" } }
@@ -20,7 +20,7 @@ Every action Reticle can perform takes the same shape: a `ref` from [`reticle_sn
 | `type` | `{ text }` | **Appends** to the current value |
 | `clear` | none | Empties an input |
 | `select` | `{ value }` | For `<select>` |
-| `check` / `uncheck` | none | Checkbox and radio |
+| `check` / `uncheck` | none | Checkbox and radio, or a `role="checkbox"`/`role="switch"` element (fails if `aria-checked` does not change) |
 | `submit` | none | Submits the element's `<form>` |
 | `press` | `{ text }` | The key **name**: `Escape`, `Tab`, `Enter` |
 | `scrollIntoView` | none |  |
@@ -93,7 +93,7 @@ Several actions in one round trip:
 ```
 
 <Warning>
-  [`reticle_act_sequence`](/tools/act-sequence) returns `ok: true` when the steps were
+  [`reticle_act { steps: [...] }`](/tools/act-sequence) returns `ok: true` when the steps were
   **dispatched**, not when they worked. Batch the setup, then prove the outcome with
   [`reticle_act_and_wait`](/tools/act-and-wait) on the final step.
 </Warning>

package/docs/agent-cheatsheet.md

@@ -4,7 +4,7 @@ description: 'One screen to get fluent: the look → act → observe → assert
 icon: bolt
 ---
 
-The loop is **look → act → observe → assert**, and only `reticle_act_and_wait` and `reticle_assert` produce a verdict. Reach for `reticle_act_and_wait({ ref, action, until })` first: it names the expected consequence before the action, which is the difference between a check and a rationalisation. `verified: "unknown"` is not a pass.
+The loop is **look → act → observe → assert**, and verdicts come from `reticle_act_and_wait`, `reticle_assert`, and `reticle_act { steps }` when a step declares `expect`. Reach for `reticle_act_and_wait({ ref, action, until })` first: it names the expected consequence before the action, which is the difference between a check and a rationalisation. `verified: "unknown"` is not a pass.
 
 One screen to get fluent. Reticle is the **proof layer for AI agents**: no screenshots, no vision model, evidence not prose. Everything below returns structured data. Full guide: [usage.md](usage.md).
 
@@ -17,7 +17,7 @@ One screen to get fluent. Reticle is the **proof layer for AI agents**: no scree
 | **observe** | `reticle_observe` / `reticle_assert { action: "wait" }` | Everything the app did after `since` / block until true. |
 | **assert** | `reticle_assert` | Evaluate a predicate → `{ pass, evidence, failureReason? }`. The end of every loop. |
 
-> **Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** Everything else moves or reads the app and proves nothing, so a drive ending without one of those two has no result however many tools it used. `reticle_act` is the tool agents reach for by habit and it catches nothing; `act_and_wait` is where defects actually surface. And `verified: "unknown"` is not a pass: it means Reticle drove the app and could not tell what happened. Report it as unknown.
+> **Verdicts come from `reticle_act_and_wait`, `reticle_assert`, and `reticle_act { steps }` when a step declares `expect`.** Everything else moves or reads the app and proves nothing, so a drive ending without a verdict has no result however many tools it used. `reticle_act` is the tool agents reach for by habit and it catches nothing; `act_and_wait` is where defects actually surface. And `verified: "unknown"` is not a pass: it means Reticle drove the app and could not tell what happened. Report it as unknown.
 
 `reticle_act` returns a `since` cursor; pass it to `reticle_observe({ since })` to scope the window. Elements are addressed by stable refs (`e7`) from `snapshot`/`query`; they re-resolve across re-renders.
 
@@ -125,9 +125,9 @@ Call an old name and you are told the new one. `reticle_tools` prints the live s
 
 - `reticle_verify`: **the only core tool that CONCLUDES.** `{ action:"crawl" }` drives every reachable control itself and reports the whole fault set in one call (destructive: it really clicks). `{ action:"flows" }` replays every saved flow with no model in the loop. Reach for it when you think you are done: every other tool here answers "here is more to look at".
 
-Not on this surface at all, and NOT reachable by any call from it: `reticle_capabilities` (the app's whole testable surface in one call), `reticle_domain` (learn the app + gaps), `reticle_baseline {action:"diff"}`, `reticle_project` (run history), `reticle_screenshot`, `reticle_visual_diff`, `reticle_storage`, `reticle_network_mock`, `reticle_clock`. They need a daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1`, which advertises the full table.
+Not on this surface at all, but one hop away: `reticle_run { tool, args }` calls any registered tool by name, advertised or not, and `reticle_tools { names: [...] }` loads its arguments. That reaches `reticle_capabilities` (the app's whole testable surface in one call), `reticle_domain` (learn the app + gaps), `reticle_baseline {action:"diff"}`, `reticle_project` (run history), `reticle_screenshot`, `reticle_visual_diff`, `reticle_storage`, `reticle_network_mock` and `reticle_clock`. A daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises them directly instead.
 
-**What the wider surface adds, if you start the daemon with `RETICLE_ADVERTISE_ALL_TOOLS=1`:** record/replay a journey (`reticle_record {action:"start"}/stop`, `reticle_replay`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_verify { action: "heal" }`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_explore` lists controls; `reticle_verify {action:"crawl"}` is now advertised directly, clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_look { action: "find" }` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, driven or leased), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session {action:"end"}` / `reticle_session {action:"resume"}` / `reticle_session {action:"messages"}`, and **`reticle_session {action:"review"}`** to drain + fix the bugs the human flagged from the panel).
+**What the wider surface adds, through `reticle_run` or advertised directly with `RETICLE_ADVERTISE_ALL_TOOLS=1`:** record/replay a journey (`reticle_record {action:"start"}/stop`, `reticle_replay`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_verify { action: "heal" }`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_explore` lists controls; `reticle_verify {action:"crawl"}` is now advertised directly, clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_look { action: "find" }` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, driven or leased), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session {action:"end"}` / `reticle_session {action:"resume"}` / `reticle_session {action:"messages"}`, and **`reticle_session {action:"review"}`** to drain + fix the bugs the human flagged from the panel).
 
 ## flows vs baselines vs project.json (the persistence layers)
 

package/docs/architecture.md

@@ -14,7 +14,7 @@ Reticle has three moving parts: a dev-only **SDK** inside your page that instrum
 
 Your app, in dev, embeds a tiny **SDK** that instruments the page (DOM, network, console, routing, framework state) and opens a WebSocket to a local **bridge**. The bridge runs inside the Reticle **server**, which also exposes an **MCP server**, the standard protocol AI agents speak.
 
-Your coding agent calls MCP tools (`reticle_query`, `reticle_act`, `reticle_assert`, …); the server turns them into commands over the WebSocket; the SDK executes them in the page and streams back structured events. The agent thus **looks, acts, observes, and asserts** on the real running app, never on a screenshot.
+Your coding agent calls MCP tools (`reticle_look { action: "find" }`, `reticle_act`, `reticle_assert`, …); the server turns them into commands over the WebSocket; the SDK executes them in the page and streams back structured events. The agent thus **looks, acts, observes, and asserts** on the real running app, never on a screenshot.
 
 ```mermaid
 flowchart LR
@@ -23,7 +23,7 @@ flowchart LR
     B["@reticlehq/browser<br/>SDK in your app<br/>(the DOM)"]
     D[(".reticle/<br/>flows · baselines<br/>runs · contract")]
 
-    A -- "MCP (stdio/SSE)<br/>reticle_query / act / assert" --> S
+    A -- "MCP (stdio/SSE)<br/>reticle_look / act / assert" --> S
     S -- "tool results" --> A
     S <-- "WebSocket<br/>commands / events" --> B
     S <--> D
@@ -37,7 +37,7 @@ Reticle is a pnpm + Turborepo monorepo. The split is not cosmetic: each boundary
 
 | Package | Runs in | Responsibility | Hard rule |
 | --- | --- | --- | --- |
-| `@reticlehq/core` | both | The **wire contract**: every constant + zod schema crossing any boundary | Depends only on `zod` |
+| `@reticlehq/core` | both | The **wire contract**: every constant + zod schema crossing any boundary | Depends only on `zod` and `open-verification` |
 | `@reticlehq/browser` | the browser | Instrument the page; execute commands; emit events | Never imports Node APIs |
 | `@reticlehq/server` | Node | The bridge, the MCP server, the `reticle` CLI, flow/run storage | Never imports DOM APIs |
 | `@reticlehq/react` | the browser | The SDK **kit** you install in a browser app: re-exports the browser sensor (so one install gives both `reticle` and `install`) and maps a DOM node → React component → source `file:line` | Core works without the source-mapping half |
@@ -59,8 +59,8 @@ The browser and server both import it; neither can invent a message the other do
 
 1. **Connect.** In dev, your app calls `reticle.connect({ session })`. The SDK opens a WebSocket to the bridge (`ws://localhost:4400/reticle` by default) and sends a `HELLO` carrying the session id, protocol version, and (if configured) a pairing token. Each browser tab uses `SESSION_AUTO` (a unique id), so multiple apps/tabs never collide.
 2. **Capture.** The SDK installs observers: a `MutationObserver` for DOM changes, wrappers around `fetch`/`XHR` for network, a console hook, a history hook for routing, and registries the app opts into (`registerStore`, `registerCapabilities`, `reticle.signal`). Events flow into a bounded **ring buffer**, so recent history is always available and memory is capped.
-3. **Look / act.** The agent calls an MCP tool. `reticle_query` finds an element by role/text/testid/ component and returns a stable **ref**. `reticle_act` dispatches an action against that ref and returns an **effect** report (did it land, did the DOM mutate, did focus move…). The server sends the command over the WebSocket; the SDK runs it and replies.
-4. **Observe.** After an action, the agent reads what happened with `reticle_network`, `reticle_console`, `reticle_state`, or the reaction digest from `reticle_act_and_wait`. The server pulls the relevant slice of the ring buffer (scoped to a cursor so stale events can't leak in) and returns a compact summary.
+3. **Look / act.** The agent calls an MCP tool. `reticle_look { action: "find" }` finds an element by role/text/testid/ component and returns a stable **ref**. `reticle_act` dispatches an action against that ref and returns an **effect** report (did it land, did the DOM mutate, did focus move…). The server sends the command over the WebSocket; the SDK runs it and replies.
+4. **Observe.** After an action, the agent reads what happened with `reticle_observe { action: "network" }`, `reticle_observe { action: "console" }`, `reticle_look { action: "state" }`, or the reaction digest from `reticle_act_and_wait`. The server pulls the relevant slice of the ring buffer (scoped to a cursor so stale events can't leak in) and returns a compact summary.
 5. **Assert.** `reticle_assert` (and a flow's declared `success`) evaluates a **predicate** over program truth (a network call that returned 200, a store value, a `signal` the app emitted), not just "an element exists." This is the difference between "looks done" and "is done."
 
 ---
@@ -87,7 +87,7 @@ The same verification runs over and over, every commit, every CI run. Reticle re
 
 ### 4. Dev-only, localhost-only, your app data stays local
 
-The SDK is tree-shaken out of production builds and connects only to a local bridge. The bridge binds to loopback by default; exposing it beyond localhost _requires_ a pairing token (the server refuses to bind a non-loopback host without one). Every environment variable that gates a security control is a single named constant, so a typo can't silently disable auth. Nothing from the app under test ever leaves your machine: no DOM, network, console, state, or source. The CLI reports anonymous, opt-out usage metrics only (a random id + event names like `invoke`/`session_start`; no code, no PII; see [telemetry](telemetry.md)); opt out with `reticle telemetry disable`, `RETICLE_TELEMETRY=0`, or `DO_NOT_TRACK=1`. The one thing that carries free text is feedback you or your agent deliberately send (`reticle feedback` / `reticle_feedback`). It is never collected passively, it is redacted before sending, and it is disabled separately with `RETICLE_FEEDBACK=0`.
+The SDK is tree-shaken out of production builds and connects only to a local bridge. The bridge binds to loopback by default; exposing it beyond localhost _requires_ a pairing token (the server refuses to bind a non-loopback host without one). Every environment variable that gates a security control is a single named constant, so a typo can't silently disable auth. Nothing from the app under test ever leaves your machine: no DOM, network, console, state, or source. The CLI reports anonymous, opt-out usage metrics only (a random id + event names like `invoke`/`session_start`; no code, no PII; see [telemetry](telemetry.md)); opt out with `reticle telemetry disable`, `RETICLE_TELEMETRY=0`, or `DO_NOT_TRACK=1`. The one thing that carries free text is feedback you or your agent deliberately send (`reticle feedback` / `reticle_session { action: "feedback" }`). It is never collected passively, it is redacted before sending, and it is disabled separately with `RETICLE_FEEDBACK=0`.
 
 ---