@reticlehq/server 2.4.0 → 2.6.0

package/docs/platform-integration.md

@@ -0,0 +1,122 @@
+# Integrating Reticle
+
+> The one guide for adopting Reticle — for a team using a coding agent on its own app, and for an AI app-builder platform (Lovable / Emergent / Bolt) embedding Reticle in its generation pipeline. Reticle reads the program from _inside_ a running app and returns a **verdict with evidence** ("did it actually work?"), not a screenshot. Enterprise/premium access lives in [`enterprise.md`](./enterprise.md).
+
+## The loop
+
+```
+generate / edit  →  boot the preview  →  Reticle verifies the critical flows  →  verdict + evidence + repair
+                                                                                │
+                                         PASS → ship & attach "verified ✓"      │
+                                         FAIL → gate the deploy, feed repair packets to the fixer agent
+```
+
+One call replays the app's key journeys and asserts **program truth** — network cardinality, store/state, emitted signals, console — then returns a deterministic, un-hallucinatable verdict.
+
+---
+
+## Quickstart
+
+### A. A team, agent on your own app (~10 min)
+
+```bash
+npx @reticlehq/server init   # auto-detects your framework, installs the kit + build plugin
+```
+
+Paste to your agent (Claude Code / Cursor / any MCP agent): `Follow https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md` It runs the wizard once (Vite/Next plugin + SDK init + MCP config), then verifies on every change. Run your dev server, then ask the agent to _"verify it with Reticle."_
+
+### B. A platform / CI, driven from your pipeline (no MCP, no human)
+
+```bash
+reticle serve --http --http-token "$TOKEN" --drive "$PREVIEW_URL"   # localhost:7331
+```
+
+```js
+const { run } = await (
+  await fetch('http://127.0.0.1:7331/verify', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-reticle-token': process.env.TOKEN },
+    body: JSON.stringify({
+      project: { name, framework, previewUrl },
+      trigger: { kind: 'oem', diffRef },
+    }),
+  })
+).json();
+
+if (run.verdict.status !== 'pass') {
+  for (const p of run.repair?.failurePackets ?? []) fixerAgent.send(p.suggestedPrompt); // self-heal
+  blockDeploy(run);
+} else attachToDeploy(run); // "verified ✓"; set profile:"prod-preview" to redact internals downstream
+```
+
+Or skip the HTTP server entirely with the one-shot CLI — `reticle verify <preview-url>` drives the preview, replays the saved flows, prints the verdict, and exits non-zero on fail (ideal for a CI step).
+
+---
+
+## In-app SDK integration — the effort, by layer
+
+Reticle embeds a **dev/preview-only** SDK (`@reticlehq/browser`, Apache-2.0, tree-shaken from production). For a platform you add this **once to your generated-app template** → every generated app is verifiable.
+
+| Layer | What you add | Unlocks | Effort |
+| --- | --- | --- | --- |
+| **1 — drive + DOM/network/console** | 1 build-plugin line + ~10-line dev-only `reticle.connect({…})` file (`npx @reticlehq/server init` does it) | broken routes, network status/cardinality (double-submit), console errors, persistence-after-reload | **Easy** (~15 min) |
+| **2 — program-state truth** | `registerStore('app', store)` (1/store, pass the store itself so mutations emit diffs) + `reticle.signal('order:saved', …)` (1/consequence) + `data-testid`s | UI-vs-store desync, dead handlers, blast-radius, source mapping | **Easy–Medium** (an afternoon, once) |
+| **3 — governance (optional)** | `registerCapabilities(...)` (signals/stores/risk zones) + recorded flows with success oracles | risk policy + sharper verdicts | **Medium**, optional |
+
+Copyable patterns: `apps/bench-app/src/reticle-dev.ts`, `apps/next-smoke/app/reticle-dev.tsx`. Without instrumentation, Layer-1 checks still work via the driven browser; Layers 2–3 are what no out-of-page tool can see.
+
+---
+
+## What it catches that a screenshot can't
+
+| Silent failure (a generated app ships it) | How Reticle catches it |
+| --- | --- |
+| Mock data — POST 200, row shows, nothing persists | persistence/`state` oracle (doesn't survive reload) |
+| Dead handler — looks done, store never changed | `state` desync |
+| Double-submit — one click, two POSTs | `net { count: 1 }` |
+| Forbidden call — a must-never-fire endpoint fired | `net { count: 0 }` |
+| Missing validation — `"abc"` becomes data | flow oracle (error shown AND nothing created) |
+| Silent console error — logged, UI still renders | `console { absent: true }` |
+| UI-vs-store desync — the total lies | reads the store, contradicts the display |
+| Blast-radius — an action corrupts unrelated state | `state { hold:true }` invariant |
+
+Live, clickable demo of each: `apps/vibe-builder-demo/` (set `BUG_MODE=…`). Proven in CI: `packages/server/src/runs/generated-app-bugs.test.ts`.
+
+---
+
+## Exact steps per platform
+
+The shape is identical (in-app SDK in the template → verify in the sandbox → act on the verdict); the specifics differ by where each platform runs the preview.
+
+### Emergent (Kubernetes pod per build, reverse-proxied preview URL)
+
+1. Add `@reticlehq/browser` + `registerStore`/`reticle.signal` to the generated-app **scaffold** (one time).
+2. In the build pod, alongside the preview: `reticle serve --http --http-token "$POD_TOKEN" --drive "$PREVIEW_URL"` (or import `ReticleRunner` in-process).
+3. In the orchestrator's generate→test→iterate loop, `POST /verify` after the preview boots.
+4. FAIL → route `repair.failurePackets[].suggestedPrompt` to the fixer subagent → re-verify (closes the loop). PASS → publish + attach the `prod-preview` run as the user-facing "verified ✓".
+
+### Lovable (Vite/React generated apps, hosted preview)
+
+1. Add the Reticle Vite plugin + dev-only `reticle.connect` to the project template (Lovable already templates Vite/React — it's one plugin line + the connect file).
+2. Run `reticle serve --http --drive <preview-url>` against the preview build in the generation worker.
+3. Call `/verify` after each generate/edit; gate the "your app is ready" signal on `verdict.status === 'pass'`; feed repair packets back into the edit agent.
+
+### Bolt.new / StackBlitz (WebContainer, in-browser runtime)
+
+1. Add the SDK to the WebContainer app template; the app + Reticle bridge run in the WebContainer.
+2. Since the runtime is in-browser, drive via the connected session (the SDK dials the bridge) rather than `--drive`; call verify from the Bolt agent after a build.
+3. Same act-on-verdict: gate + self-heal with the repair packets. (Bolt already detects terminal/compile errors; Reticle adds the _runtime program-truth_ layer it's blind to.)
+
+> Honest note: a platform can build a verification step itself. Reticle's case is the depth (program-state and source mapping), the determinism (0% flake, no LLM in the loop), the un-hallucinatable verdict, and a stable drop-in artifact. The reproducible benchmark in [`bench/`](../bench/README.md) measures the observation-cost and detection differences against other browser-automation MCPs.
+
+---
+
+## The verdict artifact
+
+`POST /verify` (and `reticle_run_export`) return a stable, versioned `ReticleVerificationRun` (defined in `@reticlehq/core`): `verdict` (pass/fail/partial, confidence, blockingRisks), `flows[]`, `checks[]`, `risks[]` (auth/payment/db/…), `repair.failurePackets[]` (what + where to fix), `evidence`. Render a legible report with `renderRunReport()` or `reticle_run_export { format: "report" }`. Profiles: `dev` (full) vs `prod-preview` (source + state redacted for downstream sharing).
+
+**Why trust it:** the verdict is mechanical — derived only from observed outcomes — so it can't report green for something it never ran (a severed backend reads as _fail_, never a confident pass). Proof: `packages/server/src/runs/false-green.test.ts`.
+
+## Licensing for embedding
+
+The embeddable SDK is **Apache-2.0** (ship it in your customers' apps). The server/CLI is **FSL** (free, no competing resale). Enterprise features + the premium-access flow: [`enterprise.md`](./enterprise.md). OEM terms: **[hey@reticle.sh](mailto:hey@reticle.sh)**.

package/docs/system-map.md

@@ -0,0 +1,152 @@
+# System map
+
+> 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`](../apps/e2e/harness-rules.md) (what a gate must do about all this) and [`telemetry-contract.md`](./telemetry-contract.md) (the rules for anything that emits).
+
+## 1. Topology — 5 processes, 4 hops
+
+```
+coding agent ──stdio──▶ reticle mcp ──HTTP POST──▶ daemon :4400 ──WebSocket──▶ browser SDK ──▶ your app
+  (client)     JSON-RPC   (proxy)   ◀───SSE─────  (bridge+tools)  ◀─────────  (@reticlehq/browser)
+                                                        │
+                                                        └─▶ .reticle/  flows · capsules · baselines · runs
+```
+
+Each hop has its own failure vocabulary, its own recovery, and its own way of lying. Nothing stated this end to end until this page, which is why gate results have been contradictory.
+
+## 2. Connection establishment
+
+| # | 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 |
+| 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** |
+| 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 | — |
+| 11 | tool call → `runTool` → `session.send` → WS command → SDK → reply | all | any hop above, mid-flight |
+
+**Sequencing hazard:** steps 6 and 7 race. The product absorbs it internally — the first live tool call blocks briefly for a session to appear rather than failing — but a gate that boots an app and immediately asks whether a session exists is outside that protection and has been burned by it. Poll for the session; never sample once.
+
+## 3. The tool graph — what produces what
+
+Three different counts, all measured, and the difference between them matters:
+
+| Count | What it is |
+| --- | --- |
+| **68** | name constants in `ReticleTool` |
+| **48** | tools advertised under `RETICLE_ADVERTISE_ALL_TOOLS=1` — what `tool-surface-sweep-test` drives (51 calls) |
+| **17** | advertised by default; the rest are reached through `reticle_run` |
+
+68 → 48 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 48 surfaces, not 68 behaviours — 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`](./gate-plan.md), Phase 4).
+
+| Token | Produced by | Consumed by | Invalidated by |
+| --- | --- | --- | --- |
+| `sessionId` | `reticle_sessions`, HELLO | ~every tool | tab close; **survives reload** via `sessionStorage` |
+| `ref` (`e115`) | `snapshot`, `query`, `scroll_to` | `inspect`, `act`, `act_and_wait`, `state` | any re-render — refuses cleanly rather than clicking the new occupant |
+| `actionId` (`a2`) | `act`, `act_and_wait` | `observe`, `network`, `console` filters | window expiry |
+| `since` cursor | every read | every read | ring-buffer eviction |
+| `capsuleSaved` | `act_and_wait` | `replay` | — |
+| flow | `record_start` → acts → `flow_save_recorded` | `flow_verify`, `flow_replay`, `flow_heal`, `affected`, `gate` | DOM drift → `flow_heal` |
+| baseline | `baseline_save`, `viewport` | `visual_diff`, `diff` | viewport change |
+| `session_lease` | direct tool results | the agent (`yield` / `end`) | **dropped on the `reticle_run` path** (#119) |
+| run artifact | `run_export`, `reticle verify` | CI, `reticle gate` | — |
+
+Two structural facts:
+
+- **`reticle_run` is a second dispatch path.** It routes through `runTool`, so telemetry is intact, but anything decorating results _above_ `runTool` silently does not apply. The session lease is the instance we know about; the next decorator inherits the same bug.
+- **`record → save → verify → heal` is the only model-free loop**, and it is what makes a cheap gate possible at all.
+
+## 4. Fragility inventory
+
+**Silent** = fails with no error surfaced to the agent or the user.
+
+### Hop 1 — client ↔ proxy
+
+| Failure | Silent | Guarded by |
+| --- | --- | --- |
+| proxy killed externally (the `lsof -ti` recipe) | **yes, total** | nothing — needs `reticle kill` (#114). See [harness rule 1](../apps/e2e/harness-rules.md) |
+| proxy uncaught exception | no | `installProxyResilience` + `proxyLog` |
+| proxy exits when the reconnect budget is spent | _was the worst bug in the product_ | `onReconnectBudgetSpent` → DORMANT, never exit |
+| client closes stdin with calls in flight | no | `SHUTDOWN_DRAIN_MS` (5s) |
+
+### Hop 2 — proxy ↔ daemon
+
+Three distinct populations of unanswered call, **all covered**:
+
+| Population                                    | Answered by                        |
+| --------------------------------------------- | ---------------------------------- |
+| forwarded, then the SSE stream dropped        | `streamLossReplies` → `-32001`     |
+| queued while dormant/reconnecting, never sent | `QUEUE_WAIT_MS` (20s) → `-32001`   |
+| POST-leg `ECONNRESET` while SSE is healthy    | `postToSession` returns the reason |
+
+Still fragile:
+
+| Failure | Silent | Note |
+| --- | --- | --- |
+| squatter on `:4400` | partly | 12s handshake, then the first tool call diagnoses it |
+| stale tool catalog served while dormant | **yes** | `ToolCatalogCache` answers `tools/list` from cache; after a version change a client can hold a catalog the daemon no longer implements |
+| handshake replay regresses | **yes** | the daemon builds a fresh `McpServer` per SSE connection, so every `tools/call` would hit an uninitialized server |
+
+### Hop 3 — daemon lifecycle
+
+| Failure | Silent | Note |
+| --- | --- | --- |
+| `serve` exits 0 on `EADDRINUSE` | **yes** | #115 — the parent reports the spawn, the child reports the bind, nothing joins them |
+| liveness is the pid file, never the port | **yes** | `daemon/daemon.ts:156` |
+| 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 |
+| a daemon spawned inside a tool call is reaped when the call ends | **yes** | `SIGTERM` within ~1s, `detached` or not |
+| no `daemon_alive` heartbeat | **fixed** | a killed daemon and a tidy exit used to read identically; the daemon now beats every 30s and `classifyDaemonLife` turns silence into `died_silently` (#123) |
+| no port arbitration | **yes** | a second daemon can bind a port a first one held |
+
+### Hop 4 — bridge ↔ SDK
+
+| Failure | Silent | Note |
+| --- | --- | --- |
+| protocol mismatch → `1008` | no, but **terminal** | the SDK stops retrying by design; the app is dark until reload (#127) |
+| another project's daemon answers | no | `authFailureReason` — evidence-based, only claims it when the daemon has demonstrably served another project |
+| `rejectAll('session disconnected')` | **fixed** | used to become `verified:"no" / assertion_failed` — 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 |
+| opaque origins (`tauri://localhost`, `file://`) | no | kept verbatim in the allow-list rather than collapsed to `"null"` |
+
+### Hop 5 — SDK internals
+
+| Failure | Silent | Note |
+| --- | --- | --- |
+| fixed 1s reconnect, no backoff, unbounded | **yes** | and the noise lands in the console channel we report to the agent (#116) |
+| `onUnreachable` suppressed after the first success | **yes** | a **mid-session** outage never warns at all |
+| offline queue overflow (`MAX_QUEUE = 500`) | no | gap marker stamped at the **oldest** drop — the honest floor for where the hole starts |
+| `sessionStorage` throws in a sandboxed iframe | no | falls back; a session must still start |
+
+## 5. Where the gates are
+
+| 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 |
+| 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 |
+| verdict | honesty | `release-smoke-test` | transport ≠ app (#124); false-green rate |
+| telemetry | silent absence | `telemetry-events-test`, `telemetry-contract.test.ts` | chokepoint coverage |
+| install | pristine-surface wiring | — | the whole class |
+| client | per-agent MCP compatibility | — | the whole class |
+
+Nine of eleven layers have a gate. The two that do not are exactly the two that need a second repo and a human. The plan for both is in [`gate-plan.md`](./gate-plan.md).
+
+## 6. Traces already encode the invariants
+
+`runTool` opens one `tool.handler` root span per call and every stage underneath inherits it. With `RETICLE_TRACE=1` that makes three assertions available from any existing battery run, at the cost of one log parser:
+
+- exactly one root span at `depth: 0` per tool call
+- **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.

package/docs/telemetry-contract.md

@@ -0,0 +1,214 @@
+# The telemetry contract
+
+> For anyone — human or agent — adding a tool, an event, a finding kind, or a failure path to Reticle.
+>
+> The rules here are enforced by `packages/server/src/telemetry/telemetry-contract.test.ts`. If you break one, that test tells you which and where. This page is why.
+
+## Why this has its own contract
+
+**Telemetry fails silently.** Nothing throws when an event is missed. No test goes red. No user complains. The data is simply, permanently absent — and you find out months later when someone asks a question the data cannot answer, about a period you can never re-collect.
+
+That has already happened here twice, and both times the code looked correct:
+
+- `daemon_stopped` was emitted fire-and-forget microseconds before `process.exit(0)`. The POST was killed every single time. The event **never once arrived**, and nothing anywhere indicated a problem.
+- `bug_found` hand-copied the twelve contradiction kinds into a local `Set`. Correct on the day it was written; the thirteenth kind would have been silently miscounted, quietly deflating the one number we intend to publish.
+
+So the rule is not "remember to add telemetry". The rule is that the guard lives in a test.
+
+## The five rules
+
+### 1. Everything routes through a chokepoint
+
+Tool usage, timing, errors, verifications and bugs are all recorded in **one place** — `runTool` in `tools/invoke-tool.ts`. Adding a tool to `TOOLS` is all it takes to be instrumented.
+
+Do **not** add telemetry inside a tool handler. If you find yourself wanting to, the metric probably belongs at the chokepoint, read off the result.
+
+> The one exception is a path that genuinely does not go through `runTool` — currently only the verification runner (`reticle verify`, the HTTP verify surface), which has its own reporter in `telemetry/run-telemetry.ts`. **If you add a second dispatch path, it needs the same treatment**, and until it has one it is invisible. That gap existed for real: CI-found bugs were uncounted.
+
+### 2. Names say what happened
+
+`<noun>_<verbed>`, lowercase, no abbreviations: `verification_completed`, `bug_found`, `runtime_crashed`.
+
+## Counting defects: instances vs distinct
+
+`bug_found` fires once per OCCURRENCE. A defect hit five times in a session is five events, which is the right raw signal — frequency is what says which classes of defect actually cost anybody anything. But it means a naive count answers "how often were defects hit", not "how many defects were found", while looking like it answers the second.
+
+So every `bug_found` carries **`repeat`**: false the first time a KIND is seen in a session, true after. Count `repeat: false` for **distinct defects**; count everything for **instances**. Measured on a real app: 7 events, 3 defects, 4 repeats. Publishing the 7 as defects would have inflated the claim by more than double.
+
+The denominator is **`verification_completed`**, which fires per verdict with `via`, `verified`, `passed` and `falseGreenCaught`. Defects per verification is the honest rate; raw defect counts grow with usage and say nothing on their own.
+
+**And `repeat` only means anything if the session remembers.** `SessionMetrics.reset()` runs at every periodic flush and used to clear the seen-kinds set with the window counters — so the same defect, re-found after a flush, reported `repeat: false` again. Sessions in the data run to 11.5 hours. Window counters zero on a flush; session-lifetime memory does not. (`session-window.test.ts`)
+
+Two rules follow, and both are gated:
+
+- **`repeat` is set at the EMISSION site, never by the classifier.** `bugsInResult` is a pure function over one tool result and cannot know what a session has already seen; if it ever grows a `repeat` field it will be guessing, and the guess becomes the published number. (`telemetry-contract.test.ts`)
+- **Session-scoped, and it cannot be otherwise.** The payload carries no selector, URL or app detail by design, so the same defect in two sessions is unrecognisable as one — and making it recognisable would require collecting exactly what this event refuses to collect.
+
+The old set failed this so badly it confused its own authors — `invoke` meant "the CLI ran" while `tool` meant "a tool was called", which is the opposite of how both read. A name that has to be looked up is a name that gets misread on a dashboard a year from now.
+
+### 3. Names, never values
+
+| Send                                 | Never send              |
+| ------------------------------------ | ----------------------- |
+| Parameter and flag **names**         | What they were set to   |
+| Error **shape** (variables stripped) | The message             |
+| **Our** stack frames                 | The user's stack frames |
+| The **kind** of a defect             | What it was found in    |
+| A hash of the git origin             | The origin              |
+
+`--http-token` holds a secret. `reticle_act`'s `args` holds the text being typed into the app, which on a login form is a password. Assume every value is the worst thing it could be.
+
+There is one narrow exception, and it is explicit rather than heuristic: parameters whose values are enums **we** defined are allow-listed in `telemetry/argument-shape.ts`, and anything unrecognised reports as `other` so a schema change cannot start forwarding free text.
+
+### 4. Never derive a vocabulary by copying it
+
+If a set of kinds already exists in `@reticlehq/core`, **import it**. Do not re-list it.
+
+```ts
+// ✗ correct today, wrong the moment core gains a member — and silent about it
+const KINDS = new Set(['ui-advanced-request-failed', 'signal-contradicted' /* …10 more */]);
+
+// ✓ cannot drift
+const KINDS = new Set(Object.values(ContradictionKind));
+```
+
+A copied enum is a drift hazard anywhere. It is a **correctness** hazard when the thing that drifts is a number you publish.
+
+### 5. A metric may never change behaviour
+
+Every send is wrapped and best-effort. A telemetry failure must not fail a tool call, a verification, a daemon start, or `reticle init`.
+
+The single exception is `daemon_stopped`, which is **awaited** — because the process exits immediately after and the send would otherwise be killed. Even then a failure resolves rather than throws.
+
+## The event kinds, all of them
+
+`TelemetryEventKind` in `@reticlehq/core` is the closed list. Seven of these went undocumented here for months — the doc described only the session-lifecycle half — so anyone building a dashboard from this page could not know that the transport and install events existed at all. A kind nobody documents is a kind nobody queries, and telemetry that nobody queries is telemetry nobody notices has stopped arriving. `telemetry-contract.test.ts` now fails when a kind is missing from this table.
+
+| Kind | When | What it answers |
+| --- | --- | --- |
+| `reticle_installed` | first-ever run on a machine | install count, and the new-user curve |
+| `cli_command_run` | a human ran a `reticle` subcommand | human intent — `verify`/`gate` mean something very different from `status`. Never emitted for the internal `_daemon` spawn |
+| `daemon_started` | the daemon came up | active sessions, DAU/WAU/MAU |
+| `daemon_stopped` | clean exit | the rich session roll-up. **Count sessions with this one** — see below |
+| `session_progress` | periodic flush from a LIVE daemon | same payload, `final: false`. Sum work across both |
+| `verification_completed` | a verdict was produced | the product's reason to exist: was an app actually verified |
+| `project_profiled` | once per daemon start | stack, size, and how deeply the feature surface is used — activation vs retention |
+| `version_changed` | the running version differs from last seen | upgrade adoption, and whether a nudge caused it |
+| `runtime_crashed` | an unhandled failure in the daemon | stability |
+| `feedback_submitted` | `reticle feedback`, or an agent's report | the qualitative channel |
+| `identified` | `reticle identify` | joins anonymous machine ids to a person who volunteered one |
+| `mcp_client_connected` | an MCP client attached | how many sessions are agent-driven at all |
+| `mcp_connection_lost` | the proxy lost its daemon | **the transport-stability metric.** The disconnect that makes a user reopen `/mcp` is invisible without it |
+| `init_completed` | `reticle init` finished | does install actually work, outside the fixtures gate |
+| `bug_found` | a defect was detected in the app under test | the value delivered, as opposed to the work done |
+
+## Sessions: `daemon_stopped` vs `session_progress`
+
+Count sessions with **`daemon_stopped`** (`final: true`). It fires once, at a clean exit.
+
+A running daemon rolls its window up every 5 minutes as **`session_progress`** (`final: false`), same payload shape. Sum work across both; count sessions with neither summed nor doubled.
+
+This split exists because the flush used to be emitted AS `daemon_stopped` — an event named for an exit, fired while the process was alive. One day's export: 98 `daemon_stopped` events were 73 exits + 25 flushes, so a session count was 34% high. Worse, the two populations are opposites — every one of the 25 flushes had tool calls and **not one of the 73 exits did**, because a daemon that has served a tool never idle-exits and so never reaches a clean shutdown. A funnel over the raw event describes active sessions at one end and abandoned ones at the other.
+
+The flush interval is also the **bound on what is lost**: nothing calls shutdown when a working daemon is finally killed, so its last partial window dies with it. At 30 minutes against a median 28-minute session that was most of the session. Only non-empty windows emit, so a short interval costs nothing on the daemons that never serve a tool.
+
+## The session summary's newer fields
+
+Four counters and one flag were added because the data could not answer questions we were already asking. All are properties on events that already exist — no new kinds — and all four counters are **omitted rather than sent as zero**, so a field's presence is itself the signal.
+
+| Field | On | Means |
+| --- | --- | --- |
+| `noSessionErrors` | session summary | tool calls that failed because there was no app to reach — no session, no session by that id, or several with none named. The largest drop-off in the funnel; it was previously reachable only by unpacking `errors[]`. |
+| `consecutiveRepeats` | session summary | longest back-to-back run per tool name. `toolCounts` reports five useful calls and five retries of one failing call identically, and those are opposite facts. |
+| `abandonedActions` | session summary | actions driven with no verdict AFTER them — the trailing unsettled run, not `actions - verifications`. That difference ignores order, so a verdict that drove nothing (a `flow_verify` over saved flows) silently paid for an abandoned action elsewhere. |
+| `verification.browser` | `verification_completed` | `headless` \| `headed` \| `attached` — who DROVE the browser. `attached` (Reticle launched nothing, the SDK connected from a browser somebody else opened) is the common case in production, so on its own this is mostly "somebody's own browser". |
+| `verification.brand` | `verification_completed` | WHICH browser it was: `chrome` \| `edge` \| `arc` \| `dia` \| `brave` \| `opera` \| `firefox` \| `safari` \| `other` — the closed `BrowserBrand` list in core. The axis `engine` cannot answer, since Chrome, Edge, Arc, Dia and Brave are all `blink`. The SDK reads `navigator.userAgentData.brands` (and the UA string on Firefox/Safari, which expose no `userAgentData`) and normalises IN THE PAGE: a raw brand or UA string is unbounded and fingerprintable and never leaves. Anything unrecognised is `other`. **Omitted rather than `"unknown"`** when the page did not say — a desktop webview has no brand and an older SDK does not report one, and a guess is indistinguishable from a measurement on a dashboard. |
+| `verification.reason` | `verification_completed` | WHICH clause of `decideVerified` produced the verdict, from core's closed `VerifiedReason`: `inconclusive` \| `observation_lost` \| `assertion_failed` \| `contradicted` \| `already_true` \| `unclean_capture` \| `vacuous_grade` \| `outcome_pending` \| `outcome_unread` \| `unsettled` \| `proved`. See below. |
+| `bug.attribution` | `bug_found` | `app` \| `request` \| `reticle` — whose fault the defect was. **Absent means unclassified**, never `app`. See below. |
+| `outage.stage` / `outage.reason` / `outage.attempts` | `mcp_connection_lost` | which stage of the outage, why the stream went away (closed `OutageReason`, `other` for anything unnamed), and how many reconnects had been tried. See below. |
+| `tzOffsetMin` | every event | minutes offset from UTC. One integer, no location. |
+| `versionChange.nudged` | `version_changed` | an agent had been told about exactly this version recently, so the nudge plausibly caused the update. The daemon that nudges and the `reticle update` that acts are different processes, so a marker file joins them. |
+
+## Why a verdict came out that way — `verification.reason`
+
+`verified` has three values. The rule that produces it has **eleven clauses**. Everything in between was thrown away at the moment it was known.
+
+Captured against the real classifier: `verified: 'unknown'` covered "the agent malformed the call", "the consequence was already true", "the app answered 202", "a 2xx body went unread", "the capture was not clean", "nothing was asserted at a real grade" and "the page never settled" — **seven causes, two wire payloads**. They belong to three different owners (the agent, the app, Reticle) and need opposite responses: teach the agent, wait and re-check, or ship a fix. On a dashboard they were one bar. `verified: 'no'` collapsed the same way — "channels disagree" (Reticle earning its keep) and "the agent's predicate failed" were the same string.
+
+`VerifiedReason` lives in `@reticlehq/core` and is the **single list**. `decideVerified` returns a member from every clause, so a new clause cannot compile without one; `verified.test.ts` drives all ten and fails if a member exists that no clause produces. `verification-of.ts` narrows the result field against `Object.values(VerifiedReason)` — anything else is dropped rather than forwarded, because a string nobody can group by is worse than a gap. **Nothing re-lists these**, including the battery spec, which imports the enum from core's build.
+
+Optional on purpose: a suite verdict (`flow_verify`) is a pass/fail with no clause behind it, and an older sender has none. Absent means unclassified.
+
+## Whose defect it was — removed, on purpose
+
+`bug.attribution` shipped twice and was wrong both times. A real drive found that across two full runs EVERY `attribution: 'app'` was a misattribution, while the one defect that genuinely was a bad agent predicate carried none — a single session would have published "2 defects in the app" against a true count of 0.
+
+A metric that is confidently wrong about whose fault a defect is, is worse than no metric: it is the number a founder steers on, and it points at the customer. Counting nothing is recoverable; publishing a false accusation about somebody's product is not.
+
+It comes back when a verdict carries the reason it came out that way. Today the payload cannot separate the cases — `element.present` covers "the button is missing", "the API is down" and "the agent mistyped a testid" identically.
+
+## What is NOT a crash — expected disconnects
+
+`runtime_crashed` answers exactly one question: is Reticle stable. One real session put **nine** events into it, all `write EPIPE` — the MCP client closed its half of the stdio pipe and the next `process.stdout.write` failed, which is how a client is supposed to leave.
+
+`daemon-resilience.ts` matches `err.code` against `EPIPE` / `ECONNRESET` / `ERR_STREAM_DESTROYED` and logs `reticle_daemon_client_disconnected` (or `reticle_mcp_proxy_client_disconnected`) instead of emitting. Two rules make this safe rather than a hole:
+
+- **Code, never message.** Prose gets wrapped, localised and rewritten; matching it would eventually swallow a real crash that merely mentioned a pipe. `daemon-resilience.test.ts` drives an error whose message says `write EPIPE` and carries no `code`, and asserts it is still a crash.
+- **Visible, never swallowed.** It still logs a line with the code. A daemon emitting a hundred of these is a finding, just not a crash.
+
+A disconnect is also **no longer fatal for the daemon**: Node's "process state is undefined" guidance is about a throw that escaped everything, not about writing to a socket somebody closed, and exiting there let one departing client take down the daemon serving every other agent.
+
+## Did MCP stay up — the `outage` block
+
+The transport-stability metric shipped with an **empty payload** for months, and it is the exact failure this page opens with. `reportMcpOutage` passed `{ outage: { stage, reason, attempts } }`, `TelemetryExtra` declared the field, and it typechecked — but `emit()` builds its event from an **explicit allow-list of keys** and `outage` was not on it, nor in the `blocks` flattening map, nor in core's `TelemetryEventSchema`. Two deliberately different outages produced byte-identical events. Nothing threw, no test went red, and the data for that whole period cannot be recovered.
+
+The lesson is not "wire the field". It is that **the battery asserted the event ARRIVED and never that it carried anything**, and a kind-only assertion cannot see an empty payload. When you add an event kind, the live check has to assert the FIELDS.
+
+- `stage` — `first` (this session lost MCP at all) or `budget_spent` (it stopped retrying). These are the two facts the event exists to separate: the share of sessions that lose MCP, and the share where it never came back on its own.
+- `reason` — closed `OutageReason`: `sse_ended` | `sse_error` | `sse_aborted` | `sse_closed` | `connect_error` | `other`. The proxy's own reason strings are free text that also feeds a log, so `mcp-outage.ts` narrows them and reports **`other`** for anything unnamed. A classifier that cannot say "I don't know" lies instead, and an unbounded string must never reach the wire.
+- `attempts` — consecutive reconnects tried when this was reported.
+
+Still true and worth knowing when you query it: `mcp_connection_lost` carries **no `sessionId`** (it fires from the proxy process, not the daemon), and is capped at two per proxy process by design.
+
+## Recording locally instead of sending — `RETICLE_TELEMETRY_FILE`
+
+Set it to a path and every event is appended there as one JSON object per line, and **nothing is sent**. The payload is the one the wire would have carried, built by the same code and redacted by the same rules, so what a run records is what a user would have sent.
+
+It exists for two reasons that pull the same way:
+
+- **A release sweep is not a user.** Driving dozens of sessions through a gate emits real `daemon_started` / `verification_completed` / `bug_found` events, indistinguishable in PostHog from people. Test runs polluting the numbers is the same class of error as counting `cli_command_run { mcp }` as human intent: the metric stops describing what it claims to.
+- **Verifying telemetry should not need a hand-rolled HTTP server.** Ad-hoc harnesses are how a check ends up measuring nothing.
+
+One deliberate exception to the rules above: `RETICLE_TELEMETRY_FILE` keeps telemetry ENABLED inside a Reticle source checkout. The checkout guard exists to stop us phoning home, and writing a local file is not phoning home — while a release sweep is driven from exactly there, so a sink that inherited the guard would record nothing and look like it had worked.
+
+`sent: true` from `reticle_feedback` means the record landed in the file, which is the honest reading of "captured" for a recorded run. An unwritable path degrades to a no-op and reports `false`; it never takes the daemon down.
+
+## Adding things: what to do
+
+| You are adding | Do this | Enforced by |
+| --- | --- | --- |
+| **A tool** | Add it to `TOOLS`. Nothing else. If its name implies a verdict (`assert`/`verify`), also add it to `VERIFICATION_TOOLS` | `telemetry-contract.test.ts` |
+| **A verdict-producing tool** | `VERIFICATION_TOOLS` — otherwise it emits no `verification_completed` and stops counting toward the product's headline metric | ✓ |
+| **A contradiction / anomaly kind** | Add it to core's enum only. `bug-found.ts` derives from it | ✓ |
+| **A new finding shape** in a tool result | Teach `bugsInResult` the field. Add a case to the contract test | ✓ |
+| **A failure path** (connect, install, crash) | Classify it into an enum with an explicit `OTHER` bucket — a classifier that cannot say "I don't know" lies instead | ✓ |
+| **An event kind** | Add to `TelemetryEventKind` + a payload schema + emit it + add a live check to `apps/e2e/specs/telemetry-events-test.mjs` that asserts the **fields**, not just that it arrived | partly — the live check is on you |
+| **A block on `TelemetryExtra`** | Also add it to the `emit()` event build, the `blocks` flattening map, AND `TelemetryEventSchema`. Missing any one of the three drops the payload in silence — see `outage` | ✗ **not enforced — be careful** |
+| **A dispatch path** that bypasses `runTool` | Give it a reporter like `run-telemetry.ts`, or it is invisible | ✗ **not enforced — be careful** |
+
+## Verifying it actually works
+
+Unit tests cannot see the failure mode that matters, because nothing throws. Two things do:
+
+```bash
+pnpm test:unit                                  # the contract test + the fingerprint/redaction guards
+node apps/e2e/specs/telemetry-events-test.mjs   # fires every event at a real endpoint, checks it lands
+```
+
+The second is the one that matters. It drives the real built modules against a real capture server — real network, real process semantics, real redaction — and asserts each event **arrives**. Half its checks are leak checks, asserting that secrets, passwords, customer emails and home directories are _absent_.
+
+**Both halves are mutation-tested.** Reintroducing the fire-and-forget bug fails 9 checks; disabling redaction fails 3. A guard that cannot fail is theatre, so these are periodically proven to bite.
+
+## The privacy line, in one sentence
+
+We measure **that** something happened and **what class** of thing it was — never **what** it was, in whose app, or containing what.