@reticlehq/server 2.13.1 → 2.14.0

package/docs/http-transport.md

@@ -0,0 +1,164 @@
+---
+title: 'HTTP transport'
+description: 'Drive the full reticle_* tool surface over plain HTTP and SSE, from a client that cannot hot-reload MCP tools or that is not an MCP client at all.'
+icon: 'plug'
+---
+
+Most clients reach Reticle over stdio: they spawn `reticle mcp`, and the tools appear in the agent's surface. That has one property you cannot always live with. **Many clients read their MCP tool list once, at startup**. If the daemon was not running when the client launched, the `reticle_*` tools are absent for the rest of that session, and the fix is to restart the client.
+
+The daemon also speaks MCP over HTTP, on the same port as everything else. Nothing has to reload for a client to reach it, so this is the transport for scripted runs, CI, a language with no MCP client library, and any editor that will not pick up tools mid-session.
+
+It is the same tool surface. Not a subset, not a simplified one. `reticle_snapshot`, `reticle_act_and_wait`, `reticle_assert` and the rest behave exactly as they do over stdio, because they are the same server behind a different transport.
+
+## The two endpoints
+
+| Method | Path | What it does |
+| --- | --- | --- |
+| `GET` | `/mcp/sse` | Opens a session. The response is an SSE stream that stays open, and every reply the server sends comes back on it. |
+| `POST` | `/mcp/message?sessionId=<id>` | Sends one JSON-RPC message into an open session. |
+
+The daemon listens on port **4400** by default (`RETICLE_PORT`, or `reticle serve --port N`). Run `reticle status` to confirm which port is live.
+
+## The handshake
+
+The one shape worth reading before you write any code: **the POST does not answer your request.** It replies `202 Accepted` with no result in it, and the actual JSON-RPC reply arrives on the SSE stream you opened first. A client that waits on the POST body waits forever.
+
+1. `GET /mcp/sse`. Hold the response open.
+2. The first frame is the endpoint announcement, and it carries the session id:
+
+   ```
+   event: endpoint
+   data: /mcp/message?sessionId=6f1c2b7e-1f4a-4a8e-9d5f-3f7a1b2c3d4e
+   ```
+
+   Use that `data` value verbatim as the path you POST to. Do not build it yourself: the session id is minted per connection.
+
+3. `POST` the `initialize` request there, then the `notifications/initialized` notification.
+4. `POST` `tools/list`, `tools/call`, and anything else. Match each reply to its request by the JSON-RPC `id`, off the SSE stream.
+
+When the daemon shuts down it writes a shutdown frame on the stream before the socket closes, so a client can tell a planned stop from a dropped connection.
+
+## Errors
+
+| Status | Meaning | What to do |
+| --- | --- | --- |
+| `400 missing sessionId` | The POST had no `sessionId` query parameter. | Use the path from the `endpoint` frame. |
+| `404 session not found` | That session is not open, usually because the SSE stream dropped. | Reconnect to `/mcp/sse` and handshake again. |
+| `503 MCP server not ready` | The daemon is up but the MCP server is not attached yet. | Retry. Unlike a `404`, the endpoint is real and coming. |
+
+`404` and `400` are kept apart on purpose: reconnecting fixes one and nothing about the other.
+
+## Authorization
+
+Two tiers, the same ones the WebSocket bridge uses.
+
+**Local clients need no token.** A request is trusted when its peer address, its `Host` header, and its `Origin`/`Referer` (when present) are all loopback. All three are required, because a DNS-rebound page reaches the daemon _as_ a loopback peer while carrying the attacker's `Host`, so peer address alone would not be a check.
+
+**Anything else must present the pairing token**, which is required whenever you bind beyond loopback with `RETICLE_HOST`. Either form works:
+
+```
+Authorization: Bearer <token>
+```
+
+```
+/mcp/sse?token=<token>
+```
+
+Set it with `RETICLE_TOKEN`. With no token configured, the daemon binds loopback-only and non-local requests are refused outright rather than falling back to trust.
+
+## A minimal client
+
+No MCP library. Node's standard library is enough. This opens a session, lists the tools, and takes a snapshot.
+
+```js
+import http from 'node:http';
+
+const PORT = 4400;
+let endpoint = null;
+let next = 1;
+const pending = new Map();
+
+// 1. Open the stream and keep it open. Every reply arrives here.
+http.get({ port: PORT, path: '/mcp/sse', agent: false }, (res) => {
+  let buffer = '';
+  res.setEncoding('utf8');
+  res.on('data', (chunk) => {
+    buffer += chunk;
+    const frames = buffer.split('\n\n');
+    buffer = frames.pop();
+    for (const frame of frames) {
+      const event = /^event: (.*)$/m.exec(frame)?.[1] ?? 'message';
+      const data = /^data: (.*)$/m.exec(frame)?.[1] ?? '';
+      if (event === 'endpoint') {
+        endpoint = data; // "/mcp/message?sessionId=…", used verbatim
+        start();
+        continue;
+      }
+      const message = JSON.parse(data);
+      pending.get(message.id)?.(message); // match the reply to its request by id
+      pending.delete(message.id);
+    }
+  });
+});
+
+// 2. POST a request; resolve when its reply comes back on the stream.
+function send(method, params) {
+  const id = next++;
+  const body = JSON.stringify({ jsonrpc: '2.0', id, method, params });
+  return new Promise((resolve) => {
+    pending.set(id, resolve);
+    const req = http.request(
+      {
+        port: PORT,
+        path: endpoint,
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+      },
+      (res) => res.resume(), // 202 Accepted; the answer is on the SSE stream
+    );
+    req.end(body);
+  });
+}
+
+async function start() {
+  await send('initialize', {
+    protocolVersion: '2024-11-05',
+    capabilities: {},
+    clientInfo: { name: 'my-client', version: '1.0.0' },
+  });
+
+  const notify = http.request(
+    { port: PORT, path: endpoint, method: 'POST', headers: { 'Content-Type': 'application/json' } },
+    (res) => res.resume(),
+  );
+  notify.end(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }));
+
+  const listed = await send('tools/list', {});
+  console.log(listed.result.tools.map((t) => t.name).join(', '));
+
+  const snapshot = await send('tools/call', { name: 'reticle_snapshot', arguments: {} });
+  console.log(snapshot.result.content[0].text);
+}
+```
+
+To watch the raw frames instead, `curl` is enough for the first half:
+
+```bash
+curl -N http://127.0.0.1:4400/mcp/sse
+```
+
+Then, from a second shell, POST to the path that stream printed:
+
+```bash
+curl -X POST 'http://127.0.0.1:4400/mcp/message?sessionId=<id>' \
+  -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+The `202` comes back here; the tool list appears in the first shell.
+
+## What this does not change
+
+The transport carries the tools. It does not replace the rest of the setup. The app still has to be instrumented and connected, and `reticle_sessions` is still what tells you whether a session is there to drive. A verdict reached over HTTP is a verdict reached the usual way: only `verified: "yes"` is a pass.
+
+The endpoints, the handshake, the three status codes and the `202`-then-SSE shape are pinned by `packages/server/src/mcp-http-transport.test.ts`, which drives them over raw HTTP with no client library, so the contract this page describes fails the build if it changes.

package/docs/index.mdx

@@ -44,9 +44,11 @@ Afterwards, use it whenever you change any user-facing behaviour.
 ```
 
 <Tip>
-  On Claude Code the plugin is shorter still: `/plugin marketplace add reticlehq/reticle` then
-  `/plugin install reticle@reticlehq`, which registers the MCP server and the skills in one step. On
-  most other agents, `npx skills add reticlehq/reticle`.
+  The plugin and the skills CLI are alternatives to the *registration* half only, not to `init`:
+  neither one touches your app, so you still run the command above afterwards to instrument it. On
+  Claude Code, `/plugin marketplace add reticlehq/reticle` then `/plugin install reticle@reticlehq`
+  registers the MCP server and the skills in one step; on most other agents, `npx skills add
+  reticlehq/reticle`.
 </Tip>
 
 <Card title="What that command actually changes" icon="wand-magic-sparkles" href="/install-agentic">

package/docs/install-manual.mdx

@@ -159,7 +159,7 @@ Screenshots and headless mode need the Rust crate, which is versioned independen
 
 ```toml
 [dependencies]
-reticle-tauri = "2.13"
+reticle-tauri = "2.14"
 ```
 
 ```rust

package/docs/packages/tauri.mdx

@@ -21,7 +21,7 @@ Tauri IPC observation needs nothing on the Rust side. An `invoke('load_todos')`
 
 ```toml
 [dependencies]
-reticle-tauri = "0.1"
+reticle-tauri = "2.14"
 ```
 
 Its own dependencies are `tauri = "2"` plus the per-platform capture backends: `objc2` and friends on macOS, `webview2-com` and `windows` on Windows, `webkit2gtk` and `cairo-rs` on Linux and the BSDs.

package/docs/packages.mdx

@@ -5,7 +5,7 @@ description: Every Reticle package. What it does, why it exists, when you actual
 icon: cubes
 ---
 
-Reticle is eleven packages, and most people install two. This page exists so you can tell which two, and so that the ones you skip stop looking mysterious.
+Reticle is twelve packages, and most people install two. This page exists so you can tell which two, and so that the ones you skip stop looking mysterious.
 
 <Note>
   Everything ships together at one version: whatever `npm view @reticlehq/core version` says, every
@@ -89,7 +89,7 @@ if (import.meta.env.DEV) reticle.connect();
 
 **Why it exists:** agents speak MCP; browsers speak WebSocket; somebody has to be fluent in both and own the `.reticle/` directory where flows, baselines and runs are stored.
 
-**Depends on:** `@modelcontextprotocol/sdk`, `@reticlehq/core`, `ws`, `zod`.
+**Depends on:** `@modelcontextprotocol/sdk`, `@reticlehq/core`, `@reticlehq/init`, `ws`, `zod`.
 
 **Do you install it?** Not into your project. Your agent launches it:
 
@@ -99,6 +99,18 @@ npx @reticlehq/server mcp
 
 ---
 
+## @reticlehq/init
+
+**The project scaffolder behind `reticle init`.** Detects the framework and package manager, writes `.reticle.json`, patches the build config, generates the connect snippet and the agent rules, and registers the MCP server with whichever clients are on the machine.
+
+**Why it exists:** nothing in it observes a running app. It is a build-time codemod that runs once. While it lived inside `@reticlehq/server`, a typo in a generated snippet forced a republish of the MCP server, and every MCP user downloaded a scaffolder they run once or never. It reaches back into the daemon for nothing: the version it stamps, the tracer, the outcome reporter and the bridge pairing token all arrive through one injected `InitHost`.
+
+**Depends on:** `@reticlehq/core`, and nothing else.
+
+**Do you install it?** No. `@reticlehq/server` depends on it at the same version, and the `reticle` CLI drives it.
+
+---
+
 ## @reticlehq/react
 
 **The kit most React users install.** It re-exports the browser sensor, so one install gives you `reticle`, `registerCapabilities` and everything else, and it maps a DOM node to its React component and source file through the fiber tree.
@@ -207,7 +219,7 @@ A lint rule makes the signal layer self-enforcing, which is the only way a conve
 
 ```toml
 [dependencies]
-reticle-tauri = "2.13"
+reticle-tauri = "2.14"
 ```
 
 <Warning>

package/docs/platform-integration.md

@@ -133,7 +133,7 @@ The shape is identical (in-app SDK in the template → verify in the sandbox →
 2. Since the runtime is in-browser, drive via the connected session (the SDK dials the bridge) rather than `--drive`; call verify from the Bolt agent after a build.
 3. Same act-on-verdict: gate + self-heal with the repair packets. (Bolt already detects terminal/compile errors; Reticle adds the _runtime program-truth_ layer it's blind to.)
 
-> Honest note: a platform can build a verification step itself. Reticle's case is the depth (program-state and source mapping), the determinism (0% flake, no LLM in the loop), the un-hallucinatable verdict, and a stable drop-in artifact. The reproducible benchmark in [`bench/`](../bench/README.md) measures the observation-cost and detection differences against other browser-automation MCPs.
+> Honest note: a platform can build a verification step itself. Reticle's case is the depth (program-state and source mapping), the determinism (0% flake, no LLM in the loop), the un-hallucinatable verdict, and a stable drop-in artifact. The reproducible benchmark in [`bench/`](https://github.com/reticlehq/reticle/blob/main/bench/README.md) measures the observation-cost and detection differences against other browser-automation MCPs.
 
 ---
 

package/docs/predicates.mdx

@@ -60,6 +60,8 @@ Add `"absent": true` to assert something is **gone**. The predicate for a remova
 
 `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.
 
+Use `scope` to restrict the search to a CSS selector or element ref. If Reticle reports that the text is split across the scope's children, retry its generated predicate with `"self": true`; that checks the scope root's combined subtree text while still enforcing `contains`.
+
 ### net
 
 ```json

package/docs/system-map.md

@@ -8,7 +8,7 @@ A tool call crosses five processes and four hops: coding agent → `reticle mcp`
 
 > 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).
+> Companion pages: [`harness-rules.md`](https://github.com/reticlehq/reticle/blob/main/apps/e2e/harness-rules.md) (what a gate must do about all this) and [`telemetry-contract.md`](./telemetry-contract.md) (the rules for anything that emits).
 
 ## 1. Topology: 5 processes, 4 hops
 
@@ -87,7 +87,7 @@ Two structural facts:
 
 | Failure | Silent | Guarded by |
 | --- | --- | --- |
-| proxy killed externally (the `lsof -ti` recipe) | **yes, total** | `reticle kill` frees the port and leaves the agent's own proxy alone. See [harness rule 1](../apps/e2e/harness-rules.md) |
+| proxy killed externally (the `lsof -ti` recipe) | **yes, total** | `reticle kill` frees the port and leaves the agent's own proxy alone. See [harness rule 1](https://github.com/reticlehq/reticle/blob/main/apps/e2e/harness-rules.md) |
 | proxy uncaught exception | no | `installProxyResilience` + `proxyLog` |
 | proxy exits when the reconnect budget is spent | _was the worst bug in the product_ | `onReconnectBudgetSpent` → DORMANT, never exit |
 | client closes stdin with calls in flight | no | `SHUTDOWN_DRAIN_MS` (5s) |

package/docs/telemetry-contract.md

@@ -152,7 +152,7 @@ Two questions get asked of `verification_completed` constantly and both have exa
 **"A large share of verdicts come back `unknown`."** `verified` has three values and the rule that produces it has eleven clauses, so `unknown` on its own is seven different situations belonging to three different owners. **Always break `unknown` down by `verification.reason`** before treating it as a quality number:
 
 - `inconclusive`, `nothing_declared`, `vacuous_grade` -- the agent's own call. Teach the agent; the product worked.
-- `outcome_pending`, `outcome_unread`, `unsettled`, `evidence_incomplete` -- the app had not finished. Wait and re-check; often a budget that ended early.
+- `outcome_pending`, `outcome_unread`, `unsettled`, `evidence_incomplete`, `window_closed_early` -- the app had not finished. Wait and re-check; often a budget that ended early.
 - `observation_lost`, `unclean_capture`, `absence_blind_spot` -- **ours**. Ship a fix. `uncleanLoss` names which of the three owners inside that one.
 
 An `unknown` rate quoted without this split is a number about all three at once and actionable by none of them.
@@ -188,7 +188,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` (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.reason` | `verification_completed` | WHICH clause of `decideVerified` produced the verdict, from core's closed `VerifiedReason`: `inconclusive` \| `observation_lost` \| `window_closed_early` \| `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". |
 | `project.stackUnknownReason` | `project_profiled` | WHY there is no `stack`, from core's closed `StackUnknownReason`: `no_app_found` \| `manifest_unrecognised` (we READ an app's manifest and knew nothing in it, which one line in `STACK_BY_DEP` fixes) \| `workspace_apps_unrecognised` \| `workspace_root_no_apps` (a monorepo root where discovery surfaced no app at all) \| `discovery_failed`. `stack` unknown is one of the largest buckets and an empty field is not a cause: it collapsed four facts with four different fixes. **Absent whenever a stack WAS found**, so its presence marks the unknown bucket. Note `workspace_root_no_apps` is expected to dominate over `workspace_apps_unrecognised`: `findWorkspaceApps` admits a directory only on a Vite/Next config file or a literal `next`/`vite` dependency, so a workspace app on any other framework is never surfaced and its manifest is never read. |
 | `bug.attribution` | `bug_found` | `app` \| `request` \| `reticle`: whose fault the defect was. **Absent means unclassified**, never `app`. See below. |
@@ -361,8 +361,8 @@ One deliberate exception to the rules above: `RETICLE_TELEMETRY_FILE` keeps tele
 
 | You are adding | Do this | Enforced by |
 | --- | --- | --- |
-| **A tool** | Add it to `TOOLS`. Nothing else. If its name implies a verdict (`assert`/`verify`), also add it to `VERIFICATION_TOOLS` | `telemetry-contract.test.ts` |
-| **A verdict-producing tool** | Add it to `VERIFICATION_TOOLS`. Otherwise it emits no `verification_completed` and stops counting toward the product's headline metric | ✓ |
+| **A tool** | Add it to `TOOLS`. Nothing else. If its name implies a verdict (`assert`/`verify`), also add it to `VERDICT_TOOLS` | `telemetry-contract.test.ts` |
+| **A verdict-producing tool** | Add it to `VERDICT_TOOLS` (`packages/server/src/tools/feedback-tools.ts`). Otherwise it emits no `verification_completed` and stops counting toward the product's headline metric | ✓ |
 | **A contradiction / anomaly kind** | Add it to core's enum only. `bug-found.ts` derives from it | ✓ |
 | **A new finding shape** in a tool result | Teach `bugsInResult` the field. Add a case to the contract test | ✓ |
 | **A failure path** (connect, install, crash) | Classify it into an enum with an explicit `OTHER` bucket; a classifier that cannot say "I don't know" lies instead | ✓ |

package/docs/telemetry-events.mdx

@@ -427,7 +427,7 @@ Read [`docs/telemetry-contract.md`](/telemetry-contract) before you touch anythi
 3. Add the payload key to `TelemetryEventSchema`.
 4. Add it to the emitter's key allowlist, or it will be silently dropped.
 5. Decide whether it is session-scoped and add it to `SESSION_SCOPED` if so.
-6. If it produces a verdict, add the tool to `VERIFICATION_TOOLS`. If it introduces a finding kind, add that to core's enum and never re-list it locally.
+6. If it produces a verdict, add the tool to `VERDICT_TOOLS` (`packages/server/src/tools/feedback-tools.ts`). If it introduces a finding kind, add that to core's enum and never re-list it locally.
 
 `telemetry-contract.test.ts` enforces the parts that can be enforced, and `pnpm test:e2e` runs a spec that fires every event kind against a real capture endpoint and asserts each one lands.
 

package/docs/telemetry.md

@@ -45,7 +45,7 @@ Eighteen kinds of events, each a single small JSON object. This is the whole lis
 
 **There is no per-tool-call event.** Tool usage is counted in memory and leaves once, inside `daemon_stopped`, as a histogram like `{"reticle_act": 40, "reticle_assert": 12}`. That is counts of tool NAMES from a fixed list we define, never arguments, results, selectors, or URLs.
 
-**Parameter and flag NAMES are collected; their VALUES are not.** We record that `reticle_act` was called with `ref` and `action`, and that you ran `reticle serve --headed --port`. We do not record what you set them to. This distinction is the whole safety property, and it is absolute for CLI flags: `--http-token` holds a secret, `--drive` holds a URL, `--storage-state` holds a file path, so no flag value is ever sent. For tool parameters there is one narrow exception: a short, explicit allowlist of parameters whose values are enums _we_ defined (`action: "click"`), listed in [`argument-shape.ts`](../packages/server/src/telemetry/argument-shape.ts). A value outside that allowlist reports as `other`, so a future schema change cannot quietly start forwarding free text. `reticle_act`'s `args` (the text being typed into your app, which on a login form is a password) is **never** in that allowlist.
+**Parameter and flag NAMES are collected; their VALUES are not.** We record that `reticle_act` was called with `ref` and `action`, and that you ran `reticle serve --headed --port`. We do not record what you set them to. This distinction is the whole safety property, and it is absolute for CLI flags: `--http-token` holds a secret, `--drive` holds a URL, `--storage-state` holds a file path, so no flag value is ever sent. For tool parameters there is one narrow exception: a short, explicit allowlist of parameters whose values are enums _we_ defined (`action: "click"`), listed in [`argument-shape.ts`](https://github.com/reticlehq/reticle/blob/main/packages/server/src/telemetry/argument-shape.ts). A value outside that allowlist reports as `other`, so a future schema change cannot quietly start forwarding free text. `reticle_act`'s `args` (the text being typed into your app, which on a login form is a password) is **never** in that allowlist.
 
 `daemon_stopped` carries: how long the session ran, how many tool calls and of which tools, how long each tool took (total and worst case), how many failed, how many verifications ran, browser/lease connection attempts with their failure causes, and which MCP clients connected (`claude-code`, `cursor`).
 
@@ -53,7 +53,7 @@ It also carries a snapshot of the **machine's** state (our own process's memory,
 
 ### Why a verdict came out that way
 
-`verification_completed` carries the **clause** that decided the verdict, from a fixed list we define: `proved`, `contradicted`, `assertion_failed`, `already_true`, `unclean_capture`, `vacuous_grade`, `outcome_pending`, `outcome_unread`, `unsettled`, `evidence_incomplete`, `observation_lost`, `inconclusive`.
+`verification_completed` carries the **clause** that decided the verdict, from a fixed list we define: `proved`, `contradicted`, `assertion_failed`, `already_true`, `unclean_capture`, `vacuous_grade`, `outcome_pending`, `outcome_unread`, `unsettled`, `evidence_incomplete`, `observation_lost`, `window_closed_early`, `inconclusive`.
 
 It exists because `verified: "unknown"` covered seven different situations belonging to three different owners (your app, your agent, and Reticle's own blind spots), and they arrived as one value. It is a **name from our own vocabulary**, never a description of your app: `contradicted` says two channels disagreed, not which ones, about what, or on which page.
 
@@ -127,7 +127,7 @@ Reticle verifies apps for AI agents, and for a long time it had no way to hear w
 
 Agents are instructed, in the tool description itself, never to include app source, secrets, or user data, and to describe the failure in their own words instead.
 
-**It is redacted before it leaves your machine.** Emails, credentials in URLs, `Authorization` headers and API-key assignments, recognizable vendor tokens (`sk-…`, `ghp_…`, `AKIA…`, `xoxb-…`, JWTs), and home-directory paths are stripped and replaced with `[redacted]`. This runs client-side, in [`feedback.ts`](../packages/server/src/telemetry/feedback.ts), so you can read exactly what it removes rather than take our word for it. It is a safety net, not a guarantee: it cannot catch a secret that looks like an ordinary sentence, which is why the instruction above comes first.
+**It is redacted before it leaves your machine.** Emails, credentials in URLs, `Authorization` headers and API-key assignments, recognizable vendor tokens (`sk-…`, `ghp_…`, `AKIA…`, `xoxb-…`, JWTs), and home-directory paths are stripped and replaced with `[redacted]`. This runs client-side, in [`feedback.ts`](https://github.com/reticlehq/reticle/blob/main/packages/server/src/telemetry/feedback.ts), so you can read exactly what it removes rather than take our word for it. It is a safety net, not a guarantee: it cannot catch a secret that looks like an ordinary sentence, which is why the instruction above comes first.
 
 **It shows you what it sends.** `reticle feedback` prints the exact payload before transmitting, and names any redaction rule that fired.
 

package/docs/tools-navigate.mdx

@@ -17,13 +17,14 @@ Real response, with the throttled-tab `session` and `warning` fields trimmed off
   "ok": true,
   "url": "http://localhost:4310/deployments",
   "confirmed": false,
-  "note": "ok means the navigation was DISPATCHED, not that the page arrived. The SDK is torn down by the navigation itself, so nothing here can see the new document. Call reticle_sessions to confirm a session reconnected at the new URL before acting; if none appears, the page did not load or is not instrumented."
+  "waitedMs": 5000,
+  "note": "ok means the navigation was DISPATCHED, not that the page arrived. The SDK is torn down by the navigation itself, so nothing here can see the new document, and no session reconnected at the new URL within 5000ms. A slow app may still be on its way (an SPA reattaching under HMR can take 30-60s): navigate again with a larger timeout_ms, or call reticle_sessions to confirm a session reconnected before acting; if none appears, the page did not load or is not instrumented."
 }
 ```
 
 ## `confirmed: true` when the page comes back in time
 
-The daemon waits briefly for the SDK to re-announce itself. When it does, you are told so and can act immediately without a `reticle_sessions` round trip. This is a real reload response:
+The daemon waits up to `timeout_ms` (default 5000) for the SDK to re-announce itself. When it does, you are told so and can act immediately without a `reticle_sessions` round trip. This is a real reload response:
 
 ```json
 {
@@ -41,6 +42,12 @@ A full navigation destroys the document the SDK was living in. Reticle cannot re
 
 Most tools would return `ok: true` and let you assume arrival. When the page then fails to load, or loads without instrumentation, you get a confusing cascade of "element not found" errors several calls later, with nothing pointing at the real cause.
 
+`waitedMs` says which of two things you are looking at. Reticle stopped waiting at the budget it had, or the page never came back. The first is fixed by asking for more: a single-page app reattaching under HMR has been measured at 30–60s, which no default should wait for on every call, but which the caller who knows the app can grant.
+
+```json
+{ "url": "/deployments", "timeout_ms": 45000 }
+```
+
 ## The pattern after navigating
 
 ```json
@@ -64,11 +71,12 @@ with [`reticle_sessions`](/tools-sessions), and only then snapshot. If no sessio
 
 ## Arguments
 
-| Argument | What it does                          |
-| -------- | ------------------------------------- |
-| `url`    | Where to go. Relative paths work      |
+| Argument | What it does |
+| --- | --- |
+| `url` | Where to go. Relative paths work |
 | `reload` | Reload in place instead of navigating |
-| `hard`   | With `reload`, bypass the cache       |
+| `hard` | With `reload`, bypass the cache |
+| `timeout_ms` | How long to wait for the page to come back before `confirmed: false`. Default 5000; 0 looks once |
 
 ## Client-side routing is different
 

package/docs/usage.md

@@ -310,9 +310,9 @@ reticle_session {action:"review"}({ sessionId })
 
 Each pending mark carries the human note, the element label, the source **`file:line`** (when the framework stamped one), and a ready-to-act `fix` hint. Open the file, apply the fix, then `reticle_session {action:"review"}({ resolve: "m1" })`. The human watching the panel sees **"✓ fixed: …"** land. Reading never consumes a mark, so you can list → fix → verify → resolve. `reticle_sessions` also reports `pendingMarks` so you notice flagged bugs during normal orientation.
 
-### `reticle_network_mock`: stub the network for error-state testing (driven mode)
+### `reticle_network_mock`: stub the network for error-state testing
 
-On a page Reticle drives (`reticle drive`), make a request return a 500, force it offline, or delay it, so testing error/edge states is one declared rule, no backend changes:
+On a page Reticle drives (`reticle drive`) or a leased Playwright tab (`reticle_lease acquire`), make a request return a 500, force it offline, or delay it, so testing error/edge states is one declared rule, no backend changes:
 
 ```
 reticle_network_mock({ mocks: [{ urlContains: "/api/pay", method: "POST", status: 500 }] })
@@ -321,7 +321,7 @@ reticle_network_mock({ mocks: [{ urlContains: "/api/feed", abort: true }] })   /
 reticle_network_mock({ clear: true }) // turn mocking off
 ```
 
-First matching rule wins (`urlContains` + optional case-insensitive `method`). Needs a driven browser; without one it returns a `recommendation` pointing at `reticle drive`.
+First matching rule wins (`urlContains` + optional case-insensitive `method`). Needs a driven or leased browser; without one it returns a `recommendation` pointing at `reticle drive`.
 
 ### `reticle_viewport`: reproducible visual baselines (driven mode)
 
@@ -597,7 +597,7 @@ export default [
 ];
 ```
 
-`mutators` lists the callee names that change state; `signalCallee` (default `['reticleSignal', 'signal']`) is the name that counts as firing a signal. See [`packages/eslint-plugin/README.md`](../packages/eslint-plugin/README.md) for scoping and matching details.
+`mutators` lists the callee names that change state; `signalCallee` (default `['reticleSignal', 'signal']`) is the name that counts as firing a signal. See [`packages/eslint-plugin/README.md`](https://github.com/reticlehq/reticle/blob/main/packages/eslint-plugin/README.md) for scoping and matching details.
 
 ---
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@reticlehq/server",
-  "version": "2.13.1",
+  "version": "2.14.0",
   "description": "Reticle bridge + MCP server. Hosts the browser WS endpoint and exposes MCP tools to the coding agent.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "reticle": "./dist/cli.js"
+    "reticle": "./bin/reticle.js"
   },
   "exports": {
     ".": {
@@ -22,7 +22,8 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "ws": "^8.21.3",
     "zod": "^3.24.1",
-    "@reticlehq/core": "2.13.1"
+    "@reticlehq/core": "2.14.0",
+    "@reticlehq/init": "2.14.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",
@@ -44,6 +45,7 @@
   "homepage": "https://github.com/reticlehq/reticle#readme",
   "bugs": "https://github.com/reticlehq/reticle/issues",
   "files": [
+    "bin",
     "dist",
     "README.md",
     "LICENSE-ENTERPRISE",
@@ -71,7 +73,8 @@
     "dev": "tsc -b --watch",
     "typecheck": "tsc -b",
     "lint": "eslint src",
-    "test:unit": "vitest run src --passWithNoTests",
+    "test:unit": "node ../../scripts/guard-tests.mjs unit",
+    "test:guards": "node ../../scripts/guard-tests.mjs guards",
     "test:coverage": "vitest run src --passWithNoTests --coverage.enabled --coverage.provider=v8 --coverage.reporter=text-summary --coverage.include='src/**/*.ts' --coverage.exclude='src/**/*.test.ts'"
   }
 }

package/dist/init/agent-rules.d.ts

@@ -1,116 +0,0 @@
-/**
- * `reticle init` writes a behavioral rule into the coding agent's instruction file so the agent
- * VERIFIES a feature with Reticle after building it — not only when the user remembers to say "test
- * it with reticle". Registering the MCP server (mcp.ts / mcp-clients.ts) only makes the tools AVAILABLE;
- * this is the piece that makes the agent reach for them, every session, unprompted.
- *
- * It carries a SECOND standing instruction, and that one is not about this project at all: send
- * feedback to the Reticle maintainers, from the moment instrumentation starts. The agent is the party
- * that experiences Reticle, and the only one who can say what it cost — and by the time anyone would
- * think to ask, the context that knew is gone. Written into the same block, because the moment the
- * rule lands (init, before any framework wiring) is the moment the setup itself is being lived
- * through, which is when the reports we hear least about are actually generated.
- *
- * The rule is framed as a definition-of-done (WHEN to verify, HOW, and the anti-reward-hacking guard),
- * written into whichever instruction file the detected agent reads: `CLAUDE.md` (Claude Code),
- * `.cursor/rules/reticle.mdc` (Cursor, `alwaysApply` so it stays in context), or `AGENTS.md` as the
- * cross-agent fallback. Idempotent via a marker block — safe to append to an existing file and a
- * re-run is a no-op. Mirrors the apply/already result shape used across init (see mcp-clients.ts).
- */
-/** Project-root instruction files the agent re-reads every session. */
-export declare const CLAUDE_MD_PATH = "CLAUDE.md";
-export declare const AGENTS_MD_PATH = "AGENTS.md";
-/**
- * The full rules, written once and pointed at from every always-loaded file.
- *
- * Two problems it solves at the same time. The rule text is dense and most of it is REFERENCE (what
- * to do when the tools are missing, what a `version_skew` field means, how to file feedback), which
- * an agent needs on the turn it hits that situation and never before — so carrying all of it in
- * `CLAUDE.md` taxed every session for text almost every session did not read. And `AGENTS.md` was
- * only written when NO agent was detected, so a repo set up on a Claude Code machine told Codex,
- * Copilot, Amp and every other agent nothing at all.
- *
- * So: the operative rules (when to verify, WHEN NOT TO, how, and the honesty guards) go in the files
- * that load every turn, and this file holds the rest, one hop away and named in that block.
- */
-export declare const RETICLE_MD_PATH = "RETICLE.md";
-/** Cursor project rule; the frontmatter `alwaysApply` keeps it in context on every turn. */
-export declare const CURSOR_RULE_PATH = ".cursor/rules/reticle.mdc";
-/**
- * Does this file already carry the managed block?
- *
- * Exported so callers cannot invent their own looser test. The begin marker carries explanatory
- * text inside the comment, so a substring check for `reticle:begin` matches files that
- * `mergeMarkedInstruction` would treat as having NO block — and the two disagreeing means a refresh
- * silently appends a second copy instead of updating the first.
- */
-export declare function hasManagedBlock(text: string): boolean;
-/**
- * How the agent must INVOKE the CLI.
- *
- * `reticle init` installs the SDK packages, never the server — so there is no `reticle` on the
- * agent's PATH, and every bare `reticle <cmd>` this rule named was an instruction that could not be
- * followed. Reported from a field sweep: three of them, in the file the agent re-reads every session.
- *
- * `npx @reticlehq/server` is the same invocation the MCP registration uses, and it is derived from
- * the package's own name so the two can never drift apart.
- */
-export declare const CLI: string;
-/**
- * Who starts the dev server, stated once and rendered everywhere it is needed.
- *
- * The old rule was "Reticle never starts the dev server for you — that's your job", and agents obeyed
- * it exactly: they read it, declined to start anything, and ended the turn with nothing verified. An
- * instruction that reliably produces no verification is a defect in the instruction.
- *
- * The AGENT starts it, not the daemon. A daemon that spawns a build process is invisible to the
- * person whose machine it is running on, was never consented to, and orphans when the daemon exits.
- * The agent already has shell access in this repo, already runs install and build commands, and runs
- * inside a host that asks the human for permission — so a dev server it starts is visible in the
- * transcript, attributable, and stoppable.
- *
- * The guards are the whole reason this is safe, so no renderer may drop them: one server at a time,
- * read the command rather than invent one, never kill anything you did not start, and leave the
- * permission prompt to the host. "Background it and say so" is no longer among them because the
- * branch above now states it at the point of action, and this text is read every turn — a rule
- * stated twice costs every agent tokens forever and is the first thing to drift.
- *
- * The RESTART branch outranks the rest and is stated first. It used to be an aside, while "if a dev
- * server is already listening, use it" was a numbered guard — so an agent resolving the two
- * reasonably reused a server started before `init` edited the build config, served a bundle with no
- * SDK in it, and landed on an empty session list with every other step done correctly.
- *
- * Exported because slash-command.ts renders the same rule; there must not be two versions of it.
- */
-export declare const DEV_SERVER_POLICY = "**A dev server already running when `reticle init` ran does not have Reticle in its bundle.** It read the build config at boot; `init` edited it afterwards. It serves the old bundle and no session appears. In order:\n\n1. **A dev server was already running?** Restart it, then hard-reload the tab. \"Something is listening\" does not mean the right bundle is served.\n2. **Nothing was running?** Start it in the BACKGROUND and say so in one line. `reticle_sessions` gives you this project's own dev command in `next_action`; use that, never compose one. Started after `init`, it needs no restart.\n\nStopping to ask is how a verification turn ends with nothing verified.\n\nFour guards, none optional:\n\n1. **Never run two at once.** One dev server on the app's port. Restarting a stale one means stopping it first, not starting a second alongside it.\n2. **Never guess the command.** It comes from `package.json` scripts. No recognisable dev script means say so and stop, not invent one.\n3. **Never kill anything you did not start**, and never a daemon or a port holder. The one exception is the restart above, and say in one line that you did it.\n4. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer.";
-/**
- * The operative rules, carried by every file that loads on every turn.
- *
- * Short on purpose. This is the text that has to CHANGE BEHAVIOUR, so it states when to verify, when
- * NOT to, how, and the guards against calling something proven when it is not. Everything an agent
- * needs only at the moment it hits a specific situation lives in RETICLE.md, named at the end.
- */
-export declare const RULE_BODY: string;
-/** The full-rules file, written verbatim (no markers: `init` owns this file entirely). */
-export declare function reticleMdFile(): string;
-export declare const AgentRuleStatus: {
-    readonly APPLY: "apply";
-    readonly ALREADY: "already";
-};
-export type AgentRuleStatus = (typeof AgentRuleStatus)[keyof typeof AgentRuleStatus];
-interface AgentRuleResult {
-    status: AgentRuleStatus;
-    /** Full file content to write when status is APPLY; the unchanged input otherwise. */
-    content: string;
-}
-/** The marker-wrapped block appended to a CLAUDE.md / AGENTS.md instruction file. */
-export declare function markedBlock(): string;
-/**
- * Merge the managed block into a marker-delimited instruction file. Already present ⇒ no change
- * (idempotent re-run). Absent/empty ⇒ the block alone. Otherwise append the block, preserving the
- * existing content and a clean separating blank line.
- */
-export declare function mergeMarkedInstruction(existing: string | null | undefined): AgentRuleResult;
-/** The Cursor rule file (.mdc): `alwaysApply` keeps the rule in every turn's context. */
-export declare function cursorRuleFile(): string;
-export {};