@reticlehq/server 2.5.0 → 2.7.0

package/docs/gates.md

@@ -0,0 +1,117 @@
+# Gates — what to run before you push
+
+> **One question this file answers:** _I changed some files. Which command do I run?_
+>
+> The _why_ behind the gate design (tiers, the merge-gate/release-gate split, what is still unbuilt) lives in [`gate-plan.md`](./gate-plan.md). This file is the routing table.
+
+---
+
+## 0. Last verified
+
+Every gate below was executed end to end against `main` on **2026-08-12** (macOS, M-series, `v2.6.0`). A green row means somebody watched it go green, not that it is supposed to be green.
+
+| Gate | Result | Wall clock |
+| --- | --- | --- |
+| `pnpm build` | ✅ | ~40s |
+| `pnpm lint` (+ both guard self-tests) | ✅ | ~15s |
+| `pnpm typecheck` | ✅ | ~10s |
+| `pnpm test:unit` | ✅ 4,315 tests / 461 files across 8 packages | ~45s |
+| `pnpm format:check` | ✅ | ~10s |
+| `pnpm test:integration` | ✅ 12/12 | 17s |
+| `pnpm test:e2e` | ✅ 32/32 specs + soak 60/60 answered | **490s** |
+| `pnpm test:e2e:desktop` | ✅ 2/2 (Electron 20, Tauri 14) | 58s |
+| `node apps/e2e/soak.mjs --self-check` | ✅ | <1s |
+| `node apps/e2e/matrix.mjs --self-check` | ✅ | <1s |
+| `pnpm matrix:compat --only cursor` | ✅ 4/4 | ~10s |
+| `pnpm bench` | ✅ 10/10 — **was failing before this sweep** (see below) | 279s |
+
+**`pnpm bench` was broken and nobody knew.** `suite-rre.mjs` recorded four flows that asserted no observable consequence and then demanded a `pass` verdict from `reticle_flow_verify` — which correctly grades an assertion-free suite `unverifiable`. The product got more honest about false greens; the benchmark measuring it did not follow, so the whole run aborted at script 9 of 10 and `replay-determinism` never ran at all. Each flow now carries a success oracle. This is the failure mode `bench/` is most exposed to: **nothing in CI runs it**, so it can only rot silently.
+
+`pnpm gate:install` (~15 min) and the Windows / Rust jobs were **not** run in this sweep — they are CI-only or network-bound. They are green on `main` per the last CI run, which is a weaker claim than every row above, and is stated that way on purpose.
+
+---
+
+## 1. The routing table
+
+Find the row that matches what you changed. Run its commands. That is the whole rule.
+
+| You changed | Run | Cost |
+| --- | --- | --- |
+| **Anything at all** | `pnpm lint && pnpm typecheck && pnpm test:unit` | ~2 min |
+| The tool surface, the wire contract (`packages/core`), or an observer | ↑ **and** `pnpm test:e2e` | +~8 min |
+| `reticle init`, `@reticlehq/vite-plugin`, `@reticlehq/next`, `@reticlehq/babel-plugin` — anything a user runs before their first session | ↑ **and** `pnpm gate:install` | +~15 min |
+| `@reticlehq/electron`, `packages/tauri`, the IPC observer, desktop capture | ↑ **and** `pnpm test:e2e:desktop` | +~3 min |
+| Telemetry, feedback, or anything that emits an event | ↑ **and** read [`telemetry-contract.md`](./telemetry-contract.md) first. `pnpm test:e2e` covers it (`telemetry-events-test`) | — |
+| `packages/tauri` (Rust) | ↑ **and** `cd packages/tauri && cargo fmt --check && cargo clippy --all-targets -- -D warnings` | +~2 min |
+| Docs, README, comments only | `pnpm format:check` | seconds |
+
+**Why routing exists.** The full set is roughly 35 minutes. A gate people resent is a gate people route around, so only the tier that can see your change is worth your time. CI runs everything regardless — routing costs you a slower red, never a missed one.
+
+---
+
+## 2. Every gate, and what each one can actually see
+
+Each gate exists because the ones above it are blind to something. That blindness is the column that matters.
+
+| Gate | Command | Proves | Blind to | CI job |
+| --- | --- | --- | --- | --- |
+| **Build** | `pnpm build` | every package compiles and emits | anything at runtime | `verify` |
+| **Lint** | `pnpm lint` | style rules, plus the dependency-boundary and lossy-transform guards | anything not expressible as a rule | `verify` |
+| **Typecheck** | `pnpm typecheck` | types agree across package boundaries | runtime behaviour | `verify` |
+| **Unit** | `pnpm test:unit` | 4,315 tests, per-package, no browser | anything crossing a package boundary at runtime | `verify` |
+| **Format** | `pnpm format:check` | Prettier | — | `verify` |
+| **Integration** | `pnpm test:integration` | real headless Chromium: browser pool, crash isolation, framework adapters, `withReticle` | the MCP surface, the daemon | `e2e` |
+| **Web e2e battery** | `pnpm test:e2e` | 30 specs against 3 booted servers and a real browser — the tool surface, the daemon lifecycle, transport faults, telemetry, trace shape — plus the soak | desktop runtimes; the install | `e2e` |
+| **Desktop battery** | `pnpm test:e2e:desktop` | a real Electron main process and a **packaged** Tauri binary, driven headless | web-only paths | `desktop-e2e` |
+| **Install gate** | `pnpm gate:install` | scaffolds 3 pristine apps, publishes this checkout to a local Verdaccio, lets `init` install itself, boots each app in a real browser, polls for a session | install _complexity_ — see [`fixtures.md`](./fixtures.md) | `install-gate` |
+| **Matrix records** | `pnpm matrix:validate` | every submitted client-compat record is well-formed | whether the client actually works | `matrix-records` |
+| **Windows** | (CI only) | that the code runs at all on the majority platform | e2e; Windows is unit-only | `windows` |
+| **Rust** | `cargo fmt/clippy/check` | `packages/tauri` compiles and lints on Linux, macOS, and cross-checks Windows | everything JS | `rust`, `rust-macos` |
+
+**The single required status check is `gate`.** It passes when every job above either succeeded or was deliberately skipped by path routing, and fails on anything else. Adding a job to `ci.yml` is half the work; adding it to `gate`'s `needs:` list is the other half — a job missing from that list runs, reports, and is structurally incapable of blocking a merge.
+
+### Guards that self-test
+
+Four checks prove they can still fail before they are trusted. A guard that has never refused anything is not a guard, so each has a negative control that CI runs **first**:
+
+```bash
+node scripts/check-boundaries.mjs --self-test        # catches a synthetic bad dependency graph
+node scripts/check-lossy-transforms.mjs --self-test  # catches an unclassified lossy export
+node apps/e2e/soak.mjs --self-check                  # the soak gate still reddens on an unanswered call
+node apps/e2e/matrix.mjs --self-check                # the validator still refuses a malformed record
+pnpm gate:install:self-test                          # mis-wires every scaffold; the gate MUST go red
+```
+
+---
+
+## 3. Gates that are not automatic
+
+These are real and they work; they are not on the PR path, so they only run when somebody runs them.
+
+| Command | What it is | When |
+| --- | --- | --- |
+| `pnpm gate:soak:record` | the half-hour release soak (20 rounds, 2s idle), re-records `bench/soak-history.jsonl` and `bench/TOOL-PROFILE.md` | before a release |
+| `pnpm matrix:compat` | drives each MCP client's config exactly the way that client would; writes a machine record for `docs/matrix/` | before a release, per client |
+| `pnpm knip` | unused files, exports, and dependencies | when the repo feels heavy |
+| `node scripts/verify.mjs` in the sibling **`reticle-fixtures`** repo | installs this commit into nine real third-party apps (install _complexity_, not regressions) | see [`fixtures.md`](./fixtures.md) |
+
+---
+
+## 4. `bench/` is not a gate
+
+`bench/` is **measurement and research**, not a merge check. Nothing there blocks a PR, nothing runs in CI, and it is allowed to bit-rot in a way a gate is not. Read [`bench/README.md`](../bench/README.md) before touching it — it says which scripts are live and which are one-off studies kept as evidence for a published claim.
+
+The one exception worth knowing: `pnpm bench` + `pnpm bench:gate` is a working regression gate for the replay numbers, and it is run by hand before a release.
+
+---
+
+## 5. When a gate fails and you think it is the gate's fault
+
+Sometimes it is. The specific failures worth recognising:
+
+- **`EADDRINUSE` / "died during boot"** — a previous run left something on `:8787`, `:4310`, or `:3100`. `run-ci.sh` frees these on exit; if it was killed, free them by hand.
+- **Killing port 4400 with `lsof -ti tcp:4400 | xargs kill -9`** — this SIGKILLs the `reticle mcp` proxy too, because the proxy holds a _client_ socket on the bridge port. Always add `-sTCP:LISTEN`. This is the root cause of most "the MCP went down" reports.
+- **A timing assertion** — if a test asserts `Date.now() - t < N`, that is a bug in the test, not a flake to re-run. Assert the bound (output size, a truncation flag), or use a generous per-test timeout. See [`harness-rules.md`](../apps/e2e/harness-rules.md).
+- **An `INCONCLUSIVE` verdict** — the harness is telling you the transport did not stay up, so it is claiming nothing about the product. That is the harness working, not the product failing.
+
+The four rules every tier obeys, and the incident behind each, are in [`apps/e2e/harness-rules.md`](../apps/e2e/harness-rules.md).

package/docs/local-registry.md

@@ -34,7 +34,7 @@ For a browser app, install `@reticlehq/react` plus the build plugin for your fra
 In your app's project root, add an `.npmrc` (scopes only `@reticle` to the local registry; everything else still comes from npm):
 
 ```ini
-@reticle:registry=http://localhost:4873/
+@reticlehq:registry=http://localhost:4873/
 ```
 
 ## 3. Install + wire it up

package/docs/matrix/2.5.0/claude-code-machine.json

@@ -0,0 +1,19 @@
+{
+  "reticle": {
+    "version": "2.5.0",
+    "commit": "33629413"
+  },
+  "client": {
+    "id": "claude-code"
+  },
+  "host": {
+    "os": "darwin 25.5.0",
+    "node": "v22.14.0"
+  },
+  "checks": {
+    "snippet": true
+  },
+  "verdict": "runnable-unverified",
+  "by": "machine (client-compat.mjs)",
+  "note": "machine-checkable half only — nobody has run this client"
+}

package/docs/matrix/2.5.0/codex-machine.json

@@ -0,0 +1,20 @@
+{
+  "reticle": {
+    "version": "2.5.0",
+    "commit": "33629413"
+  },
+  "client": {
+    "id": "codex"
+  },
+  "host": {
+    "os": "darwin 25.5.0",
+    "node": "v22.14.0"
+  },
+  "checks": {
+    "writes": false,
+    "snippet": true
+  },
+  "verdict": "manual-snippet",
+  "by": "machine (client-compat.mjs)",
+  "note": "machine-checkable half only — nobody has run this client"
+}

package/docs/matrix/2.5.0/cursor-machine.json

@@ -0,0 +1,22 @@
+{
+  "reticle": {
+    "version": "2.5.0",
+    "commit": "33629413"
+  },
+  "client": {
+    "id": "cursor"
+  },
+  "host": {
+    "os": "darwin 25.5.0",
+    "node": "v22.14.0"
+  },
+  "checks": {
+    "writes": true,
+    "parses": true,
+    "initialize": true,
+    "tools": 17
+  },
+  "verdict": "runnable-unverified",
+  "by": "machine (client-compat.mjs)",
+  "note": "machine-checkable half only — nobody has run this client"
+}

package/docs/matrix/2.5.0/gemini-machine.json

@@ -0,0 +1,22 @@
+{
+  "reticle": {
+    "version": "2.5.0",
+    "commit": "33629413"
+  },
+  "client": {
+    "id": "gemini"
+  },
+  "host": {
+    "os": "darwin 25.5.0",
+    "node": "v22.14.0"
+  },
+  "checks": {
+    "writes": true,
+    "parses": true,
+    "initialize": true,
+    "tools": 17
+  },
+  "verdict": "runnable-unverified",
+  "by": "machine (client-compat.mjs)",
+  "note": "machine-checkable half only — nobody has run this client"
+}

package/docs/matrix/2.5.0/opencode-machine.json

@@ -0,0 +1,22 @@
+{
+  "reticle": {
+    "version": "2.5.0",
+    "commit": "33629413"
+  },
+  "client": {
+    "id": "opencode"
+  },
+  "host": {
+    "os": "darwin 25.5.0",
+    "node": "v22.14.0"
+  },
+  "checks": {
+    "writes": true,
+    "parses": true,
+    "initialize": true,
+    "tools": 17
+  },
+  "verdict": "runnable-unverified",
+  "by": "machine (client-compat.mjs)",
+  "note": "machine-checkable half only — nobody has run this client"
+}

package/docs/matrix/2.5.0/vscode-machine.json

@@ -0,0 +1,22 @@
+{
+  "reticle": {
+    "version": "2.5.0",
+    "commit": "33629413"
+  },
+  "client": {
+    "id": "vscode"
+  },
+  "host": {
+    "os": "darwin 25.5.0",
+    "node": "v22.14.0"
+  },
+  "checks": {
+    "writes": true,
+    "parses": true,
+    "initialize": true,
+    "tools": 17
+  },
+  "verdict": "runnable-unverified",
+  "by": "machine (client-compat.mjs)",
+  "note": "machine-checkable half only — nobody has run this client"
+}

package/docs/matrix/2.5.0/windsurf-machine.json

@@ -0,0 +1,22 @@
+{
+  "reticle": {
+    "version": "2.5.0",
+    "commit": "33629413"
+  },
+  "client": {
+    "id": "windsurf"
+  },
+  "host": {
+    "os": "darwin 25.5.0",
+    "node": "v22.14.0"
+  },
+  "checks": {
+    "writes": true,
+    "parses": true,
+    "initialize": true,
+    "tools": 17
+  },
+  "verdict": "runnable-unverified",
+  "by": "machine (client-compat.mjs)",
+  "note": "machine-checkable half only — nobody has run this client"
+}

package/docs/matrix/MATRIX.md

@@ -0,0 +1,26 @@
+# Client matrix
+
+> Which MCP clients Reticle is known to work in, and on whose machine that was measured.
+> Generated by `node apps/e2e/matrix.mjs` — do not edit by hand.
+
+| | meaning |
+| --- | --- |
+| ✅ | a human ran the real client and the tools were usable |
+| ◐ | `init` wrote a runnable entry where the client documents it — **nobody has run that client** |
+| ✎ | `init` will not write this format (TOML); the user pastes a block |
+| ❌ | somebody ran it and it did not work — the most useful row here |
+
+**◐ is not a tick.** It means the half a machine can check passed. Only ✅ means somebody saw
+Reticle working in that client.
+
+## 2.5.0
+
+| client | verdict | tools | os | submitted by |
+| --- | --- | --- | --- | --- |
+| claude-code | ◐ runnable-unverified | — | darwin 25.5.0 | machine (client-compat.mjs) |
+| codex | ✎ manual-snippet | — | darwin 25.5.0 | machine (client-compat.mjs) |
+| cursor | ◐ runnable-unverified | — | darwin 25.5.0 | machine (client-compat.mjs) |
+| gemini | ◐ runnable-unverified | — | darwin 25.5.0 | machine (client-compat.mjs) |
+| opencode | ◐ runnable-unverified | — | darwin 25.5.0 | machine (client-compat.mjs) |
+| vscode | ◐ runnable-unverified | — | darwin 25.5.0 | machine (client-compat.mjs) |
+| windsurf | ◐ runnable-unverified | — | darwin 25.5.0 | machine (client-compat.mjs) |

package/docs/matrix/README.md

@@ -0,0 +1,59 @@
+# Submitting a client-matrix record
+
+[`MATRIX.md`](./MATRIX.md) says which MCP clients Reticle is known to work in. Right now most rows are **◐** — `init` writes a runnable entry where that client documents it, and **nobody has run that client**. Turning a ◐ into a ✅ takes about three minutes and is the single most useful thing an outside contributor can do for this project.
+
+You do not tell us it works. You **run one command, run your client, and submit what came out** — the same shape as [CNCF's Kubernetes conformance](https://github.com/cncf/k8s-conformance), and for the same reason: a claim nobody can trace back to a machine and a commit cannot gate anything.
+
+## 1. The machine half (no client needed)
+
+```bash
+pnpm build
+node apps/e2e/client-compat.mjs --only <client> --json /tmp/compat.json
+```
+
+That checks `init` writes a config where your client documents it, that it parses under **that client's own key**, and that the command inside it starts and advertises tools. It does **not** check that your client reads it — which is the whole reason step 2 exists.
+
+## 2. The human half (this is the part that matters)
+
+1. Run `npx @reticlehq/server init` in a real project.
+2. **Restart your client.** Every one of them reads MCP config at startup; this is the step people skip and then report a bug about.
+3. Ask it to list Reticle's tools. Note **how many** it lists.
+4. Kill the daemon (`lsof -nP -iTCP:4400 -sTCP:LISTEN -t | xargs kill`) and use a Reticle tool again. Does the client recover on its own, or does it need a manual reconnect?
+5. If anything failed, copy your client's error text **verbatim**. That sentence is worth more than the rest of the record put together — it is the only thing that says what your client actually thinks went wrong.
+
+## 3. Submit it
+
+Write `docs/matrix/<reticle-version>/<client>-<yourhandle>.json`:
+
+```json
+{
+  "reticle": { "version": "2.5.0", "commit": "abc1234" },
+  "client": { "id": "windsurf", "version": "1.2.3" },
+  "host": { "os": "darwin 25.5.0", "node": "v22.14.0" },
+  "checks": {
+    "registered": true,
+    "toolsVisible": 17,
+    "survivedDaemonRestart": true,
+    "clientError": ""
+  },
+  "verdict": "works",
+  "by": "your-github-handle"
+}
+```
+
+Validate it, regenerate the table, open a PR:
+
+```bash
+node apps/e2e/matrix.mjs --validate docs/matrix/<version>/<file>.json
+node apps/e2e/matrix.mjs        # regenerates MATRIX.md
+```
+
+CI runs the same validator on every PR, so a malformed record fails before a human reads it.
+
+## What the validator insists on, and why
+
+- **`works` requires `checks.toolsVisible > 0`.** "It works" with no number is the self-report this whole flow exists to replace.
+- **`broken` requires `checks.clientError`** — your client's own words, verbatim. A failure nobody can act on is worse than no record.
+- **Every record needs a host and a version.** A cell nobody can place is decoration.
+
+**A `broken` record is as welcome as a `works` one and passes exactly the same checks.** It is usually more useful: it is how we find out that a client changed its config path, or that our entry shape stopped being read. If your client does not work, that is the record we most want.

package/docs/mint.json

@@ -48,7 +48,7 @@
     },
     {
       "group": "Reference",
-      "pages": ["usage", "agent-cheatsheet"]
+      "pages": ["usage", "agent-cheatsheet", "telemetry"]
     },
     {
       "group": "Enterprise",

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

@@ -33,7 +33,7 @@ Do **not** add telemetry inside a tool handler. If you find yourself wanting to,
 
 `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.
+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, the instance count was more than double the defect count. Publishing instances as defects inflates the claim accordingly.
 
 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.
 
@@ -98,10 +98,21 @@ The single exception is `daemon_stopped`, which is **awaited** — because the p
 | `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 |
+| `app_instrumented` | the first app carrying the SDK reached this daemon | **the funnel step everything turns on** — see below |
 | `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 |
 
+## The install has two halves — `app_instrumented`
+
+Reticle is only usable when both halves are done: the MCP server is registered so the agent has the tools, and the SDK is loaded by a running page so there is something for those tools to look at. They are done by different commands, at different times, often in different directories. Almost everyone completes the first. The second is where the users go.
+
+Nothing measured the second. `daemon_started` and `mcp_client_connected` describe the agent half. `session_appConnects` describes the app half but is a **window counter** — it resets on every flush, so a user whose app connected in one window reads zero in every other. The population it under-counts is precisely the population being measured, and a funnel built on it reported fewer instrumented users than there were users calling tools, which is impossible on its face.
+
+`app_instrumented` fires **once per daemon run**, on the first session-ready only, so `daemon_started` → `app_instrumented` is a rate rather than an inference and a reloading page cannot inflate it. It carries `initialized` (had `init` run here), `agentAttached` (was an agent already waiting), and `msToFirstApp` (how long the daemon sat with nothing wired). It deliberately carries no stack and no framework: `project_profiled` already reports both for the same run, and the two join on `sessionId`.
+
+What it still cannot see is **why** an app never connected — every cause for that is page-side (the non-localhost gate, a port mismatch, a stale build, a dev server never restarted), where the daemon has no visibility. That needs the SDK to report its own refusals, and it is the next thing to build.
+
 ## Sessions: `daemon_stopped` vs `session_progress`
 
 Count sessions with **`daemon_stopped`** (`final: true`). It fires once, at a clean exit.
@@ -123,7 +134,8 @@ Four counters and one flag were added because the data could not answer question
 | `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` \| `assertion_failed` \| `contradicted` \| `already_true` \| `unclean_capture` \| `vacuous_grade` \| `outcome_pending` \| `outcome_unread` \| `unsettled` \| `proved`. See below. |
+| `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. |
+| `verification.uncleanLoss` | `verification_completed` | WHAT was lost when `reason` is `unclean_capture`, from core's closed `CaptureLoss`: `buffer_loss` (our server ring buffer evicted evidence from the window) \| `transport_gap` (our browser queue overflowed) \| `blind_spot` (a boundary in the page — a cross-origin frame, a closed shadow root) \| `other`. Three owners, three fixes, and one bar on a dashboard until this existed. ONE value, not a list — a multi-value property is not something a breakdown can group by, so the first is sent, ours before the page's. **Absent whenever the capture was clean**, so its presence is itself the signal. Reported as `other` rather than omitted when the block says dirty and names nothing: a gap there would read as "no unclean verdicts happened". |
 | `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. |
@@ -131,7 +143,7 @@ Four counters and one flag were added because the data could not answer question
 
 ## Why a verdict came out that way — `verification.reason`
 
-`verified` has three values. The rule that produces it has **ten clauses**. Everything in between was thrown away at the moment it was known.
+`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.