@reticlehq/server 3.1.0 → 3.3.0

package/dist/telemetry/session-metrics.d.ts

@@ -16,6 +16,7 @@
  * than a rule saying it shouldn't.
  */
 import { BrowserLaunchKind, type ConnectFailure, type SessionSummary } from '@reticlehq/core/telemetry';
+import type { HudUseData } from '@reticlehq/core';
 /**
  * Mutable counters for one daemon lifetime. A plain class, not a store: it is process-local, it never
  * persists, and it dies with the daemon.
@@ -24,6 +25,8 @@ export declare class SessionMetrics {
     #private;
     /** Clock injected — this file must stay testable without a real one, per the repo's clock rule. */
     constructor(now: () => number);
+    /** A person used the HUD. Names only; the wire schema has already narrowed it. */
+    recordHudUse(use: HudUseData): void;
     /**
      * Record a call starting. Returns a function to call when it finishes — that closure is what makes
      * timing correct under CONCURRENCY: several agents can be inside `runTool` at once, so a single
@@ -162,5 +165,7 @@ export declare const recordSdkFailure: (failure: {
     site: string;
     message: string;
 }) => void;
+/** Narrow-and-record one HUD use. Keeps the session hot path to a single call. */
+export declare const recordHudUse: (use: HudUseData) => void;
 /** Tests only — drop the singleton so each case starts from zero. */
 export declare const resetSessionMetrics: () => void;

package/dist/telemetry/session-metrics.js

@@ -20,6 +20,7 @@ import { errorSkeleton, fingerprintError } from './error-fingerprint.js';
 import { describeToolParams } from './argument-shape.js';
 import { machineSnapshot } from './machine-snapshot.js';
 import { classifyError } from './error-class.js';
+import { HudMetrics } from './hud-metrics.js';
 /** Cap the distinct error shapes held in memory — a pathological loop must not grow unbounded. */
 const MAX_ERROR_KINDS = 40;
 /** Distinct tool names whose repeat-runs are tracked. Its own cap: the tool surface, not error shapes. */
@@ -165,10 +166,16 @@ export class SessionMetrics {
     #surface;
     #startedAt;
     #now;
+    #hud;
     /** Clock injected — this file must stay testable without a real one, per the repo's clock rule. */
     constructor(now) {
         this.#now = now;
         this.#startedAt = now();
+        this.#hud = new HudMetrics(now);
+    }
+    /** A person used the HUD. Names only; the wire schema has already narrowed it. */
+    recordHudUse(use) {
+        this.#hud.record(use);
     }
     /**
      * Record a call starting. Returns a function to call when it finishes — that closure is what makes
@@ -555,6 +562,7 @@ export class SessionMetrics {
             ...(this.#firstAppAt === undefined
                 ? {}
                 : { msToFirstApp: Math.max(0, this.#firstAppAt - this.#startedAt) }),
+            ...this.#hud.summarize(),
             final,
             // Only on a real exit. A periodic flush carrying `exit: "unknown"` would read as a daemon that
             // died without a shutdown path, which is the one thing this field exists to make visible.
@@ -613,7 +621,8 @@ export class SessionMetrics {
             0 === this.#bugsFound &&
             0 === this.#sdkFailures &&
             0 === this.#postSocketFailures &&
-            0 === this.#postRetriesSaved);
+            0 === this.#postRetriesSaved &&
+            this.#hud.empty);
     }
     /** Zero the counters after a non-final flush so the next flush reports the NEXT window, not a total. */
     reset() {
@@ -641,6 +650,7 @@ export class SessionMetrics {
         this.#unknownToolCalls = 0;
         this.#bugsFound = 0;
         this.#bugKinds.clear();
+        this.#hud.reset();
         // #seenBugKinds is deliberately NOT cleared. It is not a window counter — it is the
         // session-lifetime memory behind `repeat` on bug_found, and zeroing it made the same defect,
         // found again after a flush, report as a newly distinct one. Sessions run to 11.5 hours in the
@@ -665,6 +675,10 @@ export const recordBrowserLatency = (ms) => {
 export const recordSdkFailure = (failure) => {
     getSessionMetrics().recordSdkFailure(failure.site, failure.message);
 };
+/** Narrow-and-record one HUD use. Keeps the session hot path to a single call. */
+export const recordHudUse = (use) => {
+    getSessionMetrics().recordHudUse(use);
+};
 /** Tests only — drop the singleton so each case starts from zero. */
 export const resetSessionMetrics = () => {
     current = undefined;

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/dist/wire-journal.d.ts

@@ -0,0 +1,31 @@
+import { Bridge } from './portal/bridge/bridge.js';
+import { FlowStore } from './language/flows/flows.js';
+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';
+import { type PruneWorkspaceOptions } from './memory/journal/on-disk/startup-maintenance.js';
+/**
+ * Wire journal capture, ambient seeding and the journal-tail flush onto a bridge.
+ *
+ * Both entry points need all three, and both used to hand-roll them. `startDaemon` only ever wired the
+ * first, so on the path every user actually takes (`reticle serve` / `reticle mcp`) the journal tail was
+ * dropped at session end and the learned ambient map was never persisted OR seeded — meaning ambient
+ * learning could not converge across sessions and the last events of every session were lost. The two
+ * call sites had already drifted once before, which is why this is one function rather than a
+ * copy-paste both are asked to keep in step.
+ */
+export declare function attachJournal(bridge: Bridge, deps: {
+    fs: FileSystemPort;
+    reticleRoot: string;
+    enabled: boolean;
+    takeAmbientTape?: () => {
+        steps: readonly TapeStep[];
+        startPath?: string;
+    } | undefined;
+    reportStep?: (step: OnboardingStep) => Promise<boolean>;
+    /** Tell cloud sync a run landed, so it cycles instead of waiting for its timer. */
+    onRunPersisted?: () => void;
+    flows?: FlowStore;
+    /** What this project is willing to keep — the `retain` block of its `.reticle.json`. */
+    retain?: PruneWorkspaceOptions;
+}): void;

package/dist/wire-journal.js

@@ -0,0 +1,100 @@
+/**
+ * Journal wiring for the composition root.
+ *
+ * A sibling of `index.ts` rather than a move into `memory/journal/`: this is COMPOSITION, not
+ * journalling. It reaches the bridge, the flow store, the telemetry funnel and the recording tape to
+ * join them together, and putting those reaches inside the journal domain would make that domain
+ * depend on four areas it has no business knowing. `index.ts` already holds every one of them, and
+ * the 1000-line backstop is what asked for the split.
+ */
+import { artifactRootResolver } from './memory/project/artifact-root-resolver.js';
+import { originOf } from './portal/session/session-manager.js';
+import { Bridge } from './portal/bridge/bridge.js';
+import { FlowStore } from './language/flows/flows.js';
+import { makeJournalAttach } from './memory/journal/attach-journal.js';
+import { makeSessionEnd, recordDriveRun } from './memory/journal/session-end.js';
+import { attachDriveRunFlush } from './memory/journal/drive-run-flush.js';
+import { AmbientStore } from './memory/journal/ambient-store.js';
+import { ensureWorkspaceGitignore } from './memory/journal/on-disk/workspace-gitignore.js';
+import { pruneWorkspace, } from './memory/journal/on-disk/startup-maintenance.js';
+import { dirname } from 'node:path';
+import { findProjectConfig } from './command/cli/ports/resolve/cli-port.js';
+import { readBackgroundTraffic } from './portal/session/facts/background-traffic.js';
+/**
+ * Wire journal capture, ambient seeding and the journal-tail flush onto a bridge.
+ *
+ * Both entry points need all three, and both used to hand-roll them. `startDaemon` only ever wired the
+ * first, so on the path every user actually takes (`reticle serve` / `reticle mcp`) the journal tail was
+ * dropped at session end and the learned ambient map was never persisted OR seeded — meaning ambient
+ * learning could not converge across sessions and the last events of every session were lost. The two
+ * call sites had already drifted once before, which is why this is one function rather than a
+ * copy-paste both are asked to keep in step.
+ */
+export function attachJournal(bridge, deps) {
+    const journalAttach = makeJournalAttach(deps);
+    const ambientStore = new AmbientStore(deps.fs, deps.reticleRoot);
+    // Built once, not per session: the resolver walks config discovery and the user-level registry,
+    // and neither changes between two tabs connecting a second apart.
+    const resolveArtifactRoot = artifactRootResolver(deps.reticleRoot);
+    bridge.attachSessionCreate((session) => {
+        // Stamp the project's own `.reticle` before ANY counter fires for this session. Without it every
+        // verdict is recorded against wherever the daemon was started, which is how one app's evidence
+        // reached a different account's production dashboard.
+        // The origin is passed for the case where the page never stamped a project id: it is the only
+        // distinguishing fact left, and without it every such app shares one bucket.
+        session.artifactRoot = resolveArtifactRoot(session.projectId, originOf(session.url)).root;
+        // The project's config sits beside its `.reticle/`, so the declaration is read from the tab's
+        // own project rather than from wherever the daemon was started.
+        session.background = readBackgroundTraffic(findProjectConfig(dirname(session.artifactRoot)));
+        // Here rather than on the start path, which was neither the moment we were about to write into a
+        // repository nor the root we were about to write into: it created `.reticle/` — holding nothing
+        // but the ignore file — wherever the daemon was launched, coming back every boot after the user
+        // deleted it, while the journals this ignore protects landed in another tree, uncovered.
+        if (deps.enabled)
+            void ensureWorkspaceGitignore(deps.fs, session.artifactRoot);
+        journalAttach(session);
+        // Seed the learned ambient map so a fresh session starts knowing which regions churn, instead of
+        // re-learning from zero. Best-effort + async: a late seed still helps, a failure is silent.
+        if (deps.enabled) {
+            void ambientStore
+                .load()
+                .then((counts) => session.seedAmbient(counts))
+                .catch(() => undefined);
+        }
+    });
+    // Teardown: flush the journal tail to disk + persist what this session learned.
+    bridge.attachSessionEnd(makeSessionEnd({
+        ...deps,
+        ...(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.
+        liveSessionIds: () => new Set(bridge.sessions.all().map((s) => s.id)),
+    }));
+    /*
+     * And the same write, DURING the session rather than only at the end of it.
+     *
+     * Teardown was the only writer of a run artifact, so every verdict produced while a tab stayed
+     * open was invisible to cloud sync — which can only push artifacts that exist. Reported as "sync
+     * is not happening" and diagnosed as the agent forgetting to sync; there is no sync command to
+     * forget. The evidence simply was not on disk yet.
+     *
+     * Safe to call repeatedly because the run id is derived from the session, so this rewrites one
+     * artifact rather than accumulating them — a property `recordDriveRun` already had, for the
+     * unrelated reason that a reconnecting tab must not publish two overlapping rows.
+     */
+    if (deps.enabled) {
+        attachDriveRunFlush({
+            resolve: (sessionId) => bridge.sessions.get(sessionId),
+            write: (session) => recordDriveRun(deps, session),
+        });
+    }
+    // One call, because "what maintenance runs at startup" needs one answer. Inlined here, the byte
+    // budget was simply missing — written, tested, and called by nothing, while the three count
+    // bounds beside it ran every time. See startup-maintenance.ts.
+    //
+    // Deliberately NOT behind `deps.enabled`. Switching journalling off is what somebody does BECAUSE
+    // the directory got too big, and both sweep sites were gated on it, so that setting was the one
+    // under which nothing ever deleted what was already there. Visual diffs, feedback copies and run
+    // artifacts do not need the journal to be written at all and kept accumulating regardless.
+    void pruneWorkspace(deps.fs, deps.reticleRoot, new Set(bridge.sessions.all().map((s) => s.id)), deps.retain ?? {});
+}

package/docs/README.md

@@ -72,6 +72,7 @@ Everything here is published to [docs.reticle.sh](https://docs.reticle.sh) by `d
 | [vs-playwright-mcp.mdx](vs-playwright-mcp.mdx) | outside-in vs inside-out, and when Playwright is right |
 | [vs-chrome-devtools-mcp.mdx](vs-chrome-devtools-mcp.mdx) | cheaper per look, catches less: the trade, measured |
 | [vs-screenshots.mdx](vs-screenshots.mdx) | why a better vision model does not fix a non-visual bug |
+| [what-is-recorded.md](what-is-recorded.md) | what Reticle keeps, what is redacted, and what it takes for any of it to leave your machine |
 | [telemetry.md](telemetry.md) | what is collected, and how to turn it off |
 | [local-registry.md](local-registry.md) | installing an unpublished build |
 | [license-activation.mdx](license-activation.mdx) | you have a key: where to set it, how to confirm it, what to do when it fails |

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.
 

package/docs/cli/cloud.mdx

@@ -20,7 +20,7 @@ These are thin clients over the `/v1` API. The logic is server-side; these verbs
 | `~/.reticle/credentials.json` | Project-scoped API keys from `reticle link`, keyed by `projectId` | Yes |
 | `<repo>/.reticle/cloud.json` | `{ projectId, projectName, url, sync, verify }`. The non-secret binding | No, commit it |
 
-Auth for any command is `RETICLE_CLOUD_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` overrides the endpoint; the default is `http://localhost:8890`. When a command falls back to that default without `RETICLE_CLOUD_URL` (or a saved session URL), it prints a one-line notice on stderr; stdout stays pure JSON for agents.
+Auth for any command is `RETICLE_API_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` overrides the endpoint; the default is `http://localhost:8890`. When a command falls back to that default without `RETICLE_CLOUD_URL` (or a saved session URL), it prints a one-line notice on stderr; stdout stays pure JSON for agents.
 
 ## The commands
 
@@ -70,7 +70,7 @@ An unattached repo also gets a next-step nudge on stderr, telling you to run `re
 npx @reticlehq/server link [--project <name|id>]
 ```
 
-Binds this repository to a cloud project. With a login token it **mints** a project-scoped key, so there is nothing to paste. With `RETICLE_CLOUD_KEY` already set, it resolves that key's project instead. `--project` accepts a slug id or a display name; omitted, it uses the `default` project. Writes `cloud.json` and the key.
+Binds this repository to a cloud project. With a login token it **mints** a project-scoped key, so there is nothing to paste. With `RETICLE_API_KEY` already set, it resolves that key's project instead. `--project` accepts a slug id or a display name; omitted, it uses the `default` project. Writes `cloud.json` and the key.
 
 ### `reticle project`
 
@@ -101,7 +101,9 @@ reticle: no .reticle/cloud.json here ... run `reticle link` first
 
 ### `reticle push`
 
-Sends local run artifacts from `.reticle` to the linked project, honoring the sync policy. With `sync.runs` off it does nothing and says so. Prints `{ pushed, failed, total, project }`.
+Sends local run artifacts from `.reticle` to the linked project, honoring the sync policy. With `sync.runs` off it does nothing and says so. Prints `{ ok, project, sent, pulled }`, where `sent` carries the accepted counts and, when the server refused anything, a `rejected` array naming each artifact's index and reason.
+
+**A rejection is a failed push.** If the server refuses any artifact, `ok` is `false` and the command exits `1`, even when other artifacts in the same bundle landed. A refused artifact never reaches the dashboard and is re-offered on every cycle, so partial loss is still loss. `ok: true` and exit `0` mean everything offered was accepted, which includes the common case of a repo that was already up to date. The accepted counts still report what did land, so a partial push is visible as one.
 
 ### `reticle runs`
 
@@ -133,12 +135,12 @@ reticle: cloud not attached here ... run `reticle link` (or set RETICLE_CLOUD_UR
 
 ## Exit codes
 
-| Code | Meaning                                                                             |
-| ---- | ----------------------------------------------------------------------------------- |
-| `0`  | Success                                                                             |
-| `1`  | The API call failed, or the repository is not attached where attachment is required |
-| `2`  | Usage error, or not signed in and no `RETICLE_CLOUD_KEY`                            |
-| `3`  | `regression` only: at least one flow broke                                          |
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | The API call failed, the repository is not attached where attachment is required, or `push` had an artifact refused |
+| `2` | Usage error, or not signed in and no `RETICLE_API_KEY` |
+| `3` | `regression` only: at least one flow broke |
 
 Output is pretty-printed JSON on stdout. Errors and next-step nudges go to stderr, so an agent parsing stdout is unaffected.
 

package/docs/cli/doctor.mdx

@@ -52,6 +52,7 @@ When nothing has connected, the `sessions` line fails and the daemon's own diagn
 | `daemon` | Whether the port holds a Reticle daemon, a foreign process (named where possible), or nothing. Adds a `version` line when the daemon's version or contract fingerprint disagrees with the CLI's |
 | `sessions` | Whether any page has actually connected. Zero is a FAILING check rather than a neutral note, because it is the state the setup most often stalls in: wired correctly, daemon up, nothing dialled in. When it is zero the daemon's own no-session diagnosis prints below the checklist |
 | `agent link` | Whether an MCP client has listed Reticle's tools on this port **and actually called one**. Every other row here checks a component; this one checks the hop between your agent and the daemon. It is possible for the SDK to be injected, a session to be live, and your client to show every tool enabled, while no request has ever crossed from the agent. That state passes every other check and is the one people lose hours to |
+| `loopback` | Which of `localhost`'s two answers reaches the bridge. Printed **only when they disagree**. The daemon binds `127.0.0.1`, and a best-effort alias forwards `[::1]` to it so the name works everywhere. When that alias cannot open (IPv6 disabled, or something already holding `[::1]` on the port) the daemon serves IPv4 perfectly and a page told to dial `localhost` still cannot reach it, because Windows Chrome tries the IPv6 answer first. Every other row here goes green in that state |
 | `bridge port` | The port your app must dial, spelled out because mixing it up with the dev server port is the most common setup failure |
 | `port check` | Only when your project's configured port disagrees with the one the daemon is on. Prints the mismatch rather than leaving you to spot it across two lines |
 | `sibling` | Only when a well-known Reticle port other than this daemon's has a listener. An observation, not a diagnosis: that listener may or may not be related |

package/docs/cli/init.mdx

@@ -19,6 +19,7 @@ npx @reticlehq/server init [--dry-run] [--port N] [--no-mcp] [--no-install] [--a
 | `--no-mcp` | boolean | `false` (MCP is registered) | Skip the MCP registration **and** the agent rule files (`CLAUDE.md`, `AGENTS.md`, `.cursor`) and the `/reticle` command |
 | `--no-install` | boolean | `false` (deps are installed) | Do not run the install. The step becomes `[⚠]` and prints the `add -D` command for you to run by hand, rather than vanishing from the plan |
 | `--app <dir>` | string | unset | Pick which app to wire in a monorepo, without changing directory |
+| `--hooks` | boolean | `false` | Also add a print-only Stop hook to `.claude/settings.json`, merged into what is there. When the agent stops without a claim that held, it prints one line; it never blocks. See [`reticle report`](/cli/report) |
 | `--yes` | boolean | `false` | Accepted for scripting. `init` has no interactive prompts today, so it is a no-op |
 
 <Warning>

package/docs/cli/report.mdx

@@ -0,0 +1,44 @@
+---
+title: reticle report
+description: What the latest session claimed, and what held. Also a print-only Stop hook for Claude Code.
+icon: clipboard-check
+---
+
+`reticle report` reads this project's most recent session from `.reticle/` and says how many of its claims held, how many failed, how many came back `unknown` and who can act on each, and how many proved nothing. It reads the journal on disk, so no daemon has to be running.
+
+```bash
+npx @reticlehq/server report [--session <id>] [--hook]
+```
+
+## Arguments and flags
+
+| Flag | Default | What it does |
+| --- | --- | --- |
+| `--session <id>` | the newest session | Report a specific session |
+| `--hook` | off | Print one line, and only when the working tree changed and no claim held |
+
+## What it prints
+
+```text
+session lease-85f8191b-3874-457b-973b-8ee365e5acfb
+2 of 4 claims held
+1 failed, 1 of them a green a channel contradicted
+1 unknown (environment: 1)
+  ✗ signal order:placed
+```
+
+An `unknown` is never counted as held. It is Reticle saying it could not tell, and the owner beside it says what to do next.
+
+## As a Claude Code Stop hook
+
+With `--hook` it prints nothing when a claim held or nothing in the tree changed, and otherwise one line, such as `Reticle: not verified. 3 claims: 1 failed, 2 unknown`. It prints Claude Code's `systemMessage` shape and always exits `0`: you see the line when the agent stops, and the agent is never blocked by it. `reticle init --hooks` adds it for you, merged into whatever `.claude/settings.json` already holds. By hand:
+
+```json
+{
+  "hooks": {
+    "Stop": [{ "hooks": [{ "type": "command", "command": "npx @reticlehq/server report --hook" }] }]
+  }
+}
+```
+
+A session last written more than an hour ago does not count as this turn, so a morning drive cannot answer for an afternoon edit. If you want the stop blocked until the change is verified, use [`reticle gate --hook`](/cli/gate) instead.

package/docs/cli/status.mdx

@@ -7,7 +7,7 @@ icon: heart-pulse
 `reticle status` is the command that tells you whether the install actually finished. Not a tick in a checklist: a connected app.
 
 ```bash
-npx @reticlehq/server status [--port N]
+npx @reticlehq/server status [--port N] [--json]
 ```
 
 ## Flags
@@ -15,10 +15,37 @@ npx @reticlehq/server status [--port N]
 | Flag | Type | Default | What it does |
 | --- | --- | --- | --- |
 | `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Which daemon to ask |
+| `--json` | flag | off | Print the machine-readable event instead of the block below |
 
 ## What it prints
 
-One JSON line on stdout. Real capture, daemon up and no app connected:
+A short block, for whoever is reading the terminal. Real capture, daemon up with two apps connected:
+
+```text
+reticle status
+  daemon       ✓ running on :4400 (pid 90790)
+  sessions     ✓ 2 pages connected
+               http://localhost:5173/  (throttled, hidden)
+               http://localhost:7699/  (throttled, hidden)
+  agent link   enumerated
+```
+
+And with no daemon on the port:
+
+```text
+reticle status
+  daemon       ✗ not running on :4999
+  agent link   never-attached
+  next         no daemon is running on this port, which is normal. An agent starts it when it
+               first calls a Reticle tool, and it exits again when idle. Ask your agent to verify
+               something, then run status again.
+```
+
+A session's parenthesised notes are the ones that explain an answer you would otherwise call a bug: `throttled` and `hidden` mean a background tab answering slowly, `stale` means the page has moved on from what the daemon last saw, and `unresponsive` means it is not answering at all.
+
+### `--json`
+
+The same facts as one event line on stderr, for a caller that parses rather than reads:
 
 ```json
 {
@@ -33,30 +60,18 @@ One JSON line on stdout. Real capture, daemon up and no app connected:
 }
 ```
 
-With an app connected, `why` is absent and each session carries its own fields:
+It is one line in the terminal, pretty-printed here, with `why` trimmed at the ellipses. With an app connected `why` is absent and each session carries its own fields:
 
 ```json
 {
-  "t": "2026-08-15T18:45:58.190Z",
-  "event": "reticle_status",
-  "port": 4400,
-  "running": true,
-  "pid": 72698,
-  "sessionCount": 1,
-  "sessions": [
-    {
-      "sessionId": "s223e0fad-e012-43f9-a23d-6d585470c90d",
-      "url": "http://localhost:4310/",
-      "throttled": false,
-      "stale": false,
-      "pendingMarks": 0
-    }
-  ]
+  "sessionId": "s223e0fad-e012-43f9-a23d-6d585470c90d",
+  "url": "http://localhost:4310/",
+  "throttled": false,
+  "stale": false,
+  "pendingMarks": 0
 }
 ```
 
-Both are one line of JSON in the terminal, pretty-printed here, with `why` trimmed at the ellipses.
-
 | Field | Meaning |
 | --- | --- |
 | `running` | Whether a usable daemon owns the port |