@reticlehq/server 2.8.0 → 2.10.0

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
@@ -103,7 +133,23 @@ export function decideVerified(inputs) {
     // A vacuous green: nothing was actually proved. Grade NONE means no signal, no request, no state
     // change and no element was pinned — the assertion could not have failed, which makes passing it
     // evidence of nothing.
+    // Two different facts used to share this answer. Everything above has already ruled out a failure,
+    // a contradiction, a dirty capture, a pending write and an unread one — so when the window ALSO
+    // settled, the engine did not fail to see: it saw the whole window, ran every oracle, and found
+    // nothing wrong. That is `no-fault`, and telling it apart from "I could not see" is the difference
+    // between "assert something" and "look again with better coverage".
+    //
+    // Gated on `true === settled` rather than on a caller's say-so. A call that returned before the app
+    // stopped moving has not earned this, whatever it declared — which is what stops `no-fault` from
+    // becoming the green-forever button an always-available "nothing was wrong" would be.
     if (honesty.grade === HonestyGrade.NONE) {
+        if (true === settled) {
+            return {
+                verified: Verified.NO_FAULT,
+                verifiedReason: VerifiedReason.NOTHING_DECLARED,
+                because: 'the page settled and no channel reported a problem, but nothing was declared to prove — this is not verification. Assert a consequence the action CHANGES (a signal, a request, a route, or store state) to get one',
+            };
+        }
         return {
             verified: Verified.UNKNOWN,
             verifiedReason: VerifiedReason.VACUOUS_GRADE,
@@ -132,15 +178,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 +208,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;
+}

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

@@ -0,0 +1,47 @@
+import { type ImpactCounts, type ImpactScope, type ImpactSnapshot } from '@reticlehq/core';
+export interface ImpactPaths {
+    project: string;
+    global: string;
+}
+/**
+ * `reticleRoot` is the project's own `.reticle` directory (what every other store here is handed);
+ * the global scope always lives beside the daemon's own state in `~/.reticle`.
+ */
+export declare function impactPaths(reticleRoot: string): ImpactPaths;
+/** Read a scope, tolerating absence and corruption: a broken file starts over rather than throwing. */
+export declare function readScope(path: string, now: number): ImpactScope;
+/** YYYY-MM-DD in local time - the day boundary a person recognises, not UTC's. */
+export declare function isoDay(now: number): string;
+/**
+ * What a fold knows beyond the counters.
+ *
+ * `runMs` is a SESSION's lifetime, and it only ever feeds the "longest run" record. It is not a
+ * counter: adding it to a total would answer a question nobody asked, and the record used to be fed
+ * a single tool call's duration instead, which made the report's superlative a number of
+ * milliseconds that never grew past one click.
+ */
+export interface ImpactFoldMeta {
+    runMs?: number;
+}
+/** Fold one delta into a scope: totals, today's bucket, records and streak. Pure. */
+export declare function applyDelta(scope: ImpactScope, delta: Partial<ImpactCounts>, now: number, meta?: ImpactFoldMeta): ImpactScope;
+/**
+ * The live impact record for one project.
+ *
+ * Holds both scopes in memory, folds deltas in synchronously (so a reader always sees the truth),
+ * and flushes to disk on a debounce.
+ */
+export declare class ImpactStore {
+    #private;
+    constructor(opts: {
+        reticleRoot: string;
+        projectName?: string;
+        now?: () => number;
+    });
+    /** Notified after every fold, so the HUD can be pushed a fresh snapshot. */
+    onChange(fn: () => void): void;
+    record(delta: Partial<ImpactCounts>, meta?: ImpactFoldMeta): void;
+    snapshot(): ImpactSnapshot;
+    /** Write now (process exit, tests). */
+    flush(): void;
+}