@reticlehq/server 2.8.0 → 2.9.0

package/docs/platform-integration.md

@@ -4,6 +4,8 @@ description: 'Adopt Reticle on your own codebase, or embed it inside an AI app-b
 icon: plug
 ---
 
+Two ways in. **A team** runs `npx @reticlehq/server init` once and points its coding agent at the MCP server. **A platform** adds the dev-only SDK to its generated-app template, runs `npx @reticlehq/server serve --http --drive <preview-url>` beside each preview, and `POST`s to `/verify` after every generate or edit, gating the ship on `run.verdict.status === 'pass'` and feeding `run.repair.failurePackets[]` back to a fixer agent.
+
 > The one guide for adopting Reticle, both for a team using a coding agent on its own app and for an AI app-builder platform (Lovable / Emergent / Bolt) embedding Reticle in its generation pipeline. Reticle reads the program from _inside_ a running app and returns a **verdict with evidence** ("did it actually work?"), not a screenshot. Enterprise/premium access lives in [`enterprise.md`](./enterprise.md).
 
 ## The loop

package/docs/predicates.mdx

@@ -1,11 +1,13 @@
 ---
-title: Predicate reference: the grammar of green
+title: 'Predicate reference: the grammar of green'
 sidebarTitle: Predicates
 description: The grammar for declaring what should be true. Every kind, every field, and which ones actually prove something.
 icon: filter
 ---
 
-A predicate declares what should be true. It is the argument to `until` on [`reticle_act_and_wait`](/tools-act-and-wait), and to `predicate` on [`reticle_assert`](/tools-assert) and [`reticle_wait_for`](/tools-wait-for).
+A predicate declares what should be true, as `{ kind, ...fields }`. Reticle has twelve kinds: `signal`, `state`, `net`, `route`, `element`, `text`, `console`, `animation`, `settled`, and the combinators `allOf`, `anyOf` and `not`. Which one you pick decides whether a green means anything.
+
+It is the argument to `until` on [`reticle_act_and_wait`](/tools-act-and-wait), and to `predicate` on [`reticle_assert`](/tools-assert) and [`reticle_wait_for`](/tools-wait-for).
 
 Every predicate is `{ kind, ...fields }`.
 
@@ -31,6 +33,8 @@ Take the advice. `element` and `text` are convenient and weak; `signal`, `state`
 | `route`            | medium    | Navigation happened                                    |
 | `console`          | medium    | Something logged, or nothing did                       |
 | `element` / `text` | weak      | Something rendered. A mock renders too                 |
+| `animation`        | weak      | An animation ran or finished                           |
+| `settled`          | timing    | The page went quiet. A precondition, not a proof       |
 
 ## The leaves
 
@@ -54,7 +58,7 @@ Add `"absent": true` to assert something is **gone**. The predicate for a remova
 { "kind": "text", "contains": "Saved successfully", "visible": true }
 ```
 
-Both `contains` and `value` are accepted. `absent: true` asserts the text is not present.
+`contains` is the field the published schema declares. `value` and `text` are accepted as aliases and rewritten to it. `absent: true` asserts the text is not present, and `visible: true` requires it to be on screen rather than merely in the DOM.
 
 ### net
 
@@ -76,7 +80,19 @@ The one that catches the expensive bug:
 { "kind": "route", "pathname": "/success" }
 ```
 
-`contains` also works.
+`pathname` matches the path exactly. `contains` matches anywhere in the whole route, path, query and fragment together. `path` is accepted as an alias for `pathname`, and `url` and `urlContains` as aliases for `contains`, but the canonical spellings are the ones above.
+
+A passing route verdict quotes the transition itself:
+
+```json
+"evidence": {
+  "from": "http://localhost:4310/",
+  "to": "http://localhost:4310/deployments",
+  "pathname": "/deployments",
+  "search": "",
+  "hash": ""
+}
+```
 
 <Warning>
   `route` asserts the route **changed**. Asserting the route you are already on always fails, and
@@ -115,7 +131,35 @@ Walks a dot-path, with numeric array indices. `equals` takes a literal, or an op
 | `$contains`               | substring or array membership |
 | `$length`                 | collection size               |
 
-Omit `equals` entirely to assert presence.
+Omit `equals` entirely to assert presence. A real `$length` check against this fixture:
+
+```json
+{ "kind": "state", "store": "app", "path": "deployments", "equals": { "$length": 40 } }
+```
+
+```json
+{
+  "verified": "yes",
+  "because": "assertion held at state grade over a clean capture with no channel disagreeing",
+  "pass": true,
+  "evidence": { "store": "app", "path": "deployments", "value": ["{…11 keys}", "…"] }
+}
+```
+
+Note `grade: state` in the `because` line, and that the evidence collapses each row to a size marker rather than returning forty objects.
+
+A miss quotes the real value back at you:
+
+```json
+{
+  "pass": false,
+  "failureReason": "state 'deployments.0.status' is \"queued\", expected \"live\"",
+  "observed": "deployments.0.status = \"queued\"",
+  "expected": "deployments.0.status = \"live\"",
+  "assertion": "state.equals",
+  "evidence": { "store": "app", "path": "deployments.0.status", "value": "queued" }
+}
+```
 
 `store` is optional. Leave it out and the path picks the store: if exactly one registered store exposes it, that one is read. Registering several is normal, so this is the common case rather than a shortcut. Name a store when two of them genuinely expose the same path, which is the only situation Reticle cannot resolve on its own. If no store exposes it, that is a failure rather than a question, and the miss names the stores it searched.
 
@@ -127,6 +171,16 @@ This is the predicate that catches a UI-versus-store desync. A deploy that only
 { "kind": "animation", "name": "dialog-in", "completed": true }
 ```
 
+`target` narrows it to one element. `completed: false` matches an animation that is still running.
+
+### settled
+
+```json
+{ "kind": "settled", "quietMs": 500 }
+```
+
+Network and DOM idle. This is the deterministic replacement for a fixed sleep, not a proof of anything: combine it with a real consequence rather than asserting it alone. Omitting `until` on [`reticle_act_and_wait`](/tools-act-and-wait) waits for exactly this.
+
 ## Combinators
 
 ```json
@@ -149,13 +203,13 @@ This is the predicate that catches a UI-versus-store desync. A deploy that only
 A combinator needs its own `kind`, and the children go in `predicates`. A bare
 `{ "allOf": [ … ] }` does not parse, and neither does `{ "kind": "allOf", "allOf": [ … ] }`.
 
-Reticle refuses the call rather than running half of it: _"Nothing ran, the predicate was not evaluated, so no verdict was produced."_ Better to be told than to get a green from an assertion that never executed.
+Reticle refuses the call rather than running half of it. The real refusal names the field, the fix and the consequence: _"predicates: Required; unknown field allOf. Nothing ran, the predicate was not evaluated, so no verdict was produced. allOf accepts: predicates."_ Better to be told than to get a green from an assertion that never executed.
 
 </Warning>
 
 `allOf` is the workhorse. "The signal fired **and** exactly one request went out **and** the console stayed clean" is a genuinely strong check, and it is one call.
 
-Each child reports its own evidence:
+Each child reports its own evidence, in order. That is a real verdict for exactly the `allOf` above:
 
 ```json
 "evidence": [
@@ -165,6 +219,21 @@ Each child reports its own evidence:
 ]
 ```
 
+On a failure each child reports separately too, so you can see which one broke:
+
+```json
+"evidence": [
+  {
+    "pass": false,
+    "expected": "an element matching {\"role\":\"dialog\"} in state 'visible'",
+    "observed": "no matching element on the page",
+    "assertion": "element.present",
+    "evidence": { "presentTestids": ["deploy-table", "filter-search", "env-filter"] }
+  },
+  { "pass": true, "evidence": { "absent": true } }
+]
+```
+
 ## Timing and scoping
 
 | Field | Where | What it does |

package/docs/quickstart.mdx

@@ -1,10 +1,12 @@
 ---
-title: Quickstart: proof in five minutes
+title: 'Quickstart: proof in five minutes'
 sidebarTitle: Quickstart
 description: Install Reticle, connect your coding agent, and get a real verdict with evidence in about five minutes.
 icon: rocket
 ---
 
+**Run `npx @reticlehq/server init` in your project, restart your dev server and your agent, then ask your agent to drive a flow.** That is the whole install. Reticle is a verification layer for AI coding agents: it embeds a dev-only SDK in your running web app so an agent can prove a change works instead of guessing.
+
 By the end of this page your agent will click a button in your app and prove what happened: the request that fired, the state that changed, and the file to open if it didn't.
 
 <Note>
@@ -81,10 +83,10 @@ npx @reticlehq/server open
 This reuses the tab you already have open, or opens one if you don't. The SDK connects to the local daemon over a WebSocket, and your agent can now see the app.
 
 <Warning>
-  If the browser console says it "could not reach the bridge", your app and the daemon disagree
-  about the port. Set it explicitly: `VITE_RETICLE_WS_URL=ws://localhost:4400/reticle` for Vite, or
-  `reticle.connect({url})`. This is the single most common setup problem, and the console message
-  tells you the exact port it tried.
+  If the browser console says `[Reticle] this page could not open a websocket to …`, your app and
+  the daemon disagree about the port. Set it explicitly:
+  `VITE_RETICLE_WS_URL=ws://localhost:4400/reticle` for Vite, or `reticle.connect({url})`. This is
+  the single most common setup problem, and the console message names the exact address it tried.
 </Warning>
 
 ## Step 4. Look at the page
@@ -193,6 +195,50 @@ Read what that actually proves:
 
 That third state is the one that matters. Most tools have two outcomes and quietly file "I couldn't tell" under "fine". A verification layer that cannot admit uncertainty is just a very confident random number generator.
 
+## Frequently asked questions
+
+<AccordionGroup>
+  <Accordion title="How long does it actually take to install Reticle?">
+    One command and two restarts. `npx @reticlehq/server init` registers the MCP server, installs
+    the SDK, wires your build config and writes the agent rules. Then restart your dev server, so it
+    picks up the new build plugin, and restart your agent, so it re-reads its MCP server list. The
+    MCP registration is global, so every later project starts with the tools already there.
+  </Accordion>
+
+<Accordion title="Do I need to write tests or learn a query syntax?">
+  No. You talk to your agent in plain language and it calls the tools. There is no spec file, no
+  selector language and no test runner involved in the loop on this page. If you later want the same
+  flow to block a bad merge, you can save it and run it in CI, but that is a separate step.
+</Accordion>
+
+<Accordion title="Will any of this end up in my production build?">
+  No. The SDK is dev-only. The Vite plugin declares `apply: 'serve'`, so it is dropped from `vite
+  build` entirely, and `connect()` self-disables when the build reports `NODE_ENV=production`. The
+  recommended wiring also guards the call behind `import.meta.env.DEV`, so there are two independent
+  locks.
+</Accordion>
+
+<Accordion title="Does my code or my app's data leave my machine?">
+  No. The daemon runs on your machine and the SDK runs in your browser. No application code, DOM,
+  network traffic or console output leaves it. Anonymous product analytics are sent unless you opt
+  out with `npx @reticlehq/server telemetry disable`, and they never include your code or your app's
+  data.
+</Accordion>
+
+<Accordion title="What if my framework is not React or Next.js?">
+  The core is framework-neutral, so DOM, network, console, routing and source mapping work anywhere
+  JavaScript runs. What varies is how `connect()` gets into your app and whether you get component
+  identity on top. See [Frameworks](/frameworks) for the exact wiring per stack and an honest table
+  of what is gated in CI versus wired but unverified.
+</Accordion>
+
+  <Accordion title="Nothing connected. What is the first thing to check?">
+    Run `npx @reticlehq/server doctor`. If it shows the daemon running but `sessions` at zero, your
+    app is not reaching the bridge, and the usual cause is a port mismatch. The bridge port is not
+    your dev-server port. See [Troubleshooting](/troubleshooting).
+  </Accordion>
+</AccordionGroup>
+
 ## Where to go next
 
 <CardGroup cols={2}>

package/docs/recipes.mdx

@@ -1,11 +1,11 @@
 ---
-title: Recipes: copy, paste, verify
+title: 'Recipes: copy, paste, verify'
 sidebarTitle: Recipes
 description: Worked examples for the situations you are actually in, with the real response each one returned.
 icon: book-open
 ---
 
-Each recipe is a situation, the call that verifies it, and what came back. Every response on this page was captured from a running app.
+Each recipe is a situation, the call that verifies it, and what came back. Every response on this page was captured from a running app on 2026-08-16. Refs like `e605` are session-specific: take your own from [`reticle_query`](/tools-query) before copying a call.
 
 ## "Did the login actually work?"
 
@@ -13,7 +13,7 @@ One call, three conditions. The signal fired, exactly one request went out, and
 
 ```json
 {
-  "ref": "e5",
+  "ref": "e605",
   "action": "click",
   "until": {
     "kind": "allOf",
@@ -51,7 +51,7 @@ Each child predicate reports its own evidence, in order. `count: 1` is the part
 ## "Did navigating actually change the view?"
 
 ```json
-{ "ref": "e17", "action": "click", "until": { "kind": "signal", "name": "nav:changed" } }
+{ "ref": "e618", "action": "click", "until": { "kind": "signal", "name": "nav:changed" } }
 ```
 
 ```json
@@ -62,9 +62,11 @@ Each child predicate reports its own evidence, in order. `count: 1` is the part
     "evidence": { "name": "nav:changed", "data": { "view": "deployments" } }
   },
   "summary": {
-    "stateDiffs": [{ "path": "view", "from": "overview", "to": "deployments" }],
-    "route": "/deployments"
-  }
+    "statePathsChanged": ["app"],
+    "stateDiffs": [{ "path": "view", "from": "overview", "to": "deployments", "atMs": 49084 }],
+    "signals": ["nav:changed"]
+  },
+  "honesty": { "grade": "signal", "coverage": { "pct": 100, "partial": false } }
 }
 ```
 
@@ -76,8 +78,9 @@ Here is a real failure, kept because it teaches more than another pass.
 
 ```json
 {
-  "ref": "e23",
+  "ref": "e623",
   "action": "click",
+  "args": { "confirmDangerous": true },
   "until": {
     "kind": "allOf",
     "predicates": [
@@ -98,19 +101,23 @@ Here is a real failure, kept because it teaches more than another pass.
         "pass": false,
         "expected": "an element matching {\"role\":\"dialog\"} in state 'visible'",
         "observed": "no matching element on the page",
-        "evidence": { "presentTestids": ["deploy-table", "filter-search", "env-filter", "…"] }
+        "assertion": "element.present",
+        "evidence": {
+          "presentTestids": ["deploy-table", "filter-search", "env-filter", "sign-out", "…"]
+        }
       },
       { "pass": true, "evidence": { "absent": true } }
     ]
   },
   "summary": {
-    "stateDiffs": [{ "path": "newDeployOpen", "from": false, "to": true }],
+    "stateDiffs": [{ "path": "newDeployOpen", "from": false, "to": true, "atMs": 60862 }],
     "signals": ["modal:opened"]
-  }
+  },
+  "capsule": { "blastRadius": ["state app", "signal modal:opened"], "firstDivergence": null }
 }
 ```
 
-Read the `summary`. The modal **did** open. `newDeployOpen` went `false → true` and the app fired `modal:opened`.
+Read the `summary`. The modal **did** open. `newDeployOpen` went `false` to `true` and the app fired `modal:opened`. `capsule.blastRadius` says the same thing as a list: the click moved the `app` store and fired `modal:opened`, and nothing else.
 
 The assertion was wrong, not the app. That modal is a `div` with no `role="dialog"`, so a role query could never match it. (Which is also an accessibility bug worth fixing, found for free.)
 
@@ -135,14 +142,16 @@ An empty `reticle_query` result tells you what _is_ there:
   "count": 0,
   "elements": [],
   "hint": {
-    "route": "/",
+    "route": "/hostile",
     "knownEmptyState": true,
-    "presentTestids": ["nav-overview", "nav-deployments", "kpi-deploys", "…"]
-  }
+    "presentTestids": ["nav-overview", "nav-deployments", "hostile-view", "hostile-ticker", "…"],
+    "presentRegions": [{ "role": "list", "childCount": 0, "name": "hostile-feed", "sample": [] }]
+  },
+  "cost": { "bytes": 402, "tokens": 101 }
 }
 ```
 
-In this case the testid existed, on another route. The hint saved a snapshot and a guess.
+The testid existed, on another route. `hint.route` says where you actually are and `presentTestids` says what is here instead, for 101 tokens and no snapshot. `presentRegions` is the other half: a list with `childCount: 0` is an empty state, which is a different bug from a list that failed to render at all.
 
 ## "Is this button destructive?"
 
@@ -158,7 +167,7 @@ Reticle refuses controls that look destructive, before acting:
 Confirm it explicitly when you mean it:
 
 ```json
-{ "ref": "e23", "action": "click", "args": { "confirmDangerous": true }, "until": { … } }
+{ "ref": "e623", "action": "click", "args": { "confirmDangerous": true }, "until": { … } }
 ```
 
 <Note>
@@ -215,10 +224,20 @@ Then drive the flow and assert the error UI appears. Pass `clear: true` to turn
 
 <Warning>
 This one needs a **Reticle-driven browser**, because mocks are applied through CDP and the always-on
-SDK cannot do that. A pooled lease is **not** enough. Verified: `reticle_lease` still returns
-`{ "ok": false, "reason": "no-cdp-provider" }`.
+SDK cannot do that. A pooled lease is **not** enough. Re-verified on 2026-08-16: calling it against a
+tab from `reticle_lease` returns
 
-Your route is `RETICLE_CDP_URL` pointed at a Chrome started with `--remote-debugging-port`. The same applies to `reticle_screenshot`, `reticle_visual_diff` and `reticle_viewport`.
+```json
+{
+  "applied": false,
+  "count": 0,
+  "ok": false,
+  "reason": "no-cdp-provider",
+  "recommendation": "this needs a Reticle-driven browser (it is applied through CDP, which the always-on SDK cannot do), start with `reticle drive <url>` or set RETICLE_CDP_URL"
+}
+```
+
+Under a driven browser the same call answers `{ "applied": true, "count": 1 }`. The same rule applies to `reticle_screenshot`, `reticle_visual_diff` and `reticle_viewport`, which report `no-visual-provider` instead.
 
 </Warning>
 
@@ -227,10 +246,31 @@ Your route is `RETICLE_CDP_URL` pointed at a Chrome started with `--remote-debug
 Record it once, replay it forever:
 
 ```json
-{ "tool": "reticle_flow_verify" }
+{ "tool": "reticle_flow_verify", "args": { "names": ["docs-check"] } }
+```
+
+Omit `names` to replay every saved flow. Either way you get one consolidated verdict, and only the failures carry detail:
+
+```json
+{
+  "status": "fail",
+  "total": 1,
+  "passed": 0,
+  "failed": 1,
+  "summary": "0/1 flows pass, 1 need attention: docs-check",
+  "failures": [
+    {
+      "flow": "docs-check",
+      "verdict": "drift",
+      "whatChanged": "testid \"login-submit\" not found",
+      "whereInSource": "src/components/Login.tsx:81",
+      "nextAction": "rebind the anchor to \"sign-out\" (closest survivor), or update the flow if the change was intended."
+    }
+  ]
+}
 ```
 
-Replays every saved flow and returns one consolidated verdict.
+It also returns `flaky`, the flows it has seen both pass and fail on unchanged code. Treat that list as a bug in the flow, not in the app.
 
 <CardGroup cols={2}>
   <Card title="The predicate grammar" icon="filter" href="/predicates">

package/docs/skill-file.mdx

@@ -1,10 +1,12 @@
 ---
-title: The SKILL file: paste and go
+title: 'The SKILL file: paste and go'
 sidebarTitle: SKILL file
 description: One URL you paste into any coding agent to teach it Reticle. How it works, what it contains, and when you need it at all.
 icon: graduation-cap
 ---
 
+Paste `https://raw.githubusercontent.com/reticlehq/reticle/main/SKILL.md` into any coding agent and say "read this and set up Reticle". The document installs Reticle, wires it into your app, and then drives a proper verification loop, choosing setup mode or test mode itself based on whether `.reticle.json` already exists. You often do not need it: `npx @reticlehq/server init` configures Claude Code and Cursor directly.
+
 `SKILL.md` is a single document you hand to a coding agent. It teaches the agent to install Reticle, wire it into your app, and then drive a verification loop properly. Without you explaining any of it.
 
 ```

package/docs/state-management.mdx

@@ -4,6 +4,8 @@ description: Register any store so Reticle can read what your app believes. Zust
 icon: database
 ---
 
+**Reticle reads any store that has `getState()` and `subscribe()`, which covers Zustand and Redux with no adapter at all. TanStack Query, Pinia, Svelte stores, Jotai, Valtio, MobX, XState and Recoil each have a one-line adapter, and `pushStore` covers anything else.** Register one with `registerStore('app', myStore)` in your dev-only `src/reticle-dev.ts`.
+
 Reading application state is what separates a verdict from a screenshot. A `200` proves the server was reachable. A rendered row proves React ran. Only state proves your app accepted the change.
 
 Reticle needs one thing from your store: a way to read it, and a way to know when it changed.

package/docs/system-map.md

@@ -4,6 +4,8 @@ description: 'How a tool call travels from a coding agent to your app and back,
 icon: map
 ---
 
+A tool call crosses five processes and four hops: coding agent → `reticle mcp` proxy (stdio) → daemon on `:4400` (HTTP POST out, SSE back) → browser SDK (WebSocket) → your app. Each hop has its own failure vocabulary and its own way of lying, and the ones marked **silent** below fail with no error reaching either the agent or you.
+
 > 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).
@@ -56,7 +58,7 @@ Three different counts, all measured, and the difference between them matters:
 | --- | --- |
 | **68** | name constants in `ReticleTool` |
 | **48** | tools advertised under `RETICLE_ADVERTISE_ALL_TOOLS=1`, i.e. what `tool-surface-sweep-test` drives (51 calls) |
-| **17** | advertised by default; the rest are reached through `reticle_run` |
+| **19** | 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).
 

package/docs/telemetry-contract.md

@@ -103,6 +103,7 @@ The single exception is `daemon_stopped`, which is **awaited**, because the proc
 | `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 |
+| `instrumentation_stalled` | the daemon waited and no app ever arrived | the same funnel step, seen from the failure side; 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 |
@@ -116,7 +117,17 @@ Nothing measured the second. `daemon_started` and `mcp_client_connected` describ
 
 `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.
+### The counterpart: `instrumentation_stalled`
+
+`app_instrumented` fires on success and only on success, so the larger population, runs where no app ever arrives, exists in the data as an **absence**. An absence is the one thing telemetry cannot interpret: it cannot separate "nothing was ever wired" from "the process was killed before it could say so" from "we never sent the event". Since the funnel breaks at this step and nowhere else, this is the one silence worth converting into a signal.
+
+`instrumentation_stalled` fires **once per daemon run**, only after the daemon has been up past a generous threshold, and **never once an app has connected**. A run that starts slowly and then works reports nothing at all. It carries the same three facts as its success counterpart so the two are directly comparable, with `msWaited` in place of `msToFirstApp`.
+
+Read it against `agentAttached`, which is what makes it actionable rather than merely sad. A stalled daemon with no agent attached is somebody who installed and walked away, and is not a defect. A stalled daemon **with** an agent attached is the failure the product actually has: the tools are loaded, something is asking for them, and there is nothing on the other end to drive.
+
+It deliberately carries no diagnosis. Whether a dev server is listening is a live probe, and running one on a timer to enrich a metric would be collecting for the metric's sake. The diagnosis belongs where a human or an agent asks for it.
+
+What neither event can 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`
 
@@ -124,9 +135,9 @@ Count sessions with **`daemon_stopped`** (`final: true`). It fires once, at a cl
 
 A running daemon rolls its window up every 5 minutes as **`session_progress`** (`final: false`), same payload shape. Sum work across both; count sessions with neither summed nor doubled.
 
-This split exists because the flush used to be emitted AS `daemon_stopped`, an event named for an exit, fired while the process was alive. One day's export: 98 `daemon_stopped` events were 73 exits + 25 flushes, so a session count was 34% high. Worse, the two populations are opposites: every one of the 25 flushes had tool calls and **not one of the 73 exits did**, because a daemon that has served a tool never idle-exits and so never reaches a clean shutdown. A funnel over the raw event describes active sessions at one end and abandoned ones at the other.
+This split exists because the flush used to be emitted AS `daemon_stopped`, an event named for an exit, fired while the process was alive. Anything counting sessions over the raw event therefore over-stated, and the two populations it merged are opposites: a flush comes from a daemon that has served tool calls, while a clean exit comes from one that has not, because a daemon that has served a tool never idle-exits and so never reaches a clean shutdown. A funnel over the raw event describes active sessions at one end and abandoned ones at the other.
 
-The flush interval is also the **bound on what is lost**: nothing calls shutdown when a working daemon is finally killed, so its last partial window dies with it. At 30 minutes against a median 28-minute session that was most of the session. Only non-empty windows emit, so a short interval costs nothing on the daemons that never serve a tool.
+The flush interval is also the **bound on what is lost**: nothing calls shutdown when a working daemon is finally killed, so its last partial window dies with it. The old 30-minute interval was long enough to lose most of a typical session that way. Only non-empty windows emit, so a short interval costs nothing on the daemons that never serve a tool.
 
 ## The session summary's newer fields
 
@@ -140,7 +151,7 @@ Four counters and one flag were added because the data could not answer question
 | `endedWithVerdict` | session summary (final only) | did this session ever produce a verdict. The headline metric, and previously the only thing in the payload that had to be COMPUTED, from lifetime counters sitting next to windowed ones, which is a subtraction that gets read wrong. Sent as `false` rather than omitted: a session that drove an app and never asked whether it worked is the finding. |
 | `verification.browser` | `verification_completed` | `headless` \| `headed` \| `attached`: who DROVE the browser. `attached` (Reticle launched nothing, the SDK connected from a browser somebody else opened) is the common case in production, so on its own this is mostly "somebody's own browser". |
 | `verification.brand` | `verification_completed` | WHICH browser it was: `chrome` \| `edge` \| `arc` \| `dia` \| `brave` \| `opera` \| `firefox` \| `safari` \| `other`, the closed `BrowserBrand` list in core. The axis `engine` cannot answer, since Chrome, Edge, Arc, Dia and Brave are all `blink`. The SDK reads `navigator.userAgentData.brands` (and the UA string on Firefox/Safari, which expose no `userAgentData`) and normalises IN THE PAGE: a raw brand or UA string is unbounded and fingerprintable and never leaves. Anything unrecognised is `other`. **Omitted rather than `"unknown"`** when the page did not say. A desktop webview has no brand and an older SDK does not report one, and a guess is indistinguishable from a measurement on a dashboard. |
-| `verification.reason` | `verification_completed` | WHICH clause of `decideVerified` produced the verdict, from core's closed `VerifiedReason`: `inconclusive` \| `observation_lost` \| `assertion_failed` \| `contradicted` \| `already_true` \| `unclean_capture` \| `vacuous_grade` \| `outcome_pending` \| `outcome_unread` \| `unsettled` \| `proved`. See below. |
+| `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` (the page never went idle and no consequence was declared) \| `evidence_incomplete` (the assertion held, but a channel's outcome had not arrived when the window closed) \| `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, such as a cross-origin frame or 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. |
@@ -184,7 +195,7 @@ So `plugin` is the only route detectable without anybody typing anything (the pl
 
 Captured against the real classifier: `verified: 'unknown'` covered "the agent malformed the call", "the consequence was already true", "the app answered 202", "a 2xx body went unread", "the capture was not clean", "nothing was asserted at a real grade" and "the page never settled": **seven causes, two wire payloads**. They belong to three different owners (the agent, the app, Reticle) and need opposite responses: teach the agent, wait and re-check, or ship a fix. On a dashboard they were one bar. `verified: 'no'` collapsed the same way: "channels disagree" (Reticle earning its keep) and "the agent's predicate failed" were the same string.
 
-`VerifiedReason` lives in `@reticlehq/core` and is the **single list**. `decideVerified` returns a member from every clause, so a new clause cannot compile without one; `verified.test.ts` drives all ten and fails if a member exists that no clause produces. `verification-of.ts` narrows the result field against `Object.values(VerifiedReason)`, and anything else is dropped rather than forwarded, because a string nobody can group by is worse than a gap. **Nothing re-lists these**, including the battery spec, which imports the enum from core's build.
+`VerifiedReason` lives in `@reticlehq/core` and is the **single list**. `decideVerified` returns a member from every clause, so a new clause cannot compile without one; `verified.test.ts` drives every member and fails if a member exists that no clause produces. `verification-of.ts` narrows the result field against `Object.values(VerifiedReason)`, and anything else is dropped rather than forwarded, because a string nobody can group by is worse than a gap. **Nothing re-lists these**, including the battery spec, which imports the enum from core's build.
 
 Optional on purpose: a suite verdict (`flow_verify`) is a pass/fail with no clause behind it, and an older sender has none. Absent means unclassified.