@reticlehq/server 2.6.0 → 2.8.0

package/dist/cli.js

@@ -22,10 +22,12 @@ 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, drivePortConflict, openInBrowser, openCommand, } from './cli/cli-launch.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 +40,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 +48,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);
@@ -132,6 +140,10 @@ async function serveWithHonestExit(parsed) {
 /** How long `serve` waits for the child to bind. Generous: a cold daemon start is seconds. */
 const SERVE_BIND_TIMEOUT_MS = 15_000;
 const PRESENCE_POLL_MS = 150;
+/** How long a daemon gets to shut down on its own before `stop` stops asking politely. */
+const GRACEFUL_STOP_MS = 5000;
+/** How long after SIGKILL before we accept the process is not ours to kill and say so. */
+const FORCED_STOP_MS = 2000;
 async function waitForPresence(port, want, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     for (;;) {
@@ -153,22 +165,61 @@ function handleStop(port, quiet) {
     }
     process.kill(pid, 'SIGTERM');
     const started = Date.now();
+    let escalated = false;
     const poll = setInterval(() => {
         if (!isAlive(pid)) {
             clearInterval(poll);
             removePid(port);
             if (!quiet)
-                log('reticle_daemon_stopped', { port, pid });
+                log('reticle_daemon_stopped', { port, pid, ...(escalated ? { escalated } : {}) });
+            return;
+        }
+        const waited = Date.now() - started;
+        // A daemon that ignores SIGTERM is WEDGED — which is the one situation `stop` exists for. Giving
+        // up here left the port held, the pid file stale, and a human running `kill -9` by hand at the
+        // first two minutes of setup. Escalate instead: graceful first, then unconditional.
+        if (!escalated && waited > GRACEFUL_STOP_MS) {
+            escalated = true;
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // Already gone between the liveness check and here — the next tick reports it stopped.
+            }
             return;
         }
-        if (Date.now() - started > 5000) {
+        if (waited > GRACEFUL_STOP_MS + FORCED_STOP_MS) {
             clearInterval(poll);
+            // Surviving SIGKILL means the pid is not ours to kill (permissions) or is an unkillable
+            // zombie. Neither is retryable, and both need the pid named so a human can act on it.
             if (!quiet)
-                log('reticle_daemon_stop_timeout', { port, pid });
+                log('reticle_daemon_stop_timeout', { port, pid, escalated });
             process.exit(1);
         }
     }, 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 });
+}
 function handleStatus(port) {
     const pid = readPid(port);
     if (null === pid || !isAlive(pid)) {
@@ -343,8 +394,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;
@@ -360,11 +415,21 @@ function handleOpen(requestedPort, url) {
             ...(connected
                 ? {}
                 : {
-                    note: 'the browser was launched but no Reticle session appeared. The app may still be ' +
-                        'loading, or it is not wired to this bridge — run `reticle doctor`, and check the ' +
-                        'app connects on port ' +
-                        String(port) +
-                        '.',
+                    // Two claims used to live here that this command cannot support. It said the browser
+                    // "was launched" — it asked the OS to open a URL and cannot see whether a window
+                    // appeared — and it offered "the app may still be loading" as a cause with equal
+                    // weight to the real one. It then pointed at `reticle doctor`, whose Chromium check is
+                    // 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.`,
                 }),
         });
     })
@@ -420,7 +485,7 @@ function handleDaemonInner(parsed) {
                 // The reason rides out on the session summary, which is the only event that fires at this
                 // exact moment. The proxy emits the matching `mcp_connection_lost` and cannot know it —
                 // it sees a socket end and nothing more, which is how a scheduled idle exit came to make up
-                // 299 of 321 "outages". See SessionSummary.exit.
+                // the large majority of "outages". See SessionSummary.exit.
                 .shutdown(reason)
                 .then(() => server.close())
                 .then(() => {
@@ -529,8 +594,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.
     //
@@ -571,20 +641,57 @@ 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,
     };
-    start(options)
-        .then(() => {
+    try {
+        await start(options);
         log('reticle_started', { port: parsed.port });
-    })
-        .catch((error) => {
-        const message = error instanceof Error ? error.message : String(error);
-        log('reticle_start_failed', { error: message });
+    }
+    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
@@ -638,6 +745,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;

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/daemon/daemon-resilience.js

@@ -42,8 +42,8 @@ const DISCONNECT_CODES = new Set([
 /**
  * Nobody went away — nobody was ever there. A refused connect is the daemon not being up YET.
  *
- * This is the difference that made `runtime_crashed` useless. Measured 2026-08-10/11: **84 of 84
- * crash events were one fingerprint, `connect ECONNREFUSED`, and every affected user was in the
+ * This is the difference that made `runtime_crashed` useless. In the field **every crash event
+ * carried one fingerprint, `connect ECONNREFUSED`, and every affected user was in the
  * never-verified set.** The proxy is BUILT to tolerate this — it answers the handshake from cache
  * and wakes a daemon on the next request — so reporting it as a crash meant the one metric that is
  * supposed to say "Reticle broke" said nothing but "the daemon had not booted yet", and a real crash

package/dist/daemon/loopback-alias.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Serve the IPv4-bound daemon on IPv6 loopback too, so `localhost` reaches it on every platform.
+ *
+ * The daemon binds `127.0.0.1` — deliberately, because Reticle must never be reachable off-host. But
+ * `localhost` is a NAME, and on Windows Chrome resolves it to `::1` before `127.0.0.1`. The SDK's
+ * default bridge URL says `localhost`. So on the platform that is most of our installs, and the
+ * browser that is most of that, the documented default cannot connect — and the error text names the
+ * daemon, containers and WSL, none of which is the cause.
+ *
+ * This is a byte forwarder rather than a second `http.Server` on purpose. The daemon speaks HTTP,
+ * WebSocket upgrades and SSE on one port; copying request/upgrade wiring onto a second server means a
+ * second place to keep in sync, and the first handler anybody forgets to mirror becomes a bug that
+ * only Windows sees. A TCP pipe carries all three and cannot drift from what it forwards.
+ *
+ * Best-effort by contract: a machine with IPv6 disabled, or something already holding `[::1]:port`,
+ * leaves the daemon exactly as it was before. Never fatal — this widens reachability, it is not a
+ * precondition for serving.
+ */
+/** IPv6 loopback. The other half of what `localhost` can mean. */
+export declare const IPV6_LOOPBACK = "::1";
+export interface LoopbackAlias {
+    /** False when the alias could not be bound — the daemon still serves IPv4 as before. */
+    opened: boolean;
+    close: () => Promise<void>;
+}
+/**
+ * Accept on `[::1]:port` and pipe each connection to `127.0.0.1:port`.
+ *
+ * Both ends are loopback, so a forwarded peer is still a loopback peer and the bridge's loopback
+ * trust holds — the alias does not widen who may connect, only which address they may name.
+ */
+export declare function openLoopbackAlias(port: number): Promise<LoopbackAlias>;

package/dist/daemon/loopback-alias.js

@@ -0,0 +1,80 @@
+/**
+ * Serve the IPv4-bound daemon on IPv6 loopback too, so `localhost` reaches it on every platform.
+ *
+ * The daemon binds `127.0.0.1` — deliberately, because Reticle must never be reachable off-host. But
+ * `localhost` is a NAME, and on Windows Chrome resolves it to `::1` before `127.0.0.1`. The SDK's
+ * default bridge URL says `localhost`. So on the platform that is most of our installs, and the
+ * browser that is most of that, the documented default cannot connect — and the error text names the
+ * daemon, containers and WSL, none of which is the cause.
+ *
+ * This is a byte forwarder rather than a second `http.Server` on purpose. The daemon speaks HTTP,
+ * WebSocket upgrades and SSE on one port; copying request/upgrade wiring onto a second server means a
+ * second place to keep in sync, and the first handler anybody forgets to mirror becomes a bug that
+ * only Windows sees. A TCP pipe carries all three and cannot drift from what it forwards.
+ *
+ * Best-effort by contract: a machine with IPv6 disabled, or something already holding `[::1]:port`,
+ * leaves the daemon exactly as it was before. Never fatal — this widens reachability, it is not a
+ * precondition for serving.
+ */
+import net from 'node:net';
+import { LOOPBACK_HOST } from '@reticlehq/core';
+/** IPv6 loopback. The other half of what `localhost` can mean. */
+export const IPV6_LOOPBACK = '::1';
+/**
+ * Accept on `[::1]:port` and pipe each connection to `127.0.0.1:port`.
+ *
+ * Both ends are loopback, so a forwarded peer is still a loopback peer and the bridge's loopback
+ * trust holds — the alias does not widen who may connect, only which address they may name.
+ */
+export function openLoopbackAlias(port) {
+    /** Every socket this alias has open, so shutdown can end them instead of waiting them out. */
+    const live = new Set();
+    const server = net.createServer((inbound) => {
+        const outbound = net.connect(port, LOOPBACK_HOST);
+        live.add(inbound).add(outbound);
+        const drop = (socket) => {
+            live.delete(socket);
+        };
+        inbound.on('close', () => drop(inbound));
+        outbound.on('close', () => drop(outbound));
+        // A dead peer on either side must tear down the pair, not surface as an unhandled 'error'
+        // event — which in Node terminates the daemon this alias exists to make reachable.
+        inbound.on('error', () => outbound.destroy());
+        outbound.on('error', () => inbound.destroy());
+        inbound.pipe(outbound);
+        outbound.pipe(inbound);
+    });
+    return new Promise((resolve) => {
+        /**
+         * Stop listening and END EVERYTHING, rather than draining.
+         *
+         * `server.close()` fires its callback only once every existing connection has gone, so a single
+         * held-open socket — a keep-alive, an SSE stream, exactly what this daemon serves — means the
+         * callback never fires. The daemon's shutdown chain awaits this, so an un-drained alias silently
+         * became a daemon that ignores SIGTERM: `reticle stop` timed out, the process stayed alive, and
+         * the port stayed held. Caught by the heartbeat spec, which is the one gate that watches a
+         * daemon actually die.
+         *
+         * A best-effort side listener must never be able to hold up the shutdown of the thing it exists
+         * to make reachable. We are exiting; ending these sockets is the correct outcome, not a
+         * compromise.
+         */
+        const close = () => new Promise((done) => {
+            server.close(() => done());
+            for (const socket of live)
+                socket.destroy();
+            live.clear();
+        });
+        server.once('error', () => {
+            // Nothing was bound, so there is nothing to close — but the caller still gets a close it can
+            // call unconditionally, rather than a shape it has to branch on.
+            resolve({ opened: false, close: () => Promise.resolve() });
+        });
+        server.listen(port, IPV6_LOOPBACK, () => {
+            // Never the reason the process stays up: if the daemon is otherwise done, this must not be
+            // what keeps the event loop alive.
+            server.unref();
+            resolve({ opened: true, close });
+        });
+    });
+}

package/dist/events/contradictions.d.ts

@@ -35,6 +35,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.
      *

package/dist/events/contradictions.js

@@ -281,23 +281,32 @@ export function findContradictions(allEvents, options = {}) {
             });
         }
     }
-    // ── The same write fired more than once ─────────────────────────────────────────────────────
-    const writeCounts = new Map();
-    for (const call of settled) {
-        if (!isMutating(call))
-            continue;
-        const key = `${call.method} ${call.url}`;
-        writeCounts.set(key, (writeCounts.get(key) ?? 0) + 1);
-    }
-    for (const [key, count] of writeCounts) {
-        if (count < 2)
-            continue;
-        found.push({
-            kind: ContradictionKind.DUPLICATE_REQUEST,
-            claim: 'one user action was performed',
-            counter: `the same write fired ${String(count)} times`,
-            detail: `${key} ×${String(count)}`,
-        });
+    // ── The same write fired more than once, inside ONE action's window ─────────────────────────
+    // Attribution is the whole rule here, not a refinement of it: counting `method + url` over whatever
+    // window the caller handed in turns two legitimate separate saves into a double submit. See
+    // ContradictionOptions.actionSince.
+    const actionSince = options.actionSince;
+    if (actionSince !== undefined) {
+        const writeCounts = new Map();
+        for (const event of events) {
+            if (event.type !== EventType.NET_REQUEST || event.t < actionSince)
+                continue;
+            const call = netCall(event);
+            if (!isMutating(call))
+                continue;
+            const key = `${call.method} ${call.url}`;
+            writeCounts.set(key, (writeCounts.get(key) ?? 0) + 1);
+        }
+        for (const [key, count] of writeCounts) {
+            if (count < 2)
+                continue;
+            found.push({
+                kind: ContradictionKind.DUPLICATE_REQUEST,
+                claim: 'one user action was performed',
+                counter: `the same write fired ${String(count)} times`,
+                detail: `${key} ×${String(count)}`,
+            });
+        }
     }
     // ── The UI advanced over a request that never came back ─────────────────────────────────────
     // Gated on the UI having moved: an in-flight request while the app is still visibly waiting is

package/dist/events/predicate-eval.d.ts

@@ -1,4 +1,4 @@
-import { ElementState, PredicateKind, type ElementQuery, type ReticleEvent } from '@reticlehq/core';
+import { ElementState, PredicateKind, type ElementDescriptor, type ElementQuery, type ReticleEvent } from '@reticlehq/core';
 import { z } from 'zod';
 export type Predicate = {
     kind: typeof PredicateKind.ELEMENT;
@@ -58,11 +58,34 @@ export type Predicate = {
     kind: typeof PredicateKind.NOT;
     predicate: Predicate;
 };
+export interface ResidualQueryChecks {
+    /** Dropped fields this side CAN check, as [field, wanted value] pairs. */
+    checks: [string, string][];
+    /** Dropped fields with no descriptor to check them against — refuse rather than ignore. */
+    unusable: string[];
+}
 /**
- * Strict on every branch. A key that is nobody's spelling is now a schema error naming it, instead of
- * a stripped field and a green — see predicate-strict.test.ts for the MCP session that found this.
+ * Split a query's dropped fields into the ones the server can still enforce and the ones it cannot.
+ *
+ * The alternative — refuse every dropped field — breaks calls that work today and that our own
+ * cheatsheet advertises (`{ role: "button", text: "Save" }`), and breaks them into no verdict at all.
+ * Enforcing what we can and refusing only the rest keeps those calls working AS WRITTEN, which is the
+ * outcome the caller was already assuming.
  */
+export declare function residualQueryChecks(query: ElementQuery): ResidualQueryChecks;
+/** Does this element satisfy every field the locator dropped? */
+export declare function satisfiesResiduals(element: ElementDescriptor, checks: readonly [string, string][]): boolean;
+/** How the element's own reading of a dropped field should be REPORTED back on a failure. */
+export declare function describeResidual(element: ElementDescriptor, field: string): string;
 export declare const PredicateSchema: z.ZodType<Predicate>;
+/**
+ * The fields a given predicate kind accepts, read off the schema itself.
+ *
+ * Derived rather than listed so the two can never disagree: a rejection message that names a stale
+ * field set is worse than one that names none, because the agent trusts it and retries into the same
+ * wall. Empty for a kind that is not in the union.
+ */
+export declare function predicateFieldsFor(kind: string): readonly string[];
 export interface EvalResult {
     pass: boolean;
     /**