@reticlehq/server 2.11.0 → 2.13.0

package/dist/cloud/sync-daemon.js

@@ -0,0 +1,260 @@
+/**
+ * Automatic sync, for the session nobody thinks about.
+ *
+ * Somebody runs Reticle all morning. Every tool call rewrites the impact record; every verification
+ * writes a run. If sync is a command a human types, the dashboard is stale for exactly as long as
+ * they are busy — which is precisely when the numbers on it would have been worth looking at.
+ *
+ * So the daemon does it. Not a new process, not a thing to remember: the daemon is already running
+ * for the whole session (it is what the agent talks to), so it is the only place where "sync while
+ * work is happening" costs nobody anything.
+ *
+ * ── THE THREE RULES THAT KEEP IT INVISIBLE ────────────────────────────────────────────────────
+ * QUIET WHEN IDLE. A cycle on an unchanged session is one small GET and nothing else. That is what
+ * makes a one-minute timer affordable; it is also why the timer is not adaptive — a scheme that
+ * "backs off when idle" is complexity paid for a cost that is already near zero.
+ *
+ * NEVER IN THE WAY. Nothing here is awaited by a tool call. A sync that can slow down or fail a
+ * verification would be a sync worth switching off, and the local record is authoritative anyway.
+ *
+ * SILENT UNLESS IT MATTERS. A failed cycle is logged once per NEW error, not once per minute: a
+ * laptop on a train would otherwise fill the log with the same line four hundred times and teach
+ * everyone to ignore it.
+ */
+import { log } from '../log.js';
+import { describeSync, runSyncCycle } from './sync-cycle.js';
+import { diskSink, diskSource, readCloudState } from './sync-disk.js';
+/** How often the daemon cycles. See the note above on why this is a constant and not a curve. */
+export const DAEMON_SYNC_INTERVAL_MS = 60_000;
+/**
+ * The cadence while something is actually happening.
+ *
+ * A fixed minute is the wrong shape for both states it has to cover. During a drive the ledger
+ * changes on every tool call and a minute of lag is what makes a dashboard feel dead; idle, a minute
+ * is already more often than nothing has changed deserves.
+ *
+ * So the interval follows the work: a cycle that MOVED something earns the fast rate, a cycle that
+ * moved nothing backs off to the slow one. No session plumbing and no new configuration — activity
+ * is inferred from what the last cycle actually sent, which is the only honest evidence available.
+ *
+ * Deliberately not per-tool-call. A push in the tool path would put the network in the agent's inner
+ * loop, and verification working with the network down is a promise this product makes.
+ */
+export const DAEMON_SYNC_ACTIVE_INTERVAL_MS = 5_000;
+/** Given to the first cycle so a freshly-started daemon does not race the session that woke it. */
+const FIRST_CYCLE_DELAY_MS = 5_000;
+/**
+ * How long a nudge waits before cycling.
+ *
+ * Long enough to COALESCE — a battery that writes six runs in a second must cause one cycle, not
+ * six — and short enough that finishing a verification and looking at the dashboard feels like one
+ * action. Not zero: a run artifact is renamed into place and the sibling records it implies are
+ * written just after, so cycling on the very first byte would ship a bundle that is missing them.
+ */
+const NUDGE_DELAY_MS = 1_500;
+const defaultRequest = async (url, init) => {
+    const res = await fetch(url, init);
+    return { status: res.status, text: await res.text() };
+};
+/**
+ * Start the loop. Safe to call for an UNLINKED project: it resolves the link on every tick and does
+ * nothing until one appears, which is what lets `reticle link` take effect without a restart.
+ */
+export function startSyncDaemon(deps) {
+    const intervalMs = deps.intervalMs ?? DAEMON_SYNC_INTERVAL_MS;
+    // Never slower than the idle rate: a deployment that lengthens the interval means "sync less", and
+    // an active burst must not quietly re-introduce the cost it was lowering.
+    const activeIntervalMs = Math.min(DAEMON_SYNC_ACTIVE_INTERVAL_MS, intervalMs);
+    const now = deps.now ?? (() => Date.now());
+    const request = deps.request ?? defaultRequest;
+    let timer;
+    let stopped = false;
+    let running = false;
+    /** The last error already reported. Repeats are swallowed so an offline laptop stays quiet. */
+    let reportedError;
+    /**
+     * Whether the last cycle found a link — undefined until the first one has looked.
+     *
+     * An unlinked project used to sync nothing and say nothing, which is indistinguishable from a
+     * working sync until somebody notices the dashboard is hours behind. Observed for real: the
+     * daemon was started from a sibling repo that had never been linked, so every call for an entire
+     * session was recorded into THAT repo's ledger and pushed nowhere, and the first evidence was a
+     * stale number on a dashboard nobody had reason to distrust.
+     *
+     * Announced on the FIRST cycle and on every change after it, so `reticle link` mid-session says
+     * so too. Once per transition, never per tick — a line every minute is a line people stop reading.
+     */
+    let wasLinked;
+    /** One root's bundle. The state, source and sink are already per-root; only the caller was not. */
+    const pushRoot = async (root, cloud) => {
+        if (null === cloud.config)
+            return undefined;
+        const full = diskSource(root);
+        return runSyncCycle({
+            config: cloud.config,
+            source: {
+                runs: () => (cloud.policy.runs ? full.runs() : []),
+                flows: () => (cloud.policy.flows ? full.flows() : []),
+                derived: (kind) => (cloud.policy.memory ? full.derived(kind) : undefined),
+            },
+            sink: diskSink(root),
+            state: readCloudState(root),
+            now,
+            request,
+        });
+    };
+    /**
+     * Push every other linked root this machine knows about.
+     *
+     * Isolated per root on purpose. A revoked credential, a deleted directory or an unreachable
+     * self-hosted server in ONE repo is a fact about that repo; letting it throw would take the
+     * daemon's own push down with it and turn one broken link into a machine-wide outage.
+     */
+    const syncOtherRoots = async () => {
+        const roots = deps.otherRoots;
+        const cloudFor = deps.cloudFor;
+        if (roots === undefined || cloudFor === undefined)
+            return;
+        let list = [];
+        try {
+            list = await roots();
+        }
+        catch {
+            // Enumeration is best-effort: a registry that cannot be read must not stop this daemon
+            // syncing the root it is standing in.
+            return;
+        }
+        for (const root of list) {
+            if (root === deps.reticleRoot)
+                continue;
+            try {
+                const cloud = await cloudFor(root);
+                if (null === cloud.config)
+                    continue;
+                const report = await pushRoot(root, cloud);
+                if (report === undefined)
+                    continue;
+                if (report.error !== undefined) {
+                    log('reticle_cloud_sync_failed', { root, error: report.error });
+                    continue;
+                }
+                const moved = report.runsSent > 0 ||
+                    report.flowsSent > 0 ||
+                    report.derivedSent.length > 0 ||
+                    report.pulled > 0;
+                // The root is NAMED here and not in the single-root log below, because with several repos
+                // reporting, "synced 3 runs" without a directory is not an answer to "synced from where".
+                if (moved)
+                    log('reticle_cloud_synced', { root, summary: describeSync(report) });
+            }
+            catch (error) {
+                log('reticle_cloud_sync_failed', {
+                    root,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    };
+    const cycle = async () => {
+        // Overlap guard: a slow cycle must not have a second one started on top of it, or two bundles
+        // race and the cursor written by the loser silently rewinds the winner's progress.
+        if (running)
+            return undefined;
+        running = true;
+        try {
+            const cloud = await deps.cloud();
+            const linked = null !== cloud.config;
+            if (linked !== wasLinked) {
+                wasLinked = linked;
+                if (linked)
+                    log('reticle_cloud_linked', {
+                        projectId: cloud.projectId,
+                        root: deps.reticleRoot,
+                    });
+                // Names the ROOT, because the answer is almost always "the daemon is not where you think it
+                // is" — and a message that omits the directory sends people to check their key instead.
+                else
+                    log('reticle_cloud_unlinked', {
+                        root: deps.reticleRoot,
+                        fix: 'run `reticle link` in this directory, or start the daemon in the linked one — nothing is being synced from here',
+                    });
+            }
+            // Every OTHER linked root, first. Their failures are logged and never abort this daemon's own
+            // push: one repo whose credential was revoked must not silence the rest of the machine.
+            await syncOtherRoots();
+            if (null === cloud.config)
+                return undefined;
+            const report = await pushRoot(deps.reticleRoot, cloud);
+            // `pushRoot` returns undefined only for an unlinked root, which the guard above has ruled out.
+            if (report === undefined)
+                return undefined;
+            if (report.error !== undefined) {
+                if (report.error !== reportedError) {
+                    reportedError = report.error;
+                    log('reticle_cloud_sync_failed', { error: report.error });
+                }
+            }
+            else {
+                reportedError = undefined;
+                // Only when something actually moved. A per-minute "nothing to send" is noise that trains
+                // people to stop reading the log.
+                const moved = report.runsSent > 0 ||
+                    report.flowsSent > 0 ||
+                    report.derivedSent.length > 0 ||
+                    report.pulled > 0;
+                if (moved)
+                    log('reticle_cloud_synced', { summary: describeSync(report) });
+                /*
+                 * A cycle that moved something means a drive is in progress, so the next one comes sooner;
+                 * one that moved nothing means the machine is idle, so it backs straight off. The rate
+                 * follows the work without needing to be told about sessions, and an idle laptop settles at
+                 * the same cost it had before this existed.
+                 */
+                nextDelay = moved ? activeIntervalMs : intervalMs;
+            }
+            return report;
+        }
+        catch (error) {
+            // Belt and braces: runSyncCycle already swallows, and a throw here would kill the timer.
+            const message = error instanceof Error ? error.message : String(error);
+            if (message !== reportedError) {
+                reportedError = message;
+                log('reticle_cloud_sync_failed', { error: message });
+            }
+            return undefined;
+        }
+        finally {
+            running = false;
+        }
+    };
+    /** The delay for the NEXT cycle: fast while the last one moved something, slow once it stops. */
+    let nextDelay = intervalMs;
+    const schedule = (delay) => {
+        if (stopped)
+            return;
+        // Replace, never stack. `nudge` and the interval both schedule, and leaving the old timer armed
+        // would let every nudge add a permanent extra cycle per minute for the life of the process.
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            void cycle().finally(() => schedule(nextDelay));
+        }, delay);
+        // Unref'd: a pending sync must never be the reason a process refuses to exit.
+        timer.unref?.();
+    };
+    schedule(FIRST_CYCLE_DELAY_MS);
+    return {
+        syncNow: cycle,
+        nudge: () => {
+            // A cycle already in flight will not pick this up, so the nudge is still scheduled behind it
+            // rather than dropped — otherwise the run that arrived during a slow cycle waits a full tick.
+            schedule(NUDGE_DELAY_MS);
+        },
+        stop: () => {
+            stopped = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+        },
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { CloudSyncState, PulledIssues, SyncSink, SyncSource } from './sync-cycle.js';
+/** What the cycle reads, backed by a real `.reticle` directory. */
+export declare function diskSource(reticleRoot: string): SyncSource;
+/** What the cycle writes back into `.reticle/`. */
+export declare function diskSink(reticleRoot: string): SyncSink;
+/** This machine's side of the conversation, or a blank one on first run. */
+export declare function readCloudState(reticleRoot: string): CloudSyncState;
+/** The decisions pulled back from the dashboard, for the HUD and for the next run to read. */
+export declare function readCloudIssues(reticleRoot: string): PulledIssues;

package/dist/cloud/sync-disk.js

@@ -0,0 +1,191 @@
+/**
+ * The filesystem half of a sync cycle: what `.reticle/` looks like to the protocol.
+ *
+ * Kept apart from `sync-cycle.ts` on purpose. The cycle is the interesting part — what to send, what
+ * to skip, what to do when the network is down — and it stays provable only because it never touches
+ * a disk. This is the boring part, and boring is what it should be: read a file, tolerate its
+ * absence, never throw.
+ *
+ * EVERY READ IS FORGIVING. A half-written impact.json from a process that died mid-flush must cost
+ * one unsynced record, not a crashed sync. There is no state here worth defending against a parse
+ * error — the file will be rewritten on the next tool call anyway.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+import { subjectFor } from '../intent/intent-subject.js';
+const JSON_SUFFIX = '.json';
+/** Read + parse, or undefined for absent/unreadable/malformed. Never throws. */
+function readJson(path) {
+    try {
+        return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Write atomically. tmp + rename, because two daemons can serve one repo at once and a half-written
+ * cursor file is one the next read discards — which would silently re-pull the whole decision
+ * history, or worse, skip it.
+ */
+function writeJson(path, value) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.${String(process.pid)}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+        renameSync(tmp, path);
+    }
+    catch {
+        // Bookkeeping that cannot be written must never break a sync. The next cycle re-derives it; the
+        // worst case is one redundant upload, which the server dedupes anyway.
+    }
+}
+/** Every `*.json` directly inside a directory, parsed. Absent directory reads as empty. */
+function readJsonDir(dir) {
+    try {
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir)
+            .filter((f) => f.endsWith(JSON_SUFFIX))
+            .map((f) => readJson(join(dir, f)))
+            .filter((v) => v !== undefined);
+    }
+    catch {
+        return [];
+    }
+}
+/** Flows live one directory deeper, under the app's own project id. */
+function readFlows(root) {
+    const dir = join(root, ReticleDir.FLOWS_SUBDIR);
+    try {
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir).flatMap((scope) => readJsonDir(join(dir, scope)));
+    }
+    catch {
+        return [];
+    }
+}
+const DERIVED_FILE = {
+    impact: ReticleDir.IMPACT_FILE,
+    flake: ReticleDir.FLAKE_FILE,
+    intent: ReticleDir.INTENT_FILE,
+};
+/** The directory the sharded intent store writes into, beside the legacy flat file. */
+const INTENT_SUBDIR = 'intent';
+const INTENT_INDEX = 'index.json';
+/**
+ * Every intent this project holds, flat file and shards merged.
+ *
+ * The store was split into one file per subject so that writing one record stops rewriting all of
+ * them. Sync was not told, and kept reading `intent.json` alone — which the migration deliberately
+ * does not delete. The result was the worst shape a sync bug can take: not an error, but a corpus
+ * that looked healthy on the dashboard and had silently stopped moving, because every intent
+ * captured after the migration stayed on the engineer's laptop.
+ *
+ * Shards WIN on a collision, matching the store's own rule: an id present in both has been migrated
+ * and possibly edited since, and letting the flat copy overwrite that would revert the edit on every
+ * cycle. `index.json` is derived from the shards and is skipped — sending it would duplicate every
+ * record as a summary of itself.
+ *
+ * Returns undefined when there is no memory at all, so a project with nothing to say sends nothing
+ * rather than an empty envelope the server has to store.
+ */
+function readIntent(reticleRoot) {
+    const legacy = readJson(join(reticleRoot, ReticleDir.INTENT_FILE));
+    const merged = {
+        ...(legacy?.intents ?? {}),
+    };
+    let shards = 0;
+    for (const file of safeReaddir(join(reticleRoot, INTENT_SUBDIR))) {
+        if (!file.endsWith(JSON_SUFFIX) || INTENT_INDEX === file)
+            continue;
+        const shard = readJson(join(reticleRoot, INTENT_SUBDIR, file));
+        // A hand-edited or half-written shard costs one subject, never the whole sync.
+        if (shard?.intents === undefined)
+            continue;
+        shards++;
+        for (const [id, record] of Object.entries(shard.intents))
+            merged[id] = record;
+    }
+    if (legacy === undefined && 0 === shards)
+        return undefined;
+    /*
+     * Stamp the SUBJECT before sending, on anything that does not already carry one.
+     *
+     * The subject ladder lives here, in the engine, and knows how to read a flow, a route and a
+     * binding predicate. The server had no access to it and had reimplemented a far weaker version —
+     * flow-or-nothing — so records this ladder files correctly arrived at the dashboard as
+     * `unsorted`. Measured on the real corpus: 105 of 163 records the engine can place were landing
+     * in the bucket of last resort, which is what made a coverage map read as one pile with six
+     * labels.
+     *
+     * Computed HERE rather than duplicated there, because two rules for one question is how the
+     * answers start disagreeing — and the one with the evidence should be the one that decides.
+     * Records that already name a subject keep it: an agent's explicit choice outranks inference.
+     */
+    const placed = Object.fromEntries(Object.entries(merged).map(([id, record]) => {
+        const held = record;
+        if ('string' === typeof held.subject && held.subject.length > 0)
+            return [id, record];
+        const subject = subjectFor({
+            surface: held.surface,
+            binding: held.binding,
+        });
+        return [id, { ...held, subject }];
+    }));
+    return { version: 1, intents: placed };
+}
+/** Directory listing that tolerates absence — an unmigrated project has no `intent/`. */
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** What the cycle reads, backed by a real `.reticle` directory. */
+export function diskSource(reticleRoot) {
+    return {
+        runs: () => readJsonDir(join(reticleRoot, ReticleDir.RUNS_SUBDIR))
+            .map((payload) => {
+            const id = payload?.runId;
+            return 'string' === typeof id ? { runId: id, payload } : undefined;
+        })
+            // A run artifact with no id cannot be diffed against the server's list, so sending it would
+            // mean re-sending it every cycle forever. Dropped rather than uploaded repeatedly.
+            .filter((r) => r !== undefined),
+        flows: () => readFlows(reticleRoot),
+        // Intent is the only derived record that is no longer one file. See readIntent.
+        derived: (kind) => 'intent' === kind ? readIntent(reticleRoot) : readJson(join(reticleRoot, DERIVED_FILE[kind])),
+    };
+}
+/** What the cycle writes back into `.reticle/`. */
+export function diskSink(reticleRoot) {
+    return {
+        writeIssues: (issues) => {
+            // MERGED, not replaced. A pull returns only what changed since the cursor, so overwriting
+            // would drop every earlier decision the moment one new decision arrived.
+            const held = readCloudIssues(reticleRoot);
+            writeJson(join(reticleRoot, ReticleDir.ISSUES_FILE), {
+                triage: { ...held.triage, ...issues.triage },
+            });
+        },
+        writeState: (state) => {
+            writeJson(join(reticleRoot, ReticleDir.CLOUD_STATE_FILE), state);
+        },
+    };
+}
+/** This machine's side of the conversation, or a blank one on first run. */
+export function readCloudState(reticleRoot) {
+    const raw = readJson(join(reticleRoot, ReticleDir.CLOUD_STATE_FILE));
+    return 'object' === typeof raw && null !== raw ? raw : {};
+}
+/** The decisions pulled back from the dashboard, for the HUD and for the next run to read. */
+export function readCloudIssues(reticleRoot) {
+    const raw = readJson(join(reticleRoot, ReticleDir.ISSUES_FILE));
+    const triage = 'object' === typeof raw && null !== raw ? raw.triage : undefined;
+    return { triage: 'object' === typeof triage && null !== triage ? triage : {} };
+}

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

@@ -0,0 +1,2 @@
+/** A stable content hash of one derived record. Must equal the server's for the same input. */
+export declare function hashPayload(payload: unknown): string;

package/dist/cloud/sync-hash.js

@@ -0,0 +1,35 @@
+/**
+ * The content hash both halves of sync compare on.
+ *
+ * The server answers "here is a hash per record you have already sent me"; the machine hashes what
+ * it holds and sends only what differs. That only works if the two sides compute the SAME number
+ * from the same record, so this function is a CONTRACT, not a utility — it has to stay byte-for-byte
+ * equivalent to the server's, and it is separated out and tested against fixed vectors for exactly
+ * that reason.
+ *
+ * Keys are sorted before serialising because two structurally identical records must hash the same
+ * however they happened to be written out. Without that, a machine whose JSON key order differed
+ * from the server's would re-upload the same unchanged record on every cycle, forever, and the whole
+ * point of hashing — not paying for what has not moved — would be lost silently.
+ */
+import { createHash } from 'node:crypto';
+/** How much of the digest is kept. Long enough that a collision is not a practical concern here. */
+const HASH_LENGTH = 32;
+/** Recursively sort object keys so serialisation is canonical. Arrays keep their order — it is data. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value !== null && 'object' === typeof value) {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => [k, canonical(v)]));
+    }
+    return value;
+}
+/** A stable content hash of one derived record. Must equal the server's for the same input. */
+export function hashPayload(payload) {
+    return createHash('sha256')
+        .update(JSON.stringify(canonical(payload)))
+        .digest('hex')
+        .slice(0, HASH_LENGTH);
+}

package/dist/crawl/crawl-tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
+import { stepCountSchema, timeoutMsSchema } from '../tools/numeric-bounds.js';
 import { crawl } from './crawl.js';
 import { routeFromUrl, routesFromEvents } from '../project/learned-routes.js';
 const nodeSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -14,9 +15,10 @@ 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. 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
-                .number()
+            maxSteps: stepCountSchema
+                .optional()
+                .describe('Maximum number of controls to click. Default: 25.'),
+            settleMs: timeoutMsSchema
                 .optional()
                 .describe('Milliseconds to wait after each click for the app to react. Default: 500.'),
             scope: z

package/dist/crawl/crawl.d.ts

@@ -4,6 +4,18 @@ export interface CrawlSession {
     command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
     elapsed(): number;
     eventsSince(cursor: number): ReticleEvent[];
+    /**
+     * Which document is on screen now, so a finding is never drawn from a page the crawl has already
+     * navigated away from. Optional for the same reason `beginAction` is: a test fake supplies a
+     * minimal session, and its absence leaves the scoping inert rather than broken.
+     */
+    readonly currentDocumentId?: string | undefined;
+    /** Which round of source edits is in force, so a finding drawn entirely from pre-edit evidence
+     *  says so. Optional for the same reason `currentDocumentId` is. */
+    readonly currentEditEpoch?: number | undefined;
+    /** The page under test, so a third-party beacon cannot be reported against a control. Optional
+     *  for the same reason `currentDocumentId` is. */
+    readonly url?: string | undefined;
     /**
      * Attribution window around each click. Optional so a caller can supply a minimal session, but a real
      * session MUST provide it: without a window the click's own effects carry no actionId, and an
@@ -44,19 +56,6 @@ 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

@@ -18,7 +18,7 @@ export const CAPPED_SNAPSHOT_NOTE = 'the page exceeded one snapshot, so controls
  * 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) {
+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');
@@ -65,7 +65,19 @@ export function legitimatelyInert(desc) {
         return true;
     if (desc.includes('[checked]'))
         return true;
-    return /\b(textbox|searchbox|combobox|spinbutton)\b/.test(desc);
+    // Inputs, and the ARIA LIVE-REGION roles.
+    //
+    // `alert`, `status`, `log`, `timer` and `marquee` exist to be READ — a screen reader announces
+    // them and nothing is meant to happen when one is clicked. Clicking twice and seeing nothing is
+    // therefore correct behaviour, and reporting it as `dead-control` accuses a working app.
+    //
+    // Found by driving a real app: the demo reported `dead-control — alert "Invalid email or
+    // password"`, which is a login form correctly telling somebody their password was wrong. That is
+    // the most expensive kind of false positive there is — the strongest claim the crawler makes,
+    // about an app that was working, and on the path a new user meets first.
+    //
+    // `alertdialog` is deliberately NOT here: it is interactive, and a word boundary keeps it out.
+    return /\b(textbox|searchbox|combobox|spinbutton|alert|status|log|timer|marquee)\b/.test(desc);
 }
 /**
  * How many interactive controls exist now that did not exist when the crawl enumerated.
@@ -199,7 +211,17 @@ export async function crawl(session, opts, sleep) {
         }
         // 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)) {
+        // A crawl clicks controls that navigate, so its windows are the ones most likely to straddle a
+        // document boundary — and a finding here is reported against a specific control by name.
+        for (const c of findContradictions(events, {
+            currentDocumentId: session.currentDocumentId,
+            currentEditEpoch: session.currentEditEpoch,
+            appOrigin: session.url,
+            // The crawl's window IS one control's click, so it can name the floor the consequence rules
+            // need — without it a crawl would report nothing about the UI moving, which is most of what a
+            // crawl is for.
+            actionSince: since,
+        })) {
             counts.contradictions += 1;
             anomalies.push({
                 kind: c.kind,