@reticlehq/server 3.3.0 → 3.5.0

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 ' +
@@ -293,8 +293,7 @@ const RULES = [
     { match: /contenteditable/i, hint: RECOVERY.UNSUPPORTED_SURFACE },
     { match: /cannot hover without a real pointer/i, hint: RECOVERY.HOVER_NEEDS_POINTER },
     { match: /cannot \w+ a (disabled|readonly) </i, hint: RECOVERY.NOT_EDITABLE },
-    // Three spellings ship — "action", "native action", "WebMCP tool" — and the rule matched one, so
-    // two thirds of the same deliberate refusal still read as a possible defect.
+    // Both "action" and "native action" refusals need the same confirmation guidance.
     {
         match: /potentially destructive (?:\w+ )*(?:action|tool) blocked/i,
         hint: RECOVERY.CONFIRM_DANGEROUS,
@@ -495,7 +494,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';
@@ -18,10 +18,11 @@ import { buildDomainModel } from '../../judgement/domain/domain-model.js';
 import { readContract } from '../../memory/project/dir/reticle-dir.js';
 import { sessionRoot } from '../../memory/project/session-root.js';
 import { buildHarnessPlan, planAsText } from './harness-plan.js';
-import { openAiDriver, openAiOptionsFromEnv } from '../../features/harness/openai-driver.js';
+import { openAiDriver, openAiOptionsFromEnv, } from '../../features/harness/openai-driver.js';
 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,7 +412,12 @@ 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 }),
+            // GPT first: a linked machine reaches it through the platform with no key of its own.
+            ...(openAiOptionsFromEnv(env) === undefined
+                ? {}
+                : { openai: openAiOptionsFromEnv(env) }),
             ...(harnessOptionsFromEnv(env) === undefined
                 ? {}
                 : { generator: harnessOptionsFromEnv(env) }),

package/dist/surface/tools/invoke-tool.js

@@ -351,9 +351,6 @@ export async function runTool(tool, deps, args) {
     // closure carries this call's own identity, which is also what makes peak-concurrency measurable.
     // A daemon that has served even one tool call is doing a job for somebody; see daemon-usefulness.
     noteToolCall();
-    // The ONBOARD firsts, at the chokepoint every call already passes through — so a second dispatch
-    // path cannot quietly stop reporting them the way an extra listener would.
-    noteOnboardingFirst(tool.name);
     // The impact record needs the project's own `.reticle` root, and this is the first place every
     // call knows it. Idempotent: the first root wins for the daemon's lifetime.
     initImpact({ reticleRoot: deps.reticleRoot });
@@ -385,10 +382,6 @@ export async function runTool(tool, deps, args) {
     // page and then wandered off" becomes a number instead of an impression.
     if (ACTION_TOOLS.has(tool.name)) {
         getSessionMetrics().recordAction();
-        // The two funnel rungs this branch is the authority on: the first action of the run, and the
-        // fact that this install has been driven at all. Reported from the set that already decides
-        // what "drove the page" means, so a fourth driving tool inherits both.
-        noteActed(args);
     }
     const settleTiming = getSessionMetrics().startToolCall(tool.name, args);
     const startedAt = Date.now();
@@ -533,6 +526,17 @@ export async function runTool(tool, deps, args) {
         // concurrency slot and peakConcurrentTools would climb forever on an unhealthy session.
         settleTiming(Date.now() - startedAt);
     }
+    // Milestones describe work that ran. Refusals and paused calls must not consume the firsts.
+    // Record action before verdict: act_and_wait can complete both in this same call.
+    if (isPlainObject(raw) && !resultIsError(raw) && raw['paused'] !== true && raw['ok'] !== false) {
+        noteOnboardingFirst(tool.name);
+        const effect = raw['effect'];
+        const acted = raw['dispatched'] !== false &&
+            (!isPlainObject(effect) || effect['dispatched'] !== false) &&
+            (tool.name !== ReticleTool.ACT_AND_WAIT || isPlainObject(effect));
+        if (ACTION_TOOLS.has(tool.name) && acted)
+            noteActed(args);
+    }
     // The human-feedback ask rides out on the first VERIFICATION that completes — the one moment the
     // experience is fresh and there is something concrete to react to. It is spliced BEFORE the
     // session-bound early return, because two of the four verification tools (flow_verify,
@@ -584,7 +588,7 @@ export async function runTool(tool, deps, args) {
     // reticle_sessions.versionSkew and a CLI log line — two places an agent driving a flow never
     // looks — so it could work a whole session against a mismatched pair and never learn the one fact
     // that explains the behaviour. It rides out here on whatever tool it happens to be calling.
-    const skew = isPlainObject(raw) ? takeVersionSkew() : undefined;
+    const skew = isPlainObject(raw) ? takeVersionSkew(deps.peerSkew) : undefined;
     // A feedback report that was accepted and then failed to send. Same one-shot channel, because the
     // reporter is the only person who can act on it and they are not reading the daemon log — and a
     // report announced as accepted and then silently lost is the failure the awaited send existed to

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/tool-kit.d.ts

@@ -59,6 +59,16 @@ export interface ToolDeps<Ext = unknown> {
      * `tools.ts`, which keeps every existing `ToolDeps` construction working unchanged.
      */
     snapshots?: SnapshotCache;
+    /**
+     * The skew between THIS client's MCP server and the daemon, told once to this connection only.
+     *
+     * Per attach for the same reason as `snapshots`: one daemon serves every agent on the machine, and
+     * a daemon-wide queue handed one agent's "restart your MCP server" to whichever agent called next,
+     * whose server matched (#1136). Absent ⇒ this connection's server matched, or it did not announce.
+     */
+    peerSkew?: {
+        take(): string | undefined;
+    };
     /** cross-run outcome memory (.reticle/project.json). */
     project: ProjectStore;
     /** optional native-input provider. undefined ⇒ everything stays synthetic. */

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

@@ -27,7 +27,7 @@ import { ActionType, FeedbackKind, QueryBy, SnapshotMode } from '@reticlehq/core
 const SAFE_ENUM_PARAMS = new Map([
     // Every entry DERIVED from the enum core already owns, never hand-listed. The first version listed
     // them literally and was wrong on the day it shipped, not merely at risk: `action` was missing
-    // `fill`, `dblclick`, `submit`, `scrollIntoView`, `drag` and `webmcp` — so `fill`, one of the most
+    // `fill`, `dblclick`, `submit`, `scrollIntoView` and `drag` — so `fill`, one of the most
     // common actions there is, silently reported as `other` — while carrying a `scroll` that
     // `ActionType` does not define. `mode` mixed SnapshotMode with unrelated session-lifecycle values.
     // Deriving is not tidiness here; it is the difference between the data being right and being wrong.
@@ -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/telemetry/onboarding-firsts.d.ts

@@ -1,9 +1,9 @@
-/** A tool call the daemon just ran. Called from the dispatch chokepoint, which sees every one. */
+/** A successful page read. The dispatcher calls this after excluding refusals and pauses. */
 export declare function noteOnboardingFirst(toolName: string): void;
 /**
  * The first ACTION of this run, and the fact that this install has been driven at all.
  *
- * Called from the dispatch chokepoint's own action branch rather than matched on a tool name here.
+ * Called after the dispatcher observes a dispatched action, rather than on an attempted call.
  * The name test was `toolName === ReticleTool.ACT`, on the worry that `act_and_wait` would report
  * one call as two different firsts — and the worry was backwards: this server's instructions tell
  * every agent to PREFER `act_and_wait`, so the step measured the tool we ask agents not to use and

package/dist/telemetry/onboarding-firsts.js

@@ -15,7 +15,7 @@ import { reportOnboardingStep } from './onboarding-funnel.js';
  * drives in another has still only crossed each of these once.
  */
 const seen = { look: false, act: false, verdict: false, driven: false };
-/** A tool call the daemon just ran. Called from the dispatch chokepoint, which sees every one. */
+/** A successful page read. The dispatcher calls this after excluding refusals and pauses. */
 export function noteOnboardingFirst(toolName) {
     if (!seen.look && LOOK_TOOLS.has(toolName)) {
         seen.look = true;
@@ -29,7 +29,7 @@ export function noteOnboardingFirst(toolName) {
 /**
  * The first ACTION of this run, and the fact that this install has been driven at all.
  *
- * Called from the dispatch chokepoint's own action branch rather than matched on a tool name here.
+ * Called after the dispatcher observes a dispatched action, rather than on an attempted call.
  * The name test was `toolName === ReticleTool.ACT`, on the worry that `act_and_wait` would report
  * one call as two different firsts — and the worry was backwards: this server's instructions tell
  * every agent to PREFER `act_and_wait`, so the step measured the tool we ask agents not to use and

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 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,13 +20,12 @@ 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 |  |
 | `upload` | `{ content?, name?, type?, path? }` | Sets a file on `<input type="file">`. Inline bytes default to `"reticle test file"` / `"file.txt"` / `"text/plain"`. `path` reads a file from disk, scoped to the project root plus any opt-in directories listed in `.reticle.json` as `"uploadRoots": ["~/Downloads", "/Volumes/fixtures"]`. A refusal names every allowed root. |
 | `drag` | `{ toRef }` | Pointer-based drag (dnd-kit, react-beautiful-dnd) plus HTML5 DnD. `target` is an alias |
-| `webmcp` | `{ tool, params }` | Calls a `navigator.modelContext` tool, if the site exposes one |
 
 ### Arguments that are not actions
 
@@ -93,7 +92,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)