@reticlehq/server 2.8.0 → 2.10.0

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,7 +25,8 @@ 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, drivePortConflict, openInBrowser, openCommand, } 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';
@@ -220,17 +224,34 @@ async function handleRestart(port, force) {
     // 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;
@@ -243,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). */
@@ -318,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');
@@ -410,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
@@ -422,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),
                 }),
         });
     })
@@ -478,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.
@@ -572,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', {});
@@ -640,59 +688,6 @@ function handleMcp(opts) {
         });
     });
 }
-function handleLegacyDrive(parsed) {
-    void driveWithHonestConflict(parsed);
-}
-/**
- * Refuse the port BEFORE binding it, and name what is holding it.
- *
- * `drive` went straight to `start`, which binds. The listen error surfaces asynchronously on the
- * server object long after `start` has resolved, so the `.catch` on that promise could never see it
- * and the process died with the raw `node:net` EADDRINUSE stack — in the one situation this command
- * is most often run in, since `reticle_sessions` recommends `reticle drive` for a throttled tab and
- * a throttled tab nearly always coexists with the daemon holding the port.
- */
-async function driveWithHonestConflict(parsed) {
-    const presence = await probePresence(parsed.port, { tcpOpen: probeDaemon, status: fetchStatus });
-    const conflict = drivePortConflict(presence, parsed.port, { ourPid: readPid(parsed.port) });
-    if (conflict !== undefined) {
-        log('reticle_drive_port_conflict', { port: parsed.port, presence, reason: conflict });
-        process.stderr.write(`${conflict}\n`);
-        process.exit(1);
-        return;
-    }
-    // The probe cannot close the race: something can take the port between here and the bind, and the
-    // bind reports it on the server, outside every promise this function holds. Catching it at the
-    // process is the only place that sees it at all — and only EADDRINUSE, so a genuine crash still
-    // crashes rather than being dressed up as a port conflict. Who won the race is not knowable from
-    // in here, so the sentence used is the one that is true of any holder.
-    process.on('uncaughtException', (error) => {
-        const code = error?.code;
-        if ('EADDRINUSE' !== code)
-            throw error;
-        const reason = drivePortConflict(PortPresence.FOREIGN, parsed.port);
-        log('reticle_drive_port_conflict', {
-            port: parsed.port,
-            presence: PortPresence.FOREIGN,
-            reason,
-        });
-        process.stderr.write(`${String(reason)}\n`);
-        process.exit(1);
-    });
-    const options = {
-        port: parsed.port,
-        driveUrl: parsed.driveUrl,
-        headless: parsed.headless,
-    };
-    try {
-        await start(options);
-        log('reticle_started', { port: parsed.port });
-    }
-    catch (error) {
-        log('reticle_start_failed', { error: error instanceof Error ? error.message : String(error) });
-        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.
@@ -782,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.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

@@ -1,4 +1,5 @@
 import { ContradictionKind, type ReticleEvent } from '@reticlehq/core';
+import { type DeclaredNetFailure } from './declared.js';
 /**
  * The contradiction hunter.
  *
@@ -18,7 +19,16 @@ import { ContradictionKind, type ReticleEvent } from '@reticlehq/core';
  * 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. */
@@ -26,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;
@@ -63,5 +82,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[];

package/dist/events/contradictions.js

@@ -4,6 +4,8 @@ import { findBodyFailures } from './body-failures.js';
 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 {
@@ -171,7 +173,7 @@ export function findContradictions(allEvents, options = {}) {
     // Needs body capture; silent without it, which is why the assert path also declares when bodies
     // were never recorded rather than letting an unread payload read as an empty one.
     found.push(...findBodyFailures(events));
-    found.push(...findEchoMismatches(events));
+    found.push(...findEchoMismatches(events, options.actionSince));
     // ── A money value written back at the wrong SCALE ───────────────────────────────────────────
     found.push(...findUnitMismatches(events, options.prior ?? []));
     // ── The action landed on something that does not react ──────────────────────────────────────
@@ -192,6 +194,9 @@ export function findContradictions(allEvents, options = {}) {
         ];
     }
     const failed = settled.filter((c) => false === c.ok);
+    // The failures NOBODY declared — see ContradictionOptions.expectedFailures. Only the heuristic
+    // "the UI moved while a request failed" rule reads this; the sharp rules still read `failed`.
+    const unexpected = failed.filter((c) => !matchesDeclaredFailure(c, options.expectedFailures ?? []));
     const advanced = uiAdvanced(events);
     const signals = events
         .filter((e) => e.type === EventType.SIGNAL)
@@ -215,7 +220,7 @@ export function findContradictions(allEvents, options = {}) {
         e.type === EventType.DOM_REMOVED ||
         e.type === EventType.DOM_TEXT);
     const fetched = events.some((e) => e.type === EventType.NET_REQUEST || e.type === EventType.NET_PENDING);
-    if (routed && !rendered && !fetched) {
+    if (routed && !rendered && !fetched && true !== options.renderProved) {
         found.push({
             kind: ContradictionKind.ROUTE_RENDERED_NOTHING,
             claim: 'the app navigated to a new route',
@@ -251,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(', ')}`,
@@ -259,12 +276,12 @@ export function findContradictions(allEvents, options = {}) {
             detail: failed.map(describe).join('; '),
         });
     }
-    else if (failed.length > 0 && advanced && !misattributed && !failureAcknowledged(events)) {
+    else if (unexpected.length > 0 && advanced && !misattributed && !failureAcknowledged(events)) {
         found.push({
             kind: ContradictionKind.UI_ADVANCED_REQUEST_FAILED,
             claim: 'the UI moved forward (DOM/store/route changed)',
-            counter: `${String(failed.length)} request(s) in the same window failed`,
-            detail: failed.map(describe).join('; '),
+            counter: `${String(unexpected.length)} request(s) in the same window failed`,
+            detail: unexpected.map(describe).join('; '),
         });
     }
     // ── A write succeeded and nothing on the client moved ───────────────────────────────────────
@@ -337,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/declared.d.ts

@@ -0,0 +1,45 @@
+/**
+ * What the caller DECLARED before acting — the oracle, read back.
+ *
+ * `act_and_wait` asks the agent to name the expected consequence BEFORE the action, and that
+ * declaration was then thrown away: everything downstream judged the window as if nobody had said
+ * what they were expecting. Two measured consequences, one bug:
+ *
+ *  - An error path can be declared exactly — `{ net, POST, /api/login, status: 500 }` — and the
+ *    contradiction hunter still reported `ui-advanced-request-failed`, because a failed request plus
+ *    a moved DOM is all it can see. The failure was EXPECTED and said so in the predicate, so a
+ *    verdict of "channels disagree" is a statement about a disagreement nobody had.
+ *  - A destination whose content was asserted and FOUND was still reported as
+ *    `route-rendered-nothing`, a clause the element evidence beside it disproves.
+ *
+ * Deliberately conservative about what counts as declared. Only what the caller REQUIRED is read:
+ * the top level and `allOf` chains. An `anyOf` branch may never have held, and a `not` declares the
+ * opposite of a consequence — honouring either would suppress a real finding on the strength of
+ * something that never happened. Pure: a predicate in, a description out.
+ */
+import type { Predicate } from './predicate-eval.js';
+/** A failing call the caller named in advance — matched against the window's real calls. */
+export interface DeclaredNetFailure {
+    method?: string;
+    urlContains?: string;
+    status?: number;
+}
+export interface DeclaredExpectations {
+    /** Requests the caller declared would FAIL, so failing is the expected outcome, not a disagreement. */
+    netFailures: readonly DeclaredNetFailure[];
+    /** The caller required something to be ON SCREEN — an element or text, present rather than absent. */
+    rendersContent: boolean;
+}
+export declare function declaredExpectations(predicate: Predicate | undefined): DeclaredExpectations;
+/**
+ * Does a call the window recorded match a failure the caller declared?
+ *
+ * Every field the caller named must agree — a declaration about `POST /api/login → 500` says nothing
+ * about `POST /api/orders`, and treating it as a blanket amnesty for failed requests would remove
+ * the check rather than inform it. Fields the caller left out are not constraints.
+ */
+export declare function matchesDeclaredFailure(call: {
+    method: string;
+    url: string;
+    status: number | undefined;
+}, declared: readonly DeclaredNetFailure[]): boolean;