@reticlehq/server 3.1.0 → 3.2.0

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

@@ -5,7 +5,7 @@
  * without a circular import — `tools.ts` assembles the groups and re-exports `ToolDef`/`ToolDeps`.
  */
 import { z } from 'zod';
-import { ReticleCommand } from '@reticlehq/core';
+import { type ProjectId, ReticleCommand } from '@reticlehq/core';
 import type { SessionManager } from '../../portal/session/session-manager.js';
 import type { RealInputProvider } from '../../portal/input/real-input.js';
 import type { BaselineStore } from '../../memory/project/baselines.js';
@@ -33,6 +33,21 @@ export interface ToolDeps<Ext = unknown> {
     recordings: RecordingStore;
     /** on-disk anchored-flow store (.reticle/flows/). */
     flows: FlowStore;
+    /**
+     * The credential this machine already holds for the linked project, if it is linked.
+     *
+     * INJECTED rather than read here. `reticle link` files a project-scoped key in
+     * `~/.reticle/credentials.json`, and the harness needs it so that somebody who has signed in and
+     * linked is not also asked to export a key by hand. Resolving it inside the tool surface would
+     * make `tools` reach into `memory/cloud`, which the directory guard refused — and it was right
+     * to: this is a port, and the daemon already resolves exactly this for cloud sync.
+     *
+     * Absent ⇒ nothing is linked, or the caller is an embedder with no filesystem. Never an error.
+     */
+    linkedCloud?: () => Promise<{
+        url: string;
+        apiKey: string;
+    } | null>;
     /** structured annotations accumulating for the live recording. */
     annotations: AnnotationStore;
     /**
@@ -65,7 +80,7 @@ export interface ToolDeps<Ext = unknown> {
      * embedding this engine may not have a filesystem to search. Absent ⇒ `reticleRoot`, which is
      * exactly today's behaviour.
      */
-    artifactRootFor?: (projectId: string | undefined) => ArtifactRoot;
+    artifactRootFor?: (projectId: ProjectId | undefined) => ArtifactRoot;
     /**
      * A verification run just landed — wake cloud sync instead of waiting for its next tick.
      *
@@ -85,7 +100,7 @@ export interface ToolDeps<Ext = unknown> {
      * test construction of ToolDeps predates it. Absence means "cannot tell", which must never be
      * treated as a mismatch.
      */
-    projectId?: string;
+    projectId?: ProjectId;
     /** injected clock for the contract's generatedAt stamp. */
     now: () => number;
     /**

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

@@ -1,10 +1,12 @@
 /** Small pure helpers shared by the MCP tool handlers. */
-interface InteractiveItem {
-    ref: string;
-    desc: string;
-}
-/** Parse interactive elements (with refs) out of a snapshot tree for exploration. */
-export declare function parseInteractive(tree: string): InteractiveItem[];
+/**
+ * The argument a call names a tab with.
+ *
+ * A named constant because dispatch now WRITES this key as well as reading it — see `runTool`,
+ * which pins the session it resolved into the args the handler is given — and a key spelled at both
+ * ends of that can drift without anything saying so.
+ */
+export declare const SESSION_ID_ARG = "sessionId";
 /**
  * The session this call is aimed at: a top-level `sessionId`, or the same key on sequence steps.
  *
@@ -36,4 +38,3 @@ export declare function sourceOf(value: unknown): {
     line: number;
     column?: number;
 } | undefined;
-export {};

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

@@ -1,15 +1,13 @@
 import { asRecord, asString } from '@reticlehq/core';
-/** Parse interactive elements (with refs) out of a snapshot tree for exploration. */
-export function parseInteractive(tree) {
-    const items = [];
-    for (const line of tree.split('\n')) {
-        const match = /\(ref=(e\d+)\)/.exec(line);
-        if (match !== null) {
-            items.push({ ref: match[1] ?? '', desc: line.replace(/\s*\(ref=e\d+\)/, '').trim() });
-        }
-    }
-    return items;
-}
+/** Small pure helpers shared by the MCP tool handlers. */
+/**
+ * The argument a call names a tab with.
+ *
+ * A named constant because dispatch now WRITES this key as well as reading it — see `runTool`,
+ * which pins the session it resolved into the args the handler is given — and a key spelled at both
+ * ends of that can drift without anything saying so.
+ */
+export const SESSION_ID_ARG = 'sessionId';
 /**
  * The session this call is aimed at: a top-level `sessionId`, or the same key on sequence steps.
  *
@@ -21,7 +19,7 @@ export function parseInteractive(tree) {
  * Mixed step ids refuse rather than pick: two named tabs is a guess we will not make.
  */
 export function sessionIdFromArgs(args) {
-    const top = asString(args['sessionId']);
+    const top = asString(args[SESSION_ID_ARG]);
     if (top !== undefined)
         return top;
     const steps = args['steps'];
@@ -29,7 +27,7 @@ export function sessionIdFromArgs(args) {
         return undefined;
     let found;
     for (const raw of steps) {
-        const id = asString(asRecord(raw)['sessionId']);
+        const id = asString(asRecord(raw)[SESSION_ID_ARG]);
         if (id === undefined)
             continue;
         if (found !== undefined && found !== id) {

package/dist/surface/tools/tools.js

@@ -504,7 +504,12 @@ export const MERGE_PLANS = [
     },
     {
         name: ReticleTool.SESSION,
-        description: 'Session lifecycle and the human channel, by action: "tune" adjusts the presenter session (e.g. idle-end window); "yield" hands control back to the human between turns (mode: waiting|ask) and is MANDATORY before you stop driving; "end" terminates the session for good; "resume" clears a human pause; "messages" drains the human→agent inbox; "review" lists/resolves the mistakes a human pinned to elements; "narrate" states your intent on the presenter HUD.',
+        description: 
+        // `yield` leads, and that is not a style choice. A catalogue prints ONE line per tool, so
+        // whatever comes first is what an agent discovers; when this sentence opened with `tune` the
+        // MANDATORY handback sat past the cut and no agent reading the catalogue ever learned it
+        // existed. The rule is: if a tool has an obligation, the obligation goes first.
+        'Session lifecycle and the human channel, by action: "yield" hands control back to the human and is MANDATORY before you stop driving (mode: waiting|ask, between turns); "tune" adjusts the presenter session (e.g. idle-end window); "end" terminates the session for good; "resume" clears a human pause; "messages" drains the human→agent inbox; "review" lists/resolves the mistakes a human pinned to elements; "narrate" states your intent on the presenter HUD.',
         members: {
             tune: ReticleTool.SESSION_TUNE,
             yield: ReticleTool.YIELD,

package/dist/telemetry/bug-found.js

@@ -18,6 +18,12 @@ import { ReticleTool } from '@reticlehq/core';
 import { BugAttribution, BugSource, ContradictionKind, isAbsenceDerived, } from '@reticlehq/core';
 /** Cap per tool call — a pathological crawl must not turn one call into a thousand events. */
 const MAX_BUGS_PER_CALL = 25;
+/** The kinds in a replay's `regressed` list — bare strings, not the `{ kind }` objects above. */
+function regressedKinds(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((kind) => 'string' === typeof kind && kind.length > 0);
+}
 function kindsOf(value) {
     if (!Array.isArray(value))
         return [];
@@ -127,7 +133,12 @@ export function bugsInResult(toolName, result) {
     const verdict = verdictOf(result);
     const passed = true === verdict;
     // 1. Contradictions — channels disagreeing. Invisible to a human watching the screen.
-    for (const kind of kindsOf(result['contradictions'])) {
+    //
+    // `crossStep` is read alongside `contradictions` because a flow replay spells them that way: a
+    // step's window closes when the step ends, so a request fired at step 2 and still unanswered at
+    // step 5 sits outside every per-step window and is exactly the shape a long journey produces.
+    // Every whole-span contradiction a replay found was unreportable for want of this one name.
+    for (const kind of [...kindsOf(result['contradictions']), ...kindsOf(result['crossStep'])]) {
         // A contradiction is two of the APP's own channels disagreeing — never the agent's phrasing.
         // Omitted for the one kind Reticle can produce on its own: see contradictionAttribution.
         bugs.push({
@@ -176,7 +187,26 @@ export function bugsInResult(toolName, result) {
             attribution: BugAttribution.UNCLASSIFIED,
         });
     }
-    // 4. Replay failures — a saved flow that used to pass no longer does. That is a regression caught,
+    // 4. A guarded defect that came BACK. The flow observed it, then observed it gone, and the app
+    //    has now reacquired it — a claim no other detector in this file can make, because only a saved
+    //    flow carries what it has already seen. It is the replay feature's stated payoff and it was
+    //    counted nowhere: `regressed` is a list of KINDS, not of anomaly objects, so neither of the
+    //    array readers above could see it.
+    for (const kind of regressedKinds(result['regressed'])) {
+        bugs.push({
+            source: BugSource.REPLAY,
+            kind,
+            // The replay carries no assertion of its own, so there is no green for this to have hidden
+            // behind. Whether it was a false green is a question about the run that reacquired the defect,
+            // not about the run that noticed.
+            falseGreen: passed,
+            tool: toolName,
+            // Same kind, same owner, wherever it arrives — the line `attributionOf` draws is the one the
+            // verdict already uses, and a defect does not change whose fault it was by coming back.
+            attribution: attributionOf(kind),
+        });
+    }
+    // 5. Replay failures — a saved flow that used to pass no longer does. That is a regression caught,
     //    which is a different and stronger claim than "a check failed".
     if ('fail' === result['status'] && Array.isArray(result['failures'])) {
         for (const failure of result['failures'].slice(0, MAX_BUGS_PER_CALL)) {

package/dist/telemetry/feedback-context.js

@@ -78,9 +78,9 @@ export function detectStack(cwd, read = readFile) {
     }
     // Otherwise look for the app. The daemon's cwd is wherever the agent's client happened to launch,
     // which for a real repo is the ROOT while the app sits in `frontend/`, `web/`, or a declared
-    // workspace. Reading one directory and giving up is why this returned nothing for every project
-    // that actually had Reticle set up: 0 of 77 instrumented projects, and 0 of 166 `size: huge` ones.
-    // The bigger the repo, the more certainly we failed.
+    // workspace. Reading one directory and giving up is why this returned nothing for essentially
+    // every project that actually had Reticle set up, and why the bigger the repo, the more certainly
+    // we failed. (The measurement that established that came from the field and stays in `plan/`.)
     //
     // `findWorkspaceApps` is init's discovery, reused rather than reimplemented: it already reads
     // declared workspaces (pnpm-workspace.yaml, package.json `workspaces`) AND scans top-level

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

@@ -0,0 +1,6 @@
+/** Run `drive` with every verdict underneath it attributed to the harness. */
+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

@@ -0,0 +1,39 @@
+/**
+ * Whether the tool call running right now belongs to one of OUR drives.
+ *
+ * `reticle_verify { action: "explore" }` hands the app to a model inside the daemon, which drives
+ * through the same dispatch chokepoint every agent uses. That is the right design — the inner
+ * `act_and_wait` and `assert` calls are real verifications and must be counted — but it left every
+ * verdict a drive produced indistinguishable from one the user's own agent earned, under the same
+ * session and the same `actor: agent`. So "did this install ever verify anything by itself" had no
+ * answer, and any per-session rate read high by however much we drove.
+ *
+ * Module state, one flag, set for the span of the drive. The same one-hop pattern `tool-refused.ts`
+ * already uses for its pending reason, and for the same reason: the fact is produced in one place
+ * and needed in another, with a chokepoint in between that has no business taking an extra argument
+ * for a metric.
+ *
+ * A COUNTER rather than a boolean, so a drive nested inside a drive cannot clear the flag on its way
+ * out and leave the outer one unmarked.
+ */
+let depth = 0;
+/** Run `drive` with every verdict underneath it attributed to the harness. */
+export async function withHarnessDrive(drive) {
+    depth += 1;
+    try {
+        return await drive();
+    }
+    finally {
+        // In a `finally` because a drive that THREW still drove: leaving the flag raised would attribute
+        // the user's own next verdict to a harness that is no longer running.
+        depth -= 1;
+    }
+}
+/** True while a harness drive is in progress. */
+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/mcp-connection.d.ts

@@ -1,5 +1,18 @@
 export declare function markDaemonStart(now: number): void;
-/** Report one client attaching. Best-effort; a metric must never affect whether a client connects. */
+/**
+ * Report one client attaching, BY NAME. Best-effort; a metric must never affect whether a client
+ * connects.
+ *
+ * The name is required in practice, and that is the fix rather than a restriction. `connection.client`
+ * was defined and documented and never once populated: the only caller reported from
+ * `transport.connect().then(...)`, which resolves when the SSE stream opens — before the client has
+ * said who it is. `clientInfo` first exists at `oninitialized`, so the event carried every fact about
+ * the connection except the one that makes "which agent client converts best" answerable at all.
+ *
+ * An unnamed call reports NOTHING. A stream that opens and never completes a handshake is a probe,
+ * not a client attaching, and counting it was what put an unattributable row exactly where the name
+ * belonged.
+ */
 export declare function reportMcpConnected(client?: string, now?: () => number): void;
 /** Tests only. */
 export declare function resetMcpConnections(): void;

package/dist/telemetry/mcp-connection.js

@@ -19,8 +19,23 @@ export function markDaemonStart(now) {
     daemonStartedAt = now;
     connectsSeen = 0;
 }
-/** Report one client attaching. Best-effort; a metric must never affect whether a client connects. */
+/**
+ * Report one client attaching, BY NAME. Best-effort; a metric must never affect whether a client
+ * connects.
+ *
+ * The name is required in practice, and that is the fix rather than a restriction. `connection.client`
+ * was defined and documented and never once populated: the only caller reported from
+ * `transport.connect().then(...)`, which resolves when the SSE stream opens — before the client has
+ * said who it is. `clientInfo` first exists at `oninitialized`, so the event carried every fact about
+ * the connection except the one that makes "which agent client converts best" answerable at all.
+ *
+ * An unnamed call reports NOTHING. A stream that opens and never completes a handshake is a probe,
+ * not a client attaching, and counting it was what put an unattributable row exactly where the name
+ * belonged.
+ */
 export function reportMcpConnected(client, now = () => Date.now()) {
+    if (client === undefined)
+        return;
     try {
         const reconnect = connectsSeen > 0;
         connectsSeen += 1;
@@ -30,7 +45,7 @@ export function reportMcpConnected(client, now = () => Date.now()) {
                 // A large value on the FIRST connect is the interesting case: Reticle was started and then
                 // sat there. On a reconnect it is just how long the daemon has been up.
                 daemonAgeMs: daemonStartedAt === undefined ? 0 : Math.max(0, now() - daemonStartedAt),
-                ...(client !== undefined ? { client } : {}),
+                client,
                 // WHAT THE AGENT HAD TO LOOK AT. Most clients that attach never call a tool, and that cohort
                 // emits nothing at all — an agent that reads the instructions, learns nothing is wired and
                 // stops has refused nothing, so `tool_refused` cannot see it either. Read off the same flag

package/dist/telemetry/onboarding-firsts.d.ts

@@ -1,5 +1,21 @@
 /** A tool call the daemon just ran. Called from the dispatch chokepoint, which sees every one. */
-export declare function noteOnboardingFirst(toolName: string, args: Record<string, unknown>): void;
+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.
+ * 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
+ * the ONBOARD phase read as "looked, never acted, then produced a verdict from nowhere". A call that
+ * both acts and proves genuinely did both, and `first_act` and `first_verdict` are different steps
+ * in different positions of the same funnel.
+ *
+ * Taking the decision from the caller is what keeps it from happening again: the dispatcher already
+ * owns the set of tools that drive the page, and a second copy of that set here is a second thing to
+ * update when a fourth driving tool arrives.
+ */
+export declare function noteActed(args: Record<string, unknown>): void;
 /**
  * The first verdict of this run.
  *
@@ -7,5 +23,18 @@ export declare function noteOnboardingFirst(toolName: string, args: Record<strin
  * and only the site that already decided "this was a verification" can say so. Reported from there.
  */
 export declare function noteFirstVerdict(): void;
+/**
+ * Something was driven on the user's own project — the FIRST_RUN rung between "the install worked"
+ * and "they used it".
+ *
+ * Declared in the closed step list from the day the funnel was written and emitted by no code at
+ * all, so any chart rendered over the declared order showed a 100% cliff in the middle of the
+ * conversion story. It reads as catastrophe and was an unwired emit.
+ *
+ * Reported from `noteActed`, so the one place that knows a tool drove the page is the one place that
+ * says so. That includes a drive we run on the user's behalf, whose own actions cross the same
+ * chokepoint — a drive that is refused before its first action drove nothing and says nothing.
+ */
+export declare function noteDriven(): void;
 /** Arm again for the next daemon run — the tests' seam, mirroring resetAppInstrumented. */
 export declare function resetOnboardingFirsts(): void;

package/dist/telemetry/onboarding-firsts.js

@@ -14,9 +14,9 @@ import { reportOnboardingStep } from './onboarding-funnel.js';
  * The flags are module state rather than per-session, because a person who tours in one tab and
  * drives in another has still only crossed each of these once.
  */
-const seen = { look: false, act: false, verdict: false };
+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. */
-export function noteOnboardingFirst(toolName, args) {
+export function noteOnboardingFirst(toolName) {
     if (!seen.look && LOOK_TOOLS.has(toolName)) {
         seen.look = true;
         void reportOnboardingStep({
@@ -25,16 +25,35 @@ export function noteOnboardingFirst(toolName, args) {
             status: OnboardingStepStatus.COMPLETED,
         });
     }
-    // An ACT, not a verdict tool that happens to act: `act_and_wait` is counted below as the verdict
-    // it produces, and counting it here too would report one call as two different firsts.
-    if (!seen.act && toolName === ReticleTool.ACT && args['action'] !== ActionType.HOVER) {
-        seen.act = true;
-        void reportOnboardingStep({
-            phase: OnboardingPhase.ONBOARD,
-            step: 'first_act',
-            status: OnboardingStepStatus.COMPLETED,
-        });
-    }
+}
+/**
+ * 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.
+ * 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
+ * the ONBOARD phase read as "looked, never acted, then produced a verdict from nowhere". A call that
+ * both acts and proves genuinely did both, and `first_act` and `first_verdict` are different steps
+ * in different positions of the same funnel.
+ *
+ * Taking the decision from the caller is what keeps it from happening again: the dispatcher already
+ * owns the set of tools that drive the page, and a second copy of that set here is a second thing to
+ * update when a fourth driving tool arrives.
+ */
+export function noteActed(args) {
+    // A hover changes nothing and is not an action anybody drove.
+    if (args['action'] === ActionType.HOVER)
+        return;
+    noteDriven();
+    if (seen.act)
+        return;
+    seen.act = true;
+    void reportOnboardingStep({
+        phase: OnboardingPhase.ONBOARD,
+        step: 'first_act',
+        status: OnboardingStepStatus.COMPLETED,
+    });
 }
 /**
  * The first verdict of this run.
@@ -52,6 +71,28 @@ export function noteFirstVerdict() {
         status: OnboardingStepStatus.COMPLETED,
     });
 }
+/**
+ * Something was driven on the user's own project — the FIRST_RUN rung between "the install worked"
+ * and "they used it".
+ *
+ * Declared in the closed step list from the day the funnel was written and emitted by no code at
+ * all, so any chart rendered over the declared order showed a 100% cliff in the middle of the
+ * conversion story. It reads as catastrophe and was an unwired emit.
+ *
+ * Reported from `noteActed`, so the one place that knows a tool drove the page is the one place that
+ * says so. That includes a drive we run on the user's behalf, whose own actions cross the same
+ * chokepoint — a drive that is refused before its first action drove nothing and says nothing.
+ */
+export function noteDriven() {
+    if (seen.driven)
+        return;
+    seen.driven = true;
+    void reportOnboardingStep({
+        phase: OnboardingPhase.FIRST_RUN,
+        step: 'driven',
+        status: OnboardingStepStatus.COMPLETED,
+    });
+}
 /** Looking: the tools that read the page without changing it. */
 const LOOK_TOOLS = new Set([
     ReticleTool.SNAPSHOT,
@@ -64,4 +105,5 @@ export function resetOnboardingFirsts() {
     seen.look = false;
     seen.act = false;
     seen.verdict = false;
+    seen.driven = false;
 }

package/dist/telemetry/verification-of.js

@@ -10,9 +10,10 @@
  * Kept in one place, out of `runTool`, because a rule this easy to get wrong should be readable and
  * testable on its own rather than inferred from a ternary inside a dispatcher.
  */
-import { CaptureLoss, VerifiedReason } from '@reticlehq/core';
+import { CaptureLoss, ReplayStatus, ReticleTool, VerificationDriver, Verified, VerifiedReason, } from '@reticlehq/core';
 import { VERDICT_TOOLS } from '../surface/tools/feedback-tools.js';
 import { getBrowserMode } from './browser-mode.js';
+import { harnessDriving } from './harness-drive.js';
 /**
  * The deciding clause, read off the result `decideVerified` wrote it onto.
  *
@@ -51,6 +52,30 @@ const SuiteStatus = {
     PASS: 'pass',
     FAIL: 'fail',
 };
+/**
+ * A flow replay's verdict, in the vocabulary the rest of this file speaks.
+ *
+ * `ReplayStatus` spells itself `ok | drift | error`, so a reader looking for `pass`/`fail` found
+ * neither and every replay emitted nothing at all — on the tool documented as the single-flow
+ * companion to the whole-suite replay, i.e. a verdict in no numerator and no denominator.
+ *
+ * `error` maps to UNKNOWN rather than to a fail. It is the flow failing to LOAD or an action failing
+ * to run, which is Reticle not being able to tell — publishing that as the app's defect is exactly
+ * the mistake the suite reader made the first time.
+ *
+ * Read for the REPLAY TOOL ONLY. `ok` is not a verdict word anywhere else in this surface, and a
+ * merged action that happens to answer with one must not be counted as a verification it never made.
+ */
+const REPLAY_VERDICTS = new Map([
+    [ReplayStatus.OK, { verified: Verified.YES, passed: true }],
+    [ReplayStatus.DRIFT, { verified: Verified.NO, passed: false }],
+    [ReplayStatus.ERROR, { verified: Verified.UNKNOWN, passed: false }],
+]);
+function replayVerdict(toolName, status) {
+    if (ReticleTool.FLOW_REPLAY !== toolName || 'string' !== typeof status)
+        return undefined;
+    return REPLAY_VERDICTS.get(status);
+}
 /**
  * Did the assertion itself pass, across three tool shapes that spell it three ways.
  *
@@ -97,13 +122,14 @@ export function verificationOf(toolName, result, durationMs, brand) {
     // here for work that happened.
     if (true === result['paused'])
         return undefined;
-    const verified = 'string' === typeof result['verified'] ? result['verified'] : undefined;
+    const replay = replayVerdict(toolName, result['status']);
+    const verified = 'string' === typeof result['verified'] ? result['verified'] : (replay?.verified ?? undefined);
     // flow_verify reports `status: pass|fail|unverifiable`; assert reports a boolean `pass`. Accept
     // either shape so the whole family is covered without normalizing four tools' contracts for a
     // metric's convenience — but a status that is neither pass nor fail is NOT a verdict, and an empty
     // suite reports exactly that.
     const status = result['status'];
-    const passed = passedOf(result, status);
+    const passed = passedOf(result, status) ?? replay?.passed;
     if (verified === undefined && passed === undefined)
         return undefined;
     const reason = reasonOf(result);
@@ -142,5 +168,7 @@ export function verificationOf(toolName, result, durationMs, brand) {
         // WHAT was lost, when the reason was that something was. Three owners, three fixes, one bar
         // until now.
         ...(uncleanLoss === undefined ? {} : { uncleanLoss }),
+        // WHOSE drive this was. Absent is the ordinary case — the agent called the tool itself.
+        ...(harnessDriving() ? { driven: VerificationDriver.HARNESS } : {}),
     };
 }

package/docs/agent-cheatsheet.md

@@ -97,7 +97,11 @@ A claim is real only when the layers agree. Check more than the UI:
 
 > **Rule:** a passing UI assert that the store, network, or signal contradicts is a **false green**.
 
-**Session health is universal.** Every live-session tool result carries a `session` block (`throttled`, `focused`, `lastSeenMs`); when `throttled:true` it also adds a `warning` + `recommendation` (refocus, or `reticle drive`). A throttled/backgrounded tab can silently no-op timers/rAF/pointer gestures. If you see `session.throttled`, distrust a green and refocus first.
+**Session health is universal.** Every live-session tool result carries a `session` block (`throttled`, `focused`, `lastSeenMs`); when `throttled:true` it also adds a `warning` + `recommendation`. Read the `recommendation`: it differs by cause, and the two causes have different fixes.
+
+`throttled` is `hidden || stale`, and it is not a verdict that the tab cannot be driven. A tab that is **hidden** does clamp timers and rAF, so an action can land on a page that never advances. A tab that is merely **stale**, meaning no health heartbeat arrived inside the window, is usually just a quiet page, and is very often still driveable; a session flagged this way has taken a sign-in and two clean net-grade verdicts with no retries. Try the drive before you conclude anything, and reach for `refuseWhenThrottled: true` when the work is timing-sensitive (animations, debounces, gestures), which is what actually degrades.
+
+**Leasing is not a free upgrade.** `reticle_lease` gives a guaranteed scriptable context, and it is a _separate_ one: the HUD lives in the human's tab, so everything you do in a lease is invisible to the person watching. Taking that advice with someone sitting in front of the app makes the product look broken while it works correctly. Working alone, lease and do not think about it; with an audience, spend a slower tab to stay visible.
 
 > Store reads (`reticle_look { action: "state" }`) are the reliable path; the DOM can lie (optimistic UI, stale render).
 
@@ -109,7 +113,7 @@ A claim is real only when the layers agree. Check more than the UI:
 
 ## Core tool set
 
-The nine tools you are shown. There is no `reticle_run` on this surface: these nine plus their actions are the whole of what you can call.
+The tools you are shown, plus `reticle_run`, which calls any registered tool by name whether or not it is advertised.
 
 `reticle_navigate` · `reticle_act` · `reticle_act_and_wait` · `reticle_assert` · `reticle_look` · `reticle_observe` · `reticle_session` · `reticle_verify` · `reticle_tools`
 
@@ -168,4 +172,4 @@ Recent additions, each of which answers a question agents were previously asking
 - **Cap broad reads.** `reticle_look { action: "find" }` takes `limit` (caps descriptors; reports `total`/`truncated`) and `count_only` (just the match count). `reticle_observe { action: "network" }` / `reticle_observe { action: "console" }` take `limit` (most-recent-N, reports `droppedOldest`) and carry the same `cost` hint, so a busy page or wide window never floods your context unnoticed.
 - **A saved flow tells you if it's a real test.** `reticle_flow_save` returns `assertions.grade` (`asserted` / `presence-only` / `assertion-free`); if it's not `asserted`, add a consequence (`reticle_annotate` assert-signal/assert-net or a success-state) so it can't pass while broken. On replay, an ambiguous heal (two testids tie) is surfaced, never auto-applied. And an `apply` heal re-replays the rebound flow and **refuses to write** if the success consequence no longer fires (`status:consequence_broken`): it heals the locator, never the intent.
 - **Predicate schema is not bloated.** The recursive predicate DSL used by `reticle_assert` / `reticle_assert { action: "wait" }` / `reticle_act_and_wait` is **factored, not inlined**: when converted to the JSON Schema MCP sends, the predicate body is emitted **once** (~2.7k chars ≈ **~685 tokens** per tool) and recursion is handled by self-`$ref` (`#/properties/predicate`), with no per-recursion duplication. No action needed.
-- **One tool surface, and it is closed.** Reticle advertises nine tools: navigate/act/act_and_wait/assert/look/observe/session/verify, plus `reticle_tools`. That is the whole detect loop, the file-pointer, the feedback channel, the handback, and the one tool that CONCLUDES, reached by an `action` argument rather than by a name each. `reticle_tools` discovers: no args lists every tool name and summary, `names:[…]` loads full params on demand. There is **no `reticle_run`** here, so a tool that is not in the nine is not reachable by any call: recording a flow, screenshots, visual diff, storage, network mocking and the clock all need a daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` (read at startup, so restart it), which advertises the full table with output schemas. `reticle_verify` is advertised: `{ action:"flows" }` replays every saved flow with no model in the loop, and `{ action:"crawl" }` drives every reachable control itself and reports the whole fault set in one call. **Sizes are deliberately not quoted here.** A count in prose goes stale, and has three times already. `reticle_tools` reports the live surface, and SKILL.md carries the one gated table.
+- **One tool surface, and a hatch behind it.** Reticle advertises navigate/act/act_and_wait/assert/look/observe/session/verify, plus `reticle_tools` and `reticle_run`. That is the whole detect loop, the file-pointer, the feedback channel, the handback, and the one tool that CONCLUDES, reached by an `action` argument rather than by a name each. `reticle_tools` discovers: no args lists every registered tool name and summary, `names:[…]` loads full params on demand. `reticle_run { tool, args }` then calls any of them, advertised or not, which is what keeps recording a flow, screenshots, visual diff, storage, network mocking and the clock reachable without spending a slot on each. A daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` (read at startup, so restart it) advertises the full table outright, with output schemas. `reticle_verify` is advertised: `{ action:"flows" }` replays every saved flow with no model in the loop, and `{ action:"crawl" }` drives every reachable control itself and reports the whole fault set in one call. **Sizes are deliberately not quoted here.** A count in prose goes stale, and has three times already. `reticle_tools` reports the live surface, and SKILL.md carries the one gated table.

package/docs/autodrive.md

@@ -28,16 +28,56 @@ A drive costs a model. A **saved flow costs nothing to run again**: `reticle_ver
 
 So the drive is a one-off: pay for it once, and the journeys it recorded become the regression suite every later run replays. That is why the harness is told to record as it goes, and why a drive that saved nothing is reported as having proved nothing, however long it ran.
 
+## It replays before it drives
+
+A drive reads `.reticle` first: every saved flow with the consequence that must still hold, and every signal and testid your app declares that no flow has ever asserted. It builds a plan from that before it opens its eyes on a page.
+
+Anything already recorded is **replayed**, deterministically, with no model call at all. Only the gaps are driven. So a second run over the same app is mostly free, and the model budget is spent on the part nobody has proved yet rather than on rediscovering what is already on disk. A replay that goes red is reported as a regression; one that DRIFTS is reported separately, because the app moved under the recording and that needs re-anchoring rather than a code change.
+
+Every journey a drive walks is saved, whatever happens to the drive, including one that broke, ran out of budget, or whose model simply stopped asking for tools.
+
 ## What it needs
 
-`ANTHROPIC_API_KEY` in the **daemon's** environment. Without it the action refuses and says so; every other part of Reticle is unaffected. Two other dials, both optional:
+**A model in the daemon's environment.** Any one of three, and the choice is reported back so a comparison can never mislabel its own arms:
+
+| Variable | Driver |
+| --- | --- |
+| `RETICLE_API_KEY` | `jev`, against the platform's own proxy, using the key `reticle link` already wrote. No model API key of your own, and the cheap path: it answers typed questions about the page rather than generating tool calls as text. |
+| `ANTHROPIC_API_KEY` | `anthropic`, which generates its calls as text. |
+| `OPENAI_API_KEY` | `openai`, the same, on OpenAI. |
+| `JEV_API_KEY` | `jev`, against TypeSafe directly, for anyone who holds their own key. |
+
+With several configured, `anthropic` is the default and `RETICLE_HARNESS_DRIVER` moves off it; with only a platform key, `jev` is not the cheaper option, it is the only one. Naming a driver that is not configured is an error, never a silent substitution.
+
+A driver can also be chosen per call, as `reticle_verify { action: "explore", driver: "jev" }`. The question people actually have is comparative, and answering it with an environment variable means restarting the daemon between arms.
+
+Three other dials, all optional:
 
 | Variable | What it does |
 | --- | --- |
-| `RETICLE_HARNESS_MODEL` | The model that drives. Defaults to a mid-tier one on purpose, for the reason below. |
+| `RETICLE_HARNESS_MODEL` | The Anthropic model that drives. Defaults to a mid-tier one on purpose, for the reason below. |
 | `RETICLE_HARNESS_MAX_STEPS` | Ceiling on model turns in one drive. Bounds cost, not value. |
 | `RETICLE_HARNESS_BASE_URL` | A proxy or gateway instead of the default API host. |
 
+## Two models, and what each one is for
+
+The `jev` driver decides; it cannot write. Every choice a drive makes is a selection from candidates Reticle enumerated off the page: which element, which tool, what consequence to claim. That is why it costs a fraction of a generating model and answers in a few hundred milliseconds.
+
+One thing in a drive is not a selection. A text field is a composition: "a business name", "a statement descriptor", "a search term that returns results" cannot be enumerated from the page. Where the field's label is enough to guess, a small table answers it. Where it is not, and a generating model is configured, that model writes the value, and nothing else.
+
+Typing is a small minority of what a drive does: clicks and navigations are the overwhelming majority. So this is escalation rather than a second model in the loop, and a drive with no text fields never calls it at all.
+
+What it writes is a FIXTURE, not an opinion. Generated values are saved to `.reticle/fill-values.json` and reused forever: the second drive pays nothing, a replay sends exactly what the recording sent, and a value you dislike is a line in a git-checked file you can edit rather than an argument with a model.
+
+## Turning it off, and who pays for it
+
+A project linked to a Reticle workspace reads two things from it before a drive starts, and honours both:
+
+- **The switch.** Autonomous driving can be turned off per project in the dashboard, under Settings → Verification model. A drive then refuses and says where to turn it back on. Everything else is unaffected, including the tools your own agent drives with.
+- **Who is paying.** Driving through the platform spends Reticle's model budget, which is free for three months once claimed and included on a paid plan. Outside both, a drive is refused with the claim link rather than run on somebody else's money.
+
+Neither applies to a drive on a model key of your own: that costs us nothing, so it is not ours to gate. A daemon that cannot reach the platform at all drives normally: an unreachable settings endpoint is not a reason to lose a feature you were never told to stop using.
+
 ## What it will not do
 
 **It does not decide whether your app is correct.** The model chooses what to _try_; the engine decides what _happened_, from what it recorded. A model that graded its own driving would be scoring its own homework, and its verdict would be unfalsifiable. So the summary it writes is an account of what it drove, and nothing downstream grades from it.

package/docs/benchmarks.md

@@ -71,7 +71,7 @@ Why not compare to traditional test frameworks (Playwright the library, Cypress,
 
 There **is** a comparison against a Playwright script, and it answers a different question: not "what does it cost an agent to look" but "what can each tool structurally SEE, at all." That one is in Part 5a. It runs no model, so nothing about it depends on how well an agent drives, which is what makes it the more durable of the two results.
 
-Tool versions are pinned in `bench/raw/run-meta.json` so any run is reproducible.
+Tool versions are recorded by hand in `bench/README.md`, not generated: the file that used to pin them is no longer produced. Treat that table as the expiry date on every cross-tool number here, and re-derive before quoting rather than assuming a run from months ago still describes today's tools.
 
 ---
 

package/docs/capabilities.mdx

@@ -4,7 +4,7 @@ description: Coverage, storage, fake clocks, autonomous crawling, visual diffing
 icon: sparkles
 ---
 
-These are the Reticle tools that do something other than look, act, observe and assert: control coverage, client storage, a fake clock, autonomous crawling, semantic and visual baselines, network mocking, flow recording and replay, and the CI artifact. Reach for them when the verify loop is not the shape of the question. They are **not on the default tool surface, and the default surface has no `reticle_run` to reach them**: start the daemon with `RETICLE_ADVERTISE_ALL_TOOLS=1` (read once at startup, so restart it) and call them by name. The `reticle_run({ tool, args })` spelling on this page works only on that surface.
+These are the Reticle tools that do something other than look, act, observe and assert: control coverage, client storage, a fake clock, autonomous crawling, semantic and visual baselines, network mocking, flow recording and replay, and the CI artifact. Reach for them when the verify loop is not the shape of the question. They are **not advertised on the default tool surface, but they are reachable from it**: `reticle_run({ tool, args })` dispatches to any registered tool by name, advertised or not, which is the spelling used on this page. To have them advertised outright instead, with their output schemas, start the daemon with `RETICLE_ADVERTISE_ALL_TOOLS=1` (read once at startup, so restart it) and call them by name.
 
 Most of the time you want the verify loop. Look, act, observe, assert. These are the tools for the times you want something else, and they are the ones people are most surprised exist.