@reticlehq/server 2.4.0 → 2.6.0

package/docs/flows.md

@@ -0,0 +1,166 @@
+# Flows, the recorder & self-healing — record once, run forever
+
+Reticle turns an interactive run into a **git-checked, replayable program** stored under `.reticle/`. Flows are anchored on **meaning** (testid + signal), not volatile element refs or coordinates, so they survive refactors — and when an anchor does drift, Reticle tells you _why_ and can repair it. This is what makes Reticle "the project's living test suite a human seeds and an agent maintains."
+
+> All of this is on-disk and human-readable, so flows are reviewed in PRs and diffed like code.
+
+## The `.reticle/` directory
+
+When you record or save a contract, Reticle writes a git-checked workspace next to your app:
+
+```
+.reticle/
+  contract.json            # the app's testable surface (testids, signals, stores)
+  flows/
+    create-drop.json       # a recorded, anchored, replayable flow
+  baselines/               # snapshot baselines (co-located)
+```
+
+The server resolves `.reticle/` from the working directory it runs in (your project root). A fresh agent can read `.reticle/contract.json` to learn the testable surface **without grepping your source**.
+
+## The contract — advertise the testable surface
+
+In your app, declare what's testable (see [Step 6 in Getting Started](getting-started.md)):
+
+```ts
+import { registerCapabilities } from '@reticlehq/react';
+registerCapabilities({
+  testids: ['add-task', 'checkout'],
+  signals: ['order:saved'],
+  stores: ['cart'],
+});
+```
+
+Then persist it to disk so it's committed and any agent can read it:
+
+| Tool | What it does |
+| --- | --- |
+| `reticle_capabilities()` | the live testable surface `{ testids, signals, stores, flows }` |
+| `reticle_contract_save()` | write the live capabilities to `.reticle/contract.json` (versioned, diffable) |
+
+## Create a flow
+
+**(a) Agent-recorded** — the agent drives, then saves:
+
+```jsonc
+reticle_record {action:"start"}({ recordingName: "create-task" })
+reticle_act({ ref: "e7", action: "click" })        // … drive the golden path …
+reticle_record {action:"stop"}({ recordingName: "create-task" })
+reticle_flow_save({ flowName: "create-task" })          // → .reticle/flows/create-task.json
+```
+
+**(b) Human-recorded (the recorder toolbar)** — with the presenter on (`present: true`), the floating panel hosts a recorder: a human clicks the golden path in the page and Reticle captures each interaction as a **semantic-anchored** step (testid, else role+name), then persists it via `reticle_flow_save_recorded`. The agent then runs and maintains it. _(First cut: structured annotations only — see below; free natural-language annotations are future work.)_
+
+### What a flow file looks like
+
+```jsonc
+{
+  "version": 1,
+  "name": "create-task",
+  "steps": [
+    { "tool": "reticle_act", "anchor": { "testid": "add-task" }, "action": "click" },
+    {
+      "tool": "reticle_act",
+      "anchor": { "testid": "add-task" },
+      "action": "click",
+      "expect": { "signal": "task:added" },
+    },
+  ],
+  "dynamic": [], // anchors whose CONTENT must not be asserted (LLM output)
+  "success": { "signal": "saved" },
+}
+```
+
+Each step binds to a **semantic anchor**, never a `eXX` ref: a `testid`/`signal` when available, else an auto-derived `component` anchor (component name + source `file:line`) for an element with no testid — so the flow stays stable with zero hand-added testids. Only when none of those resolve is a step kept `degraded: true` (a last-resort "add a testid here" marker) rather than silently dropped.
+
+## Run a flow
+
+```jsonc
+reticle_flow {action:"list"}()                                    // → flows on disk
+reticle_flow {action:"load"}({ flowName: "create-task" })   // → the flow JSON
+reticle_flow_replay({ flowName: "create-task" }) // re-resolve each anchor against the LIVE DOM, run it
+```
+
+**Watch it replay on the page.** When the presenter is on (`present: true`), a replay isn't silent — each step drives the real page, so the synthetic cursor flies to the element, the focus ring lands, and the activity log streams the journey live. You (or a teammate) literally watch the saved journey re-walk itself on your app, then see the verdict land. It's the fastest way to _see_ that a flow still works — not just read a green checkmark.
+
+`reticle_flow_replay` returns a status:
+
+- `ok` — every anchor resolved and every `expect` held.
+- `drift` — an anchor missed (a testid was renamed, or a signal never fired). The result is **legible**: `{ step, anchor, drift: { reasonKind: "testid_not_found", nearest: "send-message" } }` — never a blind failure. (This is the "whose fault is it" principle.)
+- `error` — the flow file is missing/invalid, or a resolved action failed. Runtime failures include the failed step and a top-level error envelope.
+
+A testid-_preserving_ refactor (you moved markup but kept the testids) still replays green. A step whose element has **no testid** is anchored on its component + source location (`{ kind: "component", component, source: { file, line } }`) — an auto-derived stable anchor, so a flow records cleanly with zero hand-added testids and replay re-resolves it via `reticle_query by:'component'`.
+
+### The decision envelope — what to do next, not just pass/fail
+
+On a `drift` or `error`, the replay result carries a `decision` an agent can act on directly:
+
+```jsonc
+decision: {
+  verdict: "drift",
+  whatChanged: "testid \"fault-500\" not found",
+  whereInSource: "src/Diagnostics.tsx:16",   // file:line, from the component/source anchor
+  suggestedFix: "rebind the anchor to \"fault-404\" (closest survivor)",
+  nextAction: "rebind the anchor to \"fault-404\", or update the flow if the change was intended."
+}
+```
+
+This is the feedback a human reviewer used to give — made machine-actionable, so the agent decides its next move without one.
+
+## Verify the whole suite in one call
+
+`reticle_flow_verify` replays **every** saved flow (or a named subset) deterministically — no LLM per flow — and returns one consolidated verdict. This is the regression check to run after any change:
+
+```jsonc
+reticle_flow_verify()
+// → { status: "fail", total: 4, passed: 3, failed: 1,
+//     summary: "3/4 flows pass — 1 needs attention: ship-deploy",
+//     failures: [{ flow: "ship-deploy", verdict: "drift",
+//                  whatChanged: "...", whereInSource: "src/...:NN", nextAction: "..." }] }
+```
+
+Passing flows are counted; only failures carry detail (token-cheap). Build → `reticle_flow_verify` → fix from each failure's `nextAction` → repeat — the autonomous regression loop.
+
+## Self-healing — the agent maintains the flow
+
+When a testid is renamed, the flow drifts. `reticle_flow_heal` proposes — and optionally applies — the nearest-match rebind, so flows don't rot:
+
+```jsonc
+reticle_flow_heal({ flowName: "create-task" })               // PROPOSE only — never writes
+// → { status: "drift", applied: false,
+//     proposals: [{ step: 0, from: "add-tassk", to: "add-task", confidence: 0.8 }] }
+
+reticle_flow_heal({ flowName: "create-task", apply: true })  // rewrite the anchor on disk
+// → { status: "healed", applied: true, proposals: [...] }
+```
+
+With `apply: false` the flow file is **never modified** — you get the proposed diff to review. With `apply: true` Reticle rewrites the drifted anchor(s) to the confident nearest match and a subsequent replay passes. A drift with **no** confident nearest match leaves the file untouched.
+
+## Annotations (structured)
+
+`reticle_annotate` attaches a structured annotation that compiles into the flow, so replay is a _checked_ re-run, not a blind macro:
+
+- `assert-signal` / `assert-visible` → a step `expect` predicate (the invariant).
+- `mark-dynamic` → a `flow.dynamic[]` entry — replay asserts the region's _presence_ but **not its words** (the LLM-output case: assert `caption:generated`, ignore the caption text).
+- `success-state` → `flow.success` (the golden end condition). Pass `signal`/`testid`, or `statePath` (+ `store`, `equals`) to make the golden condition a **store-truth** assertion — the app's own source of truth, which no DOM read can reach (e.g. `statePath: "deployments.0.status", equals: "live"` fails the flow if a deploy only _looks_ shipped on screen). State assertions are graded as consequences, so they satisfy the business-outcome oracle.
+
+## Flows are your test suite
+
+`.reticle/` flows can be executed as CI specs — replayed with their `expect`/`success` predicates, skipping `dynamic` regions — via `@reticlehq/test`'s `flowsAsSpecs`. See [Testing with Reticle](testing.md).
+
+## Tool reference
+
+| Tool | Args | Returns |
+| --- | --- | --- |
+| `reticle_contract_save` | `{ sessionId? }` | writes `.reticle/contract.json` |
+| `reticle_record {action:"start"}` / `reticle_record {action:"stop"}` | `{ recordingName }` | start/stop capturing the agent's acts |
+| `reticle_flow_save` | `{ flowName }` | persist the recording → `.reticle/flows/<flowName>.json` |
+| `reticle_flow_save_recorded` | `{ flowName? }` | persist a human-recorded (toolbar) flow |
+| `reticle_flow {action:"list"}` | `{}` | flows on disk |
+| `reticle_flow {action:"load"}` | `{ flowName }` | the flow JSON |
+| `reticle_flow_replay` | `{ flowName }` | `{ status, steps, decision? }` (decision on drift/fail) |
+| `reticle_flow_verify` | `{ names?, sessionId? }` | suite verdict `{ status, passed, failed, failures[] }` |
+| `reticle_flow_heal` | `{ flowName, apply? }` | propose / apply nearest-match rebind |
+| `reticle_annotate` | `{ kind, … }` | compile a structured annotation into the flow |
+
+> Flow `name` must be a single safe path segment (no `/`, `\`, `..`, or leading dot).

package/docs/gate-plan.md

@@ -0,0 +1,98 @@
+# The release gate — plan and status
+
+> What has to be true before a PR merges and before a release ships, why each piece exists, and what is built so far. Derived from [`system-map.md`](./system-map.md); the harness rules every tier obeys are in [`harness-rules.md`](../apps/e2e/harness-rules.md).
+
+## Two gates, not one
+
+|         | Merge gate                   | Release gate                                      |
+| ------- | ---------------------------- | ------------------------------------------------- |
+| Answers | does this PR break anything? | does this version work in the clients people use? |
+| Runs    | every PR                     | on a release candidate                            |
+| Who     | machines only                | machines + humans                                 |
+| Budget  | minutes                      | hours                                             |
+
+**They must stay separate.** A merge that waits on a human client matrix stalls every contribution until three people with three editors happen to be awake.
+
+## Tiers
+
+| Tier | Question | Who | When | Blocks |
+| --- | --- | --- | --- | --- |
+| 0 — repo | is the code internally consistent | Actions | every PR | merge |
+| 1 — install | does it install into an app nobody instrumented | Actions, scaffolded apps | PRs touching install/wire | merge |
+| 2 — ecosystem | does it survive third-party apps at real scale | `reticle-fixtures`, dispatch | 3×/week + release | release |
+| 3 — conformance | does each MCP client actually work | humans + headless CLIs | release candidate | the tag |
+| 4 — canary | does a real model still succeed | nightly, live LLM | nightly | nothing (alerts) |
+
+**Tier 1 vs 2.** Tier 1 scaffolds a pristine app at CI time (`npm create vite`) — clean by construction, seconds to produce, catches install _regressions_, fast enough to block a PR. Tier 2 uses vendored production apps and catches install _complexity_. Conflating them produces a gate too slow to block and too shallow to trust.
+
+**Tier 3 is the [CNCF conformance](https://github.com/cncf/k8s-conformance) model:** contributors do not _claim_ a client works, they run one command and submit its machine-generated output as a PR, which a bot validates before a human looks. Self-reported pass/fail cannot gate anything.
+
+**No LLM in the merge path.** Deterministic tests on every commit; live-model evals nightly and alert-only. The `record → save → verify → heal` chain is what makes this possible — a flow is recorded once by an agent, then replayed forever with no model.
+
+## The matrix, factored
+
+3 OS × 6 clients × 8 frameworks × 2 runtimes = 288 combinations. Nobody runs that. Test each axis against a fixed baseline of the others instead: 3 + 6 + 8 + 2 = **19 runs, plus ~4 deliberately chosen full-stack combos** where axis interaction is most likely (Windows+Cursor+Next, macOS+Claude Code+Tauri, …). Publish the factoring, and say plainly which interactions are untested.
+
+## Phases
+
+### Phase 0 — the harness contract and the map — **done**
+
+Nothing below is trustworthy until a gate result can be distinguished from a gate artifact.
+
+- [x] `docs/system-map.md` — topology, connection sequence, tool graph, fragility inventory
+- [x] `apps/e2e/harness-rules.md` — the four rules, with the incidents that produced each
+- [x] `apps/e2e/gate-harness.mjs` — the rules as code: `portHolders`, `freePortSafely`, `startOwnedDaemon`, `watchTransport`, `attributeOutcome`, plus a self-check
+- [x] `run.mjs` and `ci.yml` no longer kill client sockets on the bridge port
+
+### Phase 1 — close the silent gaps already in reach
+
+- [x] **Trace-shape assertions** — `apps/e2e/trace-shape.mjs` + `trace-shape-test`. One root span per callId, no nested span without a completed parent (the hang signature), no undeclared parentless `browser.command`, no `ok:false` without an error. Calibrated against a real 494-span run: silent there, fires on all four fault shapes.
+- [x] **Daemon truthfulness (the port half)** — `daemon/port-presence.ts` gives a three-state answer (`daemon` / `foreign` / `free`) from two probes and no platform code. `serve` now refuses a foreign port and waits for a real bind before claiming success; `status` and `doctor` name the obstacle. Guarded by `daemon-port-honesty-test`, which squats the port and includes the free-port control. (#105, #112, #115)
+- [x] **`daemon_alive` heartbeat** — `daemon/heartbeat.ts` beats unconditionally on a fixed cadence (30s, `RETICLE_HEARTBEAT_MS` to override) and `classifyDaemonLife` reads a log back into `alive` / `clean` / `signalled` / `died_silently` / `unknown`. A heartbeat nobody interprets is only log volume, so the reader ships with it and is exported for the gate. Guarded by `daemon-heartbeat-test`, which SIGKILLs a real daemon and includes the tidy-shutdown control. (#123)
+- [x] **`observation_lost`** — a new `VerifiedReason`, matched above the `pass === false` clause, so a lost connection grades UNKNOWN instead of being reported as a failed assertion. Signalled by a structured flag from `waitForPredicate`, never by matching on `failureReason` (which is free prose about the app everywhere else it is produced). Threaded through the assert and wait paths too, not just act. (#124)
+- [x] **Telemetry chokepoint coverage** — `tools/dispatch-chokepoint.test.ts` scans for any `.handler(` call outside `runTool` and fails unless it is declared with a stated reason and cost. Three exist today: family folding in `merge-tools.ts` (counted as the family, not the member), `verify-change-tools.ts` (inner `flow_verify` uncounted), and the bridge test harness. Two of those are known observability gaps — the value is that they are now _known_ and a fourth cannot arrive unnoticed. Verified by introducing a bypass and watching it redden.
+- [x] **Specified transport faults** in place of `kill -9` — `apps/e2e/fault-proxy.mjs` (no dependency; toxiproxy is not installed and the battery is deliberately dependency-free) gives none / reset-peer / blackhole / latency / truncate over `node:net`, each proven distinguishable by its own self-check. `transport-faults-test` puts it between the MCP proxy and a real daemon and asserts the product claim: every call is ANSWERED and the stdio server survives. It also separates the two unanswered-call populations by timing — a queued call answered by the 20s queue timer, a call broken in flight answered in ~600ms via `sse_aborted`. A toxic breaks the connection and never the process, so the self-inflicted `kill -9` confusion is unreachable here.
+
+### Phase 2 — the install gate
+
+- [x] **Tier 1 — all three `init` paths** — `apps/e2e/install-gate.mjs` (`pnpm gate:install`), wired into CI as its own `install-gate` job. Scaffolds `npm create vite`, `create-next-app` (app router) and `create-next-app --no-app` (pages router), publishes this checkout to a local Verdaccio, lets **`init` do its own dependency install** from it, boots each app, opens it in a real browser and POLLS for a session. **3/3 scaffolds, 8/8 assertions each.** The pages-router path — no `app/` root layout, so connect must mount via `pages/_app` — is the one that once did nothing at all, silently.
+  - `⚠` is an absolute zero, not a tolerated exemption. The earlier `file:`-wired version had to pass `--no-install` and then argue away the `⚠` it produced, which left the step most likely to regress as the one step untested.
+  - A `package-lock.json` check confirms the SDK came from the local registry. Without it a scope typo silently measures PUBLISHED code — which is exactly the defect this work found in `docs/local-registry.md` (`@reticle:` vs `@reticlehq:`).
+  - **Negative control, run FIRST in CI** (`pnpm gate:install:self-test`): every scaffold is mis-wired to a port the daemon is not on and every one must go RED. Verified — all three fail on the session assertion alone (7 passed, 1 failed), attributed FAIL rather than INCONCLUSIVE because the bridge was provably up. A guard that has never failed is not a guard.
+  - `file:` wiring is a dead end and the reason is worth keeping: npm symlinks it, which Vite resolves and Next does not; `--install-links` copies instead and then cannot resolve `workspace:*` at all.
+- [◐] **Tier 2 — built, NOT live.** The sending half is `fixtures-dispatch` in `ci.yml` (on `main` only, never fails the workflow — it is a notification, and the verdict lands in the fixtures repo's run). The receiving half is a template at [`docs/fixtures-dispatch-receiver.yml`](./fixtures-dispatch-receiver.yml), kept in the _sending_ repo so the two ends of the contract cannot drift apart.
+  - **Blocked on two things neither of which can be done from inside this repo:** a fine-grained PAT with Actions:write on `reticle-fixtures` added as `FIXTURES_DISPATCH_TOKEN`, and the template copied into that repo. Until the token exists the job says so and exits 0.
+  - **It has never run.** Every line is unverified. Tier 2 appearing in this plan is not Tier 2 being live, and the checkbox is deliberately ◐ rather than ✗ or ✓.
+- [x] **Committed baseline of what `init` plans** — `apps/e2e/install-baseline.json`, one line per step (`mark title → target`) per scaffold, diffed on every run; `--update-baseline` re-records it so a change arrives as a reviewable diff. "Zero ⚠" is an absolute and cannot carry this alone: a step silently changing mark (`✓ → ℹ`) still passes it, and a step DISAPPEARING from the plan passes it most comfortably of all, because the thing that would have warned you is the thing that is gone. A threshold answers "is this bad"; a baseline answers "is this DIFFERENT", and silent regressions are almost always the second question.
+  - The `target` is in the fingerprint and is the load-bearing field. Leaving it out — which the first version did, on an assumption about absolute paths that was simply wrong — made the app-router and pages-router baselines byte-identical, so a regression mounting the pages-router app into the wrong file would have diffed clean. `Mount ReticleDev → app/layout.tsx` vs `→ pages/_app.tsx` is the whole distinction.
+  - Proven by tampering: changing one committed entry to `vite.config.js` reddens with a readable expected/got, while every other assertion stays green — which is the point, since a one-character target change is invisible to both "zero ⚠" and "a session appeared".
+- [x] **Risk routing** — a `changes` job computes the diff with plain `git diff --name-only` (no third-party action: the question is "what changed", and a paths-filter dependency for a one-line diff is a supply-chain decision for nothing) and gates `install-gate` on it. It **fails open** — an unresolvable base ref runs every tier, because the cost of a false positive is CI time and the cost of a false negative is the 0%-connect class shipping again.
+  - The reason this was deferred is now solved rather than ignored: a job skipped by an `if:` reports **skipped**, and a branch-protection rule requiring `install-gate` directly would block every docs-only PR forever, waiting on a job that will never run. So nothing is required directly — a single aggregate `gate` job is, and it passes when every dependency succeeded **or was deliberately skipped**, and fails on anything else. `always()` on that job is load-bearing; without it the aggregate is itself skipped whenever a dependency is, reproducing the problem one level up.
+  - Routing verified against twelve representative paths without touching CI.
+
+### Phase 3 — the client matrix
+
+**Blocked on `init` learning each client.** Today only Claude Code (`claude mcp add`) and Cursor (`~/.cursor/mcp.json`) are first-class; everything else gets a printed JSON snippet, so a `v2.5.0-<client>` artifact would measure the contributor's copy-paste rather than the product.
+
+- [x] **`init` support per client** — `init/mcp-clients.ts` registers Reticle with **seven** clients, not two. Every path and shape was read from that client's own documentation rather than recalled: Cursor/Windsurf/Gemini share `mcpServers`, VS Code uses `servers`, OpenCode uses `mcp` with the command as an **array**, Codex is TOML. A single "write mcp.json" assuming the Cursor shape produces a file three of them ignore — an install that reports success and registers nothing.
+  - Detection is conservative and one-directional: we write into a config a client **already has**, never creating `~/.gemini` or `~/.codeium` for somebody who does not use them.
+  - Codex is deliberately not auto-written. Editing TOML without a parser risks every _other_ server in the user's file; it returns MANUAL with an exact block.
+- [x] **Per-client compat script** — `apps/e2e/client-compat.mjs`. Extracts the command from the config **exactly the way that client would**, runs it, and speaks MCP to it. 7/7 clients, 23 assertions, each advertising 17 tools.
+  - It proves only the half a machine can prove, and the verdict is named `runnable-unverified` so the distinction survives into the matrix. Whether the client _reads_ that path needs the real client, which is the submitted half.
+- [x] **Submission flow** — `apps/e2e/matrix.mjs --validate`, run by CI's `matrix-records` job on every PR. The validator refuses what cannot be acted on: `works` without `checks.toolsVisible` (the self-report the flow exists to replace), `broken` without the client's verbatim error, or any record with no host or version. Its self-check runs first, because a validator that has never refused anything is not a validator. Contributor guide in [`docs/matrix/README.md`](./matrix/README.md).
+- [x] **Generated `MATRIX.md`** — from submitted records, prettier-ignored because a generated file that fails `format:check` teaches people to skip the gate. **The current honest state is seven clients and ZERO ticks**: `◐` means a runnable entry was written where the client documents it and _nobody has run that client_, and the generated legend says so rather than rounding `◐` up to `✅`.
+
+### Phase 4 — rates, not booleans
+
+Connection stability is a rate. A pass/fail cannot express "breaks a lot", and a number that is not recorded cannot regress.
+
+- [x] **Soak with a recorded stability rate** — `apps/e2e/soak.mjs` (`pnpm gate:soak`), run inside the e2e battery where a paired app already exists, and appended to `bench/soak-history.jsonl` so the rate can regress against itself. One held-open MCP link for the whole run, never a reconnect per call (harness rule 3). First recorded row: **120/120 answered, 0 link drops over 39s**.
+  - **Idle time between rounds is the point**, not a pause for politeness. 150 back-to-back calls finish in seconds and measure throughput; the disconnect users actually report happens while nobody is calling — the agent is thinking and the next call finds the link gone. Keep-alives, idle shutdown and proxy timeouts all live in that gap, so a soak with no idle never enters it. `--idle-ms 30000 --rounds 60` is the half-hour release soak.
+  - Attribution is 3-valued: a transport that did not stay up reports INCONCLUSIVE and claims nothing about the product (harness rule 4).
+- [x] **Per-tool latency and failure budgets** — same run, `bench/TOOL-PROFILE.md`. Answers "which tool is breaking": `tool-surface-sweep` proves each tool is callable **once**, and one call cannot have a failure rate.
+  - **Latency is recorded, NOT gated, and that is a deliberate deviation from the wording of this plan.** CLAUDE.md: timing assertions are a bug. A p95 budget in wall-clock ms is a statement about the machine, goes red only under parallel CI load, and teaches everyone to re-run — a gate people re-run has stopped working. A >4x p95 jump prints a loud WARN instead. What IS gated: answer rate (absolute) and per-tool failure rate (vs the recorded baseline), both deterministic.
+  - The warn carries a 50ms floor, added because the first real run shouted `reticle_sessions p95 8ms vs 1ms (>4x)` — true, imperceptible, and exactly how a warning channel dies.
+  - It profiles the **6 repeatable read-only tools, not all 48 advertised**, and says so in the generated file. Repeating a mutating tool measures the fixture drifting rather than the tool degrading.
+  - Eleven-case self-check (`node apps/e2e/soak.mjs --self-check`), in CI's `matrix-records` job. It needs no build and no app — proven by running it in an empty directory, which is how a static import of the built CLI was caught.
+- [ ] false-green scorecard as a standing gate against apps we did not write (#130)
+  - **Genuinely blocked here, not deferred by choice.** "Apps we did not write" is the whole content of the check, and this repo contains only apps we wrote. It belongs to the fixtures repo (Tier 2) and needs `FIXTURES_DISPATCH_TOKEN`.

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-11** (macOS, M-series, `v2.5.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).