@reticlehq/server 2.11.0 → 2.13.0

package/dist/flows/predicate-to-expect.js

@@ -8,9 +8,12 @@ export function predicateToExpect(predicate) {
         case PredicateKind.SIGNAL: {
             if (predicate.name === undefined)
                 return undefined;
-            return predicate.dataMatches === undefined
-                ? { signal: predicate.name }
-                : { signal: predicate.name, signalData: predicate.dataMatches };
+            const signal = { signal: predicate.name };
+            if (predicate.dataMatches !== undefined)
+                signal.signalData = predicate.dataMatches;
+            if (predicate.count !== undefined)
+                signal.signalCount = predicate.count;
+            return signal;
         }
         case PredicateKind.NET: {
             const net = {};
@@ -75,29 +78,47 @@ export function predicateToExpect(predicate) {
     }
 }
 /**
- * The subset a REPLAY actually enforces today.
+ * The subset a REPLAY actually enforces.
+ *
+ * The rule has never changed: never write an assertion into a flow file that nothing evaluates. A
+ * flow reporting `grade: "asserted"` while its assertion is read by no one is a false green, in the
+ * feature whose entire purpose is preventing them.
  *
- * `flow-replay` checks exactly two things per step: `expect.element.testid` is present after the
- * action, and `expect.state` holds. A recorded `net` or `signal` expect is graded as a consequence
- * assertion by `classifyFlowAssertions` and then never evaluated — so writing one into a flow file
- * would make it report `grade: "asserted"` while nothing checks it.
+ * What changed is the SET. This kept only `element.testid` and `state`, because for a long time
+ * those were the only kinds replay checked — and the note here said lifting it "requires replay to
+ * evaluate them per step". Replay now does exactly that: `assertStepExpect` compiles every
+ * remaining kind through `successToPredicate` and waits on it. The condition was met and the filter
+ * was not updated, so the two drifted.
  *
- * That is a false green, in the feature whose entire purpose is preventing them, produced by the
- * change that was meant to strengthen it. So only the enforced kinds are recorded: a flow that says
- * it asserts something must actually go red when that thing breaks.
+ * That drift had a cost, and it fell on the agent. `reticle_act_and_wait { until }` IS the agent
+ * saying what success means, and `net` is overwhelmingly what it says. Every one of those was
+ * discarded at capture, so an agent-recorded flow reached disk assertion-free BY CONSTRUCTION and
+ * `reticle_verify` then correctly called it `unverifiable` — the record → save → verify path
+ * completing all the way to a run that could never be a pass. Found by driving it.
  *
- * Lifting this is worth doing — net and signal are the assertions agents most often make, and the
- * conversion above already handles them — but it requires replay to evaluate them per step (the
- * machinery exists: successToPredicate + the predicate engine). Until then, recording them would
- * trade a weak flow for a lying one.
+ * The list below is exactly what `successToPredicate` reads, plus the testid the step runner
+ * asserts directly against the DOM. Anything it cannot compile is still dropped.
  */
 export function enforcedOnReplay(expect) {
     if (expect === undefined)
         return undefined;
     const kept = {};
+    // The step runner asserts this one directly against the live DOM, before the predicate engine.
     if (expect.element?.testid !== undefined)
         kept.element = expect.element;
+    // Everything `successToPredicate` can compile. Replay evaluates EVERY kind of expect through it
+    // (see assertStepExpect); this list is what that function actually reads.
     if (expect.state !== undefined)
         kept.state = expect.state;
+    if (expect.signal !== undefined)
+        kept.signal = expect.signal;
+    if (expect.signalData !== undefined)
+        kept.signalData = expect.signalData;
+    if (expect.signalCount !== undefined)
+        kept.signalCount = expect.signalCount;
+    if (expect.net !== undefined)
+        kept.net = expect.net;
+    if (expect.console !== undefined)
+        kept.console = expect.console;
     return 0 === Object.keys(kept).length ? undefined : kept;
 }

package/dist/flows/recordings.d.ts

@@ -13,12 +13,15 @@ export interface RecordedStep {
 interface ActiveRecording {
     cursor: number;
     steps: RecordedStep[];
+    /** The route the journey began on. See CompiledProgram.startPath. */
+    startPath?: string;
 }
 /** A finished, replayable program compiled from a recording. */
 export interface CompiledProgram {
     name: string;
     version: number;
     steps: RecordedStep[];
+    startPath?: string;
 }
 /**
  * Tracks in-flight recordings (name -> { buffer cursor at record_start, captured steps })
@@ -26,7 +29,7 @@ export interface CompiledProgram {
  */
 export declare class RecordingStore {
     #private;
-    start(name: string, cursor: number): void;
+    start(name: string, cursor: number, startPath?: string): void;
     isRecording(name: string): boolean;
     /**
      * Number of steps captured so far in the named ACTIVE recording (0 if it
@@ -41,5 +44,14 @@ export declare class RecordingStore {
     saveCompiled(program: CompiledProgram): void;
     getCompiled(name: string): CompiledProgram | undefined;
     active(): string[];
+    /**
+     * Names of recordings that have been STOPPED and compiled.
+     *
+     * The mirror of `active()`, and needed for the same defaulting: after `reticle_record stop` a
+     * recording is no longer active, so resolving "the obvious one" from `active()` finds nothing.
+     * Saving it then demanded the exact name back from the caller, which is a thing to remember for
+     * no reason when exactly one recording exists.
+     */
+    compiled(): string[];
 }
 export {};

package/dist/flows/recordings.js

@@ -5,8 +5,12 @@
 export class RecordingStore {
     #active = new Map();
     #compiled = new Map();
-    start(name, cursor) {
-        this.#active.set(name, { cursor, steps: [] });
+    start(name, cursor, startPath) {
+        this.#active.set(name, {
+            cursor,
+            steps: [],
+            ...(startPath === undefined ? {} : { startPath }),
+        });
     }
     isRecording(name) {
         return this.#active.has(name);
@@ -39,4 +43,15 @@ export class RecordingStore {
     active() {
         return [...this.#active.keys()];
     }
+    /**
+     * Names of recordings that have been STOPPED and compiled.
+     *
+     * The mirror of `active()`, and needed for the same defaulting: after `reticle_record stop` a
+     * recording is no longer active, so resolving "the obvious one" from `active()` finds nothing.
+     * Saving it then demanded the exact name back from the caller, which is a thing to remember for
+     * no reason when exactly one recording exists.
+     */
+    compiled() {
+        return [...this.#compiled.keys()];
+    }
 }

package/dist/flows/replay.d.ts

@@ -13,8 +13,28 @@ export declare function ambiguousTestidNote(value: string): string;
  * resolution — can't drift between them.
  */
 export declare function queryRefs(result: CommandResult): string[];
-/** A destructive-action confirmation is one-shot and must never persist into a recording. */
-export declare function replayActionArgs(value: unknown, confirmDangerous?: boolean): Record<string, unknown>;
+/**
+ * The environment variable that supplies one redacted field.
+ *
+ * Named after the field so it is guessable from the flow alone: `auth-password` is read from
+ * `RETICLE_SECRET_AUTH_PASSWORD`. A scheme requiring a lookup table would mean the flow says a
+ * value is missing and cannot say what to set.
+ */
+export declare const secretEnvKey: (field: string) => string;
+/**
+ * A destructive-action confirmation is one-shot and must never persist into a recording.
+ *
+ * This is also where a REDACTED fill is supplied back. Stripping credentials out of a git-checked
+ * flow is only half a fix: sign-in still has to replay, and a flow that drifts at step two forever
+ * because its own password was removed is a flow nobody keeps — along with everything behind the
+ * login it guards. The value comes from the environment, the one place a secret can live that is
+ * neither the customer's repository nor our database.
+ *
+ * Left as the PLACEHOLDER when nothing supplies it, rather than blanked. The replay then fails at
+ * the login form with `<redacted: supply at replay>` visible in the field, which names its own fix;
+ * an empty box fails identically and tells the reader nothing.
+ */
+export declare function replayActionArgs(value: unknown, confirmDangerous?: boolean, field?: string): Record<string, unknown>;
 /**
  * Capture an act into every in-flight recording, or do nothing when none is running.
  *

package/dist/flows/replay.js

@@ -1,3 +1,4 @@
+import { REDACTED_FILL } from './flows.js';
 import { DANGEROUS_ACTION_CONFIRM_ARG, ReticleCommand, QueryBy, } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { predicateToExpect, enforcedOnReplay } from './predicate-to-expect.js';
@@ -23,12 +24,37 @@ export function queryRefs(result) {
     const elements = Array.isArray(payload['elements']) ? payload['elements'] : [];
     return elements.map((e) => asString(asRecord(e)['ref']) ?? '').filter((r) => r.length > 0);
 }
-/** A destructive-action confirmation is one-shot and must never persist into a recording. */
-export function replayActionArgs(value, confirmDangerous = false) {
+/**
+ * The environment variable that supplies one redacted field.
+ *
+ * Named after the field so it is guessable from the flow alone: `auth-password` is read from
+ * `RETICLE_SECRET_AUTH_PASSWORD`. A scheme requiring a lookup table would mean the flow says a
+ * value is missing and cannot say what to set.
+ */
+export const secretEnvKey = (field) => `RETICLE_SECRET_${field.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase()}`;
+/**
+ * A destructive-action confirmation is one-shot and must never persist into a recording.
+ *
+ * This is also where a REDACTED fill is supplied back. Stripping credentials out of a git-checked
+ * flow is only half a fix: sign-in still has to replay, and a flow that drifts at step two forever
+ * because its own password was removed is a flow nobody keeps — along with everything behind the
+ * login it guards. The value comes from the environment, the one place a secret can live that is
+ * neither the customer's repository nor our database.
+ *
+ * Left as the PLACEHOLDER when nothing supplies it, rather than blanked. The replay then fails at
+ * the login form with `<redacted: supply at replay>` visible in the field, which names its own fix;
+ * an empty box fails identically and tells the reader nothing.
+ */
+export function replayActionArgs(value, confirmDangerous = false, field) {
     const args = { ...asRecord(value) };
     delete args[DANGEROUS_ACTION_CONFIRM_ARG];
     if (confirmDangerous)
         args[DANGEROUS_ACTION_CONFIRM_ARG] = true;
+    if (REDACTED_FILL === args['value'] && field !== undefined) {
+        const supplied = process.env[secretEnvKey(field)];
+        if (supplied !== undefined && supplied.length > 0)
+            args['value'] = supplied;
+    }
     return args;
 }
 /** The element's source location from an action result, when the framework stamped one. */

package/dist/flows/server-verify.js

@@ -1,5 +1,6 @@
 import { VerifyMode } from '../cloud/cloud-config.js';
-import { submitServerVerification } from '../cloud/cloud-sync.js';
+import { CLOUD_VERIFY_TIMEOUT_MS, cloudFetch, submitServerVerification, } from '../cloud/cloud-sync.js';
+import { log } from '../log.js';
 const PASS = 'pass';
 const UNVERIFIED = 'unverified';
 const SOURCE = 'reticle-mcp';
@@ -31,7 +32,20 @@ export async function runServerVerify(deps, cloud, sessionId, flows) {
     // The server hits the URL itself; with no URL (or a localhost one it can't reach) fall back to local.
     if (previewUrl === undefined || 0 === previewUrl.length)
         return null;
-    const report = await submitServerVerification({ previewUrl, flows, source: SOURCE }, cloud.config, (url, init) => fetch(url, init));
+    // The submit blocks while the hosted runner drives a real browser, so it gets the long budget — but a
+    // budget it must have: this is awaited inside the verify tool, and an unbounded wait here is an MCP
+    // call that never returns. A timeout is reported and then falls back to the local replay below.
+    const report = await submitServerVerification({ previewUrl, flows, source: SOURCE }, cloud.config, async (url, init) => {
+        try {
+            return await cloudFetch(url, init, CLOUD_VERIFY_TIMEOUT_MS);
+        }
+        catch (error) {
+            log('cloud-server-verify-failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    });
     if (null === report)
         return null;
     // The hosted runner said it couldn't actually verify (e.g. it's not enabled yet). Never surface that as

package/dist/flows/verify-change-tools.js

@@ -5,6 +5,7 @@ import { attributedFailures } from './attributed-failure.js';
 import { Verified } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asRecord, asString } from '../tools/tools-helpers.js';
+import { workerCountSchema } from '../tools/numeric-bounds.js';
 import { loadNamedFlows, resolveChangedFiles } from '../cli/cli-flow-commands.js';
 import { affectedSavedFlows } from './flow-sources.js';
 import { FLOW_TOOLS } from './flow-tools.js';
@@ -25,8 +26,7 @@ export const VERIFY_CHANGE_TOOLS = [
                 .string()
                 .optional()
                 .describe('Git ref to diff against (e.g. "HEAD~1", "main"). Unioned with `files`.'),
-            parallel: z
-                .number()
+            parallel: workerCountSchema
                 .optional()
                 .describe('Replay this many affected flows at once (needs the browser pool).'),
             sessionId: z
@@ -197,7 +197,13 @@ async function inspectAfterReplay(deps, args, cursor) {
     }
     try {
         const session = deps.sessions.resolve(asString(args['sessionId']));
-        const contradictions = findContradictions(session.eventsSince(cursor));
+        const contradictions = findContradictions(session.eventsSince(cursor), {
+            currentDocumentId: session.currentDocumentId,
+            currentEditEpoch: session.currentEditEpoch,
+            appOrigin: session.url,
+            // The replay is the action, and the cursor is where it started.
+            actionSince: cursor,
+        });
         const snapshot = await session.command(ReticleCommand.SNAPSHOT, {
             mode: SnapshotMode.INTERACTIVE,
         });

package/dist/honesty/blind-spots.d.ts

@@ -6,7 +6,7 @@
  */
 export { BlindSpotKind } from '@reticlehq/core';
 import { BlindSpotKind, type ReticleEvent } from '@reticlehq/core';
-interface BlindSpot {
+export interface BlindSpot {
     kind: BlindSpotKind;
     count: number;
 }
@@ -55,6 +55,15 @@ export declare function buildCoverageStatement(spots: readonly BlindSpot[]): Cov
  * from what the SDK observed during the action, with no extra round-trip.
  */
 export declare function blindSpotsFromEvents(events: readonly ReticleEvent[]): BlindSpot[];
+/**
+ * Drop Electron-only coverage rows unless this session is actually an Electron renderer.
+ *
+ * The kinds live in the same vocabulary as "no store registered", so listing whatever is present
+ * reported a Vite + React tab as an un-instrumented Electron renderer. The session already knows
+ * the runtime (PAGE_HEALTH). Unknown runtime (older SDK) keeps the rows — dropping them would hide
+ * a real missing-preload warning.
+ */
+export declare function spotsForRuntime(spots: readonly BlindSpot[], runtime: string | undefined): BlindSpot[];
 /**
  * Blind spots from the session's remembered LEVEL state rather than from a window of events.
  *
@@ -63,25 +72,35 @@ export declare function blindSpotsFromEvents(events: readonly ReticleEvent[]): B
  * reports "full" for a page a third of which is unobservable — and the act tool's own description
  * tells harnesses to gate on that block. Ask the session what is true now instead of inferring it
  * from what happened to be said recently.
+ *
+ * `runtime` gates Electron-only kinds (see `spotsForRuntime`) so a web session cannot inherit them
+ * from the coverage vocabulary.
  */
-export declare function blindSpotsFromState(state: Readonly<Record<string, number>>): BlindSpot[];
+export declare function blindSpotsFromState(state: Readonly<Record<string, number>>, runtime?: string): BlindSpot[];
 /**
- * Events the BROWSER's own transport queue threw away inside this window, or 0.
+ * The narrow slice of a predicate the absence-blind-spot check needs.
  *
- * `RATE_LIMITED` — the BRIDGE sampling because events arrived faster than its per-second cap — is
- * already the one blind spot that `impeachesCapture`, on the reasoning that a green over a window
- * you did not fully see "would only describe what was observed". `TRANSPORT_OVERFLOW` is the exact
- * same loss on the other side of the wire, and it was read in journal rollups and NOWHERE on the
- * verdict path. So the identical condition downgraded a verdict from one side of the socket and was
- * invisible from the other: a window that dropped 34 events graded `proved`, in a sentence whose own
- * words were "over a clean capture".
+ * Kept minimal to avoid pulling the full Predicate type (and its transitive deps) into the
+ * honesty module. Anything that quacks like this works.
+ */
+interface AbsencePredicate {
+    kind: string;
+    absent?: boolean;
+    query?: {
+        scope?: unknown;
+    };
+}
+/**
+ * When an absence assertion targets a page with regions Reticle cannot observe, "the element is
+ * absent" means only "it is absent in what I CAN see". Returns a note when that distinction
+ * matters, undefined otherwise.
  *
- * `TRUNCATED` is deliberately NOT counted. It names the channel it capped (a DOM-mutation flood on
- * any busy page) and is routine churn; treating it as lost evidence would caveat every verdict on
- * every real app, and a caveat that is always present is one nobody reads. TRANSPORT_OVERFLOW is the
- * honest "arbitrary events are gone" marker — it cannot say which.
+ * Fires on three blind-spot kinds:
+ *   - CROSS_ORIGIN_IFRAME (only when the predicate is scoped to a frame region)
+ *   - VIRTUALIZED_UNMOUNTED — a row that was never rendered could hold the element
+ *   - CLOSED_SHADOW_ROOT — a subtree Reticle cannot see into
  */
-export declare function droppedByTransport(events: readonly ReticleEvent[]): number;
+export declare function absenceBlindSpotNote(predicate: AbsencePredicate, spots: readonly BlindSpot[]): string | undefined;
 /** The impeaching note for a transport gap, or undefined when the window was intact. */
 export declare function transportGapNote(events: readonly ReticleEvent[]): string | undefined;
 /**
@@ -93,3 +112,20 @@ export declare function transportGapNote(events: readonly ReticleEvent[]): strin
  * predicate would eventually disagree with the first about what "unwatched" means.
  */
 export declare function isStateUnwatched(spots: readonly BlindSpot[]): boolean;
+/**
+ * Does a passing verdict on this predicate REST on the window being complete?
+ *
+ * Only an absence claim does. A positive assertion that passed found its evidence, and events aged
+ * out elsewhere in the buffer do not unmake it. An absence claim concluded "nothing is there" — and
+ * the thing the buffer dropped is precisely the disproof, so "absent" degrades to "absent in what I
+ * still hold".
+ *
+ * The distinction is not optional. Scarce-loss is recorded for AGE eviction too, so `lostSince(0)`
+ * is true on any session older than the 60s cutoff; impeaching every verdict over a caller-chosen
+ * window would make `unknown` the answer to everything, which this repo has already paid for once.
+ */
+export declare function restsOnCompleteWindow(predicate: {
+    kind: string;
+    absent?: boolean;
+    predicate?: unknown;
+}): boolean;

package/dist/honesty/blind-spots.js

@@ -7,7 +7,7 @@
 // The kind enum lives in core (it crosses the wire in a BLIND_SPOT event); re-exported here so existing
 // honesty-side imports keep working.
 export { BlindSpotKind } from '@reticlehq/core';
-import { BlindSpotKind, EventType, ReticleEnv, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { AppRuntime, BlindSpotKind, EventType, PredicateKind, ReticleEnv, TRANSPORT_LIMITS, isDesktopBlindSpot, } from '@reticlehq/core';
 /**
  * Whether the observation window saw everything it was asked about.
  *
@@ -107,6 +107,19 @@ export function blindSpotsFromEvents(events) {
     }
     return [...latest].map(([kind, count]) => ({ kind, count }));
 }
+/**
+ * Drop Electron-only coverage rows unless this session is actually an Electron renderer.
+ *
+ * The kinds live in the same vocabulary as "no store registered", so listing whatever is present
+ * reported a Vite + React tab as an un-instrumented Electron renderer. The session already knows
+ * the runtime (PAGE_HEALTH). Unknown runtime (older SDK) keeps the rows — dropping them would hide
+ * a real missing-preload warning.
+ */
+export function spotsForRuntime(spots, runtime) {
+    if (runtime === undefined || AppRuntime.ELECTRON === runtime)
+        return [...spots];
+    return spots.filter((spot) => !isDesktopBlindSpot(spot.kind));
+}
 /**
  * Blind spots from the session's remembered LEVEL state rather than from a window of events.
  *
@@ -115,9 +128,16 @@ export function blindSpotsFromEvents(events) {
  * reports "full" for a page a third of which is unobservable — and the act tool's own description
  * tells harnesses to gate on that block. Ask the session what is true now instead of inferring it
  * from what happened to be said recently.
+ *
+ * `runtime` gates Electron-only kinds (see `spotsForRuntime`) so a web session cannot inherit them
+ * from the coverage vocabulary.
  */
-export function blindSpotsFromState(state) {
-    return Object.entries(state).map(([kind, count]) => ({ kind: kind, count }));
+export function blindSpotsFromState(state, runtime) {
+    const spots = Object.entries(state).map(([kind, count]) => ({
+        kind: kind,
+        count,
+    }));
+    return spotsForRuntime(spots, runtime);
 }
 /**
  * Events the BROWSER's own transport queue threw away inside this window, or 0.
@@ -135,7 +155,7 @@ export function blindSpotsFromState(state) {
  * every real app, and a caveat that is always present is one nobody reads. TRANSPORT_OVERFLOW is the
  * honest "arbitrary events are gone" marker — it cannot say which.
  */
-export function droppedByTransport(events) {
+function droppedByTransport(events) {
     let dropped = 0;
     for (const e of events) {
         if (e.type !== EventType.TRANSPORT_OVERFLOW)
@@ -145,6 +165,29 @@ export function droppedByTransport(events) {
     }
     return dropped;
 }
+/**
+ * When an absence assertion targets a page with regions Reticle cannot observe, "the element is
+ * absent" means only "it is absent in what I CAN see". Returns a note when that distinction
+ * matters, undefined otherwise.
+ *
+ * Fires on three blind-spot kinds:
+ *   - CROSS_ORIGIN_IFRAME (only when the predicate is scoped to a frame region)
+ *   - VIRTUALIZED_UNMOUNTED — a row that was never rendered could hold the element
+ *   - CLOSED_SHADOW_ROOT — a subtree Reticle cannot see into
+ */
+export function absenceBlindSpotNote(predicate, spots) {
+    if ('element' !== predicate.kind || true !== predicate.absent)
+        return undefined;
+    const relevant = spots.filter((spot) => spot.count > 0 &&
+        (spot.kind === BlindSpotKind.CROSS_ORIGIN_IFRAME
+            ? undefined !== predicate.query?.scope
+            : spot.kind === BlindSpotKind.VIRTUALIZED_UNMOUNTED ||
+                spot.kind === BlindSpotKind.CLOSED_SHADOW_ROOT));
+    if (0 === relevant.length)
+        return undefined;
+    const statement = buildCoverageStatement(relevant);
+    return `the absence assertion targeted a region Reticle could not observe (${statement.note ?? 'partial coverage'}), so a passing DOM check cannot prove absence`;
+}
 /** The impeaching note for a transport gap, or undefined when the window was intact. */
 export function transportGapNote(events) {
     const dropped = droppedByTransport(events);
@@ -163,3 +206,20 @@ export function transportGapNote(events) {
 export function isStateUnwatched(spots) {
     return spots.some((spot) => spot.kind === BlindSpotKind.UNWATCHED_STATE && spot.count > 0);
 }
+/**
+ * Does a passing verdict on this predicate REST on the window being complete?
+ *
+ * Only an absence claim does. A positive assertion that passed found its evidence, and events aged
+ * out elsewhere in the buffer do not unmake it. An absence claim concluded "nothing is there" — and
+ * the thing the buffer dropped is precisely the disproof, so "absent" degrades to "absent in what I
+ * still hold".
+ *
+ * The distinction is not optional. Scarce-loss is recorded for AGE eviction too, so `lostSince(0)`
+ * is true on any session older than the 60s cutoff; impeaching every verdict over a caller-chosen
+ * window would make `unknown` the answer to everything, which this repo has already paid for once.
+ */
+export function restsOnCompleteWindow(predicate) {
+    if (PredicateKind.NOT === predicate.kind)
+        return true;
+    return true === predicate.absent;
+}

package/dist/honesty/feature-capture.d.ts

@@ -0,0 +1,150 @@
+import { type Intent, type JournalAction } from '@reticlehq/core';
+/**
+ * Were `reticle_context` and `reticle_intent` used at all — and did using them change anything?
+ *
+ * Both shipped with the same pre-registered disproof: *if agents never call it, cut it*. Nothing
+ * recorded whether they were called, so the disproof could never be run, and a feature whose
+ * disproof cannot be run is one nobody can kill. This is the smallest thing that makes the question
+ * answerable, per session, locally — an instrument, not a scold. The numbers exist so a FEATURE can
+ * be removed, never so an agent can be blamed for how it drove.
+ *
+ * ## Fold first, record only what nothing records
+ *
+ * Three of the four questions are already answerable from what is on disk. The intent ledger says
+ * what was declared; the journal says what was driven and what verdicts were drawn. Those are folded
+ * here and never re-stored, for the reason `run-context.ts` gives at length: two ways to compute one
+ * number is worse than one way.
+ *
+ * The journal does NOT record read-only calls — it holds actions and verdicts only. So "was
+ * `reticle_context` called" has no ledger to fold, and that one thing is recorded, in memory, on the
+ * session, by `CaptureLedger`. It is the whole of the new state.
+ *
+ * ## Absent is not zero
+ *
+ * A session this daemon has recorded nothing for — journaling off, a session adopted after the fact
+ * — reports `observed: false` and states no counts at all. It has not established that the features
+ * went unused; it has established that it was not watching. This repo has shipped the other bug
+ * twice.
+ */
+/**
+ * The calls this instrument needs and the journal does not keep.
+ *
+ * Deliberately a short explicit list rather than "everything that is not an action". Under-inclusion
+ * is the safe direction: a read tool missing from here lowers the hit side and the miss side by the
+ * same call, so the comparison the disproof turns on stays fair. Over-inclusion is not — a lifecycle
+ * or disk-side tool landing in here would be counted as a "read" the agent made of the app, which it
+ * was not.
+ */
+export declare const CAPTURED_TOOLS: ReadonlySet<string>;
+/** One recorded call: which tool, what it was about, and how far into the run it happened. */
+export interface CapturedCall {
+    tool: string;
+    /** The ref or target the call named, when it named one. Absent for a whole-page read. */
+    subject?: string;
+    /**
+     * The session's dispatched-action count at the moment of the call — the same counter that mints
+     * journal action ids, so it lines up with `reticle_context`'s own `step` whenever the journal is on.
+     */
+    afterActions: number;
+}
+/**
+ * The one thing that is stored rather than folded: the read-only calls the journal never sees.
+ *
+ * In memory and per session, the same shape as `GapLedger`. It is not durable on purpose — the
+ * question is about one run, and a second file on disk would be a second thing to reconcile with the
+ * journal.
+ */
+export declare class CaptureLedger {
+    #private;
+    /**
+     * One call, under the name of the tool that RAN — every tool, not just the read set above.
+     *
+     * Separate from `note` because it answers a different question and is bounded differently: this
+     * map cannot outgrow the tool table however long the session runs, so it needs no cap and never
+     * has to report a floor. See honesty/tool-hit-rate.ts for what it feeds.
+     */
+    noteTool(tool: string): void;
+    /** How many times each tool was called this session, in first-call order. */
+    toolCalls(): ReadonlyMap<string, number>;
+    note(call: CapturedCall): void;
+    calls(): readonly CapturedCall[];
+    /** How many calls fell off the front. Non-zero means the counts below are a floor. */
+    get dropped(): number;
+}
+/**
+ * Record one captured call against the session that made it.
+ *
+ * Tolerates a session that carries no ledger, exactly as `noteSessionGaps` does and for the same
+ * reason: `Session` is satisfied structurally, and many specs — plus any consumer embedding this
+ * engine — build one as an object literal. Such a session is a real caller that simply keeps no
+ * ledger, and an instrument must never be the reason a tool call throws. Its calls are then absent
+ * rather than counted as zero, which is what `observed: false` exists to say.
+ */
+export declare function noteCapturedCall(session: {
+    capture?: CaptureLedger;
+    actionCount?: number;
+}, call: Omit<CapturedCall, 'afterActions'>): void;
+/**
+ * Count one call against the session that made it, whichever tool it was.
+ *
+ * Tolerant of a ledger-less session for exactly the reason `noteCapturedCall` is: its calls are then
+ * absent rather than counted as zero, which is what `observed: false` exists to say.
+ */
+export declare function noteToolDispatched(session: {
+    capture?: CaptureLedger;
+}, tool: string): void;
+/** What one session's use of the two features looks like. Everything but `observed` is omitted when nothing was recorded. */
+export interface FeatureCapture {
+    /** False when this daemon recorded nothing for the session — "not watched", never "not used". */
+    observed: boolean;
+    /** The ledger dropped calls, so every count is a floor. Present only when true. */
+    truncated?: boolean;
+    context?: {
+        calls: number;
+        /** The dispatched-action count each call was made at, in order. */
+        atSteps: number[];
+        acted: number;
+        refetched: number;
+        readOther: number;
+        nothingAfter: number;
+    };
+    intents?: {
+        declared: number;
+        open: number;
+    };
+    missed?: {
+        verdictsWithNoIntentDeclared: number;
+        refetchedEstablished: number;
+    };
+}
+/**
+ * Did calling `reticle_context` change what happened next?
+ *
+ * The mechanical proxy, stated so it can be argued with: look at the very next recorded call. If an
+ * action was dispatched before it — the action counter moved — the agent ACTED, and the context
+ * plausibly helped. If instead the next call is a read of a subject the context had just supplied,
+ * the agent re-fetched what it had been handed, and the context did not help.
+ *
+ * ## What this proxy CANNOT see
+ *
+ *  - Whether the agent READ the response, reasoned over it, or wrote a better answer from it. There
+ *    is no signal for that anywhere, and this must not be mistaken for one.
+ *  - Anything that happens between two Reticle calls: source edits, calls to other MCP servers, a
+ *    turn ending, a human interrupting. A long gap is invisible and reads as adjacency.
+ *  - Reads that name no ref or target (a whole-page snapshot). They land in `readOther`, never in
+ *    `refetched`, so a snapshot that duplicated the context is under-counted, not over-counted.
+ *  - Causation. `acted` is proximity in a call sequence, nothing more. An agent that would have acted
+ *    anyway is indistinguishable from one the context unblocked.
+ *  - `reticle_context` called with no session connected — it answers there by design, and there is no
+ *    per-session ledger to record it against, so those calls are missing entirely.
+ *  - Two agents driving one session. Their calls interleave into one sequence and "next call" stops
+ *    meaning "next thing that agent did".
+ */
+export declare function foldFeatureCapture(input: {
+    calls: readonly CapturedCall[];
+    dropped: number;
+    actions: readonly JournalAction[];
+    intents: readonly Intent[];
+    /** The session's dispatched-action count now, so a run that ended on an action is not read as idle. */
+    finalActions: number;
+}): FeatureCapture;