@reticlehq/server 2.7.0 → 2.9.0

package/dist/cli/status-next-action.js

@@ -0,0 +1,61 @@
+/**
+ * The sentence `status` owes the user, because `init` promised it.
+ *
+ * `init` closes with "run `npx @reticlehq/server status` — it confirms the app connected, or says
+ * exactly why it has not". On a real install, following that instruction printed `running: false,
+ * presence: "free"` and nothing else: no reason, no next step, no mention of the app. This is the last
+ * checkpoint in the setup path, so a user who arrives here and learns nothing has nowhere left to go.
+ *
+ * Deliberately thin. The differential already exists in `nextActionFor`, which ranks these causes from
+ * what the daemon knows and was rewritten this week to stop leading with a port mismatch; a second
+ * differential here could disagree with the first, and two confident answers pointing different ways
+ * is worse than one. This only supplies the facts the CLI has and renders the answer.
+ */
+import { nextActionFor } from '../session/no-session-next-action.js';
+/**
+ * What to do next, or `undefined` when a session is connected and there is nothing to fix.
+ *
+ * The success case has to stay silent: advice printed beside a working session reads as though
+ * something is still wrong, which is its own kind of lie.
+ */
+export function statusNextAction(facts) {
+    if (facts.sessionCount > 0)
+        return undefined;
+    // Ahead of everything else, because it dominates: an app that was never wired cannot connect, and
+    // no advice about dev servers or ports applies until it is. `previouslyConnected` overrides it —
+    // an app CAN be wired by the Vite or Babel plugin with no `.reticle.json` at all, so a project
+    // that has connected here before is wired whatever this file says, and sending it back to `init`
+    // would be the same wrong answer in the other direction.
+    if (!facts.initialized && !facts.previouslyConnected) {
+        return ('no app has ever connected for this project, and there is no Reticle config here — so the ' +
+            'tools are registered and the app itself is not instrumented. Those are two different halves ' +
+            'of the install. Run `npx @reticlehq/server init` in the app directory, then start the dev ' +
+            'server and load the page.');
+    }
+    if (!facts.running) {
+        // `running: false` reads as "Reticle is broken", and it usually means the opposite: the daemon is
+        // started by an agent, on demand, and idles out when nobody is driving. A user who has not
+        // attached an agent yet is exactly on track, and saying so is the whole job of this branch.
+        const wiring = facts.previouslyConnected
+            ? 'This project has connected before, so the wiring is correct.'
+            : '';
+        return (`no daemon is running on this port, which is normal — an agent starts it when it first calls a ` +
+            `Reticle tool, and it exits again when idle. ${wiring} Ask your agent to verify something, then ` +
+            `run status again.`).replace(/\s+/g, ' ');
+    }
+    // The daemon is up and no page has connected. `nextActionFor` owns the ranking; the CLI cannot see
+    // listening ports or a dev command from here, so it passes what it has and lets that function say
+    // what is missing rather than guessing at it.
+    const next = nextActionFor({
+        // The durable bit IS this side's `everConnected`. In-process the flag means "this daemon has served
+        // a session", which a daemon seconds old cannot know; from the CLI the honest equivalent is "an app
+        // for this project has connected on this port", which is the fact that decides whether the wiring
+        // is in question at all.
+        everConnected: facts.previouslyConnected,
+        initialized: facts.initialized,
+        listening: [],
+        dev: undefined,
+        previouslyConnected: facts.previouslyConnected,
+    });
+    return next.reason;
+}

package/dist/cli.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 import { pathToFileURL } from 'node:url';
+import { openFailureNote } from './cli/open-note.js';
 import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { stateDirProblem } from './daemon/state-dir.js';
+import { statusNextAction } from './cli/status-next-action.js';
+import { hasConnectedBefore } from './session/connection-memory.js';
 import { reticleStateHome } from './daemon/daemon.js';
 import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli/cli-flow-commands.js';
 import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv } from '@reticlehq/core';
@@ -11,7 +14,7 @@ import { createNodeFileSystem } from './project/fs-port.js';
 import { affectedSavedFlows } from './flows/flow-sources.js';
 import { availableUpdate } from './update/update-nudge.js';
 import { handleUpdate, handleRollback } from './cli/cli-update-commands.js';
-import { start, startDaemon } from './index.js';
+import { startDaemon } from './index.js';
 import { isCloudCommand, runCloudCommand } from './cli/cloud-cli.js';
 import { SERVER_VERSION } from './version/server-version.js';
 import { log } from './log.js';
@@ -22,10 +25,13 @@ import { installDaemonResilience, installProxyResilience, recordExitReason, Daem
 import { IdleShutdown, resolveIdleShutdownMs, resolveIdleCheckMs } from './daemon/idle-shutdown.js';
 import { DaemonHeartbeat, resolveHeartbeatMs } from './daemon/heartbeat.js';
 import { everServedToolCall } from './daemon/daemon-usefulness.js';
-import { fetchStatus, summarizeStatus, warnOnDaemonSkew, decideOpen, openInBrowser, } from './cli/cli-launch.js';
+import { fetchStatus, summarizeStatus, warnOnDaemonSkew, decideOpen, openInBrowser, openCommand, } from './cli/cli-launch.js';
+import { handleDrive } from './cli/drive-command.js';
 import { handleVerify } from './cli/cli-verify.js';
+import { runKill } from './cli/cli-kill.js';
 import { summarizeHunt } from './hunt/hunt-report.js';
 import { runInit } from './init/run.js';
+import { confirmInstall, nodeConfirmDeps } from './init/confirm.js';
 import { handleDoctor } from './cli/cli-doctor.js';
 import { buildNodeIo } from './init/node-io.js';
 import { describeLicense } from './license/license.js';
@@ -38,6 +44,7 @@ import { reportCliRun } from './telemetry/cli-telemetry.js';
 export { parseCliArgs, CLI_USAGE };
 function handleInit(parsed) {
     const cwd = process.cwd();
+    const io = buildNodeIo(cwd);
     const result = runInit({
         cwd,
         port: parsed.port,
@@ -45,9 +52,14 @@ function handleInit(parsed) {
         dryRun: parsed.dryRun,
         install: parsed.install,
         ...(parsed.app === undefined ? {} : { app: parsed.app }),
-    }, buildNodeIo(cwd));
-    if (!result.ok)
-        process.exit(1);
+        // The outcome is reported by confirmInstall instead, once it knows whether an app connected —
+        // `init` writing files was never the same thing as `init` working (#269).
+        deferOutcome: true,
+    }, io);
+    void confirmInstall(result, io, nodeConfirmDeps(parsed.port ?? RETICLE_DEFAULT_PORT)).then(() => {
+        if (!result.ok)
+            process.exit(1);
+    });
 }
 function handleServe(parsed) {
     void serveWithHonestExit(parsed);
@@ -190,17 +202,56 @@ function handleStop(port, quiet) {
         }
     }, 100);
 }
+/**
+ * `reticle restart` — free the port, then put a daemon back on it and prove it bound.
+ *
+ * The two halves are reported separately on purpose. A restart that killed the old daemon and then
+ * could not start a new one leaves the user in a different place from one that could not kill
+ * anything at all, and a single `ok: false` cannot tell them which happened.
+ */
+async function handleRestart(port, force) {
+    const freed = await runKill(port, force);
+    if (!freed) {
+        log('reticle_restart_aborted', {
+            port,
+            reason: 'the port was not freed, so nothing was started — the old holder is still there',
+        });
+        process.exit(1);
+        return;
+    }
+    // Reuses `serve`'s path, which waits for the daemon to ANSWER before claiming it started and exits
+    // non-zero when it does not. A restart that reports success for a daemon that never bound is the
+    // same lie `serve` already stopped telling.
+    await serveWithHonestExit({ port, headless: true, http: false });
+}
+/** `{ nextAction }` when there is one, `{}` when a session is connected — so the success case is silent. */
+function withNextAction(facts) {
+    const next = statusNextAction(facts);
+    return next === undefined ? {} : { nextAction: next };
+}
 function handleStatus(port) {
     const pid = readPid(port);
+    // Durable, so it survives the daemon idling out — which is the state `status` is most often run in.
+    const projectId = readProjectId(process.cwd());
+    const previouslyConnected = hasConnectedBefore(reticleStateHome(), port, projectId);
+    // Whether `init` has run HERE. Registering the MCP server does not wire the app, and more than one
+    // path does the first without the second — so this is the commonest reason `status` has nothing to
+    // report, and it was not among the facts this command could state.
+    const initialized = projectId !== undefined;
     if (null === pid || !isAlive(pid)) {
         // `running: false` on its own has been reported about a port that was demonstrably occupied,
         // because the pid file is not the port. Ask the port before answering.
         void probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }).then((presence) => {
+            const running = presenceIsUsable(presence);
             log('reticle_status', {
                 port,
-                running: presenceIsUsable(presence),
+                running,
                 presence,
                 ...(presence === PortPresence.FOREIGN ? { reason: describePresence(presence, port) } : {}),
+                // `init` promises this command says why the app has not connected. Without it the answer was
+                // `running: false` and nothing else, which reads as "Reticle is broken" for what is usually
+                // just a daemon that has not been asked to do anything yet.
+                ...withNextAction({ running, sessionCount: 0, previouslyConnected, initialized }),
             });
         });
         return;
@@ -213,10 +264,23 @@ function handleStatus(port) {
         const update = availableUpdate();
         const nudge = update === undefined ? {} : { updateAvailable: update };
         if (payload === undefined) {
-            log('reticle_status', { port, running: true, pid, ...nudge });
+            log('reticle_status', {
+                port,
+                running: true,
+                pid,
+                ...nudge,
+                ...withNextAction({ running: true, sessionCount: 0, previouslyConnected, initialized }),
+            });
             return;
         }
-        log('reticle_status', { port, running: true, pid, ...summarizeStatus(payload), ...nudge });
+        const summary = summarizeStatus(payload);
+        // Only when the daemon did NOT already explain itself. It has the whole diagnosis in-process and
+        // puts it on the wire as `why`; printing a second, thinner opinion beside it risks two confident
+        // answers pointing different ways, which is worse than one.
+        const next = summary.why === undefined
+            ? withNextAction({ running: true, ...summary, previouslyConnected, initialized })
+            : {};
+        log('reticle_status', { port, running: true, pid, ...summary, ...next, ...nudge });
     });
 }
 /** Print the running package version (resolved once in server-version.ts). */
@@ -288,13 +352,20 @@ async function handleHunt(dir) {
 }
 /** Ensure a daemon is reachable on `port` (probe the real port; spawn + wait only if nothing's there). */
 function ensureDaemon(port) {
-    return probeDaemon(port).then(async (listening) => {
+    return probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }).then(async (presence) => {
         // Attaching to whatever already owns the port is the whole point of a daemon — but it means an
         // upgrade does NOT take effect until that daemon dies, and nothing used to say so. Say it here,
         // where both versions are in hand, and keep attaching: killing another agent's daemon on a
         // version bump is worse than a loud warning.
-        if (listening)
+        if (presenceIsUsable(presence))
             return warnOnDaemonSkew(port);
+        // Not free, not a daemon: a stranger holds the port. Spawning here is guaranteed to fail —
+        // the child cannot bind — and `waitForDaemon` would then report READY anyway, because its
+        // probe is the same bare TCP connect and the stranger accepts. That is the "serve reports
+        // success for a daemon that never bound" shape. Refuse instead, with the sentence `doctor`
+        // says.
+        if (PortPresence.FREE !== presence)
+            throw new Error(describePresence(presence, port));
         const scriptPath = process.argv[1];
         if (scriptPath === undefined)
             throw new Error('cannot locate the reticle daemon script');
@@ -364,8 +435,12 @@ function handleOpen(requestedPort, url) {
             log('reticle_open', {
                 port,
                 error: `could not launch a browser: ${launchError}`,
-                recovery: 'Open the url yourself, or run `reticle doctor` — it checks the pieces this command ' +
-                    'depends on.',
+                // Points at the OS handler, not at `reticle doctor`. Doctor's browser check is about
+                // Reticle's own Chromium, which this command never touches — the same misdirect the
+                // no-session note below spells out at length, left standing here for one more release.
+                recovery: 'Nothing was opened. This command asks the OS to open a url in your default browser ' +
+                    `(\`${openCommand(decision.url, process.platform).cmd}\` on this platform) and that ` +
+                    'failed, so the fix is on the OS side: open the url yourself, or set a default browser.',
             });
             process.exit(1);
             return;
@@ -376,6 +451,7 @@ function handleOpen(requestedPort, url) {
         const connected = await waitForNewSession(port, sessions.length);
         log('reticle_open', {
             port,
+            ...(port === requestedPort ? {} : { requestedPort }),
             opened: decision.url,
             connected,
             ...(connected
@@ -388,14 +464,7 @@ function handleOpen(requestedPort, url) {
                     // about a browser THIS command never uses, so a missing Chromium reads as the
                     // explanation for a session that is missing for an unrelated reason. Both misdirects
                     // were reported from the field, each costing several calls of app-side wiring hunt.
-                    note: `the URL was handed to the system default browser (this command does not use ` +
-                        `Reticle's own Chromium, so a chromium warning from \`reticle doctor\` is unrelated ` +
-                        `to this). No Reticle session appeared. By far the likeliest cause is that the app ` +
-                        `carries no Reticle SDK, or dials a port other than ${String(port)} — run ` +
-                        `\`reticle init\` in the app's directory and restart its dev server. If the app IS ` +
-                        `wired, give the page a moment and check the browser console: the SDK announces its ` +
-                        `own connect failures there, including the one it refuses to make from a ` +
-                        `non-localhost host without allowNonLocalhost.`,
+                    note: openFailureNote(port, requestedPort),
                 }),
         });
     })
@@ -444,6 +513,12 @@ function handleDaemonInner(parsed) {
             // which is after everything below has run. Without it the exit line says `code: 0` and a
             // reader cannot tell a tidy stop from the bridge disappearing — see #123.
             recordExitReason(reason);
+            // Say so on the wire before anything closes. The proxy on the other end sees a clean stream
+            // end whether we retired on schedule or died under it, and it has no other way to tell —
+            // which is how a designed shutdown came to dominate the metric that means "the agent lost
+            // its tools". Told, the proxy classifies its own drop honestly. First, because the send has
+            // to reach a socket that is still open.
+            server.announceShutdown?.();
             // 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.
@@ -538,8 +613,15 @@ function handleMcp(opts) {
      * disappeared mid-session with nothing said. Respawning here makes the reconnect self-healing.
      */
     const ensure = async () => {
-        if (await probeDaemon(port))
+        // The same question every other surface asks. It used to be a bare TCP connect, so a stranger on
+        // the bridge port answered "a daemon is here" — the proxy connected, the stream ended, and each
+        // client request woke into the identical non-answer. Rejecting here is what puts the proxy
+        // dormant with a reason, instead of pretending the wake succeeded.
+        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+        if (presenceIsUsable(presence))
             return;
+        if (PortPresence.FREE !== presence)
+            throw new Error(describePresence(presence, port));
         const scriptPath = process.argv[1];
         if (scriptPath === undefined) {
             log('reticle_mcp_no_script', {});
@@ -560,8 +642,13 @@ function handleMcp(opts) {
                 daemonArgs.push(HTTP_TOKEN_FLAG, httpToken);
         }
         spawnDaemon(process.execPath, scriptPath, daemonArgs, port);
-        log('reticle_mcp_daemon_started', { port, ...(driveUrl !== undefined ? { driveUrl } : {}) });
+        // Announce the daemon only once the PORT ACCEPTS. This line used to be written the instant the
+        // child was spawned, which on a Windows first bootstrap meant `reticle_mcp_daemon_started`
+        // followed about ten seconds later by `reticle_mcp_daemon_unavailable` and a first
+        // `reticle_sessions` that expired. A readiness signal that precedes readiness is worse than
+        // none: a client that believes it stops waiting for the thing that has not happened.
         await waitForDaemon(port);
+        log('reticle_mcp_daemon_started', { port, ...(driveUrl !== undefined ? { driveUrl } : {}) });
     };
     // Start the proxy WHATEVER happened to the daemon.
     //
@@ -601,22 +688,6 @@ function handleMcp(opts) {
         });
     });
 }
-function handleLegacyDrive(parsed) {
-    const options = {
-        port: parsed.port,
-        driveUrl: parsed.driveUrl,
-        headless: parsed.headless,
-    };
-    start(options)
-        .then(() => {
-        log('reticle_started', { port: parsed.port });
-    })
-        .catch((error) => {
-        const message = error instanceof Error ? error.message : String(error);
-        log('reticle_start_failed', { error: message });
-        process.exit(1);
-    });
-}
 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.
@@ -669,6 +740,15 @@ function main() {
         case 'stop':
             handleStop(parsed.port, parsed.quiet);
             break;
+        case 'kill':
+            void runKill(parsed.port, parsed.force).then((freed) => {
+                if (!freed)
+                    process.exit(1);
+            });
+            break;
+        case 'restart':
+            void handleRestart(parsed.port, parsed.force);
+            break;
         case 'status':
             handleStatus(parsed.port);
             break;
@@ -697,7 +777,7 @@ function main() {
             handleOpen(parsed.port, parsed.url);
             break;
         case 'drive':
-            handleLegacyDrive(parsed);
+            handleDrive(parsed);
             break;
         case 'verify':
             handleVerify(parsed);

package/dist/crawl/crawl-tools.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
 import { crawl } from './crawl.js';
+import { routeFromUrl, routesFromEvents } from '../project/learned-routes.js';
 const nodeSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * The autonomous "smart monkey" tool. Builds on reticle_explore (which only LISTS) by
@@ -58,8 +59,10 @@ export const CRAWL_TOOLS = [
                 .describe('Present only when the page exceeded one snapshot, so controls past the cap were never listed. When present, a zero-anomaly result does NOT mean the app is clean.'),
             truncated: z.boolean(),
         },
-        handler: (deps, args) => {
+        handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
+            const since = session.elapsed();
+            const initialRoute = routeFromUrl(session.url);
             const maxSteps = asNumber(args['maxSteps']);
             const settleMs = asNumber(args['settleMs']);
             const scope = asString(args['scope']);
@@ -69,7 +72,14 @@ export const CRAWL_TOOLS = [
                 ...(scope !== undefined ? { scope } : {}),
                 ...(true === args['confirmDangerous'] ? { confirmDangerous: true } : {}),
             };
-            return crawl(session, opts, nodeSleep);
+            const report = await crawl(session, opts, nodeSleep);
+            const routes = [
+                ...(initialRoute === undefined ? [] : [initialRoute]),
+                ...routesFromEvents(session.eventsSince(since)),
+            ];
+            if (routes.length > 0)
+                await deps.project.recordRoutes(routes);
+            return report;
         },
     },
 ];

package/dist/crawl/crawl.d.ts

@@ -39,6 +39,19 @@ export interface CrawlAnomaly {
 }
 /** Said out loud when the page was larger than one snapshot, so a clean sweep cannot mean "all clear". */
 export declare const CAPPED_SNAPSHOT_NOTE = "the page exceeded one snapshot, so controls past the cap were never seen \u2014 interactiveFound is a floor, not a total; re-run with a narrower `scope` to cover the rest";
+/**
+ * Said out loud when the crawl's OWN clicks put controls on the page that it then never visited.
+ *
+ * The enumeration happens once, before the first click, so a control that only exists after a login,
+ * a modal or a tab switch is invisible to this run. Measured on the bench app: a crawl of the login
+ * screen visited three controls, its click on "Sign in" produced seven more, and it returned
+ * `truncated: false` with an empty anomaly list and nine of twelve steps unused. Read as a sweep,
+ * that is a clean bill of health for an app the crawl never entered.
+ *
+ * The same words as the capped-snapshot case on purpose — it is the same idea (interactiveFound is a
+ * floor) reached by a different route, and a second vocabulary for it would just be more to learn.
+ */
+export declare function revealedControlsNote(count: number): string;
 export interface CrawlReport {
     interactiveFound: number;
     stepsRun: number;

package/dist/crawl/crawl.js

@@ -6,6 +6,23 @@ 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';
+/**
+ * Said out loud when the crawl's OWN clicks put controls on the page that it then never visited.
+ *
+ * The enumeration happens once, before the first click, so a control that only exists after a login,
+ * a modal or a tab switch is invisible to this run. Measured on the bench app: a crawl of the login
+ * screen visited three controls, its click on "Sign in" produced seven more, and it returned
+ * `truncated: false` with an empty anomaly list and nine of twelve steps unused. Read as a sweep,
+ * that is a clean bill of health for an app the crawl never entered.
+ *
+ * The same words as the capped-snapshot case on purpose — it is the same idea (interactiveFound is a
+ * floor) reached by a different route, and a second vocabulary for it would just be more to learn.
+ */
+export function revealedControlsNote(count) {
+    return (`the page changed as you clicked: ${String(count)} control(s) that did not exist when this crawl ` +
+        'started were never visited — interactiveFound is a floor, not a total; re-run the crawl from ' +
+        'the state you are now in to cover them');
+}
 /** Any buffer event that proves the app reacted to a click (vs a dead/no-op control). */
 function isActivity(e) {
     return (e.type === EventType.NET_REQUEST ||
@@ -50,6 +67,25 @@ export function legitimatelyInert(desc) {
         return true;
     return /\b(textbox|searchbox|combobox|spinbutton)\b/.test(desc);
 }
+/**
+ * How many interactive controls exist now that did not exist when the crawl enumerated.
+ *
+ * Keyed on ref, which is the element's identity: a control that re-rendered keeps its ref and is not
+ * new, and one that vanished simply does not appear. Returns 0 rather than throwing if the snapshot
+ * fails — this is a disclosure, and failing the whole crawl to report on coverage would be worse
+ * than the silence it is fixing.
+ */
+async function countRevealed(session, opts, before) {
+    const snap = await session.command(ReticleCommand.SNAPSHOT, {
+        mode: 'interactive',
+        ...(opts.scope !== undefined ? { scope: opts.scope } : {}),
+    });
+    if (!snap.ok)
+        return 0;
+    const tree = (snap.result ?? {}).tree ?? '';
+    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;
+}
 export async function crawl(session, opts, sleep) {
     const maxSteps = opts.maxSteps ?? CRAWL_DEFAULTS.MAX_STEPS;
     const settleMs = opts.settleMs ?? CRAWL_DEFAULTS.SETTLE_MS;
@@ -168,6 +204,14 @@ export async function crawl(session, opts, sleep) {
             });
         }
     }
+    // One more look, AFTER the clicks. The enumeration above happened before any of them, so anything
+    // the crawl itself unlocked — a dashboard behind a login, a modal's contents, a tab's panel — was
+    // never in `items` and never had a chance to be visited. Counted by ref against what was
+    // enumerated, so a control that merely moved or re-rendered under the same ref is not miscounted
+    // as new, and a surface that SHRANK (a modal closed) reports nothing, because nothing went
+    // unvisited. Skipped when the snapshot was already capped: that case has its own note and a second
+    // one would only muddy it.
+    const revealed = coverageCapped ? 0 : await countRevealed(session, opts, items);
     return {
         interactiveFound: items.length,
         stepsRun,
@@ -177,8 +221,12 @@ export async function crawl(session, opts, sleep) {
         // True when coverage was bounded for EITHER reason: the step budget ran out, or the page was
         // bigger than one snapshot. Conflating "I stopped early" with "I saw everything" is what turns a
         // partial sweep into "all controls healthy".
-        truncated: items.length > stepsRun || coverageCapped,
-        ...(coverageCapped ? { coverageNote: CAPPED_SNAPSHOT_NOTE } : {}),
+        truncated: items.length > stepsRun || coverageCapped || revealed > 0,
+        ...(coverageCapped
+            ? { coverageNote: CAPPED_SNAPSHOT_NOTE }
+            : revealed > 0
+                ? { coverageNote: revealedControlsNote(revealed) }
+                : {}),
         // A bare `stepsRun: 0` made "the page had no controls" and "it had 34 and none were clicked" the
         // same answer. See crawl-empty.
         ...(() => {

package/dist/events/contradictions.d.ts

@@ -1,4 +1,5 @@
 import { ContradictionKind, type ReticleEvent } from '@reticlehq/core';
+import { type DeclaredNetFailure } from './declared.js';
 /**
  * The contradiction hunter.
  *
@@ -35,6 +36,20 @@ export interface ContradictionOptions {
      * contain. See `findUnitMismatches` for the measured case this exists for.
      */
     prior?: readonly ReticleEvent[] | undefined;
+    /**
+     * Event time at which the action that opened this window was dispatched — the attribution floor.
+     *
+     * `duplicate-request` claims "one user action was performed", and that claim is only sound over ONE
+     * action's window. `reticle_observe` takes a caller-supplied window that can be arbitrarily wide, so
+     * two legitimate separate saves to the same endpoint read as a double submit — and the finding then
+     * sat on every verdict for that tab. Undefined means nothing attributed the window to an action, and
+     * the rule stays silent rather than accusing an app of something nobody can show it did.
+     *
+     * ponytail: a NET_REQUEST is stamped when it COMPLETED, so a write dispatched before the action and
+     * landing after it counts as inside. Keying on the matching NET_PENDING would fix that; it has not
+     * been worth the second index.
+     */
+    actionSince?: number | undefined;
     /**
      * DOM mutations observed INSIDE the target's own subtree, as the act tool measured them.
      *
@@ -49,5 +64,36 @@ export interface ContradictionOptions {
      * test, which is weaker but never wrong in the direction of a false accusation.
      */
     mutatedWithin?: number | undefined;
+    /**
+     * Requests the CALLER declared would fail, read off the oracle it wrote before acting.
+     *
+     * `ui-advanced-request-failed` cannot tell "the app swallowed the error and carried on" from "the
+     * app rendered the error, which is the behaviour under test" — both are a moved DOM beside a
+     * failed request. `failureAcknowledged` recovers the first from the app's own state, and an app
+     * that renders its error straight into the DOM without touching a store defeats it.
+     *
+     * The declaration is the missing evidence, and it costs no new API: an agent verifying an error
+     * path already writes `{ net, POST, /api/login, status: 500 }` into the predicate. Measured in the
+     * field: every branch of a login error path (500, 401, 503) passed every declared clause and every
+     * run still returned `verified: "no" / contradicted`, so error handling — empty states, offline
+     * banners, 4xx/5xx messaging, lockouts — was the code least able to reach a green verdict and the
+     * most worth verifying.
+     *
+     * Scoped as narrowly as it can be: it suppresses ONLY the heuristic rule that cannot see the
+     * difference. A success signal fired over the declared failure still contradicts, and a server
+     * fault blamed on the user is still misattributed — see the negative controls in
+     * `contradictions.declared.test.ts`.
+     */
+    expectedFailures?: readonly DeclaredNetFailure[] | undefined;
+    /**
+     * The caller declared an on-screen consequence and it HELD in this window.
+     *
+     * `route-rendered-nothing` infers a blank destination from the absence of DOM events, and a
+     * verdict that names it beside an element match — heading found, with its source file and line —
+     * is a clause its own evidence disproves. Positive evidence outranks the absence it is inferred
+     * from. Undefined/false leaves the rule exactly as it was, which is the case that catches a route
+     * with no view.
+     */
+    renderProved?: boolean | undefined;
 }
 export declare function findContradictions(allEvents: readonly ReticleEvent[], options?: ContradictionOptions): Contradiction[];