@reticlehq/server 3.7.0 → 3.8.1

package/docs/system-map.md

@@ -2,13 +2,14 @@
 title: System map
 description: 'How a tool call travels from a coding agent to your app and back, and which of those failures are silent.'
 icon: map
+noindex: true
 ---
 
-A tool call crosses five processes and four hops: coding agent → `reticle mcp` proxy (stdio) → daemon on `:4400` (HTTP POST out, SSE back) → browser SDK (WebSocket) → your app. Each hop has its own failure vocabulary and its own way of lying, and the ones marked **silent** below fail with no error reaching either the agent or you.
+A tool call crosses five processes and four hops: coding agent → `reticle mcp` proxy (stdio) → daemon on port `4400` by default (HTTP POST out, SSE back) → browser SDK (WebSocket) → your app. When another project's daemon holds that port, the proxy finds this project's daemon where it moved, or starts one on a free port. Each hop has its own failure vocabulary and its own way of lying, and the ones marked **silent** below fail with no error reaching either the agent or you.
 
 > How a tool call gets from a coding agent to your app and back, what each hop can do wrong, and which of those failures are **silent**. Written for anyone touching the transport, the daemon, the bridge, or a gate, and for contributors trying to work out where their change lives.
 >
-> Companion pages: [`harness-rules.md`](https://github.com/reticlehq/reticle/blob/main/apps/e2e/harness-rules.md) (what a gate must do about all this) and [`telemetry-contract.md`](https://github.com/reticlehq/reticle/blob/main/docs/telemetry-contract.md) (the rules for anything that emits).
+> Companion pages: [`harness-rules.md`](https://github.com/reticlehq/reticle/blob/main/apps/e2e/harness-rules.md) (what a gate must do about all this) and [`contributing/telemetry/contract.md`](https://github.com/reticlehq/reticle/blob/main/contributing/telemetry/contract.md) (the rules for anything that emits).
 
 ## 1. Topology: 5 processes, 4 hops
 
@@ -37,13 +38,13 @@ Each hop has its own failure vocabulary, its own recovery, and its own way of ly
 | # | Step | Owner | Fails how |
 | --- | --- | --- | --- |
 | 1 | client spawns `reticle mcp` over stdio | client | the client's own startup timeout; **no host respawns a dead stdio server** |
-| 2 | proxy probes `:4400` (`probeDaemon`, plain TCP, 500ms) | proxy | a squatter that accepts and never serves looks alive |
+| 2 | proxy probes the bridge port, `4400` by default (`probeDaemon`, plain TCP, 500ms) | proxy | a squatter that accepts and never serves looks alive |
 | 3 | absent → spawn daemon detached, poll to `DAEMON_READY_TIMEOUT_MS` (10s) | proxy | slow CI; raise with `RETICLE_DAEMON_READY_TIMEOUT_MS` |
 | 4 | proxy opens SSE, waits for the `endpoint` frame → POST URL | proxy | an empty frame used to read as "connected"; now refused (`buildSessionUrl`) |
 | 5 | `initialize`, answered **locally** after `LOCAL_HANDSHAKE_MS` (12s) when the daemon cannot | proxy | any client with a startup budget under ~12s loses Reticle for the whole session |
 | 6 | daemon binds `:4400`, writes the pid file, starts bridge + idle watcher | daemon | `EADDRINUSE` → child exits 1, **parent already exited 0** |
 | 7 | app calls `reticle.connect()` → `ws://localhost:4400/reticle` | SDK | wrong port; missing pairing token; mixed content (Safari throws synchronously on `new WebSocket`) |
-| 8 | HELLO: `sessionId`, `projectId`, `protocolVersion`, capabilities | SDK → bridge | version mismatch → `1008` close → **the SDK stops retrying, permanently** |
+| 8 | HELLO: `sessionId`, `projectId`, `protocolVersion`, capabilities | SDK → bridge | version mismatch → `1008` close → **the SDK stops its timed retries**. It dials once more when the person returns to the tab |
 | 9 | bridge authenticates: pairing token / loopback tier / Origin allow-list | bridge | another project's daemon answers → `authFailureReason` names it |
 | 10 | Session registered, `everConnected = true` | daemon | n/a |
 | 11 | tool call → `runTool` → `session.send` → WS command → SDK → reply | all | any hop above, mid-flight |
@@ -56,13 +57,13 @@ Three different counts, all measured, and the difference between them matters:
 
 | Count | What it is |
 | --- | --- |
-| **77** | name constants in `ReticleTool` |
+| **78** | name constants in `ReticleTool` |
 | **30** | tools advertised under `RETICLE_ADVERTISE_ALL_TOOLS=1`, i.e. what `tool-surface-sweep-test` drives |
 | **10** | advertised by default; the rest are reached through `reticle_run { tool, args }` |
 
 The middle number is **family folding**: `reticle_baseline`, `reticle_session`, `reticle_record`, `reticle_flow` and `reticle_lease` each absorb their members behind an `action` parameter. So "every tool is callable" is asserted over the advertised surfaces, not over every named behaviour; a family member reachable only through an `action` value the sweep never passes is not covered by it. Worth closing when the per-tool budget lands (see [`gate-plan.md`](https://github.com/reticlehq/reticle/blob/main/docs/gate-plan.md), Phase 4).
 
-These three were each wrong by the time somebody checked: the table read 68 / 48 / 19 against a measured 76 / 30 / 10 (77 constants since), and the middle one had a derived token cost hanging off it. `surface-sizes.test.ts` is the authority and fails when a surface changes size, so prefer reading it to trusting this row.
+These three were each wrong by the time somebody checked: the table read 68 / 48 / 19 against a measured 76 / 30 / 10 (78 constants since), and the middle one had a derived token cost hanging off it. `surface-sizes.test.ts` is the authority and fails when a surface changes size, so prefer reading it to trusting this row.
 
 | Token | Produced by | Consumed by | Invalidated by |
 | --- | --- | --- | --- |
@@ -116,7 +117,7 @@ Still fragile:
 
 | Failure | Silent | Note |
 | --- | --- | --- |
-| `serve` exits 0 on `EADDRINUSE` | **yes** | #115: the parent reports the spawn, the child reports the bind, nothing joins them |
+| `serve` exits 0 on `EADDRINUSE` | **fixed** | `port-presence.ts` tells `daemon`, `foreign` and `free` apart. `serve` refuses a port that a stranger holds, so it does not report a daemon that never bound. Guarded by `daemon-port-honesty-test` (#115) |
 | liveness is the pid file, never the port | **yes** | `isRunning` in `server/src/command/daemon/daemon.ts` |
 | idle shutdown fires mid-install | **yes** | 5min base / 30min attached; already scored three fixtures as install failures |
 | `isUselessDaemon` ends a daemon that served nothing | **yes** | lifetime facts, but a gate that installs for six minutes before its first call is that daemon |
@@ -128,7 +129,7 @@ Still fragile:
 
 | Failure | Silent | Note |
 | --- | --- | --- |
-| protocol mismatch → `1008` | no, but **terminal** | the SDK stops retrying by design; the app is dark until reload (#127) |
+| protocol mismatch → `1008` | no, but **terminal** | the SDK stops its timed retries by design. It dials once more when the person returns to the tab, and the app stays dark until then (#127) |
 | another project's daemon answers | no | `authFailureReason` is evidence-based, only claiming it when the daemon has demonstrably served another project |
 | `rejectAll('session disconnected')` | **fixed** | used to become `verified:"no" / assertion_failed`, i.e. Reticle blaming the app, by file and line, for its own lost connection. Now `verified:"unknown" / observation_lost` (#124) |
 | reaper ends a quiet session | no | revivable on the agent's next action |
@@ -148,13 +149,13 @@ Still fragile:
 | Layer | Class | Covered by | Gap |
 | --- | --- | --- | --- |
 | stdio | proxy survival | `mcp-survives-test` | external SIGKILL |
-| SSE/POST | unanswered calls | `mcp-stress-test` | fault injection is `kill -9`, not specified toxics |
-| daemon | lifecycle, idle, port | `daemon-lifecycle-test`, `status-honesty-test` | port arbitration, heartbeat |
+| SSE/POST | unanswered calls | `mcp-stress-test`, `transport-faults-test` (`fault-proxy.mjs`) | n/a |
+| daemon | lifecycle, idle, port | `daemon-lifecycle-test`, `status-honesty-test`, `daemon-port-honesty-test`, `daemon-heartbeat-test` | port arbitration |
 | bridge | auth, origins, version | `version-skew-test` | desktop origins under install |
 | SDK | queue, gaps, reconnect | browser unit tests | mid-session outage → verdict |
-| tools | surface, schema, refusals | `tool-surface-sweep-test`, `tool-fuzz-test` | latency/failure budget |
+| tools | surface, schema, refusals | `tool-surface-sweep-test`, `tool-fuzz-test`, the soak (`bench/TOOL-PROFILE.md`) | latency is recorded, not gated |
 | verdict | honesty | `release-smoke-test` | transport ≠ app (#124); false-green rate |
-| telemetry | silent absence | `telemetry-events-test`, `telemetry-contract.test.ts` | chokepoint coverage |
+| telemetry | silent absence | `telemetry-events-test`, `telemetry-contract.test.ts`, `dispatch-chokepoint.test.ts` | n/a |
 | install | pristine-surface wiring | `pnpm gate:install` (thirteen pristine scaffolds) | apps with many plugins: the `reticle-fixtures` repo |
 | client | per-agent MCP compatibility | nothing | the whole class |
 
@@ -168,4 +169,4 @@ Nine of ten layers have a gate. The one that does not, per-agent MCP compatibili
 - **zero orphan spans**; 23 orphans on one healthy run is the documented signature of a hung call
 - `settleTiming` always fires; it sits in a `finally` so a thrown call cannot leak a concurrency slot
 
-Today that output is produced and discarded.
+`trace-shape-test` (`apps/e2e/trace-shape.mjs`) checks the first two on every battery run. The `settleTiming` invariant has no check yet.

package/docs/telemetry.md

@@ -1,16 +1,16 @@
 ---
 title: Telemetry
-description: 'The complete description of the anonymous usage data Reticle collects, what it is for, and how to turn it off.'
+description: 'The complete description of the usage data Reticle collects, what it is for, and how to turn it off.'
 icon: chart-line
 ---
 
-Reticle sends anonymous usage counters (which commands ran, which tools an agent called, whether a verification produced a verdict) and nothing from the app under test. To turn it off permanently, run `npx @reticlehq/server telemetry disable`.
+Reticle sends usage counters (which commands ran, which tools an agent called, whether a verification produced a verdict) and nothing from the app under test. To turn it off permanently, run `npx @reticlehq/server telemetry disable`.
 
 This page is the complete description of what is collected. If something is not listed here, it is not sent.
 
 ## The short version
 
-- **Anonymous.** We cannot tell who you are, and we do not try.
+- **No name, no email, no account.** The events do not carry who you are, and we do not try to find out. Two fields can connect events to an organization: the workspace id of a project you linked, and the licence id of a licensed build. See [the fields on every event](#what-is-sent).
 - **No code, no app data.** Nothing from the app under test (no DOM, no network traffic, no console output, no source, no file paths) ever leaves your machine.
 - **The one exception is feedback you deliberately send us**, and it is never collected passively. See [Feedback](#feedback) below.
 - **Opt out any time**, permanently, with one command:
@@ -21,38 +21,41 @@ This page is the complete description of what is collected. If something is not
 
 ## What is sent
 
-Twenty-two kinds of events, each a single small JSON object. This is the whole list, and it is the same list the code enumerates:
+Twenty-five kinds of events, each a single small JSON object. This is the whole list, and it is the same list the code enumerates:
 
 | Event | When | Extra data |
 | --- | --- | --- |
-| `reticle_installed` | The first time Reticle runs on a machine | n/a |
+| `reticle_installed` | The first real command Reticle runs on a machine. `--version`, `--help` and `telemetry` do not count | Which published install route you came through, declared by that route with `RETICLE_INSTALL_SOURCE` and never inferred, and `unknown` when nothing declared one |
 | `cli_command_run` | You run a `reticle` command | Which subcommand (`verify`, `status`, …) and which flags were present, by name |
 | `daemon_started` | The local daemon starts | n/a |
 | `daemon_stopped` | The local daemon stops | A summary of the session; see below |
 | `session_progress` | Periodically, from a daemon that is still running | The same summary as `daemon_stopped`, marked `final: false`. It exists so a long session is not invisible until it exits |
-| `app_instrumented` | The first time your app's SDK connects in a given daemon run | Nothing beyond the common fields. It is the second half of the install funnel: registering the MCP server is one thing, getting the SDK into a running page is another |
-| `verification_completed` | A verification produces a verdict | Whether it passed, whether Reticle refused to call a passing check verified, and **why** the verdict came out that way; see below |
+| `app_instrumented` | The first time your app's SDK connects in a given daemon run | Whether `reticle init` ran in this folder, whether an agent was already attached, how long the daemon ran before the app connected, and whether this is the first app ever on this machine and project. It is the second half of the install funnel: registering the MCP server is one thing, getting the SDK into a running page is another |
+| `verification_completed` | A verification produces a verdict | Whether it passed, whether Reticle refused to call a passing check verified, **why** the verdict came out that way, and the version of the Reticle SDK in the page; see below |
 | `project_profiled` | Once per daemon start | The shape of the project; see below |
-| `version_changed` | You update or roll back | The two version numbers, and which direction |
+| `version_changed` | Reticle starts on a version that differs from the last start on this machine, or you update or roll back | The two version numbers, which direction, and whether an agent had been told about the new version |
 | `runtime_crashed` | The daemon hits an uncaught error | The error's type, **Reticle's own** stack frames, and the message with variables stripped; see below |
-| `mcp_client_connected` | An agent attaches to the daemon | Whether it is a reconnect, and how long the daemon had been idle |
-| `mcp_connection_lost` | The agent's MCP tools go away | Which stage (`first`, or `budget_spent` when it stopped retrying), the cause, and the attempt count. **At most twice per session**, because a reconnect loop can fire many times in a row and an event each would bill for the pathology instead of measuring it |
+| `mcp_client_connected` | An agent's MCP server attaches to the daemon. A proxy that reconnects does not send it again | Whether this daemon had an agent before, how long the daemon had been up, the client's name from its handshake, whether an app was already connected, and the random id of the process that gives the agent its tools |
+| `mcp_connection_lost` | The agent's MCP tools go away, or come back | Which stage (`first`, `recovered` when the link came back on its own, or `budget_spent` when it stopped retrying), the cause from a closed list, the socket error code from a closed list, the attempt count, how many tool calls in flight the drop killed, and the random id of the process that gives the agent its tools. **Each stage is sent at most once per proxy process** (once for a planned daemon exit and once for a fault), because a reconnect loop can fire many times in a row and an event each would bill for the pathology instead of measuring it. The planned idle exit of the daemon sends no `first` row |
+| `mcp_proxy_exited` | The process that gives your agent its Reticle tools ends | Why it ended (`stdin_end`, `idle`, `client_gone_storm`, `wake_failed`), how long it ran, and two counts: how many times it lost the daemon and how many tool calls it carried, with its random id. Never what the calls were |
+| `daemon_died_unclean` | Reticle finds that an earlier daemon stopped without a clean exit | How long that daemon had run. Nothing else |
+| `wake_refused` | Reticle will not use the daemon port it found, because something else holds it | Whether the holder was another program (`foreign`) or a Reticle daemon for another project (`other_project`). Never the port or the project |
 | `onboarding_step` | One step of getting set up begins, finishes, fails, is skipped, or is walked away from | Which phase (`install`, `onboard`, `first_run`), which step, what became of it, how long it took, and the framework. The step name comes from a closed list we define -- it can only ever be one of the names in `core/src/onboarding.ts`, so nothing you typed or any path on your disk can arrive in it. `unattended` says whether anybody was asked anything |
 | `init_completed` | `reticle init` finishes | Whether it worked, a classified reason when it did not, and which published install route you came through, DECLARED by that route via `RETICLE_INSTALL_SOURCE` and never inferred, and `unknown` when nothing declared one |
 | `bug_found` | Reticle finds a defect in the app under test | The **kind** of defect (`signal-contradicted`, `console-error`, …) and how it was found, never what it was found in |
 | `tool_refused` | A tool cannot do what an agent asked | Which tool, why (one of six buckets: no session, no match, unsupported, bad arguments, not ready, other), and whether the same call was retried. **Never the message**, because a refusal interpolates whatever you asked for, so only the tool name and the bucket are sent. Capped at 50 per daemon run |
 | `feedback_submitted` | **Only** when you or your agent explicitly send feedback | The report; see [Feedback](#feedback). The AGENT's call does not wait for the network: the receipt says `accepted` (validated, redacted, queued), never `sent`, and a delivery that then fails is reported back on the agent's next tool result. `reticle feedback` typed by a human still waits, because a person at a terminal is owed the real answer |
-| `hud_viewed` | You open a page of the in-page HUD (Agent Log, Flows, Notes, Harness, Impact, Settings) or its account menu | Which page, from a closed list, and how many tabs had a HUD (a bucket: `1`, `2-3`, and so on). The same page reopened in the same tab within 30 seconds counts once |
-| `hud_signin_prompted` | The HUD shows you a sign-in or "link this project" prompt | Which prompt (`rail`, `harness` or `header`), once per prompt per tab |
+| `hud_viewed` | You open a page of the in-page HUD (Agent Log, Flows, Notes, Harness, Impact, Settings) or its account menu | Which page, from a closed list, and how many tabs had a HUD (a bucket: `1`, `2-3`, and so on). The same page opened again within 30 seconds counts once for the whole daemon run, also after a reload. The Agent Log that the HUD opens by itself when a page loads is not a view |
+| `hud_signin_prompted` | The HUD shows you a sign-in or "link this project" prompt | Which prompt (`rail`, `harness` or `header`), once per prompt for each daemon run |
 | `platform_linked` | A project on this machine is linked to a Reticle workspace | How (`connect`, `hud` or `link`) and the workspace's id; see [The platform side](#the-platform-side) |
-| `harness_run` | A Reticle Harness run starts, and again when it ends | Who started it (`agent`, `hud`, `dashboard`, `cli_try`, `plan`), whether the platform drove it, and at the end how it went (`proved`, `not_proved`, `failed`, `blocked`, `stopped`) and how many journeys it answered and replayed, as buckets |
+| `harness_run` | A Reticle Harness run starts, and again when it ends | Who started it (`agent`, `hud`, `dashboard`, `cli_try`, `plan`), whether the platform drove it, and at the end how it went (`proved`, `not_proved`, `failed`, `blocked`, `stopped`), how many journeys it answered and replayed, as buckets, and for a `blocked` or `failed` run why it did not drive, from a closed list (`not_linked`, `harness_off`, `no_credits`, and so on) |
 | `identified` | **Never** from this version. Only an earlier version's `reticle identify`, which has been removed | What you chose to tell us then; see [Telling us who you are](#telling-us-who-you-are) |
 
 **There is no per-tool-call event.** Tool usage is counted in memory and leaves once, inside `daemon_stopped`, as a histogram like `{"reticle_act": 40, "reticle_assert": 12}`. That is counts of tool NAMES from a fixed list we define, never arguments, results, selectors, or URLs.
 
 **Parameter and flag NAMES are collected; their VALUES are not.** We record that `reticle_act` was called with `ref` and `action`, and that you ran `reticle serve --headed --port`. We do not record what you set them to. This distinction is the whole safety property, and it is absolute for CLI flags: `--http-token` holds a secret, `--drive` holds a URL, `--storage-state` holds a file path, so no flag value is ever sent. For tool parameters there is one narrow exception: a short, explicit allowlist of parameters whose values are enums _we_ defined (`action: "click"`), listed in [`argument-shape.ts`](https://github.com/reticlehq/reticle/blob/main/server/src/telemetry/argument-shape.ts). A value outside that allowlist reports as `other`, so a future schema change cannot quietly start forwarding free text. `reticle_act`'s `args` (the text being typed into your app, which on a login form is a password) is **never** in that allowlist.
 
-`daemon_stopped` carries: how long the session ran, how many tool calls and of which tools, how long each tool took (total and worst case), how many failed, how many verifications ran, browser/lease connection attempts with their failure causes, and which MCP clients connected (`claude-code`, `cursor`). It also carries how the in-page HUD was used: presses per control (`hudControls`, by the control's name from a closed list Reticle defines, a toggle as `name:on` / `name:off`), how long the HUD sat as a bubble, collapsed or open and on which page (`hudViewMs`, `hudPanelMs`), which rail slides were shown (`hudSlides`), and the order of those presses and views, cut at 60 (`hudJourney`). Control names, never anything typed or shown on the page.
+`daemon_stopped` carries: how long the session ran, how many tool calls and of which tools, how many of those calls came before an app connected, the version of the Reticle SDK in the last page that connected, how long each tool took (total and worst case), how many failed, how many verifications ran, browser/lease connection attempts with their failure causes, and which MCP clients connected (`claude-code`, `cursor`). It also carries how the in-page HUD was used: presses per control (`hudControls`, by the control's name from a closed list Reticle defines, a toggle as `name:on` / `name:off`), how long the HUD sat as a bubble, collapsed or open and on which page (`hudViewMs`, `hudPanelMs`), which rail slides were shown (`hudSlides`), and the order of those presses and views, cut at 60 (`hudJourney`). Control names, never anything typed or shown on the page.
 
 It also carries a snapshot of the **machine's** state (our own process's memory, free and total system RAM, load average and CPU count), taken at shutdown and again on any crash. This is what separates "your machine ran out of memory" from "Reticle has a bug", which otherwise produce identical-looking failures. No hostname, no username, no paths, no process list.
 
@@ -98,11 +101,12 @@ Every event carries the same few fields:
 | Field | What it is | What it is not |
 | --- | --- | --- |
 | `anonymousId` | A random UUID minted locally on first run, stored at `~/.reticle/telemetry-id` | Not derived from your name, email, hardware, or anything else about you |
-| `projectId` | A one-way SHA-256 hash of the git origin URL, or of the directory path outside a repo | Not reversible: we can count _distinct_ projects, but not learn any project's name, URL, or location. Hashing the origin means one repo counts once instead of once per teammate and per clone |
+| `projectId` | A SHA-256 hash of the git origin URL, or of the directory path outside a repo | Not the URL or the path. We use it to count _distinct_ projects. A hash cannot be turned back into a URL, but anyone who has a URL can hash it and compare: for a public repository, the id can be matched to the repository. Hashing the origin means one repo counts once instead of once per teammate and per clone |
 | `actor` | Whether a person or an agent caused this: a typed `reticle` command is a person, an MCP tool call is the agent | Not a claim about _why_. Whether you asked your agent to verify, or it decided to, lives in a prompt Reticle never sees, and we do not guess |
 | `sessionId` | A random id for this daemon run, held in memory and never written to disk | Not a device id and not persistent: a restarted daemon gets a new one. It only groups one run's own events together |
 | `accountState` / `linked` | Whether this machine is signed out, signed in, or signed in with this project linked to a workspace | Not who is signed in: read from whether a sign-in file exists, never from what is in it |
 | `workspaceId` | Only once this project is linked: the Reticle workspace's id, the `orgId` in `.reticle/cloud.json` | Not the workspace's name and not your email. It is the one key the Reticle platform can join this usage to the workspace you created there; see [The platform side](#the-platform-side) |
+| `licenseId` | Only on a licensed (enterprise) build: the id of the licence key it runs with, sent as the event's `organization` group | Not sent by an open-source install. Our licence records connect each licence id to the company that holds the key, so these events are not anonymous to us |
 | `client` | Which coding agent the event came from, from a closed list (`claude_code`, `cursor`, `codex`, and so on, or `other`) | Not the name your agent sent: a name we do not list arrives as `other` |
 | `launch` | How `reticle` was started: `npx`, `global`, `project` or `other` | Not the path it was started from; only the bucket leaves |
 | `projectIdSource` | Whether `projectId` came from a shared git origin or from the local directory path | Not the origin or the path. It exists so we can tell when "how many people share this project" is a real measurement. Outside a pushed repo there is nothing shared to hash, so those rows always show one user |
@@ -110,7 +114,9 @@ Every event carries the same few fields:
 | `os` | The platform (`darwin` / `linux` / `win32`) | Not the OS version, hostname, or hardware |
 | `ci` | Whether the run is inside CI | n/a |
 
-There are no IP-based profiles, no cookies, no fingerprinting, and no person profiles: events are processed in "personless" mode, so they are never joined into an identity.
+There are no IP-based profiles, no cookies, no fingerprinting, and no person profiles: events are processed in "personless" mode, so they are never joined into a person profile.
+
+Your IP address is not stored, and no location is found from it. Each event tells PostHog not to look up a location (`$geoip_disable: true`). Each event also sets `$ip` to `0.0.0.0`, so PostHog does not store the address the request came from. Events from older versions do not do this.
 
 ## The platform side
 
@@ -120,11 +126,11 @@ The sign-in page Reticle opens also says where the sign-in started (`from=termin
 
 ## What is never sent
 
-Your code. Your app's DOM, network requests or responses, console logs, application state, or screenshots. File paths, project names, or git remote URLs. Your name, email or employer. Any account identifier, with one exception you opt into by linking a project: the workspace id, above. Environment variables. Anything typed into the app under test. The names of your flows, baselines, or tests. Error messages, and any stack frame belonging to your application.
+Your code. Your app's DOM, network requests or responses, console logs, application state, or screenshots. File paths, project names, or git remote URLs. Your name or email, except a reply address that you give with [feedback](#feedback). Any account identifier, with two exceptions: the workspace id of a project you linked, and the licence id of a licensed build, both above. Environment variables. Anything typed into the app under test. The names of your flows, baselines, or tests. Error messages, and any stack frame belonging to your application.
 
 A few of these are worth being explicit about, because they are the ones a product team is most tempted by:
 
-- **We do not send your project's name or its GitHub URL.** `projectId` is a one-way hash. It lets us count distinct projects and see that a project came back next week; it cannot be turned back into a repository, and we cannot look you up from it.
+- **We do not send your project's name or its GitHub URL.** `projectId` is a hash of the URL. It lets us count distinct projects and see that a project came back next week. We do not use it to find the repository. The hash is not a secret: for a public repository, anyone who has the URL can compute the same id.
 - **We do not try to work out who you work for.** No domain sniffing, no email inference, no matching a repo against a company. If you _want_ us to know, [email us](#telling-us-who-you-are).
 - **We do not record what you asked your agent to verify.** The `verification_completed` event knows that a verification happened and how it turned out. The prompt behind it is not something Reticle can see, and we do not reconstruct it.
 
@@ -136,14 +142,16 @@ Reticle verifies apps for AI agents, and for a long time it had no way to hear w
 
 | Who | How | What it carries |
 | --- | --- | --- |
-| Your agent | Calls the `reticle_session { action: "feedback" }` MCP tool (after a failure, **or to ask for a feature**) | What it wrote: an analysis, or a request with the goal behind it, what would improve, and how it works around the gap today. Plus the model it is running, which it tells us because MCP cannot |
-| You | Run `npx @reticlehq/server feedback [--rating 1-5] [--bug] "your words"` | Your words and your rating |
+| Your agent | Calls the `reticle_session { action: "feedback" }` MCP tool (after a failure, **or to ask for a feature**) | What it wrote: an analysis, or a request with the goal behind it, what would improve, and how it works around the gap today. Plus the model it is running, which it tells us because MCP cannot. If it gives a call trail, only the Reticle tool names and verdict words in it are kept. Everything else in the trail is removed before it is sent |
+| You | Run `npx @reticlehq/server feedback [--rating 1-5] [--bug] [--contact you@example.com] "your words"` | Your words and your rating, and your reply address if you give one |
 | Your agent, before Reticle works | Runs `npx @reticlehq/server feedback --agent --kind <bug\|gap\|ambiguity\|feature_request\|improvement\|experience> "what happened"` | The same words, filed from the shell. This exists for the phase where there is no daemon and no MCP tools (a failed `init`, half-finished wiring), which is the failure we are otherwise never told about |
 
 Agents are instructed, in the tool description itself, never to include app source, secrets, or user data, and to describe the failure in their own words instead.
 
 **It is redacted before it leaves your machine.** Emails, credentials in URLs, `Authorization` headers and API-key assignments, recognizable vendor tokens (`sk-…`, `ghp_…`, `AKIA…`, `xoxb-…`, JWTs), and home-directory paths are stripped and replaced with `[redacted]`. This runs client-side, in [`feedback.ts`](https://github.com/reticlehq/reticle/blob/main/server/src/telemetry/feedback.ts), so you can read exactly what it removes rather than take our word for it. It is a safety net, not a guarantee: it cannot catch a secret that looks like an ordinary sentence, which is why the instruction above comes first.
 
+**A reply address is sent only when you give it.** `--contact you@example.com` on `reticle feedback` adds one email address so that the maintainers can answer you. Your agent can pass one on with `contact`, but only an address that you typed for this purpose. It must not guess one or reuse one from somewhere else. The address goes as `feedback_contact` on that one report. It is not redacted, because you gave it to be read. Without `--contact` or `contact`, no address is sent.
+
 **It shows you what it sends.** `reticle feedback` prints the exact payload before transmitting, and names any redaction rule that fired.
 
 Alongside the report, a feedback event carries context about the environment it came from, never about you:
@@ -154,13 +162,13 @@ Alongside the report, a feedback event carries context about the environment it
 | `runtime` | `web`, `electron`, `tauri` | Desktop bugs look nothing like browser bugs |
 | `engine` | `blink`, `gecko`, `webkit` | Coarse bucket, never the user-agent string |
 | `driver` | `cdp`, `sdk` | Whether Reticle drove the page or observed your own browser |
-| `client` | `claude-code`, `cursor` | The MCP client's own name from its handshake |
+| `client` / `clientVersion` | `claude-code` / `1.0.0` | The MCP client's own name and version from its handshake |
 | `mcpScope` | `user`, `project` | How Reticle is registered |
 | `kind` | `bug`, `gap`, `ambiguity`, `feature_request`, `improvement`, `experience` | A defect, a blind spot, an undecidable verdict, a thing that does not exist, a thing that exists but is awkward, or a human's overall take |
 
 Plus the `version`, `os`, and `ci` fields every event carries. No paths, no project name, no dependency list, no user-agent string.
 
-**It has its own off switch.** To keep the anonymous counters but never send free text:
+**It has its own off switch.** To keep the usage counters but never send free text:
 
 ```bash
 RETICLE_FEEDBACK=0
@@ -170,9 +178,9 @@ Every switch in [Your choices](#your-choices) disables feedback too. If telemetr
 
 ## Telling us who you are
 
-Everything above is anonymous, and stays that way. There is no command that sends who you are: `reticle identify`, which used to, has been removed, and this version never sends an `identified` event. If you want support, an enterprise licence, or to be a design partner, email support@reticlehq.com.
+Nothing above names you, and no command adds your name: `reticle identify`, which used to, has been removed, and this version never sends an `identified` event. If you want support, an enterprise licence, or to be a design partner, email hey@reticle.sh.
 
-An identity sent by an earlier version with `reticle identify` stays linked to that machine's anonymous id until you ask for it to be removed: email support@reticlehq.com.
+An identity sent by an earlier version with `reticle identify` stays linked to that machine's anonymous id until you ask for it to be removed: email hey@reticle.sh.
 
 ## Where it goes
 

package/docs/testing.md

@@ -55,7 +55,7 @@ Any failed matcher throws with the structured evidence (near-miss, failure reaso
 ## Deterministic + honest
 
 - **`t.clock`** bakes `reticle_clock` into the spec, so time-gated UI (a 5s auto-dismiss, a 500ms hover dwell) is tested deterministically instead of racing real timers.
-- **`t.expectInputModeReal()`**: a hover/drag spec asserts native input is active; if it's running synthetic (no CDP), the spec is **skipped with a reason**, never silently passing on a no-op. Enable real input headless with `reticle drive` (see [usage §18](usage.md#18-real-input-mode-native-hover--drag)).
+- **`t.expectInputModeReal()`**: a hover/drag spec asserts native input is active; if it's running synthetic (no CDP), the spec is **skipped with a reason**, never silently passing on a no-op. Enable real input headless with `reticle drive` (see [usage §18](usage.md#18-real-input-mode-native-hover-&-drag)).
 
 ## Run a suite (headless, the same path CI uses)
 
@@ -70,7 +70,7 @@ const booted = await bootSession({ driveUrl: 'http://localhost:4310', headless:
 const { summary } = await runSpecs({
   invoke: booted.invoke,
   now: () => Date.now(),
-  buildContext: (invoke) => createTestContext(invoke, { sessionId: 'my-app' }),
+  buildContext: (invoke) => createTestContext(invoke), // one tab: omit sessionId
   print: (line) => process.stdout.write(line + '\n'),
 });
 await booted.close();
@@ -88,10 +88,14 @@ import { toJUnitXml, writeJUnit } from '@reticlehq/test';
 `.reticle/` flows (see [Flows](flows.md)) can be executed directly as specs, replayed with their `expect`/`success` predicates and skipping `dynamic` (LLM-output) regions, so the recorded map and the suite can't drift apart:
 
 ```ts
-import { flowsAsSpecs } from '@reticlehq/test';
-// register one reticleTest per flow under .reticle/flows/
+import { registerFlowSpecs } from '@reticlehq/test';
+// In a vitest file: one test per flow under .reticle/flows/. Await it at the top level.
+// `session` is the FlowReplaySession (from @reticlehq/server) for the app under test.
+await registerFlowSpecs('.reticle/flows', () => session);
 ```
 
+Without vitest, `flowsAsSpecs('.reticle/flows')` returns the specs. Call `await spec.run(session)` on each one, and read `outcome` (`pass` or `fail`).
+
 ## Authoring tip: record → prune → commit
 
 You don't have to hand-write steps. Drive the flow once (or record it via the panel), let Reticle emit the program, trim it, and commit it as a spec. The regression test is a byproduct of testing, not separate work.
@@ -126,4 +130,4 @@ Yes, `toJUnitXml` and `writeJUnit` are both exported from `@reticlehq/test`. Pas
 
 ### Do I have to write specs by hand if I already have flows?
 
-No. `flowsAsSpecs` registers one `reticleTest` per flow under `.reticle/flows/`, replayed with that flow's own `expect` and `success` predicates and skipping its `dynamic` regions. That keeps the recorded map and the CI suite from drifting apart, because they are the same artifact.
+No. `registerFlowSpecs` registers one vitest test for each flow under `.reticle/flows/`. Each test replays the flow's own `expect` and `success` predicates and skips its `dynamic` regions. These are vitest tests, not `reticleTest` specs, so `runSpecs` does not run them. That keeps the recorded map and the CI suite from drifting apart, because they are the same artifact.

package/docs/tools/act-and-wait.mdx

@@ -90,29 +90,32 @@ Real response. The `initiatorStack`, `storageDiffs` and per-event trace detail a
     "coverage": { "pct": 100, "partial": false },
     "integrity": { "clean": true, "issues": [] }
   },
+  "engineBlindSpots": [],
   "since": 44395
 }
 ```
 
 `trace` is a digest of what the app did in the window. When the counts are not enough, pass the top-level `since` cursor to [`reticle_observe`](/tools/observe) for the per-event timeline.
 
+`engineBlindSpots` lists what Reticle could not see in this session: `pixels-unobserved` once an action ran with a `<canvas>` on screen, and `claim-arithmetic-unchecked` while a claim states an amount and no `compare` ran. Do not call a run clean while it holds an entry.
+
 ## The predicate grammar
 
 `until` takes `{ kind, ...fields }`. The kinds:
 
-| Kind                      | Asserts                                                        |
-| ------------------------- | -------------------------------------------------------------- |
-| `signal`                  | The app fired a named signal, the strongest evidence available |
-| `state`                   | A store path reached a value                                   |
-| `net`                     | A request matched; `count` asserts an **exact** number         |
-| `route`                   | The route **changed**                                          |
-| `element`                 | An element appeared; `absent: true` asserts it went away       |
-| `text`                    | Text appeared or, with `absent`, disappeared                   |
-| `console`                 | Something logged; `absent: true` asserts a clean console       |
-| `animation`               | An animation ran or finished                                   |
-| `settled`                 | The page went quiet                                            |
-| `compare`                 | Two readings agree                                             |
-| `allOf` / `anyOf` / `not` | Combine the above                                              |
+| Kind | Asserts |
+| --- | --- |
+| `signal` | The app fired a signal, the strongest evidence available. With no `name`, only the app's own signals count, not Reticle's `reticle:` signals. `count` is exact |
+| `state` | A store path reached a value |
+| `net` | A request matched. `count` is **exact**, `count: 0` means it never fired, and no `count` means at least one |
+| `route` | The route **changed** |
+| `element` | An element appeared; `absent: true` asserts it went away |
+| `text` | Text appeared or, with `absent`, disappeared |
+| `console` | Something logged; `absent: true` asserts a clean console |
+| `animation` | An animation ran or finished |
+| `settled` | The page went quiet |
+| `compare` | Two readings agree |
+| `allOf` / `anyOf` / `not` | Combine the above |
 
 ### Predicates that catch real bugs
 
@@ -169,6 +172,7 @@ A verification tool that cannot describe the quality of its own evidence is aski
 | `timeout_ms` | Maximum wait, defaulting to 4000. `0` evaluates the predicate once, no wait |
 | `refuseWhenThrottled` | Throw rather than act on a throttled tab |
 | `intent` | What the change is supposed to make true, in prose, or the id of an intent declared earlier. Recorded on the verdict |
+| `detail` | `"compact"` keeps only the deciding fields. Omit it for the full result |
 | `durable` | After a `yes`, reload the page and require the element, text and state parts of `until` to hold again. A consequence that is gone after the reload turns the verdict into `no`: the UI advanced, the change did not persist |
 
 Omitting `until` waits for network and DOM idle, which is the deterministic replacement for a fixed sleep. To assert a consequence **and** settle, combine them:

package/docs/tools/act-sequence.mdx

@@ -45,72 +45,50 @@ Steps may also name a `target` instead of a `ref`, the same locator [`reticle_ac
 }
 ```
 
-Real response. Each `effects[]` entry also carries `targetMatched`, `visible`, `enabled`, `defaultPrevented`, `occluded`, `occludedBy` and `scrolledIntoView`, and each `steps[]` entry also carries `dispatched`, `settled`, `settleReason`, `component`, `role` and `name`. Those are trimmed here for length:
+Real response shape, trimmed. Each `steps[]` entry also carries `settled`, `settleReason`, `component`, `role` and `name`, and `window`, `digest` and `contradictions` for that step:
 
 ```json
 {
   "since": 3915,
   "dispatched": true,
-  "result": {
-    "ok": true,
-    "count": 3,
-    "effects": [
-      {
-        "dispatched": true,
-        "focusMoved": "null->e603",
-        "valueChanged": false,
-        "domMutatedWithin": 0
-      },
-      {
-        "dispatched": true,
-        "focusMoved": "e603->e604",
-        "valueChanged": true,
-        "domMutatedWithin": 9
-      },
-      {
-        "dispatched": true,
-        "focusMoved": "e604->null",
-        "domMutatedWithin": 15,
-        "appeared": "Signing in… | Invalid email or password | Sign in"
-      }
-    ],
-    "steps": [
-      {
-        "ref": "e603",
-        "action": "fill",
-        "testid": "login-email",
-        "source": { "file": "src/components/Login.tsx", "line": 48 }
-      },
-      {
-        "ref": "e604",
-        "action": "fill",
-        "testid": "login-password",
-        "source": { "file": "src/components/Login.tsx", "line": 59 }
-      },
-      {
-        "ref": "e605",
-        "action": "click",
-        "testid": "login-submit",
-        "source": { "file": "src/components/Login.tsx", "line": 81 }
-      }
-    ]
-  }
+  "completed": 3,
+  "recorded": 3,
+  "verified": "unknown",
+  "because": "all 3 step(s) declared nothing, so the app was driven but not verified: give each step an `expect` naming the consequence it causes",
+  "coverage": { "declared": 0, "total": 3 },
+  "steps": [
+    {
+      "ref": "e603",
+      "action": "fill",
+      "dispatched": true,
+      "testid": "login-email",
+      "source": { "file": "src/components/Login.tsx", "line": 48 }
+    },
+    {
+      "ref": "e604",
+      "action": "fill",
+      "dispatched": true,
+      "testid": "login-password",
+      "source": { "file": "src/components/Login.tsx", "line": 59 }
+    },
+    {
+      "ref": "e605",
+      "action": "click",
+      "dispatched": true,
+      "testid": "login-submit",
+      "source": { "file": "src/components/Login.tsx", "line": 81 }
+    }
+  ]
 }
 ```
 
 ## Read that response again
 
-`ok: true`. `count: 3`. Every step dispatched. And the login **failed**, look at `appeared`:
-
-```
-"appeared": "Signing in… | Invalid email or password | Sign in"
-```
-
-That password was wrong. The app rejected it. And this tool still reported `ok: true`, correctly, because `ok` means _the three actions were dispatched_, which they were.
+Every step dispatched. In this run the password was wrong, and the login **failed**. No step declared an `expect`, so the sequence cannot know that. It does not claim a pass: it answers `verified: "unknown"`, and `because` says that the app was driven but not verified.
 
 <Warning>
-  `ok: true` is a statement about the input, not about the outcome. A step with no `expect` proves
-  nothing. Put an `expect` on the step that ends the journey, or finish with
+  `dispatched: true` is a statement about the input, not about the outcome. A step with no `expect`
+  proves nothing. Put an `expect` on the step that ends the journey, or finish with
   [`reticle_act_and_wait`](/tools/act-and-wait) or [`reticle_assert`](/tools/assert).
 </Warning>
 
@@ -136,24 +114,20 @@ which returns the verdict. Putting `"expect": { "kind": "signal", "name": "auth:
 ```json
 {
   "verified": "yes",
-  "verifiedReason": "proved",
-  "because": "assertion held at signal grade over a clean capture with no channel disagreeing",
-  "verdict": {
-    "pass": true,
-    "evidence": { "name": "auth:granted", "data": { "email": "admin@reticle.dev" } }
-  },
-  "honesty": { "grade": "signal", "coverage": { "pct": 100, "partial": false } }
+  "because": "every declared consequence held, but only 1 of 3 steps declared one; the rest were driven, not verified",
+  "coverage": { "declared": 1, "total": 3 }
 }
 ```
 
-Two calls instead of four, and the last one returns a verdict. Note `grade: "signal"`, the strongest Reticle awards, because the app said so itself.
+Two calls instead of four, and the last one returns a verdict. A proved plan also carries `keep`, which is the call that saves it as a regression flow.
 
 ## What each step reports
 
-Every step comes back with the same `effect` fields as [`reticle_act`](/tools/act): `valueChanged`, `focusMoved`, `domMutatedWithin`, `occluded`. Plus its `testid`, `component` and `source`. When a sequence goes wrong, that per-step detail tells you which step, and which line of which file.
+Each step comes back with its `testid`, `component` and `source`, its `digest` (what the app did, as counts) and any `contradictions`. A step with an `expect` also carries `held`, and `observed` when it missed. When a sequence goes wrong, this tells you which step, and which line of which file.
 
 <Note>
-  Steps run in order and do not stop on a soft failure, because "the field rejected the value" is
-  not an exception. It's a result you need to see. Read `effects[]` rather than assuming `ok: true`
-  means all three did what you wanted.
+  A step that cannot be performed stops the sequence: `stalled_at` names it, and the step's `error`
+  says why. A step whose `expect` does not hold stops it too (`stopped_at`), unless you pass
+  `onDeviation: "continue"`. The steps that did not run come back unchanged in `tail`. Read
+  `verified` and `because`, not `dispatched`.
 </Note>

package/docs/tools/act.mdx

@@ -61,6 +61,8 @@ Real response:
 
 `click` · `dblclick` · `hover` · `focus` · `blur` · `fill` · `type` · `clear` · `select` · `check` · `uncheck` · `submit` · `press` · `upload` · `scrollIntoView` · `scroll` · `drag` · `tap` · `zoom`
 
+Name the element with `ref`, or with `target` to find it in the same call: `{ testid }`, `{ text }`, `{ role, name }` or `{ label }`. A `target` that matches more than one element is refused. A press of Escape, Tab or a shortcut such as Cmd+K needs neither.
+
 | Action           | Arguments                                                       |
 | ---------------- | --------------------------------------------------------------- |
 | `fill`, `select` | `{ value }`                                                     |
@@ -72,11 +74,11 @@ Real response:
 
 This is where `act` earns its place even though it proves nothing.
 
-- **`valueChanged: true`**. The field actually took the value. `false` on a `fill` usually means the input is controlled and rejected it, or it's readonly.
-- **`focusMoved: "null->e104"`**, focus went where you expected.
-- **`domMutatedWithin: 9`**, something re-rendered within 9ms. A `fill` that mutates nothing often means no handler is attached.
-- **`defaultPrevented`**. A handler called `preventDefault()`, which is why your form didn't submit.
-- **`occluded` / `occludedBy`**. The click landed on something else. This is the answer to at least half of all "the button doesn't work" reports.
+- **`valueChanged: true`**: the field took the value. `false` on a `fill` usually means that the input is controlled and rejected it, or that it is readonly.
+- **`focusMoved: "null->e104"`**: focus went where you expected.
+- **`domMutatedWithin: 9`**: something re-rendered within 9 ms. A `fill` that changes nothing often means that no handler is attached.
+- **`defaultPrevented`**: a handler called `preventDefault()`, which is why your form did not submit.
+- **`occluded` / `occludedBy`**: the click landed on something else. This is the answer to at least half of all "the button does not work" reports.
 
 ## `settled: false` is not a failure
 

package/docs/tools/assert.mdx

@@ -10,7 +10,7 @@ Verdicts come from [`reticle_act_and_wait`](/tools/act-and-wait), `reticle_asser
 
 ## A real failure
 
-Failures are more instructive than passes, so here is one. I asserted that signing in lands on `/dashboard`, after a click that did not navigate. The page was still on `/login`:
+Failures teach more than passes. This assert claims that signing in lands on `/dashboard`, after a click that did not navigate. The page was still on `/login`:
 
 ```json
 { "predicate": { "kind": "route", "pathname": "/dashboard" } }

package/docs/tools/look.mdx

@@ -12,7 +12,7 @@ icon: magnifying-glass
 
 | `action` | What it returns | Unmerged name | Details |
 | --- | --- | --- | --- |
-| `page` (default) | The semantic snapshot of what is rendered, with a `ref` for each control. `mode: "interactive"` keeps only what you can act on; `diff: true` returns only what changed since the last look | `reticle_snapshot` | [Snapshot](/tools/snapshot) |
+| `page` (default) | The semantic snapshot of what is rendered, with a `ref` for each control. `mode: "interactive"` keeps only what you can act on; `diff: true` returns only what changed since the last look; `ids: true` adds each control's test id; `audit: true` also reports clipped text, overlapping controls and low contrast | `reticle_snapshot` | [Snapshot](/tools/snapshot) |
 | `find` | A locator (testid, role, text, label, component) resolved to refs you can act on. `limit` caps the list; `count_only` returns just the count | `reticle_query` | [Query](/tools/query) |
 | `element` | Everything about one `ref`: geometry, scroll, design tokens, and on React the source `file:line` | `reticle_inspect` | [Inspect](/tools/inspect) |
 | `state` | A registered store's value. Scope it with `store`, `path` and `depth` | `reticle_state` | [State](/tools/state) |

package/docs/tools/navigate.mdx

@@ -44,7 +44,7 @@ Most tools would return `ok: true` and let you assume arrival. When the page the
 
 `confirmed: false` with a `landedOn` URL is a different case: the page arrived, but the app sent it somewhere else, such as a login or route-guard redirect. `landedOn` says where the browser actually is.
 
-`waitedMs` says which of two things you are looking at. Reticle stopped waiting at the budget it had, or the page never came back. The first is fixed by asking for more: a single-page app reattaching under HMR has been measured at 30–60s, which no default should wait for on every call, but which the caller who knows the app can grant.
+`waitedMs` is how long Reticle waited for the page to come back before it stopped. The page may still arrive after that. A single-page app that reattaches under HMR can take 30–60 s, so give a slow app a larger `timeout_ms`:
 
 ```json
 { "url": "/deployments", "timeout_ms": 45000 }