@reticlehq/server 3.2.0 → 3.4.0

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

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

@@ -0,0 +1,104 @@
+/**
+ * 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,
+        // 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.
+        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/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 |
@@ -72,6 +74,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/actions.mdx

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

package/docs/agent-cheatsheet.md

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

package/docs/architecture.md

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

package/docs/best-practices.mdx

@@ -196,7 +196,7 @@ Sessions accumulate. Four stale ones pointing at dev servers you restarted an ho
 
 ## Confirm a navigation landed
 
-`reticle_navigate` returns `confirmed: false` by design. A navigation destroys the document the SDK lives in, so it can only report dispatch. Check [`reticle_sessions`](/tools/sessions) for a session at the new URL before acting, and re-snapshot: refs do not survive a new document.
+`reticle_navigate` returns `confirmed: false` by design. A navigation destroys the document the SDK lives in, so it can only report dispatch. Check [`reticle_session { action: "list" }`](/tools/sessions) for a session at the new URL before acting, and re-snapshot: refs do not survive a new document.
 
 ## Start with what the app says about itself
 

package/docs/capabilities.mdx

@@ -55,7 +55,7 @@ Useful at the end of a drive, when the agent is about to report success. "I veri
 }
 ```
 
-Note the token redaction. Credential-shaped values are stripped here exactly as they are in [`reticle_network`](/tools/network), so reading storage never puts a session token in your context.
+Note the token redaction. Credential-shaped values are stripped here exactly as they are in [`reticle_observe { action: "network" }`](/tools/network), so reading storage never puts a session token in your context.
 
 localStorage, sessionStorage and readable cookies.
 
@@ -87,6 +87,24 @@ Toasts that auto-dismiss, debounced search, polling, session timeouts, retry bac
 
 Freeze the clock, advance it by exactly the interval, assert the consequence. No sleeping, no guessing, and the same result on a fast laptop and a loaded CI runner.
 
+<Warning>
+Freeze the clock **before** the action that schedules the timer. Reticle replaces the page's
+`setTimeout` and `setInterval` when the clock is frozen, so timers that already exist keep running
+on the browser's real clock and are not fired by `advanceMs`.
+
+If a timer is created during page mount, freeze the clock first and then reload the page so the mount-time timer is created under the fake clock.
+
+</Warning>
+
+The clock virtualizes `Date.now()`, but not every time API. `new Date()` and `performance.now()` continue to use real time. `performance.now()` is intentionally left real because React's scheduler depends on it.
+
+The reliable pattern is:
+
+1. Freeze the clock.
+2. Perform the action that schedules the timer, or reload the page if the timer is created during mount.
+3. Advance by the required interval.
+4. Assert the consequence.
+
 ### Crawl: click everything, report anomalies
 
 ```json
@@ -123,6 +141,19 @@ This is the tool for an app you did not write and do not understand yet.
   25.
 </Warning>
 
+Controls Reticle judges destructive are blocked unless you pass `confirmDangerous: true`. That covers the controls on the page the crawl started on. A control one of its clicks revealed, such as the "Yes, delete" behind a "Delete", stays blocked, so one crawl cannot finish a deletion you did not look at.
+
+### Covering everything: `exhaustive`
+
+`{ "action": "crawl", "exhaustive": true }` goes past one page. It walks every state reachable from where you start, reaching each one by replaying the path that found it from a fresh load, so it never depends on "back" working. It fills text fields before it tries a form's buttons (from `RETICLE_SECRET_<FIELD>` when set, so it gets past a login, and only on the origin the crawl started on), and treats controls that differ only by a number, like table rows, as one. A control with the same name on a different screen is tried again there. Every write it finds is then driven again with the request failing. A write counts as **branched** only when the request was actually sent and broken. With the write failing, the app must not end up where it goes when the write succeeds; if it does, you get `failure-unhandled`. That part needs a browser Reticle drives (`reticle drive`).
+
+The run folds into the app-wide coverage ledger, which `reticle_verify { action: "coverage", app: true }` also reports. It has six levels, each with what is missing: routes **reached**, controls **touched**, controls **proved** (an `act_and_wait` came back `yes`), journeys **completed**, writes **branched** (failure path driven), and app functions **executed** (V8 coverage, driven browser only, collected from the first coverage request or exhaustive crawl onward, so an ordinary drive pays nothing for it). `frontier` is the number of states found and not yet explored. Zero means every state the explorer could tell apart was explored, not that every reachable state was: a state is its route plus the names of its controls, so two screens that differ only in field values, in how many of a control they show, or in what the same controls do count as one, and the second is never visited. `reticle gate` blocks when a level falls below the best it has reached, and when a changed file never ran. A changed file whose coverage was taken before the edit is reported as `coverageStale` instead, because its counts describe the old code. When a drop was intended, `reticle gate --accept-coverage` records today's levels as the new best.
+
+<Warning>
+  Exhaustive really does click everything, repeatedly, and submits forms. `maxSteps` bounds it,
+  defaulting to 400 actions.
+</Warning>
+
 ### Reconcile: what the API said versus what rendered
 
 ```json

package/docs/cli/cloud.mdx

@@ -20,7 +20,13 @@ 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_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.
+Auth for any command is `RETICLE_API_KEY` from the environment (the agent path) if set, otherwise the login token. `RETICLE_CLOUD_URL` (or its short form `RETICLE_URL`) overrides the endpoint; without it, a command uses the saved session's host, and otherwise the hosted service, `https://app.reticle.sh`.
+
+## In CI
+
+CI needs `RETICLE_API_KEY` and nothing else: no `login`, no `link`. Commit `.reticle/cloud.json`, store the key as a secret, and the daemon and `reticle push` sync to the project the binding names. A key stored in `credentials.json` wins over the environment when both exist.
+
+The environment key is only sent to the host it belongs to: `RETICLE_CLOUD_URL` when set, otherwise the hosted service. A repo linked to a self-hosted install therefore also needs `RETICLE_CLOUD_URL` set to that install in CI. A repo with no `cloud.json` and a key in the environment syncs to the hosted service, or to `RETICLE_CLOUD_URL`.
 
 ## The commands
 
@@ -101,7 +107,13 @@ 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 run's index and reason and a `refused` array for flows, capsules and derived records. `sent.records` lists only the records the server accepted.
+
+Runs go up in batches, so a large backlog is never one oversized request.
+
+What the platform cannot read is not sent at all, and a `notSent` array says why: a record kind an older platform does not know yet (this one alone leaves `ok` true), or a flow or run in a file version it does not read. Sending those would only be refused again on every cycle.
+
+**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. The reason is kept as `sync.lastError` in `reticle whoami`, and the background daemon logs it once, until a cycle refuses nothing. A refused run is not offered again until its file changes or the platform reports that it reads more: until then it is listed under `notRetried`, and the summary reads `refused, not retried: N run(s) (reason)`. 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`
 
@@ -128,17 +140,17 @@ reticle: usage: reticle share <runId>
 `push`, `runs` and `regression` all need a project to talk to. Without one they exit `1` with the same line on stderr, measured:
 
 ```
-reticle: cloud not attached here ... run `reticle link` (or set RETICLE_CLOUD_URL/KEY)
+reticle: cloud not attached here ... run `reticle link` (or set RETICLE_API_KEY)
 ```
 
 ## 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_API_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

@@ -72,6 +72,10 @@ All three captures below are real, taken by pointing `PLAYWRIGHT_BROWSERS_PATH`
   chromium     ✓ installed (chromium-1234)
 ```
 
+**`✓ using the installed Google Chrome`** (or Microsoft Edge) means the pinned build is absent and Reticle drives the browser you already have instead, through Playwright's channel. Nothing to do: the line also names the command that adds Playwright's own build, if you want it.
+
+When neither is there, Reticle does not refuse. The first command that needs a browser (a lease, `verify`, a drive) runs the bundled Playwright's own pinned install for you, announced on stderr so `reticle mcp`'s stdout stays clean. The two `✗` lines below are what you see when that has not happened yet, or failed.
+
 **`✗ wrong revision`** means builds are installed and none of them is the wanted one. One pinned download away. The line names the revision Playwright wants, then every revision the root actually holds, then the exact command:
 
 ```

package/docs/cli/feedback.mdx

@@ -11,7 +11,7 @@ npx @reticlehq/server feedback [--rating 1-5] [--bug] "what worked, what didn't"
 npx @reticlehq/server feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"
 ```
 
-The `--agent` form is for an agent that cannot reach the `reticle_feedback` tool: during `init`, while instrumentation is half wired, or when the daemon will not start. Those are the reports that are hardest to hear and most needed, because every other path requires the tool surface to already work.
+The `--agent` form is for an agent that cannot reach the `reticle_session { action: "feedback" }` tool: during `init`, while instrumentation is half wired, or when the daemon will not start. Those are the reports that are hardest to hear and most needed, because every other path requires the tool surface to already work.
 
 ## Flags
 
@@ -63,5 +63,5 @@ npx @reticlehq/server feedback --agent --kind gap \
   icon="comments"
   href="/tools/session-and-feedback"
 >
-  `reticle_feedback` when the tools are reachable.
+  `reticle_session { action: "feedback" }` when the tools are reachable.
 </Card>

package/docs/cli/gate.mdx

@@ -7,7 +7,7 @@ icon: shield-halved
 `reticle gate` is what makes verification unavoidable. It computes the [affected](/cli/affected) flows, looks for a passing artifact for each, and fails the command if any is missing. An agent that edits a covered file cannot call itself finished without re-verifying.
 
 ```bash
-npx @reticlehq/server gate [--since <ref>] [file...]
+npx @reticlehq/server gate [--since <ref>] [--accept-coverage] [file...]
 ```
 
 ## Arguments and flags
@@ -16,6 +16,7 @@ npx @reticlehq/server gate [--since <ref>] [file...]
 | --- | --- | --- | --- |
 | `file...` | strings, positional | none | Explicit changed files |
 | `--since <ref>` | string | `HEAD` when no files are given | Also include files git reports as changed since this ref |
+| `--accept-coverage` | boolean | off | Accept today's coverage levels as the new best before judging. Use it when a drop was intended, such as a control you removed on purpose. The run reports what it accepted as `coverageAccepted` |
 
 ## What blocks and what does not
 
@@ -24,6 +25,10 @@ npx @reticlehq/server gate [--since <ref>] [file...]
 | `uncovered` | Yes | An affected flow with no passing artifact |
 | `downgraded` | Yes | A flow whose assertions were weakened since its last passing run. A green bought by weakening the test is the gaming move this exists to stop |
 | `deletedCoverage` | Yes | A flow that covered a changed file and has since vanished. Coverage deleted, not satisfied |
+| `unflowed` | Yes | A changed interactive component that no saved flow drives. Only once the project has saved flows, so a first day never blocks |
+| `coverageRegressed` | Yes | A [coverage](/capabilities) level fell below the best it has reached: something new appeared that nothing covers. Cover it, or accept the drop with `--accept-coverage` |
+| `unexecuted` | Yes | A changed file the browser loaded during a drive and never ran a function of |
+| `coverageStale` | No | A changed file whose code coverage was taken before its last edit. Its counts describe the old code, so `unexecuted` cannot judge it either way. Take coverage again after driving the change to measure it |
 | `quarantined` | No | Flows the flake ledger has quarantined. Surfaced, never blocking, because one unexplained flake that blocks a merge destroys trust in the red |
 
 ## What it prints
@@ -41,14 +46,14 @@ One `reticle_gate` line. Real capture from this repository, with the flow lists
 }
 ```
 
-`downgraded` and `deletedCoverage` appear only when they are non-empty, and neither was present in that run. The CLI prints this as a single line of JSON; it is pretty-printed here to be readable.
+`downgraded`, `deletedCoverage`, `unflowed`, `coverageRegressed`, `unexecuted`, `coverageStale` and `coverageAccepted` appear only when they are non-empty, and none was present in that run. The coverage categories need a coverage ledger, which a project gets from `reticle_verify { action: "crawl", exhaustive: true }` or `reticle_verify { action: "coverage", app: true }`; without one they never fire. The CLI prints this as a single line of JSON; it is pretty-printed here to be readable.
 
 ## Exit codes
 
 | Code | Meaning |
 | --- | --- |
-| `0` | Every affected, non-flaky flow has a passing artifact and nothing was weakened or deleted |
-| `1` | Something is uncovered, downgraded or deleted. Also `1` on any internal fault: the gate fails closed |
+| `0` | Every affected, non-flaky flow has a passing artifact, nothing was weakened or deleted, and coverage held |
+| `1` | Something is uncovered, downgraded, deleted, unflowed, unexecuted, or coverage fell. Also `1` on any internal fault: the gate fails closed |
 
 Measured on this repository, `npx @reticlehq/server gate --since HEAD~1` exited `1` with the output above: 0 of 47 flows covered, 39 uncovered and 8 quarantined.
 

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>