@reticlehq/server 2.8.0 → 2.9.0

package/dist/honesty/unread-outcome.js

@@ -1,4 +1,5 @@
-import { EventType, MUTATING_METHODS, NetInitiator } from '@reticlehq/core';
+import { EventType, MUTATING_METHODS, NetInitiator, isDevToolingUrl, } from '@reticlehq/core';
+import { asString } from '../tools/tools-helpers.js';
 const IPC_METHOD = NetInitiator.IPC.toUpperCase();
 /**
  * A write whose outcome is sitting in a payload nobody read.
@@ -29,22 +30,48 @@ const IPC_METHOD = NetInitiator.IPC.toUpperCase();
  *    The residual gap is real and narrower: a handler that RESOLVES with a failure inside its payload
  *    is invisible without body capture. That case is `findBodyFailures`, which reads the payload and
  *    catches it precisely — with capture on, where it belongs.
+ *
+ *  - **the app's own traffic only.** The DEV TOOLCHAIN writes too: Next's overlay answers
+ *    `POST /__nextjs_original-stack-frames` with a JSON body the moment the app logs one React
+ *    warning, and nothing captures it. Judged as the app's write, that made every verdict in a Next
+ *    dev app `unknown` — decided by a channel the caller never asked about, on a request the app did
+ *    not make. `findContradictions` has split this traffic out for the same reason since the overlay
+ *    turned correct navigations red; this rule was reading the unsplit window.
  */
 const OK_MIN = 200;
 const OK_MAX = 300;
-export function hasUnreadWriteOutcome(events) {
-    return events.some((event) => {
+/**
+ * The writes whose outcome went unread, as "METHOD url".
+ *
+ * Named rather than counted, because a caveat an agent cannot locate is a caveat it learns to skip.
+ * The sentence used to say "a write returned 2xx with a response body that was never recorded" and
+ * name no write, which is unactionable on any page that makes more than one call.
+ */
+export function unreadWriteLabels(events) {
+    const labels = [];
+    for (const event of events) {
         if (event.type !== EventType.NET_REQUEST)
-            return false;
+            continue;
         const method = ('string' === typeof event.data['method'] ? event.data['method'] : '').toUpperCase();
         if (method === IPC_METHOD || !MUTATING_METHODS.includes(method))
-            return false;
+            continue;
+        const url = asString(event.data['url']);
+        if (isDevToolingUrl(url))
+            continue;
         const status = event.data['status'];
         if (typeof status !== 'number' || status < OK_MIN || status >= OK_MAX)
-            return false;
+            continue;
         if (event.data['responseBody'] !== undefined)
-            return false; // read — findBodyFailures judged it
+            continue; // read — findBodyFailures judged it
         const size = event.data['responseSize'];
-        return 'number' === typeof size && size > 0;
-    });
+        if ('number' !== typeof size || size <= 0)
+            continue;
+        const label = `${method} ${url ?? ''}`.trim();
+        if (!labels.includes(label))
+            labels.push(label);
+    }
+    return labels;
+}
+export function hasUnreadWriteOutcome(events) {
+    return unreadWriteLabels(events).length > 0;
 }

package/dist/honesty/unsettled.d.ts

@@ -21,6 +21,15 @@ export interface UnsettledWindow {
     waitedFor: string;
     /** Requests that started in this window and had not come back, as "METHOD url". */
     stillInFlight: readonly string[];
+    /**
+     * Endpoints called more than once in this window, as "METHOD url ×N" — see `repeatedRequestLabels`.
+     *
+     * The case `stillInFlight` structurally cannot see: a retry loop against a dead backend completes
+     * every attempt, so nothing is ever outstanding, and the verdict fell through to a sentence that
+     * blamed unnamed churn on an app whose whole problem was one endpoint being hammered. Optional —
+     * a caller that does not supply it gets exactly the sentence that shipped before.
+     */
+    repeated?: readonly string[];
 }
 /**
  * The wait, in one phrase.

package/dist/honesty/unsettled.js

@@ -64,10 +64,14 @@ export function unsettledBecause(base, window) {
     if (window === undefined)
         return `${base} — re-check, or assert a consequence that settles`;
     if (0 === window.stillInFlight.length) {
+        const repeated = window.repeated ?? [];
         return (`${base}. It waited for ${window.waitedFor}, and no request started in this window was left ` +
-            'open — what kept the page busy was its own churn (a poll, a timer, an animation), so waiting ' +
-            'longer will not help. Assert the consequence you care about (a signal, a route change, or ' +
-            'store state) instead of waiting for idle, and re-check if the app is genuinely slow');
+            'open — what kept the page busy was its own churn ' +
+            (0 === repeated.length
+                ? '(a poll, a timer, an animation)'
+                : `(these fired repeatedly: ${repeated.join(', ')} — a poll or a retrying query)`) +
+            ', so waiting longer will not help. Assert the consequence you care about (a signal, a route ' +
+            'change, or store state) instead of waiting for idle, and re-check if the app is genuinely slow');
     }
     const shown = window.stillInFlight.slice(0, MAX_LISTED_REQUESTS);
     const rest = window.stillInFlight.length - shown.length;

package/dist/honesty/verified.d.ts

@@ -42,22 +42,48 @@ interface VerifiedInputs {
     }[];
     /** Did a real frame flush before the wait gave up? */
     settled?: boolean;
+    /**
+     * The caller NAMED the expected consequence before acting — an `until`/`predicate` of its own,
+     * rather than the default "wait for the page to go idle".
+     *
+     * This is the epistemic core of the tool: a declaration made before the action cannot be
+     * rationalised after it. When such a declaration HOLDS, settlement is corroboration, not a veto —
+     * so the two clauses that answer "the app had not gone quiet" step aside for it. Measured in the
+     * field on three different apps: the expected text was on screen, the write returned 204, the
+     * nested verdict passed with evidence, and the verdict was `unknown` because the SPA polls, or
+     * because the tab was hidden and a hidden tab never fires the animation frame `settled` is read
+     * from. A hidden tab is the NORMAL state for agent-driven verification, so a signal that is always
+     * false there cannot be a precondition for a verdict.
+     *
+     * Narrow on purpose. It steps aside for settlement ONLY: an absence-derived finding about what the
+     * action DID — a duplicate write, a dead control, a route that rendered nothing, a response
+     * nothing consumed — still downgrades, and every positively OBSERVED contradiction still wins
+     * outright. Fixing a false negative must not open a path to a false positive.
+     */
+    declaredConsequence?: boolean;
     /**
      * A write in this window answered `202 Accepted` — the server took the request and has NOT
      * finished processing it.
      */
     outcomePending?: boolean;
     /**
-     * A write in this window returned 2xx with a payload that was never recorded, so its outcome was
-     * never read. See `hasUnreadWriteOutcome` — the status line describes the transport, not the result.
+     * Writes in this window that returned 2xx with a payload that was never recorded, as "METHOD url",
+     * so their outcome was never read. See `unreadWriteLabels` — the status line describes the
+     * transport, not the result.
+     *
+     * The LABELS rather than a flag: every other clause names the evidence that decided it, and this
+     * one named nothing, so an agent holding the caveat could not tell which call it was about.
+     * Empty means nothing went unread.
      */
-    outcomeUnread?: boolean;
+    outcomeUnread?: readonly string[];
     /**
      * What the wait was for and what the window held when it ended — read ONLY by the two clauses that
      * answer UNSETTLED, which is the commonest reason a verdict comes back `unknown` and was also the
      * least actionable. Optional: without it those clauses say exactly what they said before.
      */
     unsettled?: UnsettledWindow;
+    /** A passing absence assertion targeted a region that the current capture could not observe. */
+    absenceBlindSpot?: string;
 }
 interface VerifiedVerdict {
     verified: Verified;

package/dist/honesty/verified.js

@@ -1,8 +1,10 @@
-import { Verified, VerifiedReason, isAbsenceDerived } from '@reticlehq/core';
+import { ContradictionKind, MUTATING_METHODS, Verified, VerifiedReason, isAbsenceDerived, } from '@reticlehq/core';
 import { HonestyGrade } from './honesty.js';
 import { unsettledBecause } from './unsettled.js';
 export function decideVerified(inputs) {
     const { pass, honesty, contradictions = [], settled, outcomePending, outcomeUnread } = inputs;
+    /** The caller named a consequence before acting and it held — see `declaredConsequence`. */
+    const declaredHeld = true === inputs.declaredConsequence && true === pass;
     // Ahead of the failure clause, because a failure is only the most actionable fact when there WAS
     // one. An assertion nobody could evaluate is not a defect in the app, and calling it one was
     // putting the agent's own malformed calls into the bug count.
@@ -64,14 +66,42 @@ export function decideVerified(inputs) {
     // Absence-derived only: report it, do not assert failure. UNKNOWN is the honest answer — Reticle
     // drove the app and could not yet tell. The finding still rides out in `contradictions`, so an
     // agent that wants to wait and re-check has everything it needs.
-    if (contradictions.length > 0) {
+    //
+    // ...except when the only finding is that a READ had not come back AND the caller declared the
+    // consequence that did. `request-never-settled` is a statement about when we stopped looking; the
+    // declaration is a statement about what was supposed to happen, made before it could. On a page
+    // that polls, the first is permanently true and vetoed every verdict the second earned.
+    //
+    // An open WRITE is the exception to the exception, and it is where the false-green defence lives:
+    // "the toast said Saved while the POST was still open" is the archetype this product exists to
+    // catch, and its outcome genuinely does not exist yet. A poll or a prefetch left hanging says
+    // nothing about the action; an unfinished mutation says the answer is not in yet. Read off the
+    // labels the window already carries — and when there are no labels to read, nothing is softened.
+    const openWrite = (inputs.unsettled?.stillInFlight ?? []).some((label) => MUTATING_METHODS.includes((label.split(' ')[0] ?? '').toUpperCase()));
+    const settlementOnly = declaredHeld &&
+        inputs.unsettled !== undefined &&
+        !openWrite &&
+        contradictions.every((c) => c.kind === ContradictionKind.REQUEST_NEVER_SETTLED);
+    if (contradictions.length > 0 && !settlementOnly) {
         const kinds = contradictions.map((c) => c.kind).join(', ');
         return {
             verified: Verified.UNKNOWN,
-            verifiedReason: VerifiedReason.UNSETTLED,
+            // NOT `unsettled`: this clause fires whether or not the page went idle, and naming it after
+            // idle produced verdicts that read `unsettled` beside `settled: true`.
+            verifiedReason: VerifiedReason.EVIDENCE_INCOMPLETE,
             because: unsettledBecause(`the assertion held, but this window closed before the app finished (${kinds})`, inputs.unsettled),
         };
     }
+    // An absence assertion over a region Reticle cannot observe is not disproved, but it is not proved
+    // either. This is narrower than general partial coverage: the target itself is scoped to the blind
+    // region, so the DOM result cannot answer the question the caller asked.
+    if (inputs.absenceBlindSpot !== undefined) {
+        return {
+            verified: Verified.UNKNOWN,
+            verifiedReason: VerifiedReason.ABSENCE_BLIND_SPOT,
+            because: inputs.absenceBlindSpot,
+        };
+    }
     // Below the contradiction clause, and for the same reason a contradiction outranks a dirty
     // capture: evidence AGAINST beats absence of evidence, whichever absence it is. Both can hold at
     // once — assert `{ text: 'Saved' }` that was already on screen while the write 500s — and ordering
@@ -132,15 +162,22 @@ export function decideVerified(inputs) {
     //
     // UNKNOWN, not NO: nothing is known to have failed. The remedy is in the sentence, because an
     // agent that cannot act on a caveat will learn to skip it.
-    if (true === outcomeUnread) {
+    if (outcomeUnread !== undefined && outcomeUnread.length > 0) {
         return {
             verified: Verified.UNKNOWN,
             verifiedReason: VerifiedReason.OUTCOME_UNREAD,
-            because: 'a write returned 2xx with a response body that was never recorded, so its outcome is unread — a 200 describes the transport, not the result (a batch reports per-item failures in the body, and every GraphQL error is a 200). Enable it where your app calls connect(): `reticle.connect({ captureNetworkBodies: true })`, then re-run',
+            because: `a write returned 2xx with a response body that was never recorded (${outcomeUnread.join('; ')}), so its outcome is unread` +
+                ' — a 200 describes the transport, not the result (a batch reports per-item failures in the body, and every GraphQL error is a 200). Enable it where your app calls connect(): `reticle.connect({ captureNetworkBodies: true })`, then re-run',
         };
     }
     // Never settled: the page may still be moving, so the observation window may have closed early.
-    if (false === settled) {
+    //
+    // Skipped when the caller DECLARED the consequence and it held. `settled` here is "a real
+    // animation frame fired within the budget", which a hidden or throttled tab never does — and a
+    // hidden tab is the ordinary case for agent-driven verification. It is corroboration; it is not
+    // the claim. It is still reported: `honesty.settled` carries the fact, and the sentence below says
+    // so in words.
+    if (false === settled && !declaredHeld) {
         return {
             verified: Verified.UNKNOWN,
             verifiedReason: VerifiedReason.UNSETTLED,
@@ -155,11 +192,17 @@ export function decideVerified(inputs) {
     // partial` — the prose contradicting the evidence block next to it. Whichever a reader believes,
     // one of them lied, and the whole point of this layer is that the sentence can be trusted on its
     // own. Seen on a one-way IPC send: coverage said the outcome was unobservable, `because` said clean.
+    // A green that rests on the declaration rather than on idle says so. The page not going quiet is a
+    // real fact about the app — a poll, a timer, a throttled tab — and a caller who cares must be able
+    // to see it without re-deriving it, so it is stated here and carried in `honesty.settled`.
+    const notIdle = false === settled
+        ? ', though the page never went idle — this rests on the consequence you declared, not on the page going quiet'
+        : '';
     return {
         verified: Verified.YES,
         verifiedReason: VerifiedReason.PROVED,
         because: true === honesty.coverage?.partial
-            ? `assertion held at ${honesty.grade} grade with no channel disagreeing, but coverage was PARTIAL — see \`coverage\` for what went unobserved`
-            : `assertion held at ${honesty.grade} grade over a clean capture with no channel disagreeing`,
+            ? `assertion held at ${honesty.grade} grade with no channel disagreeing, but coverage was PARTIAL — see \`coverage\` for what went unobserved${notIdle}`
+            : `assertion held at ${honesty.grade} grade over a clean capture with no channel disagreeing${notIdle}`,
     };
 }

package/dist/http-server.d.ts

@@ -11,6 +11,15 @@ export interface SharedServer {
     attachMcp(factory: () => McpServer): void;
     /** Register the JSON the daemon returns from GET /status (live sessions + health for `reticle status`). */
     attachStatus(provider: () => unknown): void;
+    /**
+     * Register the handler behind POST /drive: open a driveable browser at `url` and answer with the
+     * session it registered.
+     *
+     * This is how `reticle drive` stops fighting the daemon for the bridge port. The daemon already
+     * owns the browser plane, so driving is a request to it — see cli/drive-attach.ts. Left
+     * unattached, the route 404s, which is exactly what a newer CLI needs to hear from an older daemon.
+     */
+    attachDrive(provider: (url: string) => Promise<unknown>): void;
     /**
      * Register a callback fired when the AGENT presence changes — true when the first MCP client (any
      * agent: Codex/OpenCode/Claude/Hermes) connects, false when the last one disconnects. Agent-
@@ -18,6 +27,15 @@ export interface SharedServer {
      * "is an agent attached?". The daemon uses this to tell the panel "agent live" vs "agent stopped".
      */
     attachAgentPresence(cb: (connected: boolean) => void): void;
+    /**
+     * Tell every attached MCP proxy that this daemon is retiring, BEFORE the sockets go.
+     *
+     * The proxy sees a clean stream end whether the daemon shut down on schedule or died under it, so
+     * without this the two are one row and the transport-stability metric is dominated by the designed
+     * case. Separate from `close()` because it must run before the shutdown work rather than during it:
+     * `close()` is also the cleanup path of a start that failed, where there is nobody to tell.
+     */
+    announceShutdown(): void;
     close(): Promise<void>;
 }
 /**
@@ -32,3 +50,4 @@ export interface SharedServer {
 export declare function createSharedServer(options?: {
     token?: string;
 }): SharedServer;
+export declare function driveSchemeRefusal(url: string): string | undefined;

package/dist/http-server.js

@@ -1,6 +1,6 @@
 import * as http from 'node:http';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import { MCP_SSE_PATH, MCP_MESSAGE_PATH, STATUS_PATH } from '@reticlehq/core';
+import { MCP_SSE_PATH, MCP_MESSAGE_PATH, MCP_SHUTDOWN_EVENT, STATUS_PATH, DRIVE_PATH, } from '@reticlehq/core';
 import { getSessionMetrics } from './telemetry/session-metrics.js';
 import { noteAgentPeer, PEER_VERSION_PARAM, PEER_CONTRACT_PARAM } from './version/peer-announce.js';
 import { log } from './log.js';
@@ -18,8 +18,15 @@ import { isLoopbackHost, isLocalWebOrigin, isLoopbackPeer, requestToken, tokensM
 export function createSharedServer(options = {}) {
     let mcpFactory;
     let statusProvider;
+    let driveProvider;
     let agentPresence;
     const transports = new Map();
+    /**
+     * The raw response behind each SSE session, so the shutdown announcement can be written as an SSE
+     * frame the proxy reads and the agent never sees. `SSEServerTransport.send` only speaks JSON-RPC,
+     * and this message is addressed to the proxy rather than to the client behind it.
+     */
+    const sseStreams = new Map();
     const token = options.token;
     // The agent control plane (MCP transport) and /status carry the same trust as the browser WS: a
     // loopback peer is trusted (the local stdio proxy and `reticle status` always dial 127.0.0.1), but any
@@ -45,9 +52,23 @@ export function createSharedServer(options = {}) {
     };
     const httpServer = http.createServer((req, res) => {
         const rawUrl = req.url ?? '/';
-        const url = new URL(rawUrl, 'http://localhost');
+        // Node's HTTP parser accepts request targets the WHATWG URL parser refuses (`//` among them), and
+        // a throw in a `request` listener is an uncaughtException — which the daemon answers by exiting,
+        // taking every agent and every browser session on this port with it, from whichever project. One
+        // malformed line on a loopback socket, and it lands BEFORE the authorization check below, so
+        // nothing had to be trusted to send it.
+        const url = parseRequestTarget(rawUrl);
+        if (null === url) {
+            log('http_bad_request_target', {});
+            res.writeHead(400, { 'Content-Type': 'text/plain' });
+            res.end('bad request target');
+            return;
+        }
         const path = url.pathname;
-        if (path === STATUS_PATH || path === MCP_SSE_PATH || path === MCP_MESSAGE_PATH) {
+        if (path === STATUS_PATH ||
+            path === DRIVE_PATH ||
+            path === MCP_SSE_PATH ||
+            path === MCP_MESSAGE_PATH) {
             if (!authorized(req, url)) {
                 res.writeHead(401, { 'Content-Type': 'text/plain' });
                 res.end('unauthorized');
@@ -60,6 +81,58 @@ export function createSharedServer(options = {}) {
             res.end(body);
             return;
         }
+        if ('POST' === req.method && path === DRIVE_PATH) {
+            if (driveProvider === undefined) {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('not found');
+                return;
+            }
+            // A state-changing route must require a content type that a browser cannot send without a
+            // preflight. `text/plain`, `application/x-www-form-urlencoded` and `multipart/form-data` make
+            // a POST a CORS SIMPLE request: the browser sends it cross-origin with no preflight, and
+            // blocking the response afterwards does not un-drive the browser. Since loopback origins are
+            // authorized here by design, any page on any localhost port could otherwise reach this route
+            // by guessing ours, and drive a browser to a URL it chose.
+            //
+            // Requiring `application/json` forces a preflight, which the browser will not complete without
+            // our opt-in, and we do not opt in. One header check closes the whole class.
+            if (!isJsonRequest(req)) {
+                res.writeHead(415, { 'Content-Type': 'text/plain' });
+                res.end('expected content-type: application/json');
+                return;
+            }
+            const provider = driveProvider;
+            readBody(req)
+                .then(async (body) => {
+                const url = urlFromDriveRequest(body);
+                if (url === undefined) {
+                    res.writeHead(400, { 'Content-Type': 'text/plain' });
+                    res.end('drive requires a url');
+                    return;
+                }
+                // Before the browser is asked for anything. See driveSchemeRefusal.
+                const refusal = driveSchemeRefusal(url);
+                if (refusal !== undefined) {
+                    res.writeHead(400, { 'Content-Type': 'text/plain' });
+                    res.end(refusal);
+                    return;
+                }
+                // A refusal is an ANSWER. The caller is a foreground CLI waiting on this socket: a thrown
+                // handler that took the response down with it would hang `reticle drive` on a request
+                // that can never complete — the same shape of silence the raw EADDRINUSE bind had.
+                const payload = await provider(url).catch((err) => ({
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(payload));
+            })
+                .catch((err) => {
+                log('drive_request_error', { error: err instanceof Error ? err.message : String(err) });
+                res.writeHead(500, { 'Content-Type': 'text/plain' });
+                res.end('drive failed');
+            });
+            return;
+        }
         if ('GET' === req.method && path === MCP_SSE_PATH) {
             // The agent's MCP server announces itself here, on the connect it already makes. The daemon is
             // the single judge of skew, so this is where the third pair is decided — and unlike the CLI's
@@ -79,10 +152,12 @@ export function createSharedServer(options = {}) {
             const transport = new SSEServerTransport(MCP_MESSAGE_PATH, res);
             const sid = transport.sessionId;
             transports.set(sid, transport);
+            sseStreams.set(sid, res);
             if (1 === transports.size)
                 agentPresence?.(true); // first agent attached
             res.on('close', () => {
                 transports.delete(sid);
+                sseStreams.delete(sid);
                 transport.close().catch(() => undefined);
                 mcpServer.close().catch(() => undefined);
                 log('mcp_client_disconnected', { sessionId: sid });
@@ -137,17 +212,33 @@ export function createSharedServer(options = {}) {
     function attachStatus(provider) {
         statusProvider = provider;
     }
+    function attachDrive(provider) {
+        driveProvider = provider;
+    }
     function attachAgentPresence(cb) {
         agentPresence = cb;
     }
     function attachMcp(factory) {
         mcpFactory = factory;
     }
+    function announceShutdown() {
+        for (const [sid, stream] of sseStreams) {
+            try {
+                stream.write(`event: ${MCP_SHUTDOWN_EVENT}\ndata: {}\n\n`);
+            }
+            catch {
+                // A stream we cannot write to is a proxy that already left. Announcing a shutdown must never
+                // be the reason a shutdown fails.
+                log('mcp_shutdown_announce_failed', { sessionId: sid });
+            }
+        }
+    }
     async function close() {
         for (const transport of transports.values()) {
             await transport.close();
         }
         transports.clear();
+        sseStreams.clear();
         await new Promise((resolve, reject) => {
             httpServer.close((err) => {
                 // A server that never listened is already closed, and saying so is not an error worth
@@ -167,5 +258,112 @@ export function createSharedServer(options = {}) {
             });
         });
     }
-    return { httpServer, attachMcp, attachStatus, attachAgentPresence, close };
+    return {
+        httpServer,
+        attachMcp,
+        attachStatus,
+        attachDrive,
+        attachAgentPresence,
+        announceShutdown,
+        close,
+    };
+}
+/** Cap on a drive request body. A url is short; anything larger is not one. */
+const MAX_DRIVE_BODY_BYTES = 8 * 1024;
+/** Collect a request body, refusing one too large to be what this route accepts. */
+/**
+ * Is this a request a cross-origin page could NOT have sent without a preflight?
+ *
+ * The three CORS "simple" content types are the whole attack surface here, so anything that is not
+ * JSON is refused rather than sniffed. Parameters are allowed (`application/json; charset=utf-8`)
+ * because real clients send them.
+ */
+const JSON_MEDIA_TYPE = 'application/json';
+function isJsonRequest(req) {
+    // Read through the typed accessor rather than indexing the header bag: the index signature is
+    // `any`-shaped, and narrowing after an unsafe read is narrowing a lie.
+    const value = req.headersDistinct['content-type']?.[0];
+    if (undefined === value)
+        return false;
+    return JSON_MEDIA_TYPE === value.split(';')[0]?.trim().toLowerCase();
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        req.setEncoding('utf8');
+        req.on('data', (chunk) => {
+            body += chunk;
+            if (body.length > MAX_DRIVE_BODY_BYTES) {
+                req.destroy();
+                reject(new Error('body too large'));
+            }
+        });
+        req.on('end', () => resolve(body));
+        req.on('error', reject);
+    });
+}
+/** The `url` out of a drive request body, or undefined when there isn't a usable one. Pure. */
+/**
+ * The schemes the daemon will open in a browser it owns.
+ *
+ * `drive` exists to drive a running web app, and nothing in the product hands this route anything
+ * else — the desktop paths have their own runtimes and never come through here. So the allowlist
+ * costs nothing real and closes a class outright.
+ *
+ * Kept deliberately small. `file:` reads the disk through a browser context WE opened, `data:` is a
+ * page that came from nowhere, and `javascript:` is not a document at all. None of them is a thing
+ * anybody drives.
+ *
+ * Worth stating what this is NOT: the CORS defence on the route already keeps a web page off it,
+ * because a JSON content type forces a preflight nobody opts into. The caller reaching this check is
+ * a local process, which already has broader access than the check removes. It is hygiene about what
+ * the daemon will open on request, not a security boundary — and a refusal here should read as a
+ * refusal, not an alarm.
+ */
+const DRIVEABLE_SCHEMES = ['http:', 'https:'];
+/** The scheme of `url`, or undefined when it is not a URL at all. */
+function schemeOf(url) {
+    try {
+        return new URL(url).protocol;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function driveSchemeRefusal(url) {
+    const scheme = schemeOf(url);
+    if (scheme !== undefined && DRIVEABLE_SCHEMES.includes(scheme))
+        return undefined;
+    // Names what it got, because the caller is a CLI printing this to somebody who typed the url and
+    // needs to see which part of it was the problem.
+    return (`unsupported scheme ${scheme ?? '(unparseable url)'} — reticle drive opens a running web app, ` +
+        `so it accepts ${DRIVEABLE_SCHEMES.join(' and ')} only`);
+}
+function urlFromDriveRequest(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || null === parsed)
+        return undefined;
+    const url = parsed['url'];
+    return 'string' === typeof url && url.length > 0 ? url : undefined;
+}
+/**
+ * The one URL parse on the daemon's request path, and the only place allowed to do it.
+ *
+ * `null` for anything the parser refuses, so the caller answers rather than throwing. Exported for
+ * nothing — it is here, next to its single caller, because a second copy of this parse elsewhere in
+ * the handler would reintroduce the crash the guard exists to remove.
+ */
+function parseRequestTarget(rawUrl) {
+    try {
+        return new URL(rawUrl, 'http://localhost');
+    }
+    catch {
+        return null;
+    }
 }

package/dist/impact/impact-recorder.d.ts

@@ -0,0 +1,23 @@
+import { type ImpactCounts, type ImpactSnapshot } from '@reticlehq/core';
+import { ImpactStore, type ImpactFoldMeta } from './impact-store.js';
+/** Wire the recorder to a project. Idempotent; the first root wins for the daemon's lifetime. */
+export declare function initImpact(opts: {
+    reticleRoot: string | undefined;
+    projectName?: string;
+    now?: () => number;
+}): ImpactStore | undefined;
+/** The live store, if one has been initialised. */
+export declare function impactStore(): ImpactStore | undefined;
+/** Test seam: drop the singleton so a suite can start from a clean record. */
+export declare function resetImpactForTest(): void;
+/** Record one delta, if the recorder is live. Never throws: stats must not break a tool call. */
+export declare function recordImpact(delta: Partial<ImpactCounts>, meta?: ImpactFoldMeta): void;
+export declare function impactSnapshot(): ImpactSnapshot | undefined;
+/**
+ * What one tool call did, as counters.
+ *
+ * Pure and exported so the shape is testable without a dispatch: given a result and a duration, it
+ * says what the record should gain. `verified` is the only field that can mint a verdict, which is
+ * the same rule the product states to agents - everything else moves or reads the app.
+ */
+export declare function deltaForToolResult(raw: unknown, durationMs: number, refused: boolean): Partial<ImpactCounts>;

package/dist/impact/impact-recorder.js

@@ -0,0 +1,76 @@
+import { Verified } from '@reticlehq/core';
+import { estimateTokens } from '../session/output-budget.js';
+import { ImpactStore } from './impact-store.js';
+/**
+ * The daemon's single impact recorder.
+ *
+ * One store per daemon, created on the first call that knows the project's `.reticle` root. A
+ * module singleton for the same reason the tool counters are: the dispatch chokepoint has to be
+ * able to record without every tool threading a store through its arguments, and a second recorder
+ * would silently split the user's own history in half.
+ */
+let store;
+/** Wire the recorder to a project. Idempotent; the first root wins for the daemon's lifetime. */
+export function initImpact(opts) {
+    // No root, no record. Programmatic callers and test doubles build their own deps and are not
+    // obliged to carry one, and a courtesy counter must never be the reason a tool call throws.
+    if (opts.reticleRoot === undefined || 0 === opts.reticleRoot.length)
+        return store;
+    store ??= new ImpactStore({ ...opts, reticleRoot: opts.reticleRoot });
+    return store;
+}
+/** The live store, if one has been initialised. */
+export function impactStore() {
+    return store;
+}
+/** Test seam: drop the singleton so a suite can start from a clean record. */
+export function resetImpactForTest() {
+    store = undefined;
+}
+/** Record one delta, if the recorder is live. Never throws: stats must not break a tool call. */
+export function recordImpact(delta, meta = {}) {
+    try {
+        store?.record(delta, meta);
+    }
+    catch {
+        // Counting is a courtesy to the user; failing to count is not worth failing their call over.
+    }
+}
+export function impactSnapshot() {
+    return store?.snapshot();
+}
+/**
+ * What one tool call did, as counters.
+ *
+ * Pure and exported so the shape is testable without a dispatch: given a result and a duration, it
+ * says what the record should gain. `verified` is the only field that can mint a verdict, which is
+ * the same rule the product states to agents - everything else moves or reads the app.
+ */
+export function deltaForToolResult(raw, durationMs, refused) {
+    const delta = {
+        calls: 1,
+        drivingMs: Math.max(0, Math.round(durationMs)),
+        tokensReturned: estimateTokens(JSON.stringify(raw) ?? ''),
+    };
+    if (refused) {
+        delta.refusals = 1;
+        return delta;
+    }
+    const verified = isRecord(raw) ? raw['verified'] : undefined;
+    if (verified === Verified.YES) {
+        delta.verdicts = 1;
+        delta.passed = 1;
+    }
+    else if (verified === Verified.NO) {
+        delta.verdicts = 1;
+        delta.failed = 1;
+    }
+    else if (verified === Verified.UNKNOWN) {
+        delta.verdicts = 1;
+        delta.unknown = 1;
+    }
+    return delta;
+}
+function isRecord(value) {
+    return 'object' === typeof value && null !== value;
+}