@reticlehq/server 2.2.1 → 2.3.0

package/dist/cli-parse.js

@@ -21,6 +21,9 @@ export const CLI_USAGE = `usage:
   reticle rollback                                     (restore the previous server version and restart)
   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 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)
 
 Cloud (link this project to Reticle Cloud — runs/flows recorded on the dashboard):
   reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)
@@ -38,6 +41,7 @@ const OPEN_COMMAND = 'open';
 const DRIVE_COMMAND = 'drive';
 const VERIFY_COMMAND = 'verify';
 const AFFECTED_COMMAND = 'affected';
+const HUNT_COMMAND = 'hunt';
 const CAPSULES_COMMAND = 'capsules';
 const GATE_COMMAND = 'gate';
 const WATCH_COMMAND = 'watch';
@@ -47,6 +51,15 @@ const MCP_COMMAND = 'mcp';
 const LICENSE_COMMAND = 'license';
 const VERSION_COMMAND = 'version';
 const TELEMETRY_COMMAND = 'telemetry';
+const FEEDBACK_COMMAND = 'feedback';
+const IDENTIFY_COMMAND = 'identify';
+export const COMPANY_FLAG = '--company';
+export const EMAIL_FLAG = '--email';
+export const CONTEXT_FLAG = '--context';
+export const FORGET_FLAG = '--forget';
+/** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
+export const RATING_FLAG = '--rating';
+export const BUG_FLAG = '--bug';
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export const TelemetryAction = {
     STATUS: 'status',
@@ -54,6 +67,58 @@ export const TelemetryAction = {
     DISABLE: 'disable',
 };
 export const DAEMON_INNER_COMMAND = '_daemon';
+/**
+ * Every subcommand a person can type, as one closed vocabulary. Telemetry reports which one ran, and
+ * this is what keeps that property low-cardinality and non-identifying: an argument we do not
+ * recognize reports as `unknown` rather than being echoed, so a typo — which may be a path, a URL, or
+ * a flow name — can never reach the wire just because someone misspelled `status`.
+ *
+ * Lives here rather than in the telemetry module because this is where the command names are already
+ * defined; a second list somewhere else would drift the first time a command is added.
+ */
+export const UNKNOWN_COMMAND = 'unknown';
+const KNOWN_COMMANDS = new Set([
+    INIT_COMMAND,
+    SERVE_COMMAND,
+    STOP_COMMAND,
+    STATUS_COMMAND,
+    OPEN_COMMAND,
+    DRIVE_COMMAND,
+    VERIFY_COMMAND,
+    AFFECTED_COMMAND,
+    HUNT_COMMAND,
+    CAPSULES_COMMAND,
+    GATE_COMMAND,
+    WATCH_COMMAND,
+    UPDATE_COMMAND,
+    ROLLBACK_COMMAND,
+    MCP_COMMAND,
+    LICENSE_COMMAND,
+    VERSION_COMMAND,
+    TELEMETRY_COMMAND,
+    FEEDBACK_COMMAND,
+    IDENTIFY_COMMAND,
+    DAEMON_INNER_COMMAND,
+    // Cloud subcommands dispatch before the local parser but are still commands a human ran.
+    'login',
+    'logout',
+    'whoami',
+    'link',
+    'project',
+    'config',
+    'push',
+    'runs',
+    'regression',
+    'share',
+    'doctor',
+    'help',
+]);
+/** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
+export function knownCommand(arg) {
+    if (arg === undefined || arg === '')
+        return 'help';
+    return KNOWN_COMMANDS.has(arg) ? arg : UNKNOWN_COMMAND;
+}
 export const HEADED_FLAG = '--headed';
 export const PORT_FLAG = '--port';
 export const DRIVE_FLAG = '--drive';
@@ -328,6 +393,42 @@ export function parseCliArgs(argv, defaultPort) {
             }
             return { kind: 'telemetry', action };
         }
+        case IDENTIFY_COMMAND: {
+            const flag = (name) => {
+                const at = rest.indexOf(name);
+                return at === -1 ? undefined : rest[at + 1];
+            };
+            const context = flag(CONTEXT_FLAG);
+            const company = flag(COMPANY_FLAG);
+            const email = flag(EMAIL_FLAG);
+            return {
+                kind: 'identify',
+                ...(context !== undefined ? { context } : {}),
+                ...(company !== undefined ? { company } : {}),
+                ...(email !== undefined ? { email } : {}),
+                forget: rest.includes(FORGET_FLAG),
+            };
+        }
+        case FEEDBACK_COMMAND: {
+            const ratingAt = rest.indexOf(RATING_FLAG);
+            const rating = ratingAt === -1 ? undefined : Number(rest[ratingAt + 1]);
+            if (rating !== undefined && (!Number.isInteger(rating) || rating < 1 || rating > 5)) {
+                return { kind: 'error', message: `${RATING_FLAG} takes a whole number from 1 to 5` };
+            }
+            // Everything that is not a flag or the rating's value is the message. Quoting is the user's
+            // job for shell reasons, but joining the remainder means an unquoted sentence still works.
+            const consumed = new Set(ratingAt === -1 ? [] : [ratingAt, ratingAt + 1]);
+            const text = rest
+                .filter((arg, i) => !consumed.has(i) && !arg.startsWith('--'))
+                .join(' ')
+                .trim();
+            return {
+                kind: 'feedback',
+                text,
+                ...(rating !== undefined ? { rating } : {}),
+                bug: rest.includes(BUG_FLAG),
+            };
+        }
         case OPEN_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
             // The first non-flag arg is the url (optional — omitting reuses a connected tab).
@@ -368,6 +469,12 @@ export function parseCliArgs(argv, defaultPort) {
         }
         case CAPSULES_COMMAND:
             return { kind: 'capsules' };
+        case HUNT_COMMAND: {
+            const dir = rest.find((a) => !a.startsWith('-'));
+            return dir === undefined
+                ? { kind: 'error', message: 'usage: reticle hunt <dir-of-crawl-reports>' }
+                : { kind: 'hunt', dir };
+        }
         case AFFECTED_COMMAND: {
             const t = parseTargetArgs(rest);
             if (t.files.length === 0 && t.since === undefined) {
@@ -413,4 +520,3 @@ export function parseCliArgs(argv, defaultPort) {
             return { kind: 'error', message: CLI_USAGE };
     }
 }
-//# sourceMappingURL=cli-parse.js.map

package/dist/cli-port.d.ts

@@ -29,4 +29,3 @@ export declare function readJournalEnabled(cwd: string, env: string | undefined)
  * Pass `portFlag` when the user explicitly supplied --port; pass `undefined` to fall through.
  */
 export declare function resolvePort(portFlag: number | undefined, envPort: number | undefined, projectPort: number | undefined, defaultPort: number): number;
-//# sourceMappingURL=cli-port.d.ts.map

package/dist/cli-port.js

@@ -80,4 +80,3 @@ export function readJournalEnabled(cwd, env) {
 export function resolvePort(portFlag, envPort, projectPort, defaultPort) {
     return portFlag ?? envPort ?? projectPort ?? defaultPort;
 }
-//# sourceMappingURL=cli-port.js.map

package/dist/cli-verify.d.ts

@@ -45,4 +45,3 @@ export declare function handleVerify(parsed: {
     port?: number;
 }): void;
 export {};
-//# sourceMappingURL=cli-verify.d.ts.map

package/dist/cli-verify.js

@@ -34,7 +34,7 @@ const MSG_NO_SESSION = 'No app connected — Reticle drove the URL but no @retic
     '  Make sure the SDK is in the build and reticle.connect() runs on the preview page' +
     ' (for a non-localhost preview: allowNonLocalhost + a pairing token).';
 const MSG_NO_FLOWS = 'No saved flows to verify (.reticle/flows is empty) — refusing to report a pass for verifying nothing.\n' +
-    '  Flows are recorded interactively by an agent (reticle_record_start → act → reticle_flow_save via the\n' +
+    '  Flows are recorded interactively by an agent (reticle_record{action:"start"} → act → reticle_flow_save via the\n' +
     '  MCP tools), then committed to .reticle/flows/. In CI, check those files in and re-run `reticle verify`.';
 const MSG_VERIFY_PREFIX = 'verify failed: ';
 function errMessage(error) {
@@ -219,4 +219,3 @@ export function handleVerify(parsed) {
     };
     void runVerify({ url: parsed.url, timeoutMs: parsed.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS }, ports);
 }
-//# sourceMappingURL=cli-verify.js.map

package/dist/cli.d.ts

@@ -2,4 +2,3 @@
 import { parseCliArgs, CLI_USAGE } from './cli-parse.js';
 export { parseCliArgs, CLI_USAGE };
 export type { CliResult } from './cli-parse.js';
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { pathToFileURL } from 'node:url';
-import { realpathSync, existsSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli-flow-commands.js';
 import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv } from '@reticlehq/core';
+import { loadDotEnv } from './telemetry/dev-repo.js';
 import { createNodeFileSystem } from './project/fs-port.js';
 import { affectedSavedFlows } from './flows/flow-sources.js';
 import { checkForUpdate } from './update/update-checker.js';
@@ -11,7 +12,6 @@ import { applyUpdate, rollback } from './update/updater.js';
 import { start, startDaemon } from './index.js';
 import { isCloudCommand, runCloudCommand } from './cloud-cli.js';
 import { SERVER_VERSION } from './server-version.js';
-import { getTelemetry, TelemetryEventKind, describeTelemetry, setTelemetryEnabled, } from './telemetry/telemetry.js';
 import { log } from './log.js';
 import { readPid, isAlive, isRunning, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, } from './daemon.js';
 import { waitForDaemon, startMcpProxy, probeDaemon } from './mcp-proxy.js';
@@ -19,11 +19,16 @@ import { installDaemonResilience } from './daemon-resilience.js';
 import { IdleShutdown, resolveIdleShutdownMs } from './idle-shutdown.js';
 import { fetchStatus, summarizeStatus, decideOpen, openInBrowser } from './cli-launch.js';
 import { handleVerify } from './cli-verify.js';
+import { summarizeHunt } from './hunt/hunt-report.js';
 import { runInit } from './init/run.js';
+import { handleDoctor } from './cli-doctor.js';
 import { buildNodeIo } from './init/node-io.js';
 import { describeLicense } from './license/license.js';
 import { readProjectPort, readProjectId } from './cli-port.js';
-import { DAEMON_INNER_COMMAND, PORT_FLAG, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, parseCliArgs, CLI_USAGE, TelemetryAction, } from './cli-parse.js';
+import { DAEMON_INNER_COMMAND, PORT_FLAG, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, parseCliArgs, CLI_USAGE, } from './cli-parse.js';
+import { handleFeedback, handleIdentify, handleTelemetry } from './telemetry/feedback-cli.js';
+import { installDaemonTelemetry } from './telemetry/daemon-telemetry.js';
+import { reportCliRun } from './telemetry/cli-telemetry.js';
 // Re-exported so existing imports (and the CLI tests) keep resolving from './cli.js'.
 export { parseCliArgs, CLI_USAGE };
 function handleInit(parsed) {
@@ -100,36 +105,6 @@ function handleStatus(port) {
         log('reticle_status', { port, running: true, pid, ...summarizeStatus(payload) });
     });
 }
-/**
- * `reticle doctor` — collapse the ~6 independent first-run failure modes into one command. Checks the
- * Chromium install (the #1 silent failure), whether a daemon is up on the resolved bridge port, and
- * reminds the user which port the app must dial. Human-readable to stdout (not the JSON log).
- */
-async function handleDoctor(port) {
-    const line = (s) => {
-        process.stdout.write(`${s}\n`);
-    };
-    line('reticle doctor');
-    line(`  node         ${process.version}`);
-    try {
-        const { chromium } = await import('playwright');
-        const path = chromium.executablePath();
-        line(existsSync(path)
-            ? '  chromium     ✓ installed'
-            : '  chromium     ✗ missing — run: npx playwright install chromium');
-    }
-    catch {
-        line('  chromium     ✗ missing — run: npx playwright install chromium');
-    }
-    const pid = readPid(port);
-    if (pid !== null && isAlive(pid)) {
-        line(`  daemon       ✓ running on :${port} (pid ${pid})`);
-    }
-    else {
-        line(`  daemon       ✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`);
-    }
-    line(`  bridge port  ${port}  (your app must dial THIS port — not your dev-server port)`);
-}
 /** Print the running package version (resolved once in server-version.ts). */
 function handleVersion() {
     log('reticle_version', { version: SERVER_VERSION });
@@ -138,24 +113,6 @@ function handleVersion() {
 function handleLicense() {
     log('reticle_license', { ...describeLicense(Date.now()) });
 }
-/**
- * `reticle telemetry [status|enable|disable]` — the user-facing control for anonymous usage metrics.
- * `disable` persists a machine-wide opt-out (survives shells, unlike RETICLE_TELEMETRY=0); `status`
- * says what's on, why, and where the full policy lives. Human-readable to stdout, like `doctor`.
- */
-function handleTelemetry(action) {
-    const line = (s) => {
-        process.stdout.write(`${s}\n`);
-    };
-    if (action !== TelemetryAction.STATUS) {
-        setTelemetryEnabled(action === TelemetryAction.ENABLE);
-    }
-    const state = describeTelemetry();
-    line(`telemetry    ${state.enabled ? 'enabled' : 'disabled'}  (${state.reason})`);
-    line(`policy       ${state.policyUrl}`);
-    if (state.enabled)
-        line('opt out      reticle telemetry disable  (or RETICLE_TELEMETRY=0 / DO_NOT_TRACK=1)');
-}
 /**
  * `reticle affected <file...>` — print which saved flows must re-verify for the given changed files.
  * Environment-side (costs the agent nothing per turn); the foundation of watch/gate. Never throws:
@@ -179,6 +136,42 @@ async function handleAffected(files, since) {
         });
     }
 }
+/**
+ * `reticle hunt <dir>` — aggregate crawl reports from many checkouts into one number.
+ *
+ * Detection already exists (`reticle_crawl`). This is the arithmetic that turns a pile of runs into
+ * the claim worth making: over N already-merged, already-green changes, how many carried a candidate
+ * false green? No control arm is needed, because those changes SHIPPED — the counterfactual is
+ * already established, which is what makes this the cheapest credible evidence available.
+ *
+ * Each file in <dir> is one crawl result. Producing them is a shell loop over a commit range:
+ * check out, boot the app, `reticle_crawl`, write the JSON here.
+ */
+async function handleHunt(dir) {
+    try {
+        const fs = createNodeFileSystem();
+        const names = await fs.readdir(dir);
+        const runs = [];
+        for (const name of names.filter((n) => n.endsWith('.json'))) {
+            const raw = await fs.readFile(join(dir, name));
+            if (raw === undefined)
+                continue;
+            const parsed = JSON.parse(raw);
+            const report = parsed;
+            runs.push({
+                label: report.label ?? name.replace(/\.json$/, ''),
+                anomalies: report.anomalies ?? [],
+                ...(report.stepsRun === undefined ? {} : { stepsRun: report.stepsRun }),
+            });
+        }
+        log('reticle_hunt', { ...summarizeHunt(runs) });
+    }
+    catch (error) {
+        log('reticle_hunt_failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
 /** `reticle update` — install the latest server version and restart (moved off the MCP surface). */
 async function handleUpdate() {
     try {
@@ -237,7 +230,11 @@ function handleOpen(requestedPort, url) {
         const { sessions } = summarizeStatus(await fetchStatus(port));
         const decision = decideOpen(sessions, url);
         if (decision.action === 'need-url') {
-            log('reticle_open', { port, error: 'no app connected — pass a url: reticle open <url>' });
+            log('reticle_open', {
+                port,
+                error: 'no app connected — pass a url: reticle open <url>. Desktop app (Electron/Tauri)? ' +
+                    'There is no url to open: start it as you normally would and it connects to this bridge itself.',
+            });
             return;
         }
         if (decision.action === 'reuse') {
@@ -269,10 +266,9 @@ function handleDaemonInner(parsed) {
     startDaemon(options)
         .then((server) => {
         log('reticle_daemon_ready', { port: parsed.port, pid: process.pid });
-        // A live daemon IS an active session (the numerator of "active sessions" + DAU/WAU/MAU). Pair the
-        // START here with an END (carrying duration) on any clean shutdown below — best-effort, non-blocking.
-        const sessionStartedAt = Date.now();
-        void getTelemetry().emit(TelemetryEventKind.SESSION_START);
+        // Daemon lifecycle telemetry: started, a one-shot project profile, the periodic counter flush,
+        // and the rich summary on shutdown. All of it lives in one module — see daemon-telemetry.ts.
+        const daemonTelemetry = installDaemonTelemetry(process.cwd());
         // Publish to the discovery registry so a build plugin can find this daemon by projectId — no
         // hand-reconciled port. Written from the child (only it knows its cwd); removePid drops it.
         const registryProjectId = readProjectId(process.cwd());
@@ -289,11 +285,12 @@ function handleDaemonInner(parsed) {
             process.exit(1);
         });
         const shutdown = () => {
-            void getTelemetry().emit(TelemetryEventKind.SESSION_END, {
-                sessionMs: Date.now() - sessionStartedAt,
-            });
-            server
-                .close()
+            // Awaited before the close/exit chain: `process.exit(0)` kills an in-flight POST, and this is
+            // the one event carrying the whole session. A failed send resolves anyway (emit swallows its
+            // own errors), so this can delay the exit by at most the send timeout, never prevent it.
+            void daemonTelemetry
+                .shutdown()
+                .then(() => server.close())
                 .then(() => {
                 removePid(parsed.port);
                 process.exit(0);
@@ -392,14 +389,21 @@ function handleLegacyDrive(parsed) {
     });
 }
 function main() {
+    // Before anything reads process.env — notably the telemetry gate and the bridge's security
+    // options — fold in a project-local `.env`. Values already in the environment always win.
+    loadDotEnv(process.cwd());
     const argv = process.argv.slice(2);
     // Every invocation passes through here — the single chokepoint for the "how often is it used / how
     // many distinct machines + projects" metrics. Fire-and-forget: a metric must never delay or fail a run.
-    const telemetry = getTelemetry();
-    // `detach` so a quick command (`version`/`gate`) exits immediately instead of waiting out the POST.
-    if (telemetry.firstRun)
-        void telemetry.emit(TelemetryEventKind.INSTALL, { detach: true });
-    void telemetry.emit(TelemetryEventKind.INVOKE, { detach: true });
+    //
+    // `_daemon` is EXCLUDED, and that exclusion is the whole point of this branch. `reticle mcp` and
+    // `reticle serve` start the daemon by re-running this very binary, so the child re-entered main()
+    // and emitted a second event for what a person experienced as one action. The old `invoke` metric
+    // was therefore inflated ~2x — and inflated worst on the agent-driven sessions that matter most,
+    // while one-shot commands like `version` counted once. That skewed the RATIO between commands, not
+    // just the scale, which is the kind of error you cannot correct for after the fact. The daemon's
+    // own lifecycle is already reported by `daemon_started` / `daemon_stopped`; it is not a CLI run.
+    reportCliRun(argv);
     // Cloud subcommands (login/link/project/config/push) are a distinct family with their own async client;
     // handle them before the local typed parser so `reticle login` etc. work as one tool.
     if (isCloudCommand(argv[0])) {
@@ -434,6 +438,12 @@ function main() {
         case 'telemetry':
             handleTelemetry(parsed.action);
             break;
+        case 'feedback':
+            void handleFeedback(parsed.text, parsed.rating, parsed.bug);
+            break;
+        case 'identify':
+            void handleIdentify(parsed);
+            break;
         case 'version':
             handleVersion();
             break;
@@ -458,6 +468,9 @@ function main() {
         case 'affected':
             void handleAffected(parsed.files, parsed.since);
             break;
+        case 'hunt':
+            void handleHunt(parsed.dir);
+            break;
         case 'gate':
             void handleGate(parsed.files, parsed.since);
             break;
@@ -500,4 +513,3 @@ function isEntryPoint() {
 if (isEntryPoint()) {
     main();
 }
-//# sourceMappingURL=cli.js.map

package/dist/cloud/cloud-config.d.ts

@@ -34,4 +34,3 @@ export interface ProjectCloud {
  * so the single-project / CI flow is unchanged. `homeDir` is injected (testable; `os.homedir()` at call).
  */
 export declare function resolveProjectCloud(fs: FileSystemPort, reticleRoot: string, homeDir: string, env: NodeJS.ProcessEnv): Promise<ProjectCloud>;
-//# sourceMappingURL=cloud-config.d.ts.map

package/dist/cloud/cloud-config.js

@@ -84,4 +84,3 @@ export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
     const config = key !== null ? { url: link.url.replace(/\/+$/, ''), apiKey: key } : null;
     return { config, policy, verify: link.verify, projectId: link.projectId };
 }
-//# sourceMappingURL=cloud-config.js.map

package/dist/cloud/cloud-sync.d.ts

@@ -110,20 +110,20 @@ declare const ServerVerificationSchema: z.ZodObject<{
     }>, "many">;
     summary: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    verificationId: string;
-    verdict: string | null;
     flows: {
         status: string;
         name: string;
     }[];
-    summary: string;
-}, {
     verificationId: string;
     verdict: string | null;
+    summary: string;
+}, {
     flows: {
         status: string;
         name: string;
     }[];
+    verificationId: string;
+    verdict: string | null;
     summary: string;
 }>;
 export type ServerVerification = z.infer<typeof ServerVerificationSchema>;
@@ -140,4 +140,3 @@ export declare function submitServerVerification(body: {
     source: string;
 }, config: CloudConfig | null, fetchImpl: FetchPostJsonLike): Promise<ServerVerification | null>;
 export {};
-//# sourceMappingURL=cloud-sync.d.ts.map

package/dist/cloud/cloud-sync.js

@@ -173,4 +173,3 @@ export async function submitServerVerification(body, config, fetchImpl) {
         return null;
     }
 }
-//# sourceMappingURL=cloud-sync.js.map

package/dist/cloud-cli.d.ts

@@ -1,4 +1,3 @@
 export declare const isCloudCommand: (cmd: string | undefined) => boolean;
 /** Dispatch a cloud subcommand. Returns the process exit code. */
 export declare const runCloudCommand: (argv: readonly string[]) => Promise<number>;
-//# sourceMappingURL=cloud-cli.d.ts.map

package/dist/cloud-cli.js

@@ -102,7 +102,15 @@ const api = async (method, url, token, body) => {
         init.body = JSON.stringify(body);
     const res = await fetch(url, init);
     const text = await res.text();
-    const json = text.length > 0 ? JSON.parse(text) : null;
+    let json = null;
+    if (text.length > 0) {
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`expected JSON from ${method} ${url} but got: ${text.slice(0, 120)}`);
+        }
+    }
     if (!res.ok) {
         const parsed = z.object({ error: z.object({ message: z.string() }) }).safeParse(json);
         throw new Error(parsed.success ? parsed.data.error.message : `${res.status} ${res.statusText}`);
@@ -504,4 +512,3 @@ export const runCloudCommand = async (argv) => {
         return 1;
     }
 };
-//# sourceMappingURL=cloud-cli.js.map

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

@@ -5,4 +5,3 @@ import type { ToolDef } from '../tools/tools.js';
  * it drives the app — so it's an explicit, bounded tool, never part of a passive read.
  */
 export declare const CRAWL_TOOLS: ToolDef[];
-//# sourceMappingURL=crawl-tools.d.ts.map

package/dist/crawl/crawl-tools.js

@@ -11,7 +11,7 @@ const nodeSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export const CRAWL_TOOLS = [
     {
         name: ReticleTool.CRAWL,
-        description: 'Autonomously click every reachable interactive control (bounded by maxSteps, default 25) and report anomalies WITHOUT a script: console errors, failed requests (status ≥ 400), and DEAD controls (dispatched but the app did nothing). DESTRUCTIVE — it really clicks (may navigate/mutate state); use reticle_explore first for a non-destructive list. Returns { interactiveFound, stepsRun, anomalies[{kind,ref,desc,detail}], counts, visited, truncated }.',
+        description: 'Autonomously click every reachable interactive control (bounded by maxSteps, default 25) and report anomalies WITHOUT a script. Two classes: single-channel faults (console errors, failed requests ≥400, DEAD controls that dispatched but did nothing) and CONTRADICTIONS — two channels disagreeing about the same click, e.g. the UI advanced while its write failed, a success signal fired over a failed request, a write succeeded and nothing changed, the same write fired twice, or the UI moved on over an in-flight request. Contradictions are the false greens a human cannot see, because a human watches one channel (the screen) and it looks correct. DESTRUCTIVE — it really clicks (may navigate/mutate state); use reticle_explore first for a non-destructive list. Returns { interactiveFound, stepsRun, anomalies[{kind,ref,desc,detail}], counts, visited, truncated }.',
         inputSchema: {
             maxSteps: z.number().optional().describe('Maximum number of controls to click. Default: 25.'),
             settleMs: z
@@ -70,4 +70,3 @@ export const CRAWL_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=crawl-tools.js.map

package/dist/crawl/crawl.d.ts

@@ -1,4 +1,4 @@
-import { CrawlAnomalyKind, type CommandResult, type ReticleEvent } from '@reticlehq/core';
+import { CrawlAnomalyKind, ContradictionKind, 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>;
@@ -16,7 +16,13 @@ export interface CrawlSession {
 }
 type CrawlSleep = (ms: number) => Promise<void>;
 export interface CrawlAnomaly {
-    kind: CrawlAnomalyKind;
+    /**
+     * A single-channel fault (something bad in one stream) or a CONTRADICTION (two channels
+     * 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.
+     */
+    kind: CrawlAnomalyKind | ContradictionKind;
     /** The control that triggered it. */
     ref: string;
     desc: string;
@@ -41,6 +47,7 @@ export interface CrawlReport {
         consoleErrors: number;
         failedRequests: number;
         deadControls: number;
+        contradictions: number;
     };
     /** Descriptions of the controls actually clicked. */
     visited: string[];
@@ -62,6 +69,13 @@ export interface CrawlOptions {
  * orchestration over a CrawlSession: no browser/Node imports, fully unit-testable with a fake.
  * Single-pass by design (no re-discovery) so it always terminates and never explodes on navigation.
  */
+/**
+ * Controls whose correct behaviour IS to do nothing when clicked.
+ *
+ * Read off the same descriptor the crawler already has, so no extra round trip: `[disabled]` is inert
+ * by definition, an already `[checked]` radio/checkbox is idempotent, and clicking a text field
+ * focuses it rather than changing anything.
+ */
+export declare function legitimatelyInert(desc: string): boolean;
 export declare function crawl(session: CrawlSession, opts: CrawlOptions, sleep: CrawlSleep): Promise<CrawlReport>;
 export {};
-//# sourceMappingURL=crawl.d.ts.map

package/dist/crawl/crawl.js

@@ -1,6 +1,7 @@
-import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, DANGEROUS_ACTION_CONFIRM_ARG, EventType, ReticleCommand, } from '@reticlehq/core';
+import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, ContradictionKind, DANGEROUS_ACTION_CONFIRM_ARG, EventType, ReticleCommand, } from '@reticlehq/core';
 import { parseInteractive, asRecord, asNumber, asString, sourceOf, } from '../tools/tools-helpers.js';
 import { ReticleTool } from '../tools/tool-names.js';
+import { findContradictions } from '../events/contradictions.js';
 /** Said out loud when the page was larger than one snapshot, so a clean sweep cannot mean "all clear". */
 export const CAPPED_SNAPSHOT_NOTE = 'the page exceeded one snapshot, so controls past the cap were never seen — interactiveFound is a floor, not a total; re-run with a narrower `scope` to cover the rest';
 /** Any buffer event that proves the app reacted to a click (vs a dead/no-op control). */
@@ -33,6 +34,20 @@ function failedRequests(events, floor) {
  * orchestration over a CrawlSession: no browser/Node imports, fully unit-testable with a fake.
  * Single-pass by design (no re-discovery) so it always terminates and never explodes on navigation.
  */
+/**
+ * Controls whose correct behaviour IS to do nothing when clicked.
+ *
+ * Read off the same descriptor the crawler already has, so no extra round trip: `[disabled]` is inert
+ * by definition, an already `[checked]` radio/checkbox is idempotent, and clicking a text field
+ * focuses it rather than changing anything.
+ */
+export function legitimatelyInert(desc) {
+    if (desc.includes('[disabled]'))
+        return true;
+    if (desc.includes('[checked]'))
+        return true;
+    return /\b(textbox|searchbox|combobox|spinbutton)\b/.test(desc);
+}
 export async function crawl(session, opts, sleep) {
     const maxSteps = opts.maxSteps ?? CRAWL_DEFAULTS.MAX_STEPS;
     const settleMs = opts.settleMs ?? CRAWL_DEFAULTS.SETTLE_MS;
@@ -50,7 +65,7 @@ export async function crawl(session, opts, sleep) {
     const coverageCapped = snapshot.truncated === true;
     const anomalies = [];
     const visited = [];
-    const counts = { consoleErrors: 0, failedRequests: 0, deadControls: 0 };
+    const counts = { consoleErrors: 0, failedRequests: 0, deadControls: 0, contradictions: 0 };
     const seen = new Set();
     let stepsRun = 0;
     for (const item of items) {
@@ -107,9 +122,34 @@ export async function crawl(session, opts, sleep) {
                 ...source,
             });
         }
+        // CONTRADICTIONS: the channels disagree about what this click did. Reported per control, so a
+        // crawl of an unknown app surfaces its false greens without anyone knowing where to look.
+        for (const c of findContradictions(events)) {
+            counts.contradictions += 1;
+            anomalies.push({
+                kind: c.kind,
+                ref: item.ref,
+                desc: item.desc,
+                detail: `${c.claim}, but ${c.counter} — ${c.detail}`,
+                ...source,
+            });
+        }
         // DEAD: the click dispatched but the app produced no activity and no error to explain it.
+        //
+        // Unless the control is SUPPOSED to be inert. Measured on a shipments console: every one of the
+        // crawler's three anomalies was a control behaving correctly — a `[disabled]` button, an already
+        // `[checked]` radio, and a text input (a click focuses it; mutating would be the surprise). An
+        // anomaly list that is 100% false on a real app is worse than no anomaly list, because the agent
+        // spends its budget disproving it and learns to skip the field.
+        //
+        // Deliberately NOT fixed by counting focus as activity: focus moving is not the app reacting, and
+        // treating it as such would make a genuinely dead button that takes focus look alive — trading
+        // noise for the false negative this check exists to catch.
         const dispatched = asRecord(act.result)['dispatched'] !== false && act.ok;
-        if (dispatched && errs.length === 0 && !events.some(isActivity)) {
+        if (dispatched &&
+            errs.length === 0 &&
+            !events.some(isActivity) &&
+            !legitimatelyInert(item.desc)) {
             counts.deadControls += 1;
             anomalies.push({
                 kind: CrawlAnomalyKind.DEAD_CONTROL,
@@ -133,4 +173,3 @@ export async function crawl(session, opts, sleep) {
         ...(coverageCapped ? { coverageNote: CAPPED_SNAPSHOT_NOTE } : {}),
     };
 }
-//# sourceMappingURL=crawl.js.map