@reticlehq/server 2.9.0 → 2.11.0

package/SKILL.md

@@ -1,6 +1,6 @@
 # Reticle
 
-Reticle embeds a dev-only SDK in the user's running app and exposes it to you as `reticle_*` MCP tools. You look, act, observe, and assert against the real app. No screenshots, and no browser download for the verify loop — it drives the tab the user already has open.
+Reticle embeds a dev-only SDK in the user's running app and exposes it to you as `reticle_*` MCP tools. You look, act, observe, and assert against the real app. No screenshots, and no browser download for the verify loop: it drives the tab the user already has open.
 
 This file is the whole critical path and nothing else. Everything it leaves out is at `https://docs.reticle.sh`, one page at a time.
 
@@ -14,6 +14,18 @@ This file is the whole critical path and nothing else. Everything it leaves out
 
 **Do not tell the user Reticle is set up until step 5 has produced a verdict.** The most common failure in the field is an agent that finishes step 1, reports success, and leaves a user with config files and no instrumented page.
 
+## Setup runs to the end without you
+
+**Do not stop, and do not ask the user anything, until their app is running with Reticle inside it and a session is connected.** Everything between here and that point is yours to do: run `init`, fix the wiring it could not, start the dev server, open the browser. Not one of those needs a human, and every one of them has been the place an onboarding turn died with nothing to show.
+
+Questions you must not ask, because the repo you are sitting in already answers them: which framework, which package manager, which port, which editor or MCP client, whether to start the dev server, whether to open the browser, whether to carry on. Decide, act, and say what you did in one line.
+
+There are exactly three places you may stop, and none is a question about a preference:
+
+1. **No recognisable dev script in `package.json`.** Say so; do not invent one.
+2. **Your host asks the human to approve a command.** That prompt belongs to the host. Never bypass or suppress it, and take a refusal as the answer.
+3. **On a first install only, the client restart that loads the MCP tools** (step 2). Even then, keep going until the app is running and connected, and stop for the restart last, with only the drive left.
+
 Setup requires a client restart, which ends your turn. This file was fetched into the context that just ended, so nothing carries it across unless you make it. **Before you trigger the restart, write the remaining steps into `RETICLE-SETUP.md` at the repo root**, one line each, with the step you stopped at marked. That file is what you re-read afterwards. Delete it once step 5 has produced a verdict.
 
 Better still, install the on-disk copy first. It survives the restart on its own, and it is the same content:
@@ -80,25 +92,29 @@ RETICLE_INSTALL_SOURCE=skill_file npx @reticlehq/server@latest init
 
 It detects the framework, package manager and UI library, registers the MCP server with the agents on the machine, installs the SDK, writes `.reticle.json` and the `/reticle` command, wires the build config, and scaffolds a capabilities file from the `data-testid` values it found.
 
-**Ask nothing:** not the framework, package manager, port, editor, or MCP client. Every one is answerable from the repo you are sitting in. In a monorepo run it at the root anyway; it finds the app under `apps/*` or `packages/*`.
+**Ask nothing:** not the framework, package manager, port, editor, or MCP client. Every one is answerable from the repo you are sitting in. In a monorepo run it at the root anyway. With one app under `apps/*` or `packages/*` it wires that app silently. With several it wires nothing, lists them, and names the flag: re-run with `--app <dir>` for the one the user is working in, the one their request named, or the one whose `package.json` has the dev script. **Pick it yourself and re-run.** Asking which app they meant is the most likely place this whole install stops, and the answer is almost always in the request you were already given.
 
 **Never ask about the port.** There are two, and conflating them is a top setup failure. The dev-server port (3000, 5173) belongs to the project's own dev script and the daemon never binds it. The bridge port (**4400**) is the daemon-to-SDK channel and defaults correctly.
 
-Read the report: `✓` applied, `·` already wired, `–` skipped, `ℹ` done but incomplete in a way that matters, `⚠` needs your edit. **`⚠` and `ℹ` both need you.** `ℹ` is the one people skim past: the step ran, and something about the result still stops a session appearing. Each line carries the exact snippet. A non-zero exit is a to-do list, not a failed install. Fix every `⚠` before moving on — per-framework wiring is at `https://docs.reticle.sh/install-manual.md`.
+Read the report: `✓` applied, `·` already wired, `–` skipped, `ℹ` done but incomplete in a way that matters, `⚠` needs your edit. **`⚠` and `ℹ` both need you.** `ℹ` is the one people skim past: the step ran, and something about the result still stops a session appearing. Each line carries the exact snippet. A non-zero exit is a to-do list, not a failed install. Fix every `⚠` before moving on. Per-framework wiring is at `https://docs.reticle.sh/install-manual.md`.
 
-## 2. Register the MCP server, then restart the client.
+**If the user gave you a license key**, along with the install request or at any later point, see [License key](#license-key) below and do it before moving on.
 
-Call `reticle_sessions`. If the tool exists, skip to step 3.
+## 2. Check for the tools. Do not stop for them.
 
-If it does not: your client read its server list at startup and has not re-read it. No retry loads it. `init` registers globally once per machine, so this bites on the first install only.
+Call `reticle_sessions`. If the tool exists, go to step 3 and never mention a restart.
 
-Say this once and then stop:
+If it does not: your client read its server list at startup and has not re-read it. No retry, config edit or slash command loads it into the process you are already in. `init` registers globally once per machine, so this bites on the first install only.
 
-> "Reticle is installed. Restart your client so it picks up the new MCP server, then say **'continue Reticle setup'**. Three steps are left, and your app is not instrumented until they are done."
+**This is not a reason to stop.** Steps 3 and 4 need no MCP tools at all: they are a build config, a dev server and a browser tab, and every one of them is yours to do from the shell. An install that halts here leaves the user with config files, an uninstrumented page, and a question to answer; that is the single most common failure in the field, and it is this paragraph's fault when it happens.
+
+So carry straight on through steps 3 and 4. Ask for the restart **once, at the end**, when a session is connected and the only thing left is the drive:
+
+> "Reticle is installed and your app is connected. Restart your client so it picks up the MCP server, then say **'continue Reticle setup'**. One step is left: driving a flow."
 
 Claude Code: restart (`/mcp` does not re-read the config). VS Code: press Start in `.vscode/mcp.json`. Cursor, Windsurf, Zed: reload the window.
 
-**Do not report setup as finished here.** When the tools return, resume at step 3.
+**Do not report setup as finished at that point either.** When the tools return, resume at step 5.
 
 ## 3. Wire the SDK into the app, and start the dev server.
 
@@ -109,7 +125,7 @@ This is the step the funnel dies on. The daemon runs, the MCP server registers,
 - **Vite + React**: `reticle()` is in the `plugins` array of `vite.config.*`.
 - **Next.js**: `withReticle` wraps the export in `next.config.*`, `reticle-dev.tsx` exists, and it is mounted in the root layout or `_app`.
 - **Remix**, **Astro**: wired by `init`, each with an app in this repo that a gate drives.
-- **Anything else**: nothing is wired. Do it by hand — fetch `https://docs.reticle.sh/frameworks.md`.
+- **Anything else**: nothing is wired. Do it by hand: fetch `https://docs.reticle.sh/frameworks.md`.
 
 Those four are the frameworks with an app and a CI gate behind them. The SDK is framework-agnostic and usually connects elsewhere, but say so honestly rather than reporting a proven install.
 
@@ -120,7 +136,7 @@ Two rules that cause silent failures if broken:
 
 Then make sure something is serving the app.
 
-**If a dev server is already listening, use it. If none is, start one yourself** — read the project's own dev script out of `package.json` (`dev`, `start`, whatever this project calls it), run it in the BACKGROUND, and tell the user in one line that it is running and how to stop it. Stopping here to ask is how a setup turn ends with nothing verified.
+**If a dev server is already listening, use it. If none is, start one yourself**: read the project's own dev script out of `package.json` (`dev`, `start`, whatever this project calls it), run it in the BACKGROUND, and tell the user in one line that it is running and how to stop it. Stopping here to ask is how a setup turn ends with nothing verified.
 
 The daemon deliberately will not do this for you. A build process started by a long-lived background daemon is invisible to the person whose machine it runs on and orphans when the daemon exits; a dev server YOU start is in the transcript, attributable, and stoppable.
 
@@ -128,11 +144,21 @@ Five guards, none optional:
 
 1. **Never start a second one.** If something is already listening on the app's port, use it.
 2. **Never guess the command.** It comes from `package.json` scripts. No recognisable dev script means say so and stop, not invent one.
-3. **Never kill anything.** Not a dev server, not a daemon, not a port holder — including one you started.
+3. **Never kill anything.** Not a dev server, not a daemon, not a port holder, including one you started.
 4. **Background it, and say so.** A dev server the human does not know about is the same failure one step later.
 5. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer.
 
-Then ask the user to open the app in their browser.
+Then open the app yourself. Do not ask the user to do it. A setup turn that ends on "now open your browser" ends with nothing verified:
+
+```bash
+npx @reticlehq/server open <the url the dev server is serving>
+```
+
+That reuses an already-connected tab or opens a new one, and waits for the page to register. On a headless machine with no browser to open, take a tab Reticle owns instead, once the tools are reachable:
+
+```
+reticle_run({ tool: "reticle_lease", args: { action: "acquire", url: "<the same url>" } })
+```
 
 ## 4. Prove a page is connected. This is a gate.
 
@@ -142,7 +168,7 @@ reticle_sessions()
 
 You need a session whose URL matches the app's localhost address. **Nothing below this line is meaningful until you have one, and you may not report setup complete without one.**
 
-**Empty list?** Read `next_action` first, then `why`. `next_action` is the machine-readable half: it names which of the four cases this is and, when there is one, the literal command to run and the port — sourced from this project's own scripts, never guessed. `why` is the same thing in prose for the human. The daemon can see whether a session was ever here and whether a dev server is listening. Then, in order: is the SDK imported and called in the app entry, is the dev server actually serving that entry, is the connect guarded on `hostname === 'localhost'`, and is the bridge port the same number on both sides. **Nothing listening at all? That one is yours — start it, per step 3.** If something IS listening, do not tell the user to start what they are already running; the fault is the SDK not loading in the page. Full checklist: `https://docs.reticle.sh/troubleshooting.md`.
+**Empty list?** Read `next_action` first, then `why`. `next_action` is the machine-readable half: it names which of the four cases this is and, when there is one, the literal command to run and the port, sourced from this project's own scripts, never guessed. `why` is the same thing in prose for the human. The daemon can see whether a session was ever here and whether a dev server is listening. Then, in order: is the SDK imported and called in the app entry, is the dev server actually serving that entry, is the connect guarded on `hostname === 'localhost'`, and is the bridge port the same number on both sides. **Nothing listening at all? That one is yours: start it, per step 3.** If something IS listening, do not tell the user to start what they are already running; the fault is the SDK not loading in the page. Full checklist: `https://docs.reticle.sh/troubleshooting.md`.
 
 ## 5. Drive one real flow and produce a verdict.
 
@@ -152,14 +178,14 @@ A connected session is not a result. The user has installed something and seen n
 
 Tell the user to keep the tab visible. The HUD is on by default (glow border, animated cursor, narration per step) and watching you drive their own app is the demo.
 
-Drive it in as few calls as you can. Every call is a full model turn, and in a client that asks the user to approve each one it is also a click — a flow driven one call at a time is how a person gives up before they ever see a verdict.
+Drive it in as few calls as you can. Every call is a full model turn, and in a client that asks the user to approve each one it is also a click. A flow driven one call at a time is how a person gives up before they ever see a verdict.
 
 1. `reticle_snapshot({ mode: "interactive" })` **once**, for the whole flow. Not once per step.
-2. `reticle_act_sequence` for the setup — every fill and every intermediate click in ONE call.
+2. `reticle_act_sequence` for the setup: every fill and every intermediate click in ONE call.
 3. `reticle_act_and_wait({ ref, action, until })` for the final step only. This is the call that produces the verdict, and `until` names the expected consequence before the action fires.
 4. `reticle_state()` once at the end.
 
-Four calls for a login, not fourteen. If `reticle_state` comes back empty or `hasCapabilities` is false, the generated capabilities file registered no store. Say so in one line and offer to finish it. Never report a clean install over an empty state read.
+Four calls for a login, not fourteen. If `reticle_state` comes back empty or `hasCapabilities` is false, the capabilities file `init` generated registered nothing, which is what its `ℹ AGENT: finish the capabilities file` line was telling you. **Finish it yourself, before you drive**: open `src/reticle-dev.*`, register the app's store if it has one, and list the `testids` the flow you picked actually touches. Do not offer, and do not ask; it is a few lines in a file `init` already wrote for you. Never report a clean install over an empty state read.
 
 **Then save what you just drove.** Two calls, and they are what make every future check a single call instead of a repeat of this one. Wrap the drive above in a recording:
 
@@ -170,7 +196,7 @@ reticle_run({ tool: "reticle_record", args: { action: "stop",  recordingName: "<
 reticle_run({ tool: "reticle_flow_save", args: { flowName: "<flow>" } })
 ```
 
-`reticle_flow_save` returns `assertions.grade`. If it is not `asserted`, the flow only clicks — it will pass even when the feature is broken. Say that in one line rather than presenting it as a regression check.
+`reticle_flow_save` returns `assertions.grade`. If it is not `asserted`, the flow only clicks: it will pass even when the feature is broken. Say that in one line rather than presenting it as a regression check.
 
 Tell the user plainly: that flow is now saved to `.reticle/flows/`, and re-verifying it after any future change is one call with no model in the loop.
 
@@ -178,7 +204,7 @@ Tell the user plainly: that flow is now saved to `.reticle/flows/`, and re-verif
 
 `init` writes a managed block into the project's `CLAUDE.md` and `AGENTS.md` (and `.cursor/rules/reticle.mdc` where it applies), plus a `RETICLE.md` reference file and the `/reticle` command. That block is what makes the next agent verify its own work instead of guessing.
 
-Confirm the block is present, between `<!-- reticle:begin ... -->` and `<!-- reticle:end -->`. **Do not hand-write your own copy** — the markers are how a re-run stays idempotent, and a second unmarked copy will never be updated again. If it is missing, re-run `init`.
+Confirm the block is present, between `<!-- reticle:begin ... -->` and `<!-- reticle:end -->`. **Do not hand-write your own copy.** The markers are how a re-run stays idempotent, and a second unmarked copy will never be updated again. If it is missing, re-run `init`.
 
 **Only after step 5 has produced a verdict**, report what you drove and what it produced, then:
 
@@ -190,11 +216,23 @@ Stop here. Do not continue into VERIFY.
 
 ---
 
+# License key
+
+Enterprise features are unlocked by a signed key, verified locally with Ed25519 and **no network call**. If the user hands you one, during setup or at any later point:
+
+1. Append `RETICLE_LICENSE_KEY=<key>` to the project's `.env`, creating the file if it is not there. The CLI folds a project-local `.env` into the environment on every invocation, so nothing else has to change.
+2. Make sure `.env` is in `.gitignore`. A license key in git is a leaked credential, so check before you write and add the line if it is missing.
+3. Confirm with `npx @reticlehq/server license`, which prints `active`, `eval`, `missing` or `expired`.
+
+Never echo the key back in your reply, and never put it in a commit, a code comment, or a feedback report. The rest: `curl https://docs.reticle.sh/enterprise.md`.
+
+---
+
 # VERIFY
 
 **Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** Everything else (`act`, `snapshot`, `query`, `navigate`, `observe`, `network`, `console`) moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used.
 
-A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown. **Never weaken a check to make it pass.**
+A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown. `verified: "no-fault"` is not a pass either. It means the page settled and no channel reported a problem, but nothing was declared to prove, so assert a consequence the action CHANGES. **Never weaken a check to make it pass.**
 
 ## Take the cheapest path that answers the question
 
@@ -202,14 +240,14 @@ Work down this list and stop at the first row that fits. Do not hand-drive a flo
 
 | The question | The call | Calls |
 | --- | --- | --- |
-| "Did my edit break anything?" | `reticle_run({ tool: "reticle_verify_change", args: { files: ["src/App.tsx"] } })` | 1 |
+| "Did my edit break anything?" | `reticle_run({ tool: "reticle_verify", args: { action: "change", files: ["src/App.tsx"] } })` | 1 |
 | "Does this known journey still work?" | `reticle_run({ tool: "reticle_flow_replay", args: { flowName: "login" } })` | 1 |
 | "Does this new behaviour work?" | `reticle_act_sequence` for the setup, then ONE `reticle_act_and_wait` | 2 |
 | No MCP available at all | `npx @reticlehq/server verify <url>` in the shell | 1, no MCP |
 
-`reticle_verify_change` and `reticle_flow_replay` are **not on the advertised tool list** — they are reached through `reticle_run` exactly as written above. That is the supported call shape, not a workaround, and it is why you have to be told they exist at all.
+`reticle_verify` and `reticle_flow_replay` are **not on the advertised tool list**: they are reached through `reticle_run` exactly as written above. That is the supported call shape, not a workaround, and it is why you have to be told they exist at all.
 
-`reticle_verify_change` answers `unknown` when no saved flow covers the files you changed. That is the honest answer and not a failure — nothing ran, so nothing was proved. It is also the signal to record one. Never read it as a pass.
+`reticle_verify {action:"change"}` answers `unknown` when no saved flow covers the files you changed. That is the honest answer and not a failure. Nothing ran, so nothing was proved. It is also the signal to record one. Never read it as a pass.
 
 ## Record once, replay cheaply
 
@@ -222,7 +260,7 @@ reticle_run({ tool: "reticle_record", args: { action: "stop",  recordingName: "c
 reticle_run({ tool: "reticle_flow_save", args: { flowName: "checkout" } })
 ```
 
-From then on that journey re-verifies in one call, deterministically, and `reticle_verify_change` can start answering `yes` or `no` for the files it touches instead of `unknown`.
+From then on that journey re-verifies in one call, deterministically, and `reticle_verify {action:"change"}` can start answering `yes` or `no` for the files it touches instead of `unknown`.
 
 Check `assertions.grade` on the save. Anything other than `asserted` means the flow only acts, so it will pass even if the feature breaks.
 
@@ -243,11 +281,11 @@ reticle_act_and_wait({ sessionId, ref, action: "click", until: { kind: "allOf",
 
 Prefer `reticle_act_and_wait({ ref, action, until })`. It names the expected consequence **before** the action, which is the difference between a check and a rationalisation.
 
-A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown. **Never weaken a check to make it pass.**
+A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown. `verified: "no-fault"` is not a pass either. It means the page settled and no channel reported a problem, but nothing was declared to prove, so assert a consequence the action CHANGES. **Never weaken a check to make it pass.**
 
 Then report what you drove, what it produced, and the `file:line` for anything broken.
 
-The surface is deliberately small: `default` 18, `all` 30. Editors budget tools across every MCP server you have connected (Cursor allows 40 in total), so the count is capped rather than allowed to grow. `reticle_tools` loads the argument grammar for the rest on demand, and `reticle_run` invokes any of them by name — nothing is unreachable, the cold tail just costs one discovery hop.
+The surface is deliberately small: `default` 18, `all` 28. Editors budget tools across every MCP server you have connected (Cursor allows 40 in total), so the count is capped rather than allowed to grow. `reticle_tools` loads the argument grammar for the rest on demand, and `reticle_run` invokes any of them by name. Nothing is unreachable; the cold tail just costs one discovery hop.
 
 - Batching, regression suites, reading a verdict: `https://docs.reticle.sh/agent-cheatsheet.md`
 - Every predicate and action: `https://docs.reticle.sh/predicates.md`, `https://docs.reticle.sh/actions.md`

package/dist/capsule/capsule-store.d.ts

@@ -31,19 +31,19 @@ export declare const CapsuleSchema: z.ZodObject<{
     /** Minimal steps to reproduce (prefix-trimmed). */
     steps: z.ZodArray<z.ZodType<FlowStep, z.ZodTypeDef, FlowStep>, "many">;
 }, "strip", z.ZodTypeAny, {
+    expected: string;
     origin: string;
     version: 1;
     id: string;
-    expected: string;
     observed: string;
     steps: FlowStep[];
     createdAt: number;
     flow?: string | undefined;
 }, {
+    expected: string;
     origin: string;
     version: 1;
     id: string;
-    expected: string;
     observed: string;
     steps: FlowStep[];
     createdAt: number;

package/dist/cli/cli-parse.d.ts

@@ -13,7 +13,7 @@ export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '.
  * telling readers to do exactly that on 110 lines before it was caught, so the invocation now leads
  * the usage block rather than being a footnote somewhere else.
  */
-export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)\n                --app picks WHICH app in a monorepo, when several are found\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N]\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle Cloud; runs/flows recorded on the dashboard):\n  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push                                          (send local run artifacts to the dashboard)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
+export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)\n                --app picks WHICH app in a monorepo, when several are found\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N]\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle Cloud; runs/flows recorded on the dashboard):\n  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push                                          (send local run artifacts to the dashboard)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export declare const TelemetryAction: {
     readonly STATUS: "status";

package/dist/cli/cli-parse.js

@@ -40,7 +40,7 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
   reticle license                                      (show enterprise license status: active | eval | missing)
   reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)
   reticle feedback [--rating 1-5] [--bug] "message"    (tell us what worked and what didn't; prints exactly what it sends)
-  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "message"
+  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> "message"
                                                        (agents: file from anywhere, including a setup that never finished)
   reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]
                                                        (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)

package/dist/cli/cli-verify.js

@@ -226,7 +226,7 @@ export function portBusyMessage(port) {
     return (`reticle verify needs port ${String(port)} — the port your app dials — and a Reticle daemon is ` +
         'already listening on it. It did not start a second one.\n\n' +
         '  • If you have the Reticle tools, ask the daemon that is already running instead: ' +
-        'reticle_run { tool: "reticle_verify_change", args: { files: ["..."] } }\n' +
+        'reticle_run { tool: "reticle_verify", args: { action: "change", files: ["..."] } }\n' +
         `  • Or stop it and re-run: npx @reticlehq/server stop --port ${String(port)}\n` +
         `  • Or run both on another port, if your app is configured for it: RETICLE_PORT=<port> ` +
         'npx @reticlehq/server verify <url>');

package/dist/crawl/crawl.d.ts

@@ -1,4 +1,4 @@
-import { CrawlAnomalyKind, ContradictionKind, type CommandResult, type ReticleEvent } from '@reticlehq/core';
+import { type CommandResult, type ReticleEvent } from '@reticlehq/core';
 /** The slice of Session the crawler needs — so tests inject a fake without a live browser. */
 export interface CrawlSession {
     command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
@@ -21,8 +21,13 @@ export interface CrawlAnomaly {
      * disagreeing about the same click). The second kind is why an autonomous crawl is worth more
      * than a human clicking the same buttons: a person sees only the screen, so a UI that advanced
      * while its write failed looks like success to them and always will.
+     *
+     * `CrawlAnomalyKind` and `ContradictionKind` are what THIS package puts here, and both are still
+     * enforced at the emit sites below. The type is a plain string because a rule registered by a
+     * consumer contributes kinds this package has never heard of, and a closed union here would mean
+     * a consumer's private vocabulary had to ship in the free product to be reportable.
      */
-    kind: CrawlAnomalyKind | ContradictionKind;
+    kind: string;
     /** The control that triggered it. */
     ref: string;
     desc: string;

package/dist/crawl/crawl.js

@@ -1,5 +1,5 @@
 import { span } from '../trace.js';
-import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, ContradictionKind, DANGEROUS_ACTION_CONFIRM_ARG, EventType, ReticleCommand, } from '@reticlehq/core';
+import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, DANGEROUS_ACTION_CONFIRM_ARG, EventType, ReticleCommand, } from '@reticlehq/core';
 import { crawlEmptyNote } from './crawl-empty.js';
 import { parseInteractive, asRecord, asNumber, asString, sourceOf, } from '../tools/tools-helpers.js';
 import { ReticleTool } from '../tools/tool-names.js';
@@ -86,6 +86,37 @@ async function countRevealed(session, opts, before) {
     const known = new Set(before.map((i) => (i.ref !== '' ? i.ref : i.desc)));
     return parseInteractive(tree).filter((i) => !known.has(i.ref !== '' ? i.ref : i.desc)).length;
 }
+/**
+ * The confirmation half of the dead-control rule. Kept separate so the rule above reads as one
+ * question, and so the second click gets its own window: reusing the first would let the first
+ * click's own (absent) activity decide the second, which is not a second sample at all.
+ *
+ * `true` means "silent both times" — the only state the anomaly is reported in. Anything that goes
+ * wrong here returns `false`: a confirmation that cannot run is not evidence, and the direction that
+ * costs a missed finding is better than the one that invents one.
+ */
+async function stillSilent(session, item, settleMs, opts, sleep) {
+    const since = session.elapsed();
+    session.beginAction?.(ReticleTool.CRAWL, { ref: item.ref, action: ActionType.CLICK });
+    try {
+        const again = await session.command(ReticleCommand.ACT, {
+            ref: item.ref,
+            action: ActionType.CLICK,
+            args: true === opts.confirmDangerous ? { [DANGEROUS_ACTION_CONFIRM_ARG]: true } : {},
+        });
+        await sleep(settleMs);
+        // A control that has GONE (the first click removed it) is not a dead control — it did something.
+        if (!again.ok || false === asRecord(again.result)['dispatched'])
+            return false;
+        return !session.eventsSince(since).some(isActivity);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        session.finishAction?.();
+    }
+}
 export async function crawl(session, opts, sleep) {
     const maxSteps = opts.maxSteps ?? CRAWL_DEFAULTS.MAX_STEPS;
     const settleMs = opts.settleMs ?? CRAWL_DEFAULTS.SETTLE_MS;
@@ -194,14 +225,26 @@ export async function crawl(session, opts, sleep) {
             0 === errs.length &&
             !events.some(isActivity) &&
             !legitimatelyInert(item.desc)) {
-            counts.deadControls += 1;
-            anomalies.push({
-                kind: CrawlAnomalyKind.DEAD_CONTROL,
-                ref: item.ref,
-                desc: item.desc,
-                detail: 'clicked but the app did nothing (no DOM/network/route/signal change)',
-                ...source,
-            });
+            // CONFIRM IT. One silent sample is a sample, not a fact, and this is the strongest claim the
+            // crawler makes — "your button does nothing" is the finding a reader acts on immediately.
+            //
+            // Measured on a fixture whose FIXED twin has a working primary CTA: the crawl reported it dead
+            // on 2 of 3 runs, always a control the drive had already clicked successfully moments earlier.
+            // A false positive in this tier is the most expensive kind there is — it is the tier a verdict
+            // is built from, and the twin column is the whole claim this product makes.
+            //
+            // A second click costs one round trip on the rare control that looked dead, and nothing at all
+            // on every control that did not. A genuinely dead control is silent twice; the flake is not.
+            if (await stillSilent(session, item, settleMs, opts, sleep)) {
+                counts.deadControls += 1;
+                anomalies.push({
+                    kind: CrawlAnomalyKind.DEAD_CONTROL,
+                    ref: item.ref,
+                    desc: item.desc,
+                    detail: 'clicked TWICE and the app did nothing either time (no DOM/network/route/signal change)',
+                    ...source,
+                });
+            }
         }
     }
     // One more look, AFTER the clicks. The enumeration above happened before any of them, so anything

package/dist/dev/stale-issue-guard.d.ts

@@ -0,0 +1,43 @@
+/**
+ * An issue we have already fixed must not still read as available work.
+ *
+ * Three contributor PRs died on arrival in one week for this. #373 was filed at 09:52 and fixed by
+ * us at 12:33 the same day, then left open for three more days — somebody started on it on day two.
+ * #398 shipped and stayed open; a second contributor rebuilt it from scratch. `GITHUB.md` already
+ * documents the same failure costing three contributors before either of those, which makes this the
+ * third recurrence of a defect we have written down and asked ourselves to remember.
+ *
+ * Remembering is not a mechanism, and this is the smallest one that works: a commit saying it closes
+ * an issue is a claim that the issue is done. If that issue is still open and unlabelled afterwards,
+ * the tracker is lying to whoever reads it next — and the person it lies to is by definition someone
+ * looking for something to work on.
+ *
+ * ## Why `fixed-pending-release` is an accepted answer
+ *
+ * Work fixed on an unreleased branch is legitimately still open; the issue closes when the version
+ * ships. The label is what tells a contributor not to start, so the label — not the closure — is
+ * what this guard is actually asking for. That is also why the fix is cheap: nobody has to change
+ * when they close things, only to say so.
+ *
+ * Pure. The git log and the GitHub lookup belong to the caller, which is what makes every branch
+ * below testable without a network or a repo.
+ */
+export interface IssueState {
+    number: number;
+    state: 'open' | 'closed';
+    labels: readonly string[];
+}
+/** The label that means "fixed, waiting for a release" — an honest reason to still be open. */
+export declare const PENDING_RELEASE_LABEL = "fixed-pending-release";
+export declare function closedRefsIn(commitMessage: string): number[];
+/**
+ * Of the issues these commits claimed to close, the ones still reading as available work.
+ *
+ * An issue that could not be looked up is deliberately silent rather than failing. A rate limit, a
+ * transferred issue or a deleted one would otherwise turn this red for a reason unrelated to what it
+ * guards, and a guard that goes red for unrelated reasons gets disabled — which costs more than the
+ * defect it was catching.
+ */
+export declare function staleIssues(claimed: readonly number[], issues: readonly IssueState[]): number[];
+/** The message the guard prints. Held here so the check and its tests cannot describe it differently. */
+export declare function staleIssueReport(stale: readonly number[]): string;

package/dist/dev/stale-issue-guard.js

@@ -0,0 +1,75 @@
+/**
+ * An issue we have already fixed must not still read as available work.
+ *
+ * Three contributor PRs died on arrival in one week for this. #373 was filed at 09:52 and fixed by
+ * us at 12:33 the same day, then left open for three more days — somebody started on it on day two.
+ * #398 shipped and stayed open; a second contributor rebuilt it from scratch. `GITHUB.md` already
+ * documents the same failure costing three contributors before either of those, which makes this the
+ * third recurrence of a defect we have written down and asked ourselves to remember.
+ *
+ * Remembering is not a mechanism, and this is the smallest one that works: a commit saying it closes
+ * an issue is a claim that the issue is done. If that issue is still open and unlabelled afterwards,
+ * the tracker is lying to whoever reads it next — and the person it lies to is by definition someone
+ * looking for something to work on.
+ *
+ * ## Why `fixed-pending-release` is an accepted answer
+ *
+ * Work fixed on an unreleased branch is legitimately still open; the issue closes when the version
+ * ships. The label is what tells a contributor not to start, so the label — not the closure — is
+ * what this guard is actually asking for. That is also why the fix is cheap: nobody has to change
+ * when they close things, only to say so.
+ *
+ * Pure. The git log and the GitHub lookup belong to the caller, which is what makes every branch
+ * below testable without a network or a repo.
+ */
+/** The label that means "fixed, waiting for a release" — an honest reason to still be open. */
+export const PENDING_RELEASE_LABEL = 'fixed-pending-release';
+/**
+ * Issue numbers a commit message CLAIMS to have closed.
+ *
+ * Only the closing verbs GitHub itself acts on. A bare `#447`, a `Refs #447` or a `see #447` is how
+ * a change points at context it did not close — the exact habit we want to encourage — so counting
+ * those would make the guard cry wolf on good behaviour, and a check that cries wolf is one people
+ * learn to skip.
+ */
+const CLOSING_REF = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)/gi;
+export function closedRefsIn(commitMessage) {
+    const seen = new Set();
+    for (const match of commitMessage.matchAll(CLOSING_REF)) {
+        const raw = match[1];
+        if (raw === undefined)
+            continue;
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed))
+            seen.add(parsed);
+    }
+    return [...seen];
+}
+/**
+ * Of the issues these commits claimed to close, the ones still reading as available work.
+ *
+ * An issue that could not be looked up is deliberately silent rather than failing. A rate limit, a
+ * transferred issue or a deleted one would otherwise turn this red for a reason unrelated to what it
+ * guards, and a guard that goes red for unrelated reasons gets disabled — which costs more than the
+ * defect it was catching.
+ */
+export function staleIssues(claimed, issues) {
+    const byNumber = new Map(issues.map((issue) => [issue.number, issue]));
+    return claimed.filter((number) => {
+        const issue = byNumber.get(number);
+        if (issue === undefined)
+            return false;
+        if ('closed' === issue.state)
+            return false;
+        return !issue.labels.includes(PENDING_RELEASE_LABEL);
+    });
+}
+/** The message the guard prints. Held here so the check and its tests cannot describe it differently. */
+export function staleIssueReport(stale) {
+    const list = stale.map((n) => `#${String(n)}`).join(', ');
+    return (`${list} ${1 === stale.length ? 'is' : 'are'} still OPEN, and a commit on this branch says it ` +
+        `closes ${1 === stale.length ? 'it' : 'them'}. Anyone browsing the tracker reads that as work ` +
+        `nobody has started. Close ${1 === stale.length ? 'it' : 'them'}, or label ` +
+        `${1 === stale.length ? 'it' : 'them'} \`${PENDING_RELEASE_LABEL}\` if the fix is waiting on a ` +
+        `release. This has cost three contributors an evening each; it is not bookkeeping.`);
+}

package/dist/domain/domain-tools.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { asNumber } from '../tools/tools-helpers.js';
+import { sessionRoot } from '../project/session-root.js';
+import { asNumber, asString } from '../tools/tools-helpers.js';
 import { ReticleTool } from '../tools/tool-names.js';
 import { readContract } from '../project/reticle-dir.js';
 import { buildDomainModel } from './domain-model.js';
@@ -74,7 +75,7 @@ export const DOMAIN_TOOLS = [
                 if (loaded.ok)
                     flows.push(loaded.value);
             }
-            const contract = await readContract(deps.fs, deps.reticleRoot);
+            const contract = await readContract(deps.fs, sessionRoot(deps, asString(args['sessionId'])));
             const project = await deps.project.read();
             const runs = project.ok ? project.file.runs : [];
             const model = buildDomainModel(flows, contract.ok ? contract.capabilities : null, runs);

package/dist/ee/audit-log.js

@@ -3,9 +3,9 @@
  * ee feature follows: call assertEnterprise...) first, then do the privileged work. The body here is a
  * stub — the real audit sink is the hosted control plane. It exists now to prove the gate.
  */
-import { assertEnterprise } from '../license/license.js';
+import { assertEnterprise, EnterpriseFeature } from '../license/license.js';
 /** Record an audit event — gated. Throws EnterpriseLicenseError in production without a valid license. */
 export function recordAuditEvent(event, ctx) {
-    assertEnterprise('audit-log', ctx);
+    assertEnterprise(EnterpriseFeature.AUDIT_LOG, ctx);
     return event; // stub: a real implementation persists to the enterprise audit store
 }

package/dist/events/body-failures.d.ts

@@ -1,4 +1,4 @@
 import { type ReticleEvent } from '@reticlehq/core';
-import type { Contradiction } from './contradictions.js';
+import type { OwnContradiction } from './contradictions.js';
 /** Contradictions for 2xx responses whose bodies report failure. One per offending call. */
-export declare function findBodyFailures(events: readonly ReticleEvent[]): Contradiction[];
+export declare function findBodyFailures(events: readonly ReticleEvent[]): OwnContradiction[];

package/dist/events/contradiction-folds.d.ts

@@ -0,0 +1,45 @@
+import type { ReticleEvent } from '@reticlehq/core';
+import type { Contradiction, ContradictionOptions } from './contradictions.js';
+/**
+ * Rules a CONSUMER adds to the contradiction pass, without editing the ones this package ships.
+ *
+ * Every rule in `contradictions.ts` is a pure fold over a recording — events in, findings out, no
+ * session, no clock, no IO. A service embedding this engine wants rules of exactly that shape for
+ * itself, and the only thing standing between it and one was that `findContradictions` folds over a
+ * list written into its own body. Appending to that list means editing this package, which means a
+ * fork, which means the consumer's rules and this package's rules become one tree to merge forever.
+ *
+ * A registry rather than a parameter on `findContradictions`, deliberately. There are six call sites
+ * and a consumer reaches none of them: the tools call the pass internally, and a tool handler is
+ * handed a deps bag, not options. Threading a parameter would mean touching every path a verdict can
+ * take — and would still miss the one inside `crawl`. Registration happens once, at boot, by whoever
+ * composed the process.
+ *
+ * This is not a public plugin API and should not be documented as one. It has a single intended
+ * consumer, which is a service we own, and its shape is free to change in lockstep with it.
+ */
+/**
+ * One consumer rule.
+ *
+ * Receives the app's OWN events — dev-tooling traffic is already removed, exactly as it is for the
+ * shipped rules. A second answer to "which events count" would be a second product.
+ */
+export type ContradictionFold = (events: readonly ReticleEvent[], options: ContradictionOptions) => readonly Contradiction[];
+/**
+ * Add a rule to every verdict this engine produces. Returns the undo.
+ *
+ * The undo is not a convenience: without it a registry is process-global state that tests cannot
+ * clean up, so each one starts depending on the order it ran in.
+ */
+export declare function registerContradictionFold(fold: ContradictionFold): () => void;
+/** What is registered right now. Exported so a guard can assert the registry is empty by default. */
+export declare function registeredContradictionFolds(): readonly ContradictionFold[];
+/**
+ * Run every registered rule, containing anything one of them throws.
+ *
+ * A registered fold is somebody else's code running inside every verdict path this package has. If a
+ * throw could propagate, one defect in a consumer's rule would take down `assert`, `act_and_wait`,
+ * `observe` and `crawl` at once — turning a missing finding into a dead engine. Contained and logged:
+ * the rules that did run still report, and the failure is visible rather than swallowed.
+ */
+export declare function runRegisteredFolds(events: readonly ReticleEvent[], options: ContradictionOptions): Contradiction[];