@reticlehq/server 3.2.0 → 3.4.0

package/dist/judgement/domain/domain-model.js

@@ -12,7 +12,7 @@
  *
  * Pure: no IO, no clock. The tool layer loads flows + contract and calls this.
  */
-import { AnchorKind, } from '@reticlehq/core';
+import { AnchorKind, PredicateKind, compareSourceClauses, } from '@reticlehq/core';
 import { classifyFlowAssertions, FlowAssertionGrade } from '../../language/flows/flow-classify.js';
 import { successLabel } from '../../language/flows/flow-success.js';
 import { flowRisk, latestRun, rankByRisk, RiskLevel } from './flow-risk.js';
@@ -25,16 +25,47 @@ function flatten(steps) {
     }
     return out;
 }
+/*
+ * The vocabulary a flow uses, read out of a predicate TREE.
+ *
+ * These were property reads when `expect` was a struct with one slot per kind. A predicate nests, and
+ * the domain model is about what a flow TALKS ABOUT, so the walk goes all the way down: a signal
+ * named inside an `allOf` two levels deep is still a signal this flow depends on, and missing it
+ * would quietly shrink the model that decides which flows a change affects.
+ */
+function walkClauses(predicate) {
+    if (predicate === undefined)
+        return [];
+    if (PredicateKind.ALL_OF === predicate.kind || PredicateKind.ANY_OF === predicate.kind) {
+        return predicate.predicates.flatMap(walkClauses);
+    }
+    if (PredicateKind.NOT === predicate.kind)
+        return walkClauses(predicate.predicate);
+    if (PredicateKind.COMPARE === predicate.kind)
+        return compareSourceClauses(predicate);
+    return [predicate];
+}
+function signalNamesIn(predicate) {
+    return walkClauses(predicate)
+        .filter((c) => PredicateKind.SIGNAL === c.kind)
+        .map((c) => (PredicateKind.SIGNAL === c.kind ? c.name : undefined))
+        .filter((name) => name !== undefined);
+}
+function elementTestidsIn(predicate) {
+    return walkClauses(predicate)
+        .map((c) => (PredicateKind.ELEMENT === c.kind ? c.query.testid : undefined))
+        .filter((testid) => testid !== undefined);
+}
 function flowSignals(flow) {
     const set = new Set();
     for (const step of flatten(flow.steps)) {
         if (step.anchor.kind === AnchorKind.SIGNAL)
             set.add(step.anchor.name);
-        if (step.expect?.signal !== undefined)
-            set.add(step.expect.signal);
+        for (const name of signalNamesIn(step.expect))
+            set.add(name);
     }
-    if (flow.success?.signal !== undefined)
-        set.add(flow.success.signal);
+    for (const name of signalNamesIn(flow.success))
+        set.add(name);
     return [...set];
 }
 function flowTestids(flow) {
@@ -42,11 +73,11 @@ function flowTestids(flow) {
     for (const step of flatten(flow.steps)) {
         if (step.anchor.kind === AnchorKind.TESTID)
             set.add(step.anchor.value);
-        if (step.expect?.element?.testid !== undefined)
-            set.add(step.expect.element.testid);
+        for (const testid of elementTestidsIn(step.expect))
+            set.add(testid);
     }
-    if (flow.success?.element?.testid !== undefined)
-        set.add(flow.success.element.testid);
+    for (const testid of elementTestidsIn(flow.success))
+        set.add(testid);
     return [...set];
 }
 const EMPTY_CONTRACT = { testids: [], signals: [], stores: [], flows: [] };

package/dist/judgement/oracles/self-instrument.js

@@ -9,7 +9,7 @@
  * `missing-signal` while honesty said `no-signal-on-mutation` for the same absence.
  */
 import { InstrumentationGapKind } from '@reticlehq/core/artifacts';
-/** PascalCase a store name for a `useX.getState` hint (cart → Cart). */
+/** PascalCase a store name for a `useX` hint (cart → Cart). */
 function pascal(name) {
     return 0 === name.length ? name : name[0]?.toUpperCase() + name.slice(1);
 }
@@ -18,7 +18,9 @@ function insertFor(gap) {
         case InstrumentationGapKind.NO_SIGNAL_ON_MUTATION:
             return `reticle.signal('${gap.name}');`;
         case InstrumentationGapKind.NO_STORE_REGISTERED:
-            return `registerStore('${gap.name}', () => use${pascal(gap.name)}.getState());`;
+            // The store itself, so its subscribe is wired too. A `() => useX.getState()` getter is
+            // readable but never reports a change, which is the state this gap is about (#1146).
+            return `registerStore('${gap.name}', use${pascal(gap.name)});`;
         case InstrumentationGapKind.MISSING_TESTID:
             return `data-testid="${gap.name}"`;
     }

package/dist/judgement/outcome/assertion-integrity.d.ts

@@ -1,4 +1,4 @@
-import { type FlowExpect } from '@reticlehq/core';
+import { type Predicate } from '@reticlehq/core';
 /**
  * Anti-reward-hacking (research-mandated). Test-gated agents pass gates by WEAKENING assertions — the
  * canonical documented failure. Flows are git-checked and agent-editable, so a mustHold that dropped
@@ -7,10 +7,10 @@ import { type FlowExpect } from '@reticlehq/core';
  * and flow_verify surface it.
  */
 /** True when `after` weakened `before` — a real consequence became a fakeable presence-only check. */
-export declare function isAssertionDowngrade(before: FlowExpect | undefined, after: FlowExpect | undefined): boolean;
+export declare function isAssertionDowngrade(before: Predicate | undefined, after: Predicate | undefined): boolean;
 export interface StepExpect {
     step: number;
-    expect?: FlowExpect;
+    expect?: Predicate;
 }
 interface DowngradeFinding {
     step: number;

package/dist/judgement/runs/artifact/gap-report.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The session gap, as a person reads it — and as a Stop hook prints it.
+ *
+ * `gapSummary` folds the journal into what was claimed and what held. This is its only renderer, so
+ * `reticle report` and the hook cannot describe the same session two different ways.
+ */
+import type { GapSummary } from './gap-summary.js';
+/**
+ * One line when the agent finishes without a single `yes`, and nothing otherwise.
+ *
+ * Silent after a `yes` on purpose: a hook that speaks on every stop is a hook people turn off, and the
+ * question it exists to raise is "did anything get proved at all". Every answer that is not a yes is
+ * counted by name — an `unknown` is never folded into anything, because that fold is the false green.
+ */
+export declare function gapHookLine(gap: GapSummary): string | undefined;
+/** The whole gap: held of claimed first, then each kind of not-held with who can act on it. */
+export declare function gapReportLines(gap: GapSummary): string[];

package/dist/judgement/runs/artifact/gap-report.js

@@ -0,0 +1,46 @@
+const HOOK_PREFIX = 'Reticle: not verified.';
+const NO_CLAIM_HOOK = `${HOOK_PREFIX} No claim was checked this session`;
+const NO_CLAIM_REPORT = 'no claims this session, so nothing was verified';
+const plural = (n, word) => `${String(n)} ${word}${1 === n ? '' : 's'}`;
+/**
+ * One line when the agent finishes without a single `yes`, and nothing otherwise.
+ *
+ * Silent after a `yes` on purpose: a hook that speaks on every stop is a hook people turn off, and the
+ * question it exists to raise is "did anything get proved at all". Every answer that is not a yes is
+ * counted by name — an `unknown` is never folded into anything, because that fold is the false green.
+ */
+export function gapHookLine(gap) {
+    if (0 < gap.held)
+        return undefined;
+    if (0 === gap.claims)
+        return NO_CLAIM_HOOK;
+    const parts = [
+        0 < gap.failed ? `${String(gap.failed)} failed` : undefined,
+        0 < gap.undecided ? `${String(gap.undecided)} unknown` : undefined,
+        0 < gap.nothingToProve ? `${String(gap.nothingToProve)} proved nothing` : undefined,
+    ].filter((part) => part !== undefined);
+    return `${HOOK_PREFIX} ${plural(gap.claims, 'claim')}: ${parts.join(', ')}`;
+}
+/** The whole gap: held of claimed first, then each kind of not-held with who can act on it. */
+export function gapReportLines(gap) {
+    if (0 === gap.claims)
+        return [NO_CLAIM_REPORT];
+    const lines = [`${String(gap.held)} of ${plural(gap.claims, 'claim')} held`];
+    if (0 < gap.failed) {
+        const caught = 0 < gap.falseGreensCaught
+            ? `, ${String(gap.falseGreensCaught)} of them a green a channel contradicted`
+            : '';
+        lines.push(`${String(gap.failed)} failed${caught}`);
+    }
+    if (0 < gap.undecided) {
+        const owners = Object.entries(gap.undecidedBy)
+            .map(([owner, n]) => `${owner}: ${String(n)}`)
+            .join(', ');
+        lines.push(`${String(gap.undecided)} unknown${'' === owners ? '' : ` (${owners})`}`);
+    }
+    if (0 < gap.nothingToProve)
+        lines.push(`${String(gap.nothingToProve)} proved nothing`);
+    for (const failure of gap.failures)
+        lines.push(`  ✗ ${failure.claim}`);
+    return lines;
+}

package/dist/judgement/runs/artifact/gap-summary.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The gap, as a number the person who ran the session can see.
+ *
+ * Reticle's whole claim is that it measures the distance between what an agent believed happened
+ * and what did. It measures that on every verdict, writes the answer into the journal, and shows it
+ * to nobody: the counts exist, the reasons exist, the contradictions exist, and no surface anywhere
+ * says "you made 14 claims, 9 held, 2 were false, 3 could not be decided, and here is who owns each
+ * of those three". The value of the product is the one thing it never reports.
+ *
+ * A FOLD over the journal, never a second store — the rule `run-context.ts` next door states, for
+ * the same reason: two ways to compute one number is worse than one way, because the day they
+ * disagree the disagreement lands inside a verdict and a user finds it before we do.
+ *
+ * Nothing here sends anything anywhere, and that is deliberate rather than incidental. This is the
+ * LOCAL half. Whether a fleet-wide version of the same number is worth collecting is a separate
+ * decision with a separate owner, and building the local one first is what makes that decision
+ * answerable from something other than a guess.
+ */
+import { VerifiedReason, VerdictAttribution, type JournalAction } from '@reticlehq/core';
+/** One claim that did not hold, in the words it was made and the engine's reason for refusing it. */
+export interface GapFailure {
+    claim: string;
+    reason?: VerifiedReason;
+}
+export interface GapSummary {
+    /** Actions that asserted something. An action that only drove the app is not a claim. */
+    claims: number;
+    held: number;
+    failed: number;
+    /** `unknown`: Reticle could not tell. Never folded into held or failed — that is the false green. */
+    undecided: number;
+    /**
+     * `no-fault`: nothing was declared, so nothing was checked.
+     *
+     * The fourth answer, kept apart from the other three. Folding it anywhere is how a session that
+     * proved nothing reads as a session that proved something.
+     */
+    nothingToProve: number;
+    /**
+     * WHO can act on each undecided verdict, counted per owner.
+     *
+     * The only part of an `unknown` a reader can do anything with: the four owners imply four
+     * different next moves — wait, fix the app, fix the harness, look again. Empty when nothing was
+     * undecided, and a verdict that recorded no reason contributes to no owner rather than to a
+     * guessed one.
+     */
+    undecidedBy: Partial<Record<VerdictAttribution, number>>;
+    /**
+     * Failures where a CHANNEL disagreed with what the app showed.
+     *
+     * Counted apart from an ordinary failure because they mean different things to the reader: an
+     * assertion that failed is a check doing its job, and a contradiction is a green that would have
+     * been believed. This number is the product's own headline, measured on the reader's own session.
+     */
+    falseGreensCaught: number;
+    failures: GapFailure[];
+}
+export declare function gapSummary(actions: readonly JournalAction[]): GapSummary;

package/dist/judgement/runs/artifact/gap-summary.js

@@ -0,0 +1,85 @@
+/**
+ * The gap, as a number the person who ran the session can see.
+ *
+ * Reticle's whole claim is that it measures the distance between what an agent believed happened
+ * and what did. It measures that on every verdict, writes the answer into the journal, and shows it
+ * to nobody: the counts exist, the reasons exist, the contradictions exist, and no surface anywhere
+ * says "you made 14 claims, 9 held, 2 were false, 3 could not be decided, and here is who owns each
+ * of those three". The value of the product is the one thing it never reports.
+ *
+ * A FOLD over the journal, never a second store — the rule `run-context.ts` next door states, for
+ * the same reason: two ways to compute one number is worse than one way, because the day they
+ * disagree the disagreement lands inside a verdict and a user finds it before we do.
+ *
+ * Nothing here sends anything anywhere, and that is deliberate rather than incidental. This is the
+ * LOCAL half. Whether a fleet-wide version of the same number is worth collecting is a separate
+ * decision with a separate owner, and building the local one first is what makes that decision
+ * answerable from something other than a guess.
+ */
+import { JournalVerdictEffectSchema, Verified, VerifiedReason, VerdictAttribution, verdictAttributionOf, } from '@reticlehq/core';
+/**
+ * The reason, as the engine's own enum, or undefined.
+ *
+ * The journal stores `reason` as a free string rather than the enum — deliberately, because the
+ * ledger has to keep reading records written by an older engine whose vocabulary it cannot know.
+ * So a reason this build does not recognise is treated exactly like an absent one: no owner. The
+ * alternative is attributing an unknown word to one of four buckets, which is inventing an
+ * attribution nobody recorded.
+ */
+function knownReason(reason) {
+    if (reason === undefined)
+        return undefined;
+    const known = Object.values(VerifiedReason);
+    return known.includes(reason) ? reason : undefined;
+}
+/** The verdict a verification tool recorded on this action, if it recorded one. */
+function verdictOf(action) {
+    const parsed = JournalVerdictEffectSchema.safeParse(action.effect);
+    return parsed.success ? parsed.data : undefined;
+}
+export function gapSummary(actions) {
+    const summary = {
+        claims: 0,
+        held: 0,
+        failed: 0,
+        undecided: 0,
+        nothingToProve: 0,
+        undecidedBy: {},
+        falseGreensCaught: 0,
+        failures: [],
+    };
+    for (const action of actions) {
+        const verdict = verdictOf(action);
+        if (verdict === undefined)
+            continue;
+        summary.claims += 1;
+        switch (verdict.verified) {
+            case Verified.YES:
+                summary.held += 1;
+                break;
+            case Verified.NO: {
+                summary.failed += 1;
+                if (VerifiedReason.CONTRADICTED === verdict.reason)
+                    summary.falseGreensCaught += 1;
+                const reason = knownReason(verdict.reason);
+                summary.failures.push(reason === undefined ? { claim: verdict.claim } : { claim: verdict.claim, reason });
+                break;
+            }
+            case Verified.UNKNOWN: {
+                summary.undecided += 1;
+                // A record written before `reason` existed has none, and must not be read as though it did:
+                // counting it under an owner would invent an attribution nobody recorded.
+                const reason = knownReason(verdict.reason);
+                const owner = reason === undefined ? undefined : verdictAttributionOf(reason);
+                if (owner !== undefined && VerdictAttribution.NONE !== owner) {
+                    summary.undecidedBy[owner] = (summary.undecidedBy[owner] ?? 0) + 1;
+                }
+                break;
+            }
+            case Verified.NO_FAULT:
+                summary.nothingToProve += 1;
+                break;
+        }
+    }
+    return summary;
+}

package/dist/judgement/runs/artifact/render-report.js

@@ -35,7 +35,10 @@ const CHECK_GLYPH = {
     [Verified.NO_FAULT]: '–',
 };
 function checkLine(c) {
-    return `  ${CHECK_GLYPH[c.status]} ${c.kind}: ${c.predicate}`;
+    // No kind, no prefix. A check folded from a journal that never recorded one has nothing to name
+    // here, and printing a placeholder would read as a kind.
+    const read = c.kind === undefined ? '' : `${c.kind}: `;
+    return `  ${CHECK_GLYPH[c.status]} ${read}${c.predicate}`;
 }
 function riskLine(r) {
     return `  ⚠ ${r.surface} (${r.severity})${r.gated ? ' [GATED]' : ''} — ${r.detail}`;

package/dist/judgement/runs/artifact/replay-mapping.d.ts

@@ -4,8 +4,8 @@
  * perspective a flow that drifted no longer behaves, so it must not read as green. The actionable
  * "why" is lifted from the replay's decision envelope (or its error) into failureReason.
  */
-import { ReplayStatus, RunFlowStatus, type FlowReplayResult, type RunFlowResult } from '@reticlehq/core';
+import { ReplayStatus, RunFlowStatus, type FlowFile, type FlowReplayResult, type RunFlowResult } from '@reticlehq/core';
 /** OK → PASS; DRIFT/ERROR → FAIL (a healed flow is produced by the heal path, not plain replay). */
 export declare function runFlowStatusOf(status: ReplayStatus): RunFlowStatus;
 /** Map one replay (plus its measured duration) into a RunFlowResult for the artifact's flows[]. */
-export declare function mapReplayToFlowResult(replay: FlowReplayResult, durationMs: number): RunFlowResult;
+export declare function mapReplayToFlowResult(replay: FlowReplayResult, durationMs: number, flow?: FlowFile): RunFlowResult;

package/dist/judgement/runs/artifact/replay-mapping.js

@@ -4,21 +4,52 @@
  * perspective a flow that drifted no longer behaves, so it must not read as green. The actionable
  * "why" is lifted from the replay's decision envelope (or its error) into failureReason.
  */
-import { ReplayStatus, RunFlowStatus, } from '@reticlehq/core';
+import { ReplayStatus, RUN_RECORDING_MAX_BYTES, RUN_STEP_RESULTS_MAX, RUN_TEXT_MAX, RunFlowStatus, } from '@reticlehq/core';
 import { SUCCESS_STEP_TOOL } from '../../../language/flows/flow-success.js';
 /** OK → PASS; DRIFT/ERROR → FAIL (a healed flow is produced by the heal path, not plain replay). */
 export function runFlowStatusOf(status) {
     return status === ReplayStatus.OK ? RunFlowStatus.PASS : RunFlowStatus.FAIL;
 }
+const clip = (text) => text.length > RUN_TEXT_MAX ? `${text.slice(0, RUN_TEXT_MAX - 1)}…` : text;
+/** One step as synced: what it did, where, and whether it held. */
+function stepResultOf(step) {
+    return {
+        step: step.step,
+        anchor: clip(step.anchor),
+        ok: step.ok,
+        ...(step.page === undefined ? {} : { page: step.page }),
+        ...(step.endPage === undefined ? {} : { endPage: step.endPage }),
+        ...(step.consequence === undefined ? {} : { consequence: clip(step.consequence) }),
+        ...(step.error === undefined ? {} : { error: clip(step.error) }),
+        ...(step.drift === undefined ? {} : { drift: step.drift.reasonKind }),
+    };
+}
+/**
+ * The flow as recorded, when it is small enough to travel — what lets a teammate replay this run
+ * from the cloud. Fill values were already redacted when the flow was saved.
+ */
+function recordingOf(flow) {
+    const recording = {
+        ...(flow.startPath === undefined ? {} : { startPath: flow.startPath }),
+        steps: flow.steps,
+    };
+    return Buffer.byteLength(JSON.stringify(recording)) > RUN_RECORDING_MAX_BYTES
+        ? { recordingOmitted: true }
+        : { recording };
+}
 /** Map one replay (plus its measured duration) into a RunFlowResult for the artifact's flows[]. */
-export function mapReplayToFlowResult(replay, durationMs) {
-    const status = runFlowStatusOf(replay.status);
-    const failureReason = status === RunFlowStatus.FAIL
-        ? (replay.decision?.whatChanged ??
-            replay.decision?.summary ??
-            replay.error?.message ??
-            'flow failed')
-        : undefined;
+export function mapReplayToFlowResult(replay, durationMs, flow) {
+    // A replay that could not start returns OK with no steps. Nothing ran, so it is SKIPPED — which
+    // every reader of a run (the verdict, the gate) already refuses to count as a pass.
+    const status = replay.unverifiable === undefined ? runFlowStatusOf(replay.status) : RunFlowStatus.SKIPPED;
+    const failureReason = replay.unverifiable !== undefined
+        ? replay.unverifiable.reason
+        : status === RunFlowStatus.FAIL
+            ? (replay.decision?.whatChanged ??
+                replay.decision?.summary ??
+                replay.error?.message ??
+                'flow failed')
+            : undefined;
     // A flow with a success oracle gets a synthetic 'success' step appended by replay; surface its label
     // as the run's `oracle` so the verdict counts this flow as consequence-backed (→ HIGH confidence),
     // not a bare smoke click. Without this, an oracle-backed pass reads as MEDIUM and undersells itself.
@@ -30,5 +61,9 @@ export function mapReplayToFlowResult(replay, durationMs) {
         durationMs,
         ...(oracle !== undefined ? { oracle } : {}),
         ...(failureReason !== undefined ? { failureReason } : {}),
+        ...(0 === replay.steps.length
+            ? {}
+            : { stepResults: replay.steps.slice(0, RUN_STEP_RESULTS_MAX).map(stepResultOf) }),
+        ...(flow === undefined ? {} : recordingOf(flow)),
     };
 }

package/dist/judgement/runs/artifact/to-artifact.d.ts

@@ -22,8 +22,13 @@ export declare const OVP_ARTIFACT_VERSION = 1;
 export interface ExportedCheck {
     /** What was claimed, as the person or agent wrote it. */
     readonly claim: string;
-    /** Which source of truth answering it required. */
-    readonly reads: PredicateKind;
+    /**
+     * Which source of truth answering it required.
+     *
+     * Absent when the run did not record one -- which is the same rule the rest of this file follows:
+     * a kind nobody wrote down is left out, never filled in with a plausible one.
+     */
+    readonly reads?: PredicateKind;
     /**
      * Was the claim written down before the action, or after it?
      *

package/dist/judgement/runs/artifact/to-artifact.js

@@ -31,7 +31,7 @@ function exportedChecks(run) {
     for (const check of run.checks) {
         decided.push({
             claim: check.predicate,
-            reads: check.kind,
+            ...(check.kind === undefined ? {} : { reads: check.kind }),
             verdict: check.status,
             // Spread, so a value the run did not record leaves the key out rather than writing a
             // comfortable default. `declaredBeforeActing: false` says the claim came afterwards; absent

package/dist/judgement/runs/context-tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import {} from '@reticlehq/core';
 import { runContextFor } from './artifact/run-context.js';
+import { gapSummary } from './artifact/gap-summary.js';
 import { openSessionIntents } from '../../memory/intent/open-intents.js';
 import { ReticleTool } from '@reticlehq/core';
 import { sessionIdShape } from '../../surface/tools/tool-kit.js';
@@ -27,9 +28,13 @@ const CONTEXT_OUTPUT_SCHEMA = {
     proven: z
         .array(z.unknown())
         .describe('Claims a verdict already settled, each `{ claim, verified, source?, doc?, epoch? }`. Read this before re-driving something: re-proving it is slow, and assuming it is a false green.'),
+    gap: z
+        .object({})
+        .passthrough()
+        .describe('The distance between what was claimed and what held, over THIS session: `{ claims, held, failed, undecided, nothingToProve, undecidedBy, falseGreensCaught, failures }`. `undecidedBy` says WHO can act on each unknown — environment (wait), code (fix the app), harness (fix Reticle or the call), could-not-see (look again). Folded from the same journal as everything else here, so it cannot disagree with it.'),
     remaining: z
         .array(z.string())
-        .describe('The intents from .reticle/intent.json that no verdict has discharged. Derived from the ledger, never a guess at what you meant to do next.'),
+        .describe('The intents from .reticle/intent/ that no verdict has discharged. Derived from the ledger, never a guess at what you meant to do next.'),
 };
 /** The ledger and the live page state this run is folded out of. `[]`/undefined when nothing is connected. */
 async function evidenceFor(deps, sessionId) {
@@ -57,14 +62,27 @@ async function evidenceFor(deps, sessionId) {
 export const CONTEXT_TOOLS = [
     {
         name: ReticleTool.CONTEXT,
-        description: 'What THIS run has already established, so you do not rediscover it. Call it when your own copy is gone: right after a compaction, at the top of a fresh sub-agent, or at the start of a turn you did not begin. Returns `established` (what Reticle OBSERVED, with the source file:line where one was reported), `proven` (claims a verdict already settled, so you neither re-prove them nor assume them) and `remaining` (the intents from .reticle/intent.json that nothing has discharged). It is a FOLD over the journal, never a second store, so it cannot disagree with the ledger. Bounded and superseding rather than accumulating, and anything observed under a replaced document or before your last source edit is already dropped rather than presented as current. Only what Reticle observed goes in: it never reports what you intended or believed.',
+        description: 'What THIS run has already established, so you do not rediscover it. Call it when your own copy is gone: right after a compaction, at the top of a fresh sub-agent, or at the start of a turn you did not begin. Returns `established` (what Reticle OBSERVED, with the source file:line where one was reported), `proven` (claims a verdict already settled, so you neither re-prove them nor assume them) and `remaining` (the intents from .reticle/intent/ that nothing has discharged). It is a FOLD over the journal, never a second store, so it cannot disagree with the ledger. Bounded and superseding rather than accumulating, and anything observed under a replaced document or before your last source edit is already dropped rather than presented as current. Only what Reticle observed goes in: it never reports what you intended or believed.',
         example: {},
         inputSchema: { ...sessionIdShape },
         outputSchema: CONTEXT_OUTPUT_SCHEMA,
         handler: async (deps, args) => {
             const sessionId = asString(args['sessionId']);
             const evidence = await evidenceFor(deps, sessionId);
-            return runContextFor({ ...evidence, intents: await openSessionIntents(deps, sessionId) });
+            const context = runContextFor({
+                ...evidence,
+                intents: await openSessionIntents(deps, sessionId),
+            });
+            /*
+             * The gap rides on `reticle_context` rather than on a tool of its own.
+             *
+             * This is the one call an agent makes when it needs to know what the run has already settled,
+             * which is exactly the moment "and what did NOT settle, and whose problem each of those is"
+             * is worth reading. It is folded from the same journal the rest of this response is folded
+             * from, so it costs one more pass over an array already in hand and cannot disagree with the
+             * `proven` list beside it.
+             */
+            return { ...context, gap: gapSummary(evidence.actions) };
         },
     },
 ];

package/dist/judgement/runs/drive-run.js

@@ -24,7 +24,7 @@
  */
 import { isValidRunId } from '../../memory/project/dir/reticle-dir.js';
 import { defaultRunId } from './runner-port.js';
-import { JournalVerdictEffectSchema, RunAgentKind, PredicateKind, RunFramework, RunProfile, RunTrigger, } from '@reticlehq/core';
+import { JournalVerdictEffectSchema, RunAgentKind, RunFramework, RunProfile, RunTrigger, } from '@reticlehq/core';
 import { withCorrections } from './late-answer.js';
 /** The author of record when no MCP peer introduced itself. Mirrors verification-sync's default. */
 const UNNAMED_AGENT = 'reticle-mcp';
@@ -77,13 +77,18 @@ export function driveRunFrom(actions, deps) {
     const checks = [];
     for (const verdict of found) {
         checks.push({
-            kind: PredicateKind.ELEMENT,
             predicate: verdict.claim,
             status: verdict.verified,
             ...(verdict.source === undefined ? {} : { evidence: { source: verdict.source } }),
             // Carried through rather than recomputed. These were established at the moment the verdict
             // was made and written down then; a run built later cannot know any of them, and inferring
             // them here would be inventing evidence about evidence.
+            //
+            // `kind` was the one field that rule was not applied to: it was stamped `element` on every
+            // check ever folded, including the ones whose `grade` in the same object said `net`. A
+            // journal old enough to have no kind now produces a check with no kind, which is the honest
+            // answer -- a missing field, rather than a wrong one nothing downstream can question.
+            ...(verdict.kind === undefined ? {} : { kind: verdict.kind }),
             ...(verdict.declaredBeforeActing === undefined
                 ? {}
                 : { declaredBeforeActing: verdict.declaredBeforeActing }),

package/dist/judgement/runs/verification-sync.d.ts

@@ -1,9 +1,11 @@
-import { type ProjectId, type FlowReplayResult } from '@reticlehq/core';
+import { type ProjectId, type FlowFile, type FlowReplayResult } from '@reticlehq/core';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 /** A replay plus the wall-clock time it took — the shape the verify handler already collects. */
 export interface TimedReplay {
     replay: FlowReplayResult;
     durationMs: number;
+    /** The flow file that was replayed, so the synced run can carry its recording. */
+    flow?: FlowFile;
 }
 /**
  * Persist the suite's run artifact and best-effort mirror it to the cloud. Never throws into the verify

package/dist/judgement/runs/verification-sync.js

@@ -23,7 +23,7 @@ import { rootForProjectId } from '../../memory/project/session-root.js';
 const RETICLE_MCP_AGENT_ID = 'reticle-mcp';
 /** Assemble the ReticleVerificationRun artifact for a verify suite (pure — no IO). */
 function assembleRun(deps, timed, projectId) {
-    const flows = timed.map((t) => mapReplayToFlowResult(t.replay, t.durationMs));
+    const flows = timed.map((t) => mapReplayToFlowResult(t.replay, t.durationMs, t.flow));
     const input = {
         runId: defaultRunId(),
         durationMs: flows.reduce((sum, f) => sum + f.durationMs, 0),

package/dist/language/flows/annotate-notes/annotate.d.ts

@@ -1,19 +1,4 @@
 import { type Annotation, type AnnotateOutcome } from '@reticlehq/core';
-/**
- * The PURE compiler at the heart of the annotation facet. A structured annotation +
- * the current captured-step count → an AnnotateOutcome (a result envelope + the patch to apply to
- * the AnnotationStore). No IO, no clock, unit-testable in isolation.
- *
- * assert-signal → step.expect.signal (+ signalData) on the LAST step (needs ≥1 step)
- * assert-visible → step.expect.element.testid on the LAST step (needs ≥1 step)
- * mark-dynamic → flow.dynamic[] += testid flow-level, allowed with 0 steps
- * success-state → flow.success = { signal | state | net | console | element | text } flow-level,
- *                 resolved in that precedence order (a consequence beats a presence check)
- *
- * FIRST CUT: only the four structured kinds above. Free natural-language annotation → predicate
- * compilation is explicitly FUTURE — an NL string never reaches here (AnnotationSchema
- * rejects it upstream; the tool maps that to UNKNOWN_KIND). No NL parser exists or is faked.
- */
 export declare function compileAnnotation(a: Annotation, stepCount: number): AnnotateOutcome;
 /**
  * Human-readable confirmation text for the recorder strip / tool result,