@reticlehq/server 2.11.0 → 2.12.0

package/dist/flows/flow-replay-run.js

@@ -3,6 +3,10 @@ import { asString } from '../tools/tools-helpers.js';
 import { replayFlow } from './flow-replay.js';
 import { assertSuccess, dynamicTestids, successLabel, SUCCESS_STEP_TOOL } from './flow-success.js';
 import { buildDecision, unverifiableReason } from './decision.js';
+import { classifyFlowAssertions } from './flow-classify.js';
+import { dischargeFlowIntent, flowIntentStatement, flowReplayVerdictId } from './flow-intent.js';
+import { IntentStore } from '../intent/intent-store.js';
+import { sessionRoot } from '../project/session-root.js';
 import { waitForPredicate } from '../events/predicate.js';
 import { computeSegments } from '../journal/rollups.js';
 import { AssertionTiersStore } from './assertion-tiers-store.js';
@@ -10,7 +14,7 @@ import { toFlowSources } from './flow-sources.js';
 import { reportAndAccumulate } from '../journal/deviation-service.js';
 import { EnvelopeStore } from '../journal/envelope-store.js';
 import { homedir } from 'node:os';
-import { syncRunRecordToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { cloudFetch, syncRunRecordToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
 import { log } from '../log.js';
 export function latestRecordedFlow(events) {
@@ -66,7 +70,7 @@ async function recordReplayRun(deps, name, status, driftSteps, durationMs, proje
     const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
     if (null === cloud.config || !cloud.policy.memory)
         return; // not attached / memory disabled → local only
-    const result = await syncRunRecordToCloud({ kind: RunKind.FLOW_REPLAY, name, status: runStatus, at: deps.now(), durationMs }, projectId, cloud.config, (url, init) => fetch(url, init));
+    const result = await syncRunRecordToCloud({ kind: RunKind.FLOW_REPLAY, name, status: runStatus, at: deps.now(), durationMs }, projectId, cloud.config, cloudFetch);
     if (result.outcome !== SyncOutcome.SYNCED) {
         log('cloud-run-record-sync-failed', { flow: name, status: result.status, error: result.error });
     }
@@ -120,6 +124,13 @@ export async function replayNamedFlow(deps, args) {
             error: { code: loaded.code, message: flowErrorMessage(loaded.code) },
         };
     }
+    // What this flow is FOR, from the shared ledger — so a failure can report the business outcome
+    // that stopped being true before the step that stopped being green. Undefined when nothing
+    // declared one, which the decision then says plainly rather than inventing a goal from step names.
+    const intents = new IntentStore(deps.fs, sessionRoot(deps, asString(args['sessionId'])), {
+        now: deps.now,
+    });
+    const intentSaid = await flowIntentStatement(intents, loaded.value);
     const session = deps.sessions.resolve(asString(args['sessionId']));
     // Captured before replay: if the tab isn't on the flow's start page, a step-1 drift is a wrong-page
     // symptom, not a regression — surface that on the decision instead of a bare "a step no longer matches".
@@ -156,6 +167,18 @@ export async function replayNamedFlow(deps, args) {
         })), 
         // Record what this flow COVERS so a later deletion can be scoped to the files that changed.
         toFlowSources([{ name, steps: loaded.value.steps }])[0]?.sources ?? []);
+        // The ledger learns what this run proved. Only a flow that COULD have gone red discharges: an
+        // assertion-free flow is never bound, and `dischargeIntent` refuses an unbound intent, so the
+        // guard here is the cheap half of a rule the ledger already enforces. `grade` is what makes a
+        // later weakening visible — an intent re-proved by a weaker flow says so in the git diff.
+        if (unverifiableReason(loaded.value) === undefined) {
+            const provedAt = deps.now();
+            await dischargeFlowIntent(intents, loaded.value, {
+                verdictId: flowReplayVerdictId(name, provedAt),
+                grade: classifyFlowAssertions(loaded.value).grade,
+                at: provedAt,
+            });
+        }
     }
     // Push-default: the deviation report over this drive's segments, learned across runs. Best-effort.
     const deviation = await computeReplayDeviation(deps, session, replayFloor);
@@ -167,7 +190,7 @@ export async function replayNamedFlow(deps, args) {
             steps,
             error: { code: ReplayStatus.ERROR, message: failed.error ?? 'flow action failed' },
         };
-        errored.decision = buildDecision(errored, loaded.value);
+        errored.decision = buildDecision(errored, loaded.value, intentSaid);
         applyStartPathHint(errored, startPathHint);
         if (deviation !== undefined)
             errored.deviation = deviation;
@@ -182,7 +205,7 @@ export async function replayNamedFlow(deps, args) {
     if (cannotFail !== undefined)
         result.unverifiable = { reason: cannotFail };
     if (status !== ReplayStatus.OK)
-        result.decision = buildDecision(result, loaded.value);
+        result.decision = buildDecision(result, loaded.value, intentSaid);
     applyStartPathHint(result, startPathHint);
     if (deviation !== undefined)
         result.deviation = deviation;

package/dist/flows/flow-success.js

@@ -38,9 +38,21 @@ export function successLabel(success) {
 export function successToPredicate(success, dynamic) {
     const parts = [];
     if (success.signal !== undefined) {
-        parts.push(success.signalData !== undefined
-            ? { kind: PredicateKind.SIGNAL, name: success.signal, dataMatches: success.signalData }
-            : { kind: PredicateKind.SIGNAL, name: success.signal });
+        const signal = {
+            kind: PredicateKind.SIGNAL,
+            name: success.signal,
+        };
+        if (success.signalData !== undefined)
+            signal.dataMatches = success.signalData;
+        if (success.signalCount !== undefined) {
+            signal.count = success.signalCount;
+            // Same post-settle reasoning as net.count: the success waiter is wait-until-true, so an exact
+            // count is transiently satisfied the instant the FIRST matching signal fires — before a
+            // double-fire's duplicate arrives. Gating on `settled` forces the count to be read only after
+            // the app goes quiet, by which point the duplicate IS counted and the over-count fails.
+            parts.push({ kind: PredicateKind.SETTLED });
+        }
+        parts.push(signal);
     }
     if (success.net !== undefined) {
         const net = { kind: PredicateKind.NET };

package/dist/flows/flow-tools.js

@@ -6,7 +6,7 @@ import { recordSuiteFlakes } from './suite-flakes.js';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
 import { log } from '../log.js';
-import { syncFlowToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { cloudFetch, syncFlowToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 import { mapWithConcurrency, resolveConcurrency } from './parallel-suite.js';
 import { acquireLeasedSession } from '../tools/lease-tools.js';
 import { homedir } from 'node:os';
@@ -30,7 +30,7 @@ async function syncSavedFlowToCloud(deps, flow, projectId) {
     const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
     if (null === cloud.config || !cloud.policy.flows)
         return; // not attached / flows disabled → local only
-    const result = await syncFlowToCloud(flow, cloud.config, projectId, (url, init) => fetch(url, init));
+    const result = await syncFlowToCloud(flow, cloud.config, projectId, cloudFetch);
     if (result.outcome !== SyncOutcome.SYNCED) {
         log('cloud-flow-sync-failed', { flow: flow.name, status: result.status, error: result.error });
     }
@@ -86,6 +86,17 @@ function flowsForSession(deps, projectId) {
     }
     return { flows: new FlowStore(deps.fs, resolved.root, { now: deps.now }), root: resolved.root };
 }
+/**
+ * How a save reports that nobody said what the flow is for.
+ *
+ * Declared once and shared by every save tool: an undeclared field is stripped from
+ * `structuredContent` by a schema-strict MCP client, so a save path that forgot this line would
+ * report the nudge to the unit tests and to nobody else.
+ */
+const INTENT_GAP_FIELD = z
+    .unknown()
+    .optional()
+    .describe('Present ONLY when the flow was saved with nothing saying what it is for: { kind, missing, cost, fix }. The flow is on disk either way — this never blocks a save. Close it by saving again with `intent`, or by setting the flow file’s `intentId` to an intent already in the ledger. Nothing here is ever derived from the flow name, the steps or the assertions: a guessed goal reads as the author’s own words.');
 export const FLOW_TOOLS = [
     {
         name: ReticleTool.FLOW_SAVE,
@@ -98,6 +109,10 @@ export const FLOW_TOOLS = [
             flowName: z
                 .string()
                 .describe('Name for the flow file (saved to .reticle/flows/<flowName>.json). Use again in reticle_flow{action:"load"} / reticle_flow_replay.'),
+            intent: z
+                .string()
+                .optional()
+                .describe('What this flow is FOR, in prose: which user does what, and what should become true. Answer it here rather than in a second call. Without it the flow still saves, but the day it goes red the report can only name the step that broke, not the thing that stopped being true.'),
             sessionId: z
                 .string()
                 .optional()
@@ -124,6 +139,7 @@ export const FLOW_TOOLS = [
                 warning: z.string().optional(),
             })
                 .optional(),
+            intentGap: INTENT_GAP_FIELD,
             error: z.string().optional(),
             code: z.string().optional(),
         },
@@ -138,7 +154,9 @@ export const FLOW_TOOLS = [
             }
             // fold any structured annotations (expect/dynamic/success/intent) onto the saved flow.
             const success = deps.annotations.success(name);
-            const intent = deps.annotations.intent(name);
+            // The inline argument wins over an annotation left from an earlier call: it is the more recent
+            // statement, and it is the one the author just typed.
+            const intent = asString(args['intent']) ?? deps.annotations.intent(name);
             const annotations = {
                 stepExpect: deps.annotations.stepExpect(name),
                 dynamic: deps.annotations.dynamic(name),
@@ -477,6 +495,10 @@ export const FLOW_TOOLS = [
                 .string()
                 .optional()
                 .describe('Override the flow name embedded in the recorded flow. Omit to use the recorder-assigned name.'),
+            intent: z
+                .string()
+                .optional()
+                .describe('What this flow is FOR, in prose: which user does what, and what should become true. The recorder captures clicks, not goals, so this is the only place the goal can come from. Without it the flow still saves, but the day it goes red the report can only name the step that broke.'),
             ...{
                 sessionId: z
                     .string()
@@ -491,6 +513,7 @@ export const FLOW_TOOLS = [
             stepCount: z.number().optional(),
             degraded: z.number().optional(),
             empty: z.boolean().optional(),
+            intentGap: INTENT_GAP_FIELD,
             error: z.string().optional(),
             code: z.string().optional(),
         },
@@ -504,7 +527,12 @@ export const FLOW_TOOLS = [
                 };
             }
             const override = asString(aliasParam(args, 'flowName', ['flow'])['flowName']);
-            const flow = override !== undefined ? { ...recorded.flow, name: override } : recorded.flow;
+            const intent = asString(args['intent']);
+            const flow = {
+                ...recorded.flow,
+                ...(override === undefined ? {} : { name: override }),
+                ...(intent === undefined ? {} : { intent }),
+            };
             // The store stamps the project into the file AND routes it to the per-project subdir (a shared
             // daemon serves many apps), so location and content agree from one source of truth.
             const emptyRecorded = emptyFlowRefusal(flow.steps.length, flow.name);

package/dist/flows/flows.d.ts

@@ -1,5 +1,5 @@
 import { FlowErrorCode } from '@reticlehq/core';
-import type { FlowAnchor, FlowExpect, FlowFile, FlowStep, HealChange } from '@reticlehq/core';
+import type { FlowAnchor, FlowExpect, FlowFile, FlowStep, HealChange, InstrumentationGap } from '@reticlehq/core';
 import type { CompiledProgram, RecordedStep } from './recordings.js';
 import type { FileSystemPort } from '../project/fs-port.js';
 /** A monotonic clock injected for createdAt — never call Date.now inside the store (rule 7). */
@@ -30,6 +30,11 @@ interface SaveSummary {
     stepCount: number;
     degraded: number;
     empty: boolean;
+    /**
+     * Present only when the flow was saved with nothing saying what it is for. Never blocks the save,
+     * and absent the moment the flow carries prose or an `intentId`. See `flowIntentGap`.
+     */
+    intentGap?: InstrumentationGap;
 }
 /**
  * The structured annotations folded onto a flow at save time: per-step

package/dist/flows/flows.js

@@ -3,6 +3,8 @@ import { AnchorKind, DEGRADED_ANCHOR_ROLE, FLOW_FILE_VERSION, FlowErrorCode, Flo
 import { ReticleTool } from '../tools/tool-names.js';
 import { asString, asRecord } from '../tools/tools-helpers.js';
 import { applyHealChanges } from './heal.js';
+import { flowIntentGap, linkFlowIntent } from './flow-intent.js';
+import { IntentStore } from '../intent/intent-store.js';
 import { flowDir, flowPath, reticleDirPaths, isValidFlowName } from '../project/reticle-dir.js';
 /**
  * A projectId only scopes storage when it's a safe single path segment (it's stamped from the
@@ -168,6 +170,34 @@ export class FlowStore {
     #serialize(flow) {
         return `${JSON.stringify(flow, null, JSON_INDENT)}\n`;
     }
+    /**
+     * Register the flow's business goal in the intent ledger and stamp the row's id onto the flow.
+     *
+     * Both save paths route through here — the compiled-recording one and the in-page recorder one —
+     * because a flow's goal must land in the ledger whichever way the flow arrived. A flow with no
+     * goal is returned untouched and nothing is written, so an older flow keeps its exact bytes.
+     */
+    #linkIntent(flow) {
+        return linkFlowIntent(new IntentStore(this.#fs, this.#root, this.#clock), flow);
+    }
+    /**
+     * What a caller is told about a flow that just landed on disk.
+     *
+     * Both save paths build it here rather than each assembling their own object, because the two used
+     * to be duplicates and the intent nudge is exactly the kind of field that gets added to one of a
+     * pair. A flow saved by the recorder and a flow saved from a compiled recording are the same
+     * regression test, and must not report differently for having arrived by a different door.
+     */
+    #summary(flow) {
+        const gap = flowIntentGap(flow);
+        return {
+            name: flow.name,
+            stepCount: flow.steps.length,
+            degraded: flow.steps.filter((s) => true === s.degraded).length,
+            empty: 0 === flow.steps.length,
+            ...(gap === undefined ? {} : { intentGap: gap }),
+        };
+    }
     /**
      * Convert a CompiledProgram (testid-normalized) into an anchored, on-disk flow + write it.
      * Optionally fold structured annotations (per-step expect, dynamic[], success) onto
@@ -186,19 +216,10 @@ export class FlowStore {
             createdAt: this.#clock.now(),
             steps,
         };
-        const flow = withAnnotations(base, annotations);
+        const flow = await this.#linkIntent(withAnnotations(base, annotations));
         await this.#fs.mkdir(flowDir(this.#root, pid));
         await this.#fs.writeFile(flowPath(this.#root, program.name, pid), this.#serialize(flow));
-        const degraded = flow.steps.filter((s) => true === s.degraded).length;
-        return {
-            ok: true,
-            value: {
-                name: program.name,
-                stepCount: flow.steps.length,
-                degraded,
-                empty: 0 === flow.steps.length,
-            },
-        };
+        return { ok: true, value: this.#summary(flow) };
     }
     /**
      * Persist an already-anchored FlowFile captured in-page (no recompilation). The
@@ -215,19 +236,10 @@ export class FlowStore {
         const parsed = FlowFileSchema.safeParse(stamped);
         if (!parsed.success)
             return { ok: false, code: FlowErrorCode.PARSE_FAILED };
-        const valid = parsed.data;
+        const valid = await this.#linkIntent(parsed.data);
         await this.#fs.mkdir(flowDir(this.#root, pid));
         await this.#fs.writeFile(flowPath(this.#root, asFlowName(valid.name), pid), this.#serialize(valid));
-        const degraded = valid.steps.filter((s) => true === s.degraded).length;
-        return {
-            ok: true,
-            value: {
-                name: valid.name,
-                stepCount: valid.steps.length,
-                degraded,
-                empty: 0 === valid.steps.length,
-            },
-        };
+        return { ok: true, value: this.#summary(valid) };
     }
     /**
      * Apply confident testid rebinds to an on-disk flow (the reticle_flow_heal

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 = {};

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

@@ -197,7 +197,10 @@ 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,
+        });
         const snapshot = await session.command(ReticleCommand.SNAPSHOT, {
             mode: SnapshotMode.INTERACTIVE,
         });

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

@@ -65,23 +65,6 @@ export declare function blindSpotsFromEvents(events: readonly ReticleEvent[]): B
  * from what happened to be said recently.
  */
 export declare function blindSpotsFromState(state: Readonly<Record<string, number>>): BlindSpot[];
-/**
- * Events the BROWSER's own transport queue threw away inside this window, or 0.
- *
- * `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".
- *
- * `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.
- */
-export declare function droppedByTransport(events: readonly ReticleEvent[]): number;
 /** The impeaching note for a transport gap, or undefined when the window was intact. */
 export declare function transportGapNote(events: readonly ReticleEvent[]): string | undefined;
 /**

package/dist/honesty/blind-spots.js

@@ -135,7 +135,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)

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;