@reticlehq/server 2.11.0 → 2.12.0

package/dist/oracles/self-instrument.js

@@ -4,33 +4,39 @@
  * apply instrumentation proposals as concrete diffs, so the AGENT closes the gap and the app's
  * observability compounds run over run — instead of a human being a prerequisite. Deterministic mapping
  * from a located gap to the code to insert; pure and testable. Result-enrichment wiring is a later step.
+ *
+ * Kinds come from `@reticlehq/core`. A second enum here is how `reticle_domain` used to say
+ * `missing-signal` while honesty said `no-signal-on-mutation` for the same absence.
  */
-export const InstrumentationGapKind = {
-    MISSING_SIGNAL: 'missing-signal',
-    UNREGISTERED_STORE: 'unregistered-store',
-    MISSING_TESTID: 'missing-testid',
-};
+import { InstrumentationGapKind } from '@reticlehq/core';
 /** PascalCase a store name for a `useX.getState` hint (cart → Cart). */
 function pascal(name) {
     return 0 === name.length ? name : name[0]?.toUpperCase() + name.slice(1);
 }
 function insertFor(gap) {
     switch (gap.kind) {
-        case InstrumentationGapKind.MISSING_SIGNAL:
+        case InstrumentationGapKind.NO_SIGNAL_ON_MUTATION:
             return `reticle.signal('${gap.name}');`;
-        case InstrumentationGapKind.UNREGISTERED_STORE:
+        case InstrumentationGapKind.NO_STORE_REGISTERED:
             return `registerStore('${gap.name}', () => use${pascal(gap.name)}.getState());`;
         case InstrumentationGapKind.MISSING_TESTID:
             return `data-testid="${gap.name}"`;
     }
 }
 function rationaleFor(gap) {
-    const base = gap.kind === InstrumentationGapKind.MISSING_SIGNAL
-        ? `emit a consequence signal so verification proves the outcome, not just presence`
-        : gap.kind === InstrumentationGapKind.UNREGISTERED_STORE
-            ? `register the store so state assertions can read the source of truth`
-            : `add a stable testid so the anchor survives refactors`;
-    return gap.context === undefined ? base : `${base} — ${gap.context}`;
+    let base;
+    switch (gap.kind) {
+        case InstrumentationGapKind.NO_SIGNAL_ON_MUTATION:
+            base = `emit a consequence signal so verification proves the outcome, not just presence`;
+            break;
+        case InstrumentationGapKind.NO_STORE_REGISTERED:
+            base = `register the store so state assertions can read the source of truth`;
+            break;
+        case InstrumentationGapKind.MISSING_TESTID:
+            base = `add a stable testid so the anchor survives refactors`;
+            break;
+    }
+    return undefined === gap.context ? base : `${base} — ${gap.context}`;
 }
 /** Turn located capability gaps into ready-to-apply instrumentation proposals. Deterministic. */
 export function proposeInstrumentation(gaps) {

package/dist/pool/browser-pool.d.ts

@@ -9,7 +9,6 @@
  * The browser is injected via a `Launcher` so all lifecycle logic is testable without real Chromium;
  * the thin Playwright adapter that satisfies these interfaces lives separately.
  */
-/** The minimal page surface the pool drives. Real Playwright `Page` satisfies this. */
 export interface PooledPage {
     goto(url: string, opts?: {
         timeoutMs?: number;
@@ -17,6 +16,12 @@ export interface PooledPage {
     close(): Promise<void>;
     /** Fires when THIS page's renderer crashes — lets the pool reclaim just this lease, not the fleet. */
     onCrash(handler: () => void): void;
+    /**
+     * Fires for each console message the page logs. OPTIONAL: a fake that does not implement it makes
+     * the pool record nothing, which is the correct degradation — an absent dial address must read as
+     * "the page said nothing", never as "the page dialled correctly".
+     */
+    onConsole?(handler: (text: string) => void): void;
 }
 /** An isolated browsing context (cookies/storage). Real Playwright `BrowserContext` satisfies this. */
 export interface PooledContext {
@@ -114,6 +119,12 @@ export declare class BrowserPool {
         signal?: AbortSignal;
         sessionId?: string;
     }): Promise<Lease>;
+    /**
+     * The websocket address this lease's page reported it could not reach, if it reported one.
+     *
+     * Undefined means the page said nothing — never that it dialled the right place.
+     */
+    dialFailureUrl(sessionId: string): string | undefined;
     /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
     shutdown(): Promise<void>;
 }

package/dist/pool/browser-pool.js

@@ -9,6 +9,8 @@
  * The browser is injected via a `Launcher` so all lifecycle logic is testable without real Chromium;
  * the thin Playwright adapter that satisfies these interfaces lives separately.
  */
+/** The minimal page surface the pool drives. Real Playwright `Page` satisfies this. */
+import { unreachableUrlIn } from '@reticlehq/core';
 /** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
 export const DEFAULT_LEASE_TTL_MS = 5 * 60_000;
 /** Default cap on how long a lease's initial navigation may take before it fails (frees the slot). */
@@ -147,6 +149,7 @@ export class BrowserPool {
         await this.#waitForSlot(opts.signal);
         const sessionId = opts.sessionId ?? this.#genId();
         let context;
+        let pending;
         try {
             const browser = await this.#ensureBrowser();
             context = await browser.newContext();
@@ -156,6 +159,19 @@ export class BrowserPool {
             page.onCrash(() => {
                 void this.#release(sessionId);
             });
+            // Listen BEFORE goto: the SDK's connect attempt races the navigation's own resolution, and a
+            // listener attached afterwards misses the first failures — the only ones logged before the
+            // retry backoff stretches out.
+            page.onConsole?.((text) => {
+                const dialled = unreachableUrlIn(text);
+                if (dialled === undefined)
+                    return;
+                const active = this.#active.get(sessionId);
+                if (active !== undefined)
+                    active.dialFailureUrl = dialled;
+                else
+                    pending = dialled; // logged during goto, before the lease is registered below
+            });
             await page.goto(url, { timeoutMs: this.#navTimeout });
             // The browser can crash WHILE goto is resolving; #onCrash then clears #active and zeroes
             // #occupied. Registering the lease now would resurrect a dead entry against a crashed browser with
@@ -163,7 +179,13 @@ export class BrowserPool {
             // no longer the live browser, bail — the catch below closes the context and returns the slot.
             if (this.#browser !== browser)
                 throw new Error('browser crashed during navigation');
-            this.#active.set(sessionId, { context, page, url, touchedAt: this.#now() });
+            this.#active.set(sessionId, {
+                context,
+                page,
+                url,
+                touchedAt: this.#now(),
+                ...(pending === undefined ? {} : { dialFailureUrl: pending }),
+            });
             return {
                 sessionId,
                 url,
@@ -179,6 +201,14 @@ export class BrowserPool {
             throw err;
         }
     }
+    /**
+     * The websocket address this lease's page reported it could not reach, if it reported one.
+     *
+     * Undefined means the page said nothing — never that it dialled the right place.
+     */
+    dialFailureUrl(sessionId) {
+        return this.#active.get(sessionId)?.dialFailureUrl;
+    }
     /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
     async shutdown() {
         this.#closed = true; // set first so any woken waiter rejects instead of relaunching a browser

package/dist/pool/playwright-launcher.js

@@ -6,6 +6,7 @@
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
 import { BrowserLaunchKind } from '@reticlehq/core';
+import { chromiumLaunchOptions } from '../chromium-launch-options.js';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../telemetry/connect-failure.js';
 import { chromiumInstallCommand, bundledPlaywrightVersion } from '../cli/chromium-hint.js';
@@ -40,6 +41,7 @@ function wrapBrowser(browser) {
                         goto: (url, opts) => page.goto(url, gotoOptions(opts?.timeoutMs)),
                         close: () => page.close(),
                         onCrash: (handler) => page.on('crash', handler),
+                        onConsole: (handler) => page.on('console', (msg) => handler(msg.text())),
                     };
                 },
                 close: () => context.close(),
@@ -72,7 +74,7 @@ export function playwrightLauncher(opts = {}) {
         // number that actually costs memory and the one that explains a slow machine.
         const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.POOLED);
         try {
-            const browser = wrapBrowser(await chromium.launch({ headless }));
+            const browser = wrapBrowser(await chromium.launch(chromiumLaunchOptions(headless)));
             settle();
             return browser;
         }

package/dist/project/fs-port.d.ts

@@ -36,7 +36,10 @@ export interface FileSystemPort {
     /** Modification time in epoch ms — for recency-based retention pruning. Rejects if absent. */
     stat(path: string): Promise<{
         mtimeMs: number;
+        size: number;
     }>;
+    /** Resolve symlinks to their real path — for upload trust-boundary checks. Rejects if absent. */
+    realpath(path: string): Promise<string>;
     /** ENOENT classifier — narrows unknown without `any`, so callers can distinguish missing-file. */
     isNotFound(error: unknown): boolean;
 }

package/dist/project/fs-port.js

@@ -1,4 +1,4 @@
-import { access, appendFile, mkdir, open, readdir, readFile, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import { access, appendFile, mkdir, open, readdir, readFile, realpath, rename, rm, stat, writeFile, } from 'node:fs/promises';
 /** Production adapter — the single import site of node:fs/promises in the server. */
 export function createNodeFileSystem() {
     return {
@@ -46,8 +46,9 @@ export function createNodeFileSystem() {
         },
         stat: async (path) => {
             const s = await stat(path);
-            return { mtimeMs: s.mtimeMs };
+            return { mtimeMs: s.mtimeMs, size: s.size };
         },
+        realpath: (path) => realpath(path),
         isNotFound: (error) => 'ENOENT' === error?.code,
     };
 }

package/dist/project/memory-fs.js

@@ -78,7 +78,12 @@ export function createMemoryFs() {
             return Promise.resolve();
         },
         stat(path) {
-            return written.has(norm(path)) ? Promise.resolve({ mtimeMs: 0 }) : Promise.reject(notFound());
+            return written.has(norm(path))
+                ? Promise.resolve({ mtimeMs: 0, size: 0 })
+                : Promise.reject(notFound());
+        },
+        realpath(path) {
+            return written.has(norm(path)) ? Promise.resolve(norm(path)) : Promise.reject(notFound());
         },
         isNotFound(error) {
             return 'ENOENT' === error?.code;

package/dist/project/project-tools.js

@@ -1,9 +1,9 @@
 import { z } from 'zod';
-import { ProjectReadError, RunKind, RunStatus } from '@reticlehq/core';
+import { ProjectReadError, RunStatus } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
-import { fetchProjectRegressionFromCloud, resolveCloudConfig } from '../cloud/cloud-sync.js';
+import { cloudFetch, fetchProjectRegressionFromCloud, resolveCloudConfig, } from '../cloud/cloud-sync.js';
 import { RunStore } from '../runs/run-store.js';
 import { diffRuns as diffVerificationRuns, } from '../runs/run-diff.js';
 const REGRESSION_STATUSES = new Set([
@@ -45,7 +45,7 @@ async function cloudRegression(deps, sessionId) {
     catch {
         projectId = undefined;
     }
-    const report = await fetchProjectRegressionFromCloud(config, projectId, (url, init) => fetch(url, init));
+    const report = await fetchProjectRegressionFromCloud(config, projectId, cloudFetch);
     return report ?? undefined;
 }
 /** The two most-recent runs for `name`, oldest-first, or undefined if there are fewer than two. */
@@ -152,33 +152,4 @@ export const PROJECT_TOOLS = [
             });
         },
     },
-    {
-        name: ReticleTool.RUN_RECORD,
-        description: 'Explicitly record a run outcome into .reticle/project.json (the manual companion to the auto-record on reticle_flow_replay). Use it to log the result of an assertion sequence or a manual journey so future runs can diff against it. Returns { recorded:true, name, status }.',
-        inputSchema: {
-            name: z.string().describe('Run name for grouping in reticle_project history.'),
-            status: z.nativeEnum(RunStatus).describe('Outcome: pass | fail | drift | error'),
-            kind: z.nativeEnum(RunKind).optional(),
-            summary: z.string().optional().describe('One-line human summary of what this run covered.'),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            recorded: z.boolean(),
-            runName: z.string(),
-            status: z.string(),
-        },
-        handler: async (deps, args) => {
-            const name = asString(args['name']) ?? '';
-            const status = args['status'];
-            const kindArg = args['kind'];
-            const summary = asString(args['summary']);
-            await deps.project.recordRun({
-                kind: 'string' === typeof kindArg ? kindArg : RunKind.MANUAL,
-                name,
-                status,
-                ...(summary !== undefined ? { summary } : {}),
-            });
-            return { recorded: true, runName: name, status };
-        },
-    },
 ];

package/dist/project/reticle-dir.d.ts

@@ -15,6 +15,8 @@ export interface ReticleDirPaths {
     project: string;
     /**.../.reticle/impact.json (what Reticle has done for this user, local only) */
     impact: string;
+    /**.../.reticle/intent.json (what changes were supposed to make true — git-checked) */
+    intent: string;
     /**.../.reticle/visual (PNG baselines + diffs) */
     visual: string;
     /**.../.reticle/runs (verification-run artifacts) */

package/dist/project/reticle-dir.js

@@ -8,6 +8,7 @@ export function reticleDirPaths(root) {
         baselines: join(root, ReticleDir.BASELINES_SUBDIR),
         project: join(root, ReticleDir.PROJECT_FILE),
         impact: join(root, ReticleDir.IMPACT_FILE),
+        intent: join(root, ReticleDir.INTENT_FILE),
         visual: join(root, ReticleDir.VISUAL_SUBDIR),
         runs: join(root, ReticleDir.RUNS_SUBDIR),
         sessions: join(root, ReticleDir.SESSIONS_SUBDIR),

package/dist/runs/context-tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDef } from '../tools/tool-kit.js';
+export declare const CONTEXT_TOOLS: ToolDef[];

package/dist/runs/context-tools.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import {} from '@reticlehq/core';
+import { runContextFor } from './run-context.js';
+import { openSessionIntents } from '../intent/open-intents.js';
+import { ReticleTool } from '../tools/tool-names.js';
+import { sessionIdShape } from '../tools/tool-kit.js';
+import { asString } from '../tools/tools-helpers.js';
+/**
+ * What this run has established, asked for by the one party that knows when it is needed.
+ *
+ * Reticle holds the trajectory: the journal, the verdicts, the intent ledger. The agent holds a copy
+ * in its context window, and that copy is the one that disappears — at a compaction, at the end of a
+ * turn, at the handover to a sub-agent. Reticle's does not disappear at the same moment. So this is
+ * not a competing memory; it is the ground truth compaction destroyed, handed back on request.
+ *
+ * ## Why it is PULLED
+ *
+ * The same content was once pushed onto every session-bound tool response. It cost +136% on a
+ * verdict and was cut, because most of the time the agent still had the context and we were paying
+ * on every call to duplicate what it knew. Nobody but the agent can tell when that stops being true.
+ * So the agent asks, once, at the moment it knows its own memory is gone, and pays once.
+ *
+ * ## Why it is on the EXTENDED surface rather than the default
+ *
+ * The default surface is a hard COUNT — editors budget tools across every connected MCP server, so a
+ * slot taken here is taken from a tool that has already earned it, and nothing on that list has been
+ * demoted for this. The claim behind this tool is unmeasured, which is the same test `reticle_intent`
+ * and the `reticle_capabilities` demotion were held to, and it fails that test today.
+ *
+ * The reachability argument is also stronger here than for most of the cold tail. The caller is,
+ * by construction, an agent that has just lost its context and is re-reading the tool list it was
+ * handed this turn — so `reticle_tools` (advertised on every surface) is exactly the call it is
+ * already going to make, and this tool is one `reticle_run` hop behind it. A tool that is only useful
+ * after a discovery step, to a caller who is already performing a discovery step, is the cheapest
+ * possible thing to leave off the hot list. It moves to the default surface when a measurement says
+ * the pull happens often enough to be worth a permanent slot, and not before.
+ */
+/** What the run has established, and where each part of it came from. */
+const CONTEXT_OUTPUT_SCHEMA = {
+    step: z
+        .number()
+        .describe('How many actions this run has dispatched. Counted off the journal, not a counter of its own.'),
+    established: z
+        .array(z.unknown())
+        .describe('What Reticle OBSERVED, folded and capped, each `{ key, fact, source?, doc?, epoch? }`. `key` is the subject, so re-observing it supersedes rather than appends. Anything seen under a replaced document or a pre-edit epoch is already gone from this list.'),
+    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.'),
+    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.'),
+};
+/** The ledger and the live page state this run is folded out of. `[]`/undefined when nothing is connected. */
+async function evidenceFor(deps, sessionId) {
+    try {
+        const session = deps.sessions.resolve(sessionId);
+        return {
+            actions: await session.readJournalActions(),
+            events: await session.queryEvents({}),
+            currentDocumentId: session.currentDocumentId,
+            currentEditEpoch: session.currentEditEpoch,
+        };
+    }
+    catch {
+        // `resolve` throws when nothing is connected, when the id names no session, and when several are
+        // connected and none was named. All three mean the same thing here: there is no run to report,
+        // and an empty context is the honest answer rather than a reason to fail the call.
+        return {
+            actions: [],
+            events: [],
+            currentDocumentId: undefined,
+            currentEditEpoch: undefined,
+        };
+    }
+}
+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.',
+        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) });
+        },
+    },
+];

package/dist/runs/run-context.d.ts

@@ -0,0 +1,40 @@
+import { type EstablishedFact, type Intent, type JournalAction, type ProvenClaim, type ReticleEvent, type RunContext } from '@reticlehq/core';
+/**
+ * The SUBJECT a journal action was about: the ref it spent, else the target it resolved from.
+ *
+ * Exported so the feature-use instrument files a re-fetch under the same key this fold establishes
+ * it under. A second copy of this rule there would be a second definition of "the same subject".
+ */
+export declare function subjectOf(action: JournalAction): string | undefined;
+/**
+ * Fold the journal into candidate facts, newest last.
+ *
+ * Only the last `RUN_ESTABLISHED_CAP` actions are read: anything older cannot survive the fold, so
+ * parsing it would be work done to throw away. An action with no observed settle outcome states
+ * nothing and is skipped — "we drove it and cannot say what happened" is not an established fact,
+ * and writing it down as one is how a memory starts lying.
+ */
+export declare function establishedFromJournal(actions: readonly JournalAction[], events: readonly ReticleEvent[]): EstablishedFact[];
+/**
+ * What a verdict already settled, newest last.
+ *
+ * Both verdict tools write here. `reticle_act_and_wait` closes its attribution window with one;
+ * `reticle_assert` drives nothing, so it appends its record WITHOUT opening a window — same effect
+ * shape, so this fold reads one kind of verdict rather than two.
+ */
+export declare function provenFromJournal(actions: readonly JournalAction[], events: readonly ReticleEvent[]): ProvenClaim[];
+/**
+ * The context for one run.
+ *
+ * `step` is the journal's action count rather than a counter of its own, for the reason at the top
+ * of this file: a second counter is a second thing that can disagree with the ledger. The document
+ * and epoch are the session's own, so the staleness rule here is the same one every other verdict in
+ * this codebase is scoped by.
+ */
+export declare function runContextFor(input: {
+    actions: readonly JournalAction[];
+    events: readonly ReticleEvent[];
+    intents: readonly Intent[];
+    currentDocumentId: string | undefined;
+    currentEditEpoch: number | undefined;
+}): RunContext;

package/dist/runs/run-context.js

@@ -0,0 +1,158 @@
+import { EventType, JournalVerdictEffectSchema, RUN_ESTABLISHED_CAP, buildRunContext, } from '@reticlehq/core';
+/**
+ * The run, derived from the journal that is already there.
+ *
+ * `.reticle/sessions/<id>/` already holds an append-only causal ledger of every action dispatched
+ * and every event observed. The run is a FOLD over that, never a second store — the same argument
+ * that deleted `instrumentation_stalled` from this codebase applies without modification: 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. So nothing here writes: it reads the ledger and
+ * folds it, and if the fold is wrong the ledger is still the single authority.
+ *
+ * **One run per session, for now.** Nothing here assumes it: the fold is pure and takes its evidence
+ * as arguments, so a later multi-run or multi-agent model is a change of caller, not a rewrite. It
+ * is not built today because nobody has hit the case, and a coordination model invented ahead of its
+ * first user is a guess.
+ *
+ * Only what Reticle OBSERVED goes in. A settle outcome is an observation. A route change is an
+ * observation. A verdict a verification tool recorded is an observation. What the agent meant to do
+ * next is not, and never enters here.
+ */
+/**
+ * The one key the route is filed under.
+ *
+ * The subject of "the app is on /checkout" is the route itself, so a later route change SUPERSEDES
+ * rather than appends. Filing it per-path would accumulate every page ever visited, which is the
+ * token bomb the cap exists to prevent.
+ */
+const ROUTE_KEY = 'route';
+/** The conclusions this fold is allowed to state, as prose rather than transcript. */
+const Fact = {
+    route: (to) => `route is ${to}`,
+    settled: (verb) => `${verb} settled`,
+    unsettled: (verb) => `${verb} did not settle`,
+};
+/**
+ * The SUBJECT a journal action was about: the ref it spent, else the target it resolved from.
+ *
+ * Exported so the feature-use instrument files a re-fetch under the same key this fold establishes
+ * it under. A second copy of this rule there would be a second definition of "the same subject".
+ */
+export function subjectOf(action) {
+    const ref = action.args['ref'];
+    if ('string' === typeof ref && ref.length > 0)
+        return ref;
+    const target = action.args['target'];
+    if ('string' === typeof target && target.length > 0)
+        return target;
+    return undefined;
+}
+/** What the action did, in the caller's own vocabulary — 'click', 'fill', else the tool's name. */
+function verbOf(action) {
+    const named = action.args['action'];
+    return 'string' === typeof named && named.length > 0 ? named : action.tool;
+}
+/** 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;
+}
+/** Which document and edit epoch each action was observed under, read off its attributed events. */
+function scopeByAction(events) {
+    const out = new Map();
+    for (const event of events) {
+        if (event.actionId === undefined)
+            continue;
+        if (event.documentId === undefined && event.editEpoch === undefined)
+            continue;
+        const existing = out.get(event.actionId) ?? {};
+        out.set(event.actionId, {
+            doc: event.documentId ?? existing.doc,
+            epoch: event.editEpoch ?? existing.epoch,
+        });
+    }
+    return out;
+}
+/**
+ * Fold the journal into candidate facts, newest last.
+ *
+ * Only the last `RUN_ESTABLISHED_CAP` actions are read: anything older cannot survive the fold, so
+ * parsing it would be work done to throw away. An action with no observed settle outcome states
+ * nothing and is skipped — "we drove it and cannot say what happened" is not an established fact,
+ * and writing it down as one is how a memory starts lying.
+ */
+export function establishedFromJournal(actions, events) {
+    const scope = scopeByAction(events);
+    let route;
+    for (const event of events) {
+        if (EventType.ROUTE_CHANGE !== event.type)
+            continue;
+        const pathname = event.data['pathname'];
+        const to = 'string' === typeof pathname ? pathname : event.data['to'];
+        if ('string' !== typeof to)
+            continue;
+        route = { key: ROUTE_KEY, fact: Fact.route(to), doc: event.documentId, epoch: event.editEpoch };
+    }
+    const out = [];
+    for (const action of actions.slice(-RUN_ESTABLISHED_CAP)) {
+        const settled = action.settled;
+        if (undefined === settled)
+            continue;
+        const key = subjectOf(action);
+        if (undefined === key)
+            continue;
+        const verb = verbOf(action);
+        out.push({
+            key,
+            fact: settled ? Fact.settled(verb) : Fact.unsettled(verb),
+            // The source pointer the verdict already reported. Read off the ledger rather than looked up
+            // again: a second lookup could disagree with the one the agent was shown.
+            source: verdictOf(action)?.source,
+            ...(scope.get(action.actionId) ?? {}),
+        });
+    }
+    if (route !== undefined)
+        out.push(route);
+    return out;
+}
+/**
+ * What a verdict already settled, newest last.
+ *
+ * Both verdict tools write here. `reticle_act_and_wait` closes its attribution window with one;
+ * `reticle_assert` drives nothing, so it appends its record WITHOUT opening a window — same effect
+ * shape, so this fold reads one kind of verdict rather than two.
+ */
+export function provenFromJournal(actions, events) {
+    const scope = scopeByAction(events);
+    const out = [];
+    for (const action of actions.slice(-RUN_ESTABLISHED_CAP)) {
+        const verdict = verdictOf(action);
+        if (undefined === verdict)
+            continue;
+        out.push({
+            claim: verdict.claim,
+            verified: verdict.verified,
+            source: verdict.source,
+            ...(scope.get(action.actionId) ?? {}),
+        });
+    }
+    return out;
+}
+/**
+ * The context for one run.
+ *
+ * `step` is the journal's action count rather than a counter of its own, for the reason at the top
+ * of this file: a second counter is a second thing that can disagree with the ledger. The document
+ * and epoch are the session's own, so the staleness rule here is the same one every other verdict in
+ * this codebase is scoped by.
+ */
+export function runContextFor(input) {
+    return buildRunContext({
+        step: input.actions.length,
+        intents: input.intents,
+        established: establishedFromJournal(input.actions, input.events),
+        proven: provenFromJournal(input.actions, input.events),
+        currentDocumentId: input.currentDocumentId,
+        currentEditEpoch: input.currentEditEpoch,
+    });
+}

package/dist/runs/run-diff.d.ts

@@ -1,6 +1,6 @@
 import type { ReticleVerificationRun } from '@reticlehq/core';
 /** A per-flow change between two runs. Only flows with a meaningful change are reported. */
-export interface FlowDelta {
+interface FlowDelta {
     name: string;
     beforeMs: number;
     afterMs: number;
@@ -29,3 +29,4 @@ export interface RunDiff {
  * console diffs land once runs persist per-step detail.
  */
 export declare function diffRuns(before: ReticleVerificationRun, after: ReticleVerificationRun, noiseFloorPct?: number): RunDiff;
+export {};

package/dist/runs/verification-sync.js

@@ -14,7 +14,7 @@ import { buildVerificationRun } from './build-verification-run.js';
 import { mapReplayToFlowResult } from './replay-mapping.js';
 import { defaultRunId } from './runner-port.js';
 import { RunStore } from './run-store.js';
-import { syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { cloudFetch, syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
 import { log } from '../log.js';
 /** Assemble the ReticleVerificationRun artifact for a verify suite (pure — no IO). */
@@ -58,7 +58,7 @@ export async function persistAndSyncVerificationRun(deps, timed, projectId) {
     const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
     if (null === cloud.config || !cloud.policy.runs)
         return run.runId; // not attached / runs disabled → local only
-    const result = await syncRunToCloud(run, cloud.config, (url, init) => fetch(url, init));
+    const result = await syncRunToCloud(run, cloud.config, cloudFetch);
     if (result.outcome !== SyncOutcome.SYNCED) {
         log('cloud-run-sync-failed', { runId: run.runId, status: result.status, error: result.error });
     }

package/dist/session/dev-server-probe.d.ts

@@ -69,13 +69,5 @@ export declare function probeDevServerStates(ports?: readonly number[], probe?:
     serving: number[];
     slow: number[];
 }>;
-/**
- * The strongest state either loopback family reports.
- *
- * Serving a document beats a bare connection beats nothing, so a server bound to only one family is
- * still seen at its best — the same "either, not both" rule `anyFamilyServes` follows, extended to
- * three states.
- */
-export declare function anyFamilyState(port: number, probe?: (port: number, host: string) => Promise<PortState>): Promise<PortState>;
 /** Every candidate port serving a document, in ascending order. Never rejects. */
 export declare function probeDevServers(ports?: readonly number[], probe?: (port: number) => Promise<boolean>): Promise<number[]>;

package/dist/session/dev-server-probe.js

@@ -132,7 +132,7 @@ export async function probeDevServerStates(ports = [...DEV_SERVER_PORTS], probe
  * still seen at its best — the same "either, not both" rule `anyFamilyServes` follows, extended to
  * three states.
  */
-export async function anyFamilyState(port, probe = probeState) {
+async function anyFamilyState(port, probe = probeState) {
     const answers = await Promise.all(PROBE_HOSTS.map((host) => probe(port, host).catch(() => PortState.CLOSED)));
     if (answers.includes(PortState.SERVES_DOCUMENT))
         return PortState.SERVES_DOCUMENT;