@reticlehq/server 2.5.0 → 2.7.0

package/dist/tools/tools.js

@@ -78,6 +78,10 @@ const RAW_TOOLS = [
                 recommendation: z.string().optional(),
             }))
                 .describe('Connected browser sessions with health state. `projectId` groups sessions by app (stable across port changes); `leased` marks a pool-managed headless context vs a human tab.'),
+            why: z
+                .string()
+                .optional()
+                .describe('Present ONLY when `sessions` is empty: why nothing is connected, and the next action that fixes it. An empty list is never the end of the road — read this before concluding the app cannot be driven.'),
         },
         handler: async (deps) => {
             const provider = deps.realInput;
@@ -87,6 +91,14 @@ const RAW_TOOLS = [
                 realInputAvailable: provider !== undefined ? await provider.isAvailableFor(s.url) : false,
                 leased: leasedIds.has(s.sessionId),
             })));
+            // An empty list is the most common thing this tool ever returns, and on its own it is a dead
+            // end: the agent asked the one question it knows to ask, got a confident-looking answer with
+            // no next step, and stopped. The daemon already knows WHY nothing is connected — say it here
+            // rather than only when a later tool fails for want of a session.
+            if (0 === sessions.length) {
+                const why = deps.sessions.noSessionHint();
+                return { sessions, ...(why === undefined ? {} : { why }) };
+            }
             return { sessions };
         },
     },
@@ -193,6 +205,10 @@ const RAW_TOOLS = [
                 .string()
                 .optional()
                 .describe('CSS selector or element ref to restrict the search to a subtree.'),
+            self: z
+                .boolean()
+                .optional()
+                .describe('Return the `scope` element ITSELF instead of searching inside it. Use when the target is a plain layout container with no role, name, testid or text of its own — which is routinely the element that carries the handler, and is otherwise unreachable because every query excludes its own scope root. Requires `scope`.'),
             attrs: z
                 .array(z.string())
                 .optional()
@@ -297,7 +313,13 @@ const RAW_TOOLS = [
                 // The handler forwards an explicit allowlist, so a new input is silently dropped unless it is
                 // added here — the browser saw no `attrs` and returned undefined while the unit tests, which
                 // call matchQuery directly, passed. Schema plus implementation is not the whole wire.
+                //
+                // It happened again with `self`, in the same session that wrote this comment: declared on the
+                // tool, implemented in the browser, verified by unit tests that call `runQuery` directly, and
+                // dropped here — so the live call returned zero matches with no error. `query-forwarding.test.ts`
+                // now asserts the payload, because a comment is not a guard.
                 attrs: args['attrs'],
+                self: args['self'],
             }).then((result) => withSizeCost(paginateQueryResult(result, asNumber(args['limit']), true === args['count_only'])));
         },
     },

package/dist/visual/capture-cleanup.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Remember the private parent of a capture after the daemon has read it.
+ *
+ * Legacy captures live directly in `tmpdir()` and therefore have no directory to reclaim. The
+ * caller has already applied the capture-path trust-boundary check; this second exact parent check
+ * keeps the cleanup set limited to the one-level private layout.
+ */
+export declare function trackCaptureDirectory(path: string): void;
+/**
+ * Remove empty private capture directories during the daemon's existing awaited shutdown path.
+ *
+ * Deliberately `rmdir`, never recursive removal: captures are unlinked after reading, so a genuine
+ * directory is empty by shutdown. If anything unexpected remains, refusing to remove the directory
+ * is safer than widening a renderer-supplied path into a recursive delete.
+ */
+export declare function cleanupCaptureDirectories(): Promise<void>;

package/dist/visual/capture-cleanup.js

@@ -0,0 +1,39 @@
+import { rmdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname } from 'node:path';
+import { RETICLE_CAPTURE_FILE_PREFIX } from '@reticlehq/core';
+/** Private shell directories whose captures this daemon has successfully consumed. */
+const captureDirectories = new Set();
+/**
+ * Remember the private parent of a capture after the daemon has read it.
+ *
+ * Legacy captures live directly in `tmpdir()` and therefore have no directory to reclaim. The
+ * caller has already applied the capture-path trust-boundary check; this second exact parent check
+ * keeps the cleanup set limited to the one-level private layout.
+ */
+export function trackCaptureDirectory(path) {
+    const parent = dirname(path);
+    if (dirname(parent) === tmpdir() && basename(parent).startsWith(RETICLE_CAPTURE_FILE_PREFIX)) {
+        captureDirectories.add(parent);
+    }
+}
+/**
+ * Remove empty private capture directories during the daemon's existing awaited shutdown path.
+ *
+ * Deliberately `rmdir`, never recursive removal: captures are unlinked after reading, so a genuine
+ * directory is empty by shutdown. If anything unexpected remains, refusing to remove the directory
+ * is safer than widening a renderer-supplied path into a recursive delete.
+ */
+export async function cleanupCaptureDirectories() {
+    await Promise.all([...captureDirectories].map(async (dir) => {
+        try {
+            await rmdir(dir);
+        }
+        catch {
+            // Best-effort shutdown housekeeping. A non-empty or already-removed directory is harmless.
+        }
+        finally {
+            captureDirectories.delete(dir);
+        }
+    }));
+}

package/dist/visual/visual-tools.d.ts

@@ -1,4 +1,22 @@
 import type { ToolDef } from '../tools/tools.js';
+/**
+ * Only read a capture the shell wrote. The path arrives from the PAGE, and the daemon must not
+ * become a file-read oracle for whatever a compromised renderer names.
+ *
+ * Two layouts are accepted, and the pair is the whole subtlety:
+ *
+ * - `<tmp>/<prefix><dir>/<prefix><n>.png` — the shell's own PRIVATE capture directory, created 0700
+ *   so no other local user can read the screenshot or pre-place a symlink at the path we write.
+ * - `<tmp>/<prefix><pid>-<n>.png` — the legacy flat layout. Kept because the shell ships as a
+ *   SEPARATE package on the user's own upgrade schedule: an app still on the older
+ *   `@reticlehq/electron` talking to a newer daemon must keep getting screenshots, not silently
+ *   start returning no image. It grants the daemon nothing it did not already have.
+ *
+ * Every comparison is an exact match against an UNRESOLVED path, which is what refuses traversal:
+ * `<tmp>/<prefix>x/../../etc/<prefix>passwd.png` has a grandparent of `<tmp>/<prefix>x/..`, not
+ * `<tmp>`. Exactly one directory level is allowed, so a deeper nesting is refused too.
+ */
+export declare function isCapturePath(path: string): boolean;
 /**
  * The opt-in pixel layer. Both tools require a DRIVEN browser (reticle drive /
  * RETICLE_CDP_URL) — the always-on SDK ships no screenshotter — and return a structured NO_PROVIDER

package/dist/visual/visual-tools.js

@@ -5,6 +5,7 @@ import { sessionIdShape } from '../tools/tool-kit.js';
 import { asNumber, asRecord, asString } from '../tools/tools-helpers.js';
 import { diffPng } from './visual-diff.js';
 import { VisualStore } from './visual-store.js';
+import { trackCaptureDirectory } from './capture-cleanup.js';
 import { readFile, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, dirname } from 'node:path';
@@ -87,6 +88,7 @@ async function desktopCapture(deps, sessionId, fullPage) {
     try {
         const bytes = await readFile(path);
         await unlink(path).catch(() => undefined);
+        trackCaptureDirectory(path);
         return isCompletePng(bytes) ? { png: new Uint8Array(bytes) } : {};
     }
     catch {
@@ -94,12 +96,29 @@ async function desktopCapture(deps, sessionId, fullPage) {
     }
 }
 /**
- * Only read a capture the shell wrote: inside the OS temp dir, with Reticle's own filename prefix.
- * The path arrives from the PAGE, and the daemon must not become a file-read oracle for whatever a
- * compromised renderer names.
+ * Only read a capture the shell wrote. The path arrives from the PAGE, and the daemon must not
+ * become a file-read oracle for whatever a compromised renderer names.
+ *
+ * Two layouts are accepted, and the pair is the whole subtlety:
+ *
+ * - `<tmp>/<prefix><dir>/<prefix><n>.png` — the shell's own PRIVATE capture directory, created 0700
+ *   so no other local user can read the screenshot or pre-place a symlink at the path we write.
+ * - `<tmp>/<prefix><pid>-<n>.png` — the legacy flat layout. Kept because the shell ships as a
+ *   SEPARATE package on the user's own upgrade schedule: an app still on the older
+ *   `@reticlehq/electron` talking to a newer daemon must keep getting screenshots, not silently
+ *   start returning no image. It grants the daemon nothing it did not already have.
+ *
+ * Every comparison is an exact match against an UNRESOLVED path, which is what refuses traversal:
+ * `<tmp>/<prefix>x/../../etc/<prefix>passwd.png` has a grandparent of `<tmp>/<prefix>x/..`, not
+ * `<tmp>`. Exactly one directory level is allowed, so a deeper nesting is refused too.
  */
-function isCapturePath(path) {
-    return dirname(path) === tmpdir() && basename(path).startsWith(RETICLE_CAPTURE_FILE_PREFIX);
+export function isCapturePath(path) {
+    if (!basename(path).startsWith(RETICLE_CAPTURE_FILE_PREFIX))
+        return false;
+    const parent = dirname(path);
+    if (parent === tmpdir())
+        return true;
+    return dirname(parent) === tmpdir() && basename(parent).startsWith(RETICLE_CAPTURE_FILE_PREFIX);
 }
 /**
  * A PNG is complete only if it ends with IEND. This check exists because a truncated image once

package/docs/README.md

@@ -0,0 +1,55 @@
+# Docs index
+
+Two audiences share this directory, which is why it looked like twenty-five unsorted files. Every page states its own audience in the first blockquote; this index is the shortcut.
+
+**User docs are published** to [reticle.sh](https://reticle.sh) via `mint.json`. **Contributor docs are not** — they are for people working _on_ Reticle, and they live here because they belong next to what they describe.
+
+---
+
+## For people using Reticle
+
+**Start:** [getting-started.md](getting-started.md) → [usage.md](usage.md) (the full tool reference).
+
+| Page | What it answers |
+| --- | --- |
+| [getting-started.md](getting-started.md) | install it, connect an agent, verify something |
+| [usage.md](usage.md) | every tool, every argument — the reference |
+| [agent-cheatsheet.md](agent-cheatsheet.md) | the condensed version an agent keeps in context |
+| [architecture.md](architecture.md) | how it works, and why it is built this way |
+| [platform-integration.md](platform-integration.md) | Vite, Next, Remix, Astro, plain HTML |
+| [desktop-apps.md](desktop-apps.md) | Electron and Tauri |
+| [integration-patterns.md](integration-patterns.md) | wiring it into a real codebase |
+| [flows.md](flows.md) | record → save → replay → heal |
+| [testing.md](testing.md) | `@reticlehq/test` — turning a session into a CI suite |
+| [multi-agent-testing.md](multi-agent-testing.md) | more than one agent on one app |
+| [human-control.md](human-control.md) | taking the wheel back from the agent |
+| [deploy-checks.md](deploy-checks.md) | running Reticle against a deployed build |
+| [token-efficiency.md](token-efficiency.md) | why it costs less than a screenshot loop |
+| [benchmarks.md](benchmarks.md) | how the numbers were measured, including where Reticle loses |
+| [telemetry.md](telemetry.md) | what is collected, and how to turn it off |
+| [local-registry.md](local-registry.md) | installing an unpublished build |
+| [enterprise.md](enterprise.md) | the licensed surface |
+
+## For people working on Reticle
+
+**Start:** [`CONTRIBUTING.md`](../CONTRIBUTING.md) → [gates.md](gates.md).
+
+| Page | What it answers |
+| --- | --- |
+| [gates.md](gates.md) | **I changed some files — which gate do I run?** |
+| [gate-plan.md](gate-plan.md) | why the gates are shaped this way, and what is still unbuilt |
+| [system-map.md](system-map.md) | how a tool call reaches the app, and which failures are silent |
+| [telemetry-contract.md](telemetry-contract.md) | required reading before touching anything that emits |
+| [debugging.md](debugging.md) | debugging Reticle itself — the four signals and what each answers |
+| [fixtures.md](fixtures.md) | the sibling `reticle-fixtures` repo: install complexity, not regressions |
+| [matrix/README.md](matrix/README.md) | submitting an MCP-client compatibility record — the best first contribution |
+| [matrix/MATRIX.md](matrix/MATRIX.md) | which clients are known to work (generated; do not hand-edit) |
+| [`../apps/README.md`](../apps/README.md) | what belongs in `apps/`, and what does not |
+| [`../apps/e2e/harness-rules.md`](../apps/e2e/harness-rules.md) | the four rules every gate obeys, and the incident behind each |
+| [`../bench/README.md`](../bench/README.md) | what in `bench/` is live and what is a kept one-off study |
+
+`fixtures-dispatch-receiver.yml` is not a doc — it is the workflow template `reticle-fixtures` needs, kept in this repo so the two ends of the contract cannot drift apart.
+
+---
+
+**Adding a page?** Put it in the right table above. If it is user-facing, add it to `mint.json` too — a page that is published but unlisted is a page nobody finds, and a page listed here but absent from `mint.json` is one users cannot reach at all.

package/docs/agent-cheatsheet.md

@@ -7,10 +7,12 @@ One screen to get fluent. Reticle is the **proof layer for AI agents** — no sc
 | Verb | Tool | One-liner |
 | --- | --- | --- |
 | **look** | `reticle_snapshot` / `reticle_query` | See the page (semantic tree) / find one specific element. |
-| **act** | `reticle_act` / `reticle_act_and_wait` | Click/fill a `ref` / act + wait for a predicate in one hop. |
+| **act** | **`reticle_act_and_wait`** / `reticle_act_sequence` / `reticle_act` | **Act + name the consequence, one hop — reach for this first.** / batch a whole journey in one hop / move the app and prove nothing. |
 | **observe** | `reticle_observe` / `reticle_wait_for` | Everything the app did after `since` / block until true. |
 | **assert** | `reticle_assert` | Evaluate a predicate → `{ pass, evidence, failureReason? }`. The end of every loop. |
 
+> **Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** Everything else moves or reads the app and proves nothing, so a drive ending without one of those two has no result however many tools it used. `reticle_act` is the tool agents reach for by habit and it catches nothing; `act_and_wait` is where defects actually surface. And `verified: "unknown"` is not a pass — it means Reticle drove the app and could not tell what happened. Report it as unknown.
+
 `reticle_act` returns a `since` cursor — pass it to `reticle_observe({ since })` to scope the window. Elements are addressed by stable refs (`e7`) from `snapshot`/`query`; they re-resolve across re-renders.
 
 **`assert`/`wait_for` are auto-scoped to your last act.** By default they only count events buffered _since_ the most recent act, so a stale signal from a previous step can't fake a pass — pass an explicit `since` to override. **Clicks run the code, not pixels:** `reticle_act` click fires the full pointer sequence on the element (no coordinate gesture for the HUD to intercept), reports `occluded:true` when something covers the target, and stays synthetic even with CDP configured (use `args:{ native:true }` for a trusted native click).
@@ -21,6 +23,16 @@ One screen to get fluent. Reticle is the **proof layer for AI agents** — no sc
 - Need to wait without acting? `reticle_wait_for({ predicate: { kind: "settled", quietMs } })`.
 - Waiting for a specific outcome? Pass that consequence as the predicate (`{ signal }` / `{ net }`), or `allOf` it with `{ kind: "settled" }` to wait for both the event _and_ the page going quiet.
 
+**A predicate that does not parse produces NO verdict — not a failing one.** Nothing runs, so the drive ends with no result at all, which is strictly worse than a failure. The shapes below are the ones agents reach for most; the first column now works, but knowing the second saves you the round trip:
+
+| You may write | It means |
+| --- | --- |
+| `{ kind: "text", text: "Saved" }` | `{ kind: "text", contains: "Saved" }` |
+| `{ kind: "element", role: "button", text: "Save" }` | `{ kind: "element", query: { role, text } }` |
+| `{ kind: "route", url: "/checkout" }` | `{ kind: "route", contains: "/checkout" }` |
+
+If a predicate is still rejected, the error names the fields **that kind** accepts — read it rather than guessing again, and note `state` spells its selector `path` while `route` spells its `pathname`.
+
 **Assert a consequence, not just presence.** `{ signal }` / `{ net }` prove the feature actually did something; `{ element }` / `{ text }` only prove something is on screen — which a stale render or a locator healed to the wrong element can fake. A _passing_ presence-only `reticle_assert` returns `advice` nudging you to a consequence; heed it on anything that matters.
 
 ## The 4-layer cross-check — never trust a green the state contradicts
@@ -50,7 +62,7 @@ A claim is real only when the layers agree. Check more than the UI:
 
 The tools advertised DIRECTLY — what you'll use 90% of the time. Everything else is one `reticle_run` away (see Token note below).
 
-`reticle_sessions` · `reticle_navigate` · `reticle_snapshot` · `reticle_query` · `reticle_act` · `reticle_act_and_wait` · `reticle_observe` · `reticle_network` · `reticle_console` · `reticle_wait_for` · `reticle_assert` · `reticle_state` · `reticle_inspect` (DOM node → `src/App.tsx:104`) · `reticle_feedback` (tell the maintainers what is missing) · `reticle_session` (hand back: `{action:"yield"}` the moment you stop driving, `{action:"resume"}` after a human pause).
+`reticle_sessions` · `reticle_navigate` · `reticle_snapshot` · `reticle_query` · `reticle_act` · `reticle_act_sequence` · `reticle_act_and_wait` · `reticle_observe` · `reticle_network` · `reticle_console` · `reticle_wait_for` · `reticle_assert` · `reticle_state` · `reticle_inspect` (DOM node → `src/App.tsx:104`) · `reticle_feedback` (tell the maintainers what is missing) · `reticle_session` (hand back: `{action:"yield"}` the moment you stop driving, `{action:"resume"}` after a human pause).
 
 Frequently useful but NOT core, so reach them through `reticle_run({ tool, args })`: `reticle_domain` (learn the app + gaps), `reticle_capabilities` (the app's declared testable surface), `reticle_baseline {action:"diff"}`, `reticle_project` (run history).
 
@@ -71,7 +83,7 @@ Frequently useful but NOT core, so reach them through `reticle_run({ tool, args
 ## Start here
 
 0. Just ran `reticle init` / started the dev server? Poll `reticle_sessions()` until your tab appears — readiness is server-internal now, so the first live call already blocks until the SDK connects.
-1. `reticle_sessions` — find the connected tab (omit `sessionId` if there's only one).
+1. `reticle_sessions` — find the connected tab (omit `sessionId` if there's only one). **An empty list is not a dead end: read the `why` field.** It names which case this is — no app running, an app running that has never dialled this daemon, a project that never went through `init`, or a tab that closed — and the fix for each. Do not fall back to static reasoning until you have read it.
 2. `reticle_domain` — learn the app BEFORE testing: the saved flows, what each asserts, and the **gaps** (declared signals/testids that no flow verifies — untested intent). Tells you what to test and where the real risk is without crawling the whole app. Falls back to `reticle_capabilities` for the raw testable surface (`testids`, `signals`, `stores`, `flows`).
 3. Run the loop: **look → act → observe → assert**, cross-checking the 4 layers on anything that matters.
 

package/docs/benchmarks.md

@@ -2,7 +2,7 @@
 
 > This page assumes **zero** testing background. By the end you'll understand what software testing is, why AI coding agents made it urgent, how to tell a good verification tool from a bad one, and exactly how Reticle measures up against the main alternatives — including the places Reticle loses. If a term looks like jargon, it's defined the first time it appears.
 >
-> _The headline charts below are rendered from the measured numbers (`assets/readme/`, rendered from the measured `history.jsonl` via `assets/benchmarks/render.mjs`); supporting diagrams live in `bench/artifacts/`._
+> _Where the pictures come from, stated accurately: the **SVG charts** (`bench/artifacts/`) are generated from measured raws by `bench/harness/charts.mjs`. The **headline PNG cards** (`assets/readme/`) are screenshots of hand-authored HTML in `assets/benchmarks/src/`, rendered by `assets/benchmarks/render.mjs` — their figures are typed in by a human and are **not** read from `history.jsonl`, which this line previously claimed. Treat a card as a design asset that has to be updated by hand when a number moves, and `bench/SCORECARD.md` (plus its freshness banner) as the source of truth._
 
 ---
 

package/docs/fixtures-dispatch-receiver.yml

@@ -0,0 +1,76 @@
+# Copy this into `reticle-fixtures` as `.github/workflows/verify-on-dispatch.yml`.
+#
+# It is kept HERE, in the repo that sends the dispatch, on purpose: the two halves have to agree on
+# an event name and a payload shape, and a contract whose two ends live in different repositories
+# drifts the first time somebody edits one of them. This file is the sending end's statement of what
+# the receiving end must look like.
+#
+# It has never run. Nothing in this repository can verify it — the dispatch needs a token that does
+# not exist yet, and the receiver needs to be committed to another repository. Treat every line as
+# unverified until somebody has watched one green run, and do not let its presence here be mistaken
+# for Tier 2 being live.
+name: Verify a Reticle commit against the fixtures
+
+on:
+  repository_dispatch:
+    types: [reticle-commit]
+  workflow_dispatch:
+    inputs:
+      sha:
+        description: Reticle commit to verify
+        required: true
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    # Nine real apps, each installed and booted. This is why Tier 2 cannot block a merge.
+    timeout-minutes: 90
+    steps:
+      - name: Check out the fixtures (the pristine surface)
+        uses: actions/checkout@v4
+        with:
+          # `clean` is the branch that has NEVER been instrumented. Running init over an already
+          # wired app reports "already wired" for every step and proves nothing, which is exactly how
+          # an install regression ships unnoticed.
+          ref: clean
+
+      - name: Check out the Reticle commit under test
+        uses: actions/checkout@v4
+        with:
+          repository: reticlehq/reticle
+          ref: ${{ github.event.client_payload.sha || inputs.sha }}
+          path: reticle
+
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Build the release candidate
+        working-directory: reticle
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm build
+
+      - run: npx playwright install --with-deps chromium
+
+      - name: Materialise the fixture apps
+        run: node scripts/materialise.mjs
+
+      - name: Install into every fixture and open each one in a browser
+        # `--local` is the whole point: without it the gate can only confirm what already shipped,
+        # which is the wrong half of the question before a release.
+        run: node scripts/verify.mjs --local ./reticle
+        env:
+          # The fixtures gate's own idle shutdown once fired mid-install and scored three fixtures as
+          # install failures. A gate owns its daemon for the whole run — see the reticle repo's
+          # apps/e2e/harness-rules.md, rule 2.
+          RETICLE_IDLE_SHUTDOWN_MS: '0'
+
+      - name: Upload the run
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: fixtures-run
+          path: runs/
+          if-no-files-found: ignore

package/docs/fixtures.md

@@ -26,3 +26,20 @@ The last step is the one that earns its keep. Every install bug found so far has
 `apps/` — bench-app, next-smoke, the Remix and Astro examples, the Electron and Tauri smoke apps, atlas, and the API. These are the CI gates (`pnpm test:e2e`, `pnpm test:e2e:desktop`), and `integration-coverage.test.ts` fails if one of them goes missing while `SKILL.md` still offers its framework.
 
 The split is: **`apps/` proves the tools work. `reticle-fixtures` proves the install works.**
+
+## Wiring Tier 2 (not yet live)
+
+CI can ask this repo to verify a Reticle commit automatically — the [`vite-ecosystem-ci`](https://github.com/vitejs/vite-ecosystem-ci) shape, where a separate repo holds the downstream apps and the main repo asks it to run. The sending half is built (`fixtures-dispatch` in `.github/workflows/ci.yml`); the receiving half is a template at [`docs/fixtures-dispatch-receiver.yml`](./fixtures-dispatch-receiver.yml).
+
+**It is inert until two things happen, and neither can be done from inside this repository:**
+
+1. A fine-grained PAT with **Actions: write** on `reticlehq/reticle-fixtures`, added to `reticlehq/reticle` as the secret `FIXTURES_DISPATCH_TOKEN`. Until it exists the job logs that Tier 2 is unwired and exits 0 — it never reddens CI, because a dispatch failure has nothing to do with the change being pushed.
+2. The template copied into `reticle-fixtures` as `.github/workflows/verify-on-dispatch.yml`.
+
+The template lives in the _sending_ repo deliberately: the two halves must agree on an event name and payload shape, and a contract whose ends live in different repositories drifts the first time somebody edits one of them.
+
+**Nothing here has ever run.** Treat every line as unverified until somebody has watched one green run. Tier 2 being present in the plan is not Tier 2 being live.
+
+### Why Tier 2 exists when Tier 1 already passes
+
+`pnpm gate:install` (Tier 1) scaffolds pristine apps and catches install **regressions**. It cannot catch install **complexity**: `rowy` is 70 dependencies of somebody else's product, `phanpy` has a 130-line vite config holding ten plugins inside a `defineConfig` callback. That is where install bugs actually hide, and a scaffold deliberately has none of it. The two tiers answer different questions and neither substitutes for the other.

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 18 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`.