@reticlehq/server 2.9.0 → 2.10.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.
 
@@ -84,7 +84,7 @@ It detects the framework, package manager and UI library, registers the MCP serv
 
 **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.
 
@@ -109,7 +109,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 +120,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,7 +128,7 @@ 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.
 
@@ -142,7 +142,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,10 +152,10 @@ 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.
 
@@ -170,7 +170,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 +178,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:
 
@@ -194,7 +194,7 @@ Stop here. Do not continue into 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 +202,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 +222,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 +243,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/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[];

package/dist/events/contradiction-folds.js

@@ -0,0 +1,42 @@
+import { log } from '../log.js';
+const FOLDS = [];
+/**
+ * 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 function registerContradictionFold(fold) {
+    FOLDS.push(fold);
+    return () => {
+        const at = FOLDS.indexOf(fold);
+        if (at !== -1)
+            FOLDS.splice(at, 1);
+    };
+}
+/** What is registered right now. Exported so a guard can assert the registry is empty by default. */
+export function registeredContradictionFolds() {
+    return [...FOLDS];
+}
+/**
+ * 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 function runRegisteredFolds(events, options) {
+    const found = [];
+    for (const fold of FOLDS) {
+        try {
+            found.push(...fold(events, options));
+        }
+        catch (error) {
+            log('contradiction_fold_failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return found;
+}

package/dist/events/contradictions.d.ts

@@ -19,7 +19,16 @@ import { type DeclaredNetFailure } from './declared.js';
  * Pure: a window of events in, findings out. No session, no IO, no clock.
  */
 export interface Contradiction {
-    kind: ContradictionKind;
+    /**
+     * Typed `string`, not `ContradictionKind`, because the vocabulary is open at the EDGE.
+     *
+     * `ContradictionKind` enumerates what THIS package's rules emit, and every one of them is still
+     * checked against it — see `OwnContradiction`, which is what the folds below build. A rule
+     * registered by a consumer emits kinds this package has never heard of and must not have to add
+     * them here to be reportable: a shared enum is exactly how a consumer's private vocabulary ends up
+     * shipped in the free product by accident.
+     */
+    kind: string;
     /** What one channel asserted — the optimistic half. */
     claim: string;
     /** What the other channel asserted — the half that contradicts it. */
@@ -27,6 +36,15 @@ export interface Contradiction {
     /** Concrete evidence, so the agent can go straight to the call or the control. */
     detail: string;
 }
+/**
+ * A contradiction emitted by one of THIS package's rules — the kind is closed.
+ *
+ * Widening `Contradiction.kind` to `string` for the consumer seam would otherwise have made every
+ * emit site below accept a typo'd literal. This keeps them checked without closing the edge.
+ */
+export type OwnContradiction = Contradiction & {
+    kind: ContradictionKind;
+};
 export interface ContradictionOptions {
     /** The action that opened this window, when one did. Enables the no-effect check. */
     action?: string | undefined;

package/dist/events/contradictions.js

@@ -5,6 +5,7 @@ import { findEchoMismatches } from './echo-mismatch.js';
 import { findUnitMismatches } from './unit-mismatch.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
 import { matchesDeclaredFailure } from './declared.js';
+import { runRegisteredFolds } from './contradiction-folds.js';
 function netCall(e) {
     const status = asNumber(e.data['status']);
     return {
@@ -255,7 +256,19 @@ export function findContradictions(allEvents, options = {}) {
     // claimed success" about an app that plainly reported a failure is true in outline and wrong in
     // its reasoning, which is how a checker stops being believed.
     const successSignals = signals.filter((name) => !ACKNOWLEDGED.test(name));
-    if (failed.length > 0 && successSignals.length > 0) {
+    // An app that RETRACTED has not claimed success, whenever it fired the optimistic signal.
+    //
+    // The weaker UI rule below already consulted this and the sharper signal rule did not, so an app
+    // that announced "ack:requested", met a 500, and then correctly emitted "ack:failed" and rolled the
+    // row back was reported as explicitly asserting success — the strongest accusation this file makes,
+    // against code doing exactly the right thing. On a fixture suite the scenario's FIXED twin produced
+    // the same finding as the build that swallowed the failure, which makes the finding worthless on
+    // the one measurement that scores precision.
+    //
+    // Ordering cannot decide this: an optimistic UI legitimately fires its success signal BEFORE the
+    // response, so "the claim must follow the failure" would miss the real defect. What separates them
+    // is not when the app spoke, it is whether it took it back.
+    if (failed.length > 0 && successSignals.length > 0 && !failureAcknowledged(events)) {
         found.push({
             kind: ContradictionKind.SIGNAL_CONTRADICTED,
             claim: `the app fired ${successSignals.map((s) => `"${s}"`).join(', ')}`,
@@ -341,5 +354,7 @@ export function findContradictions(allEvents, options = {}) {
             });
         }
     }
-    return found;
+    // Consumer rules run LAST and over the same app-only window, so a service embedding this engine
+    // adds to the verdict rather than forking the file that produces it.
+    return [...found, ...runRegisteredFolds(events, options)];
 }

package/dist/events/echo-mismatch.d.ts

@@ -1,5 +1,5 @@
 import { type ReticleEvent } from '@reticlehq/core';
-import type { Contradiction } from './contradictions.js';
+import type { OwnContradiction } from './contradictions.js';
 /**
  * Contradictions for writes whose response echoes a different value than the request asked for.
  *
@@ -7,4 +7,4 @@ import type { Contradiction } from './contradictions.js';
  * action that opened this window was dispatched. A finding about a request that had already settled
  * before the agent acted otherwise reads as a verdict on the change it just made.
  */
-export declare function findEchoMismatches(events: readonly ReticleEvent[], actionSince?: number): Contradiction[];
+export declare function findEchoMismatches(events: readonly ReticleEvent[], actionSince?: number): OwnContradiction[];

package/dist/events/stale-response.d.ts

@@ -1,4 +1,3 @@
 import { type ReticleEvent } from '@reticlehq/core';
-import type { Contradiction } from './contradictions.js';
-/** The one contradiction, or none. Reported once per window — a race is a fact about the window. */
-export declare function findStaleResponses(events: readonly ReticleEvent[]): Contradiction[];
+import type { OwnContradiction } from './contradictions.js';
+export declare function findStaleResponses(events: readonly ReticleEvent[]): OwnContradiction[];

package/dist/events/stale-response.js

@@ -91,6 +91,49 @@ function flights(events) {
  */
 const MAX_FLIGHTS_PER_PATH = 60;
 /** The one contradiction, or none. Reported once per window — a race is a fact about the window. */
+/**
+ * How long after a superseded response lands we look for the app reacting to it.
+ *
+ * A handler runs on the microtask that resolves the fetch; the render follows within a frame or two.
+ * Beyond this the connection between the response and any change is speculation.
+ */
+const APPLY_WINDOW_MS = 500;
+/**
+ * How far BEFORE the completion stamp a reaction still counts as reacting to it.
+ *
+ * Not a fudge factor — a correction for which of the two is stamped first. `NET_REQUEST` is emitted
+ * when the observer's wrapper sees the fetch settle, and the app's own handler runs on the same
+ * microtask; in practice the app's state write, signal and DOM text land at or a millisecond BEFORE
+ * the completion event that caused them.
+ *
+ * So a strictly-forward window could not see the application at all, and the rule could never fire on
+ * real traffic however plainly the app misbehaved. Sixteen passing unit tests did not catch that,
+ * because synthetic events are written with the reaction placed after the cause.
+ */
+const APPLY_SLACK_MS = 100;
+/**
+ * Did the app REACT to this response — did anything user-visible move after it landed?
+ *
+ * The question the rule could not previously ask, and the difference between a defect and a
+ * correctly-handled race. An app that guards against superseded responses still RACES: two requests
+ * overlap and settle out of order exactly as before. What it does not do is act on the loser.
+ *
+ * Without this check the rule fires identically on both, which is worse than not having it: a
+ * detector that accuses correct code teaches people to ignore it, and it takes the true positives
+ * down with it.
+ */
+function appliedAfter(events, settledAt) {
+    return events.some((event) => {
+        if (event.t < settledAt - APPLY_SLACK_MS || event.t > settledAt + APPLY_WINDOW_MS)
+            return false;
+        return (event.type === EventType.STATE_CHANGE ||
+            event.type === EventType.SIGNAL ||
+            event.type === EventType.DOM_TEXT ||
+            event.type === EventType.DOM_ADDED ||
+            event.type === EventType.DOM_REMOVED ||
+            event.type === EventType.DOM_ATTR);
+    });
+}
 export function findStaleResponses(events) {
     // Grouped by path first: two reads of DIFFERENT endpoints can never race, and comparing them was
     // the bulk of the work on any real page, which talks to many endpoints at once.
@@ -105,13 +148,13 @@ export function findStaleResponses(events) {
     }
     for (const group of byPath.values()) {
         const reads = group.slice(-MAX_FLIGHTS_PER_PATH);
-        const found = raceIn(reads);
+        const found = raceIn(reads, events);
         if (found !== undefined)
             return [found];
     }
     return [];
 }
-function raceIn(reads) {
+function raceIn(reads, events) {
     for (const first of reads) {
         for (const second of reads) {
             if (first.id === second.id)
@@ -127,6 +170,10 @@ function raceIn(reads) {
             // Parallel pagination is not a race — see differsOnlyByEnumeration.
             if (differsOnlyByEnumeration(queryOf(first.url), queryOf(second.url)))
                 continue;
+            // The race happened. Whether it MATTERS is whether the app acted on the loser — an app that
+            // drops superseded responses races just as visibly and is not broken.
+            if (!appliedAfter(events, first.settledAt))
+                continue;
             return {
                 kind: ContradictionKind.STALE_RESPONSE_APPLIED,
                 claim: `both reads of ${pathOf(first.url)} returned successfully and the page settled`,

package/dist/events/unit-mismatch.d.ts

@@ -1,5 +1,5 @@
 import { type ReticleEvent } from '@reticlehq/core';
-import type { Contradiction } from './contradictions.js';
+import type { OwnContradiction } from './contradictions.js';
 /**
  * @param prior events from BEFORE the window, used only to learn what the API has stated.
  *
@@ -13,4 +13,4 @@ import type { Contradiction } from './contradictions.js';
  * every other rule blame this action for events it did not cause, and would re-report every earlier
  * mistake on every assert.
  */
-export declare function findUnitMismatches(events: readonly ReticleEvent[], prior?: readonly ReticleEvent[]): Contradiction[];
+export declare function findUnitMismatches(events: readonly ReticleEvent[], prior?: readonly ReticleEvent[]): OwnContradiction[];

package/dist/flows/flow-tools.js

@@ -292,7 +292,7 @@ export const FLOW_TOOLS = [
             unverifiable: z
                 .object({ reason: z.string() })
                 .optional()
-                .describe('Set on an ok replay that cannot fail: the flow asserts no observable consequence, so it passes even when the feature is broken. Same reason reticle_flow_verify reports.'),
+                .describe('Set on an ok replay that cannot fail: the flow asserts no observable consequence, so it passes even when the feature is broken. Same reason reticle_verify{action:"flows"} reports.'),
             decision: z
                 .object({
                 verdict: z.string(),

package/dist/flows/verify-change-tools.js

@@ -97,7 +97,7 @@ export const VERIFY_CHANGE_TOOLS = [
             const cursor = cursorBeforeReplay(deps, args);
             const verify = FLOW_TOOLS.find((tool) => tool.name === ReticleTool.FLOW_VERIFY);
             if (verify === undefined)
-                throw new Error('reticle_flow_verify is not registered');
+                throw new Error('the whole-suite replay tool is not registered');
             const suite = asRecord(await verify.handler(deps, {
                 names: affected,
                 ...(asNumber(args['parallel']) === undefined ? {} : { parallel: args['parallel'] }),