@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,84 @@
+/**
+ * Render an ReticleVerificationRun into a legible human/agent-facing report — the "is this actually
+ * useful?" moment. Pure + deterministic (no clock, no IO): the same run renders the same text, so it's
+ * safe in CI and as a partner-facing artifact. Raw JSON is the contract; this is the read.
+ */
+import { Verified, RunFlowStatus, VerdictStatus, } from '@reticlehq/core';
+const VERDICT_GLYPH = {
+    [VerdictStatus.PASS]: '✓ PASS',
+    [VerdictStatus.FAIL]: '✗ FAIL',
+    [VerdictStatus.PARTIAL]: '◑ PARTIAL',
+    [VerdictStatus.UNKNOWN]: '? NOTHING PROVED',
+};
+const flowGlyph = (s) => s === RunFlowStatus.PASS
+    ? '✓'
+    : s === RunFlowStatus.HEALED
+        ? '✓~'
+        : s === RunFlowStatus.SKIPPED
+            ? '–'
+            : '✗';
+function flowLine(f) {
+    const head = `  ${flowGlyph(f.status)} ${f.name} (${f.steps} steps, ${f.durationMs}ms)`;
+    return f.failureReason !== undefined ? `${head} — ${f.failureReason}` : head;
+}
+/**
+ * One glyph per verdict, and four of them.
+ *
+ * A check that could not be decided used to print `✗`, because anything that was not a pass was
+ * rendered as a failure. That told a reader the app was broken when the truth was that we could not
+ * see -- opposite next moves, one symbol.
+ */
+const CHECK_GLYPH = {
+    [Verified.YES]: '✓',
+    [Verified.NO]: '✗',
+    [Verified.UNKNOWN]: '?',
+    [Verified.NO_FAULT]: '–',
+};
+function checkLine(c) {
+    return `  ${CHECK_GLYPH[c.status]} ${c.kind}: ${c.predicate}`;
+}
+function riskLine(r) {
+    return `  ⚠ ${r.surface} (${r.severity})${r.gated ? ' [GATED]' : ''} — ${r.detail}`;
+}
+/** Render the run as a plain-text report. Sections with no content are omitted. */
+export function renderRunReport(run) {
+    const out = [];
+    out.push(`Reticle verification — ${run.project.name}  [${run.profile}]`);
+    out.push(`Verdict: ${VERDICT_GLYPH[run.verdict.status]}  ·  confidence: ${run.verdict.confidence}` +
+        (run.verdict.blockingRisks > 0 ? `  ·  ${run.verdict.blockingRisks} blocking risk(s)` : ''));
+    if (run.flows.length > 0) {
+        const passed = run.flows.filter((f) => f.status === RunFlowStatus.PASS || f.status === RunFlowStatus.HEALED).length;
+        out.push('', `Flows: ${passed}/${run.flows.length} passed`);
+        for (const f of run.flows)
+            out.push(flowLine(f));
+    }
+    // Counted, not subtracted. `total - failed` called every undetermined check a pass, which is the
+    // arithmetic version of the same false green.
+    const provedChecks = run.checks.filter((c) => c.status === Verified.YES).length;
+    if (run.checks.length > 0) {
+        out.push('', `Checks: ${provedChecks}/${run.checks.length} proved`);
+        for (const c of run.checks)
+            out.push(checkLine(c));
+    }
+    if (run.risks.length > 0) {
+        out.push('', 'Risks:');
+        for (const r of run.risks)
+            out.push(riskLine(r));
+    }
+    const packets = run.repair?.failurePackets ?? [];
+    if (packets.length > 0) {
+        out.push('', 'How to fix:');
+        for (const p of packets) {
+            const where = p.sourceLocation !== undefined
+                ? ` (${p.sourceLocation.file}${p.sourceLocation.line !== undefined ? `:${p.sourceLocation.line}` : ''})`
+                : '';
+            out.push(`  → ${p.flow ?? 'check'}${where}: ${p.suggestedPrompt}`);
+        }
+    }
+    if (run.verdict.status !== VerdictStatus.PASS && run.verdict.reasons.length > 0) {
+        out.push('', 'Why it failed:');
+        for (const reason of run.verdict.reasons)
+            out.push(`  - ${reason}`);
+    }
+    return out.join('\n');
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Pure mapping from a flow-replay outcome (the existing reticle_flow_verify machinery) into the
+ * verification-run artifact's per-flow shape. DRIFT and ERROR both collapse to FAIL — from a host's
+ * 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 { 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;
+}
+/** 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;
+    // 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.
+    const oracle = replay.steps.find((s) => s.tool === SUCCESS_STEP_TOOL)?.anchor;
+    return {
+        name: replay.name,
+        status,
+        steps: replay.steps.length,
+        durationMs,
+        ...(oracle !== undefined ? { oracle } : {}),
+        ...(failureReason !== undefined ? { failureReason } : {}),
+    };
+}

package/dist/judgement/runs/artifact/run-store.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Persistence for verification-run artifacts at .reticle/runs/<runId>.json. Mirrors ProjectStore:
+ * injected FileSystemPort, never-throws read, path-segment guard on the runId (the tool-arg attack
+ * surface). One artifact per file (unlike project.json's single rolling file) so a host can attach an
+ * individual run to a deploy. The run is already clock-stamped by buildVerificationRun, so the store
+ * needs no clock.
+ */
+import { RunReadError, type ReticleVerificationRun, type RunId } from '@reticlehq/core';
+import type { FileSystemPort } from '../../../memory/project/fs/fs-port.js';
+/** Never-throws read result (mirrors ReadProjectResult). */
+export type ReadRunResult = {
+    ok: true;
+    run: ReticleVerificationRun;
+} | {
+    ok: false;
+    reason: RunReadError;
+};
+/** Optional retention overrides (defaults to the protocol caps). Injectable so tests prune fast. */
+interface RunStoreOptions {
+    retention?: number;
+    slack?: number;
+    /**
+     * Called after a run artifact is safely on disk. Used to wake cloud sync so a finished
+     * verification reaches the dashboard promptly instead of waiting for the next timer tick.
+     *
+     * A callback rather than a dependency on the sync daemon: the store's job is durability, and a
+     * store that imported the cloud would make "write a run" fail whenever the cloud did. It is
+     * invoked AFTER the rename, so nothing can observe a run that is not yet readable, and it must
+     * never throw — see the call site.
+     */
+    onWrote?: () => void;
+}
+export declare class RunStore {
+    #private;
+    constructor(fs: FileSystemPort, root: string, opts?: RunStoreOptions);
+    /**
+     * Write one run artifact. Creates .reticle/runs/ first; byte-stable (fixed indent + trailing newline).
+     * Guards runId as a safe path segment BEFORE building the path — a runId can originate from a caller
+     * (an OEM may set it), so an unsafe value must never escape .reticle/runs/ (mirrors the read guard).
+     */
+    write(run: ReticleVerificationRun): Promise<void>;
+    /** Never throws. Invalid id / missing → MISSING; bad JSON or failed schema → MALFORMED. */
+    read(runId: RunId): Promise<ReadRunResult>;
+    /** List run ids on disk (filenames minus.json). Empty when the runs dir is absent. */
+    list(): Promise<RunId[]>;
+    /** The most-recent run by createdAt (undefined when none). Powers reticle_run_export's default. */
+    latest(): Promise<ReticleVerificationRun | undefined>;
+    /**
+     * The two most-recent runs by createdAt as `[previous, current]` (oldest-first), or undefined when
+     * fewer than two readable runs exist. Powers reticle_run_export's `format:"diff"` (run-to-run deltas).
+     */
+    latestTwo(): Promise<[ReticleVerificationRun, ReticleVerificationRun] | undefined>;
+}
+export {};

package/dist/judgement/runs/artifact/run-store.js

@@ -0,0 +1,150 @@
+/**
+ * Persistence for verification-run artifacts at .reticle/runs/<runId>.json. Mirrors ProjectStore:
+ * injected FileSystemPort, never-throws read, path-segment guard on the runId (the tool-arg attack
+ * surface). One artifact per file (unlike project.json's single rolling file) so a host can attach an
+ * individual run to a deploy. The run is already clock-stamped by buildVerificationRun, so the store
+ * needs no clock.
+ */
+import { asRunId, ReticleVerificationRunSchema, RUN_RETENTION, RUN_RETENTION_SLACK, RunReadError, } from '@reticlehq/core';
+import { reticleDirPaths, isValidRunId, runPath } from '../../../memory/project/dir/reticle-dir.js';
+const JSON_INDENT = 2;
+const JSON_EXT = '.json';
+const TMP_EXT = '.tmp';
+export class RunStore {
+    #fs;
+    #root;
+    #retention;
+    #slack;
+    #onWrote;
+    constructor(fs, root, opts = {}) {
+        this.#fs = fs;
+        this.#root = root;
+        this.#retention = opts.retention ?? RUN_RETENTION;
+        this.#slack = opts.slack ?? RUN_RETENTION_SLACK;
+        this.#onWrote = opts.onWrote;
+    }
+    /**
+     * Write one run artifact. Creates .reticle/runs/ first; byte-stable (fixed indent + trailing newline).
+     * Guards runId as a safe path segment BEFORE building the path — a runId can originate from a caller
+     * (an OEM may set it), so an unsafe value must never escape .reticle/runs/ (mirrors the read guard).
+     */
+    async write(run) {
+        if (!isValidRunId(run.runId)) {
+            throw new Error(`refusing to write run with unsafe runId: ${JSON.stringify(run.runId)}`);
+        }
+        await this.#fs.mkdir(reticleDirPaths(this.#root).runs);
+        // Atomic publish: write a temp file then rename, so a crash mid-write never leaves a half-written
+        // artifact (a partial.json would otherwise read back as MALFORMED).
+        const path = runPath(this.#root, run.runId);
+        const tmp = `${path}${TMP_EXT}`;
+        await this.#fs.writeFile(tmp, `${JSON.stringify(run, null, JSON_INDENT)}\n`);
+        await this.#fs.rename(tmp, path);
+        // AFTER the rename: a listener that reads the run back must find it there. Swallowed, because
+        // this is a notification — a sync that cannot be woken must never fail the write it followed.
+        try {
+            this.#onWrote?.();
+        }
+        catch {
+            // Not this store's problem, and not worth failing a durable write over.
+        }
+        await this.#pruneOld();
+    }
+    /**
+     * Keep .reticle/runs/ bounded. Only acts once the count exceeds RUN_RETENTION + SLACK, then deletes the
+     * oldest (by createdAt) back down to RUN_RETENTION — so the read-all is amortized, not per-write.
+     */
+    async #pruneOld() {
+        const ids = await this.list();
+        if (ids.length <= this.#retention + this.#slack)
+            return;
+        // `id: RunId`, not `string`. `list()` already returns RunId[]; annotating the local as string
+        // silently discarded the brand and handed a bare string to runPath — which is the transposition
+        // the brand exists to prevent, reintroduced by a type annotation rather than by a bad call.
+        const stamped = [];
+        for (const id of ids) {
+            const result = await this.read(id);
+            stamped.push({ id, at: result.ok ? result.run.createdAt : 0 });
+        }
+        stamped.sort((a, b) => a.at - b.at);
+        for (const { id } of stamped.slice(0, stamped.length - this.#retention)) {
+            await this.#fs.rm(runPath(this.#root, id));
+        }
+    }
+    /** Never throws. Invalid id / missing → MISSING; bad JSON or failed schema → MALFORMED. */
+    async read(runId) {
+        if (!isValidRunId(runId))
+            return { ok: false, reason: RunReadError.MISSING };
+        const path = runPath(this.#root, runId);
+        if (!(await this.#fs.exists(path)))
+            return { ok: false, reason: RunReadError.MISSING };
+        let text;
+        try {
+            text = await this.#fs.readFile(path);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: this.#fs.isNotFound(error) ? RunReadError.MISSING : RunReadError.MALFORMED,
+            };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return { ok: false, reason: RunReadError.MALFORMED };
+        }
+        const result = ReticleVerificationRunSchema.safeParse(parsed);
+        if (!result.success)
+            return { ok: false, reason: RunReadError.MALFORMED };
+        return { ok: true, run: result.data };
+    }
+    /** List run ids on disk (filenames minus.json). Empty when the runs dir is absent. */
+    async list() {
+        const dir = reticleDirPaths(this.#root).runs;
+        if (!(await this.#fs.exists(dir)))
+            return [];
+        let entries;
+        try {
+            entries = await this.#fs.readdir(dir);
+        }
+        catch {
+            return [];
+        }
+        return entries
+            .filter((e) => e.endsWith(JSON_EXT))
+            .map((e) => asRunId(e.slice(0, -JSON_EXT.length)));
+    }
+    /** The most-recent run by createdAt (undefined when none). Powers reticle_run_export's default. */
+    async latest() {
+        const ids = await this.list();
+        let best;
+        for (const id of ids) {
+            const result = await this.read(id);
+            if (result.ok && (best === undefined || result.run.createdAt > best.createdAt)) {
+                best = result.run;
+            }
+        }
+        return best;
+    }
+    /**
+     * The two most-recent runs by createdAt as `[previous, current]` (oldest-first), or undefined when
+     * fewer than two readable runs exist. Powers reticle_run_export's `format:"diff"` (run-to-run deltas).
+     */
+    async latestTwo() {
+        const runs = [];
+        for (const id of await this.list()) {
+            const result = await this.read(id);
+            if (result.ok)
+                runs.push(result.run);
+        }
+        if (runs.length < 2)
+            return undefined;
+        runs.sort((a, b) => a.createdAt - b.createdAt);
+        const previous = runs[runs.length - 2];
+        const current = runs[runs.length - 1];
+        if (previous === undefined || current === undefined)
+            return undefined;
+        return [previous, current];
+    }
+}

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

@@ -0,0 +1,119 @@
+import { type PredicateKind, type ReticleVerificationRun, type VerdictStatus, type Verified } from '@reticlehq/core';
+/**
+ * Turning what a run recorded into a document somebody outside this repository can read.
+ *
+ * The run file is ours. It is shaped for the tools that write it, it changes when they change, and
+ * it carries fields nobody else has a use for. That is exactly right for a file we produce and
+ * consume, and no basis at all for asking a stranger to depend on it.
+ *
+ * So this is one pure function and the internal shapes stay as they are. If nobody ever adopts the
+ * format, the cost of having tried is this file.
+ *
+ * The rule it follows: **never say more than the run can back up.** Anything the run did not record
+ * is left out rather than filled in, because a default is a claim, and a claim nobody checked is the
+ * precise thing this whole system exists to stop producing. An empty string where a commit should be
+ * is not "no commit" to a reader -- it is a commit whose name is empty.
+ */
+/** What this document is, said in the document, so a reader never has to guess from its shape. */
+export declare const OVP_ARTIFACT_KIND = "ovp.verification";
+/** The version of the specification this document follows. See open-verification/SPEC.md. */
+export declare const OVP_ARTIFACT_VERSION = 1;
+/** One thing that was claimed, and what checking it came out as. */
+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;
+    /**
+     * Was the claim written down before the action, or after it?
+     *
+     * The difference between a check and a rationalisation, and the first of the four things that
+     * make this document something other than an ordinary test report.
+     */
+    readonly declaredBeforeActing?: boolean;
+    /**
+     * What kind of evidence bought the answer.
+     *
+     * A green has a price. Flattening a presence check and a network observation into one word lets
+     * the cheap evidence pass for the dear evidence.
+     */
+    readonly grade?: string;
+    /**
+     * What could not be seen while this was being checked.
+     *
+     * The property with no prior art anywhere: every other test report is silent about its own blind
+     * spots. An empty list says nothing was hidden. Absent says nobody looked.
+     */
+    readonly couldNotSee?: readonly string[];
+    /**
+     * What it came out as: `yes`, `no`, `unknown` or `no-fault`.
+     *
+     * This was a boolean, on the reasoning that a check is one observation and the four-valued
+     * verdict belongs to the run. That reasoning was wrong in the way this project exists to catch:
+     * a boolean has no way to say "I could not tell", so checks that said it were dropped on the way
+     * out, and the document a stranger reads was silent about our own blind spots while listing the
+     * app's. The specification says a verdict is one of four things; this is that verdict.
+     */
+    readonly verdict: Verified;
+    /** This check's own name, so a later document can cite it. */
+    readonly checkId?: string;
+    /**
+     * The earlier check this one corrects, as `<runId>#<checkId>`.
+     *
+     * The protocol's revision, reaching a reader at last. Present only on a correction, and the
+     * check it names is still in this same document, exactly as it was first given.
+     */
+    readonly supersedes?: string;
+}
+/** What was verified, and about what. */
+export interface ExportedArtifact {
+    readonly kind: typeof OVP_ARTIFACT_KIND;
+    readonly specVersion: typeof OVP_ARTIFACT_VERSION;
+    /** Which run this came from, so an export can be traced to what produced it. */
+    readonly runId: string;
+    /** What was being verified. */
+    readonly subject: {
+        readonly name: string;
+        readonly commit?: string;
+        readonly url?: string;
+    };
+    /** How long the run took, in milliseconds. Included because a verdict without one is a claim
+     * about an unbounded stretch of time, and the specification says a verdict is about a window. */
+    readonly durationMs: number;
+    /**
+     * Which round of source edits this evidence belongs to.
+     *
+     * Evidence gathered before the change under test is true about the old code. Nothing else in this
+     * document catches that, and nothing else in the industry records it.
+     */
+    readonly editEpoch?: number;
+    readonly checks: readonly ExportedCheck[];
+    /**
+     * The run's own summary over its checks.
+     *
+     * A different question from a check's verdict and so a different vocabulary, deliberately:
+     * `partial` says some held and some did not, which is not something a single claim can be.
+     */
+    readonly summary: {
+        readonly status: VerdictStatus;
+        /** Why, in the words the run recorded. Never re-worded here. */
+        readonly because: readonly string[];
+        /** Which check this is about, when it is about one, so a later document can correct it. */
+        readonly checkId?: string;
+        /**
+         * The earlier verdict this replaces, written `<runId>#<checkId>`.
+         *
+         * Present only on a correction, and the document it names is not withdrawn. Both stand, so
+         * "we always knew" stops being expressible.
+         */
+        readonly supersedes?: string;
+    };
+}
+/**
+ * Export a run.
+ *
+ * Pure: the same run in, the same document out, every time. No clock is read -- stamping "exported
+ * at" would make two exports of one run differ, and a document that changes when nothing changed is
+ * not evidence of anything.
+ */
+export declare function toArtifact(run: ReticleVerificationRun): ExportedArtifact;

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

@@ -0,0 +1,83 @@
+import {} from '@reticlehq/core';
+/**
+ * Turning what a run recorded into a document somebody outside this repository can read.
+ *
+ * The run file is ours. It is shaped for the tools that write it, it changes when they change, and
+ * it carries fields nobody else has a use for. That is exactly right for a file we produce and
+ * consume, and no basis at all for asking a stranger to depend on it.
+ *
+ * So this is one pure function and the internal shapes stay as they are. If nobody ever adopts the
+ * format, the cost of having tried is this file.
+ *
+ * The rule it follows: **never say more than the run can back up.** Anything the run did not record
+ * is left out rather than filled in, because a default is a claim, and a claim nobody checked is the
+ * precise thing this whole system exists to stop producing. An empty string where a commit should be
+ * is not "no commit" to a reader -- it is a commit whose name is empty.
+ */
+/** What this document is, said in the document, so a reader never has to guess from its shape. */
+export const OVP_ARTIFACT_KIND = 'ovp.verification';
+/** The version of the specification this document follows. See open-verification/SPEC.md. */
+export const OVP_ARTIFACT_VERSION = 1;
+/**
+ * Every check, including the ones nothing could decide.
+ *
+ * This used to drop those, because the exported outcome was a boolean and neither `true` nor
+ * `false` is true of them. Dropping was the least-wrong option available and it was still wrong:
+ * a reader comparing the document to their session found verdicts simply absent, and a reader who
+ * did not compare read a shorter, cleaner list than the evidence supports.
+ */
+function exportedChecks(run) {
+    const decided = [];
+    for (const check of run.checks) {
+        decided.push({
+            claim: check.predicate,
+            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
+            // says nobody recorded which, and a reader must be able to tell those apart.
+            ...(check.declaredBeforeActing === undefined
+                ? {}
+                : { declaredBeforeActing: check.declaredBeforeActing }),
+            ...(check.grade === undefined ? {} : { grade: check.grade }),
+            ...(check.couldNotSee === undefined ? {} : { couldNotSee: check.couldNotSee }),
+            // A correction, when this check is one. The check it names is not withdrawn: both reach
+            // the reader, so "we always knew" stays unsayable.
+            ...(check.checkId === undefined ? {} : { checkId: check.checkId }),
+            ...(check.supersedes === undefined ? {} : { supersedes: check.supersedes }),
+        });
+    }
+    return decided;
+}
+/**
+ * Export a run.
+ *
+ * Pure: the same run in, the same document out, every time. No clock is read -- stamping "exported
+ * at" would make two exports of one run differ, and a document that changes when nothing changed is
+ * not evidence of anything.
+ */
+export function toArtifact(run) {
+    return {
+        kind: OVP_ARTIFACT_KIND,
+        specVersion: OVP_ARTIFACT_VERSION,
+        runId: run.runId,
+        subject: {
+            name: run.project.name,
+            // Spread rather than assigned, so an absent value leaves the key out entirely instead of
+            // writing `undefined` into it. See the rule at the top of this file.
+            ...(run.project.commit === undefined ? {} : { commit: run.project.commit }),
+            ...(run.project.previewUrl === undefined ? {} : { url: run.project.previewUrl }),
+        },
+        durationMs: run.durationMs,
+        ...(run.editEpoch === undefined ? {} : { editEpoch: run.editEpoch }),
+        checks: exportedChecks(run),
+        summary: {
+            status: run.verdict.status,
+            because: run.verdict.reasons,
+            // Spread, per the rule at the top: a correction that is not one must not carry an empty
+            // pointer, which a reader would take for a citation nothing resolves.
+            ...(run.verdict.checkId === undefined ? {} : { checkId: run.verdict.checkId }),
+            ...(run.verdict.supersedes === undefined ? {} : { supersedes: run.verdict.supersedes }),
+        },
+    };
+}

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

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

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

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import {} from '@reticlehq/core';
+import { runContextFor } from './artifact/run-context.js';
+import { openSessionIntents } from '../../memory/intent/open-intents.js';
+import { ReticleTool } from '@reticlehq/core';
+import { sessionIdShape } from '../../surface/tools/tool-kit.js';
+import { asString } from '@reticlehq/core';
+/**
+ * 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.
+ *
+ * PULLED, not pushed onto every session-bound tool response: only the agent knows when its context
+ * is gone, so it asks once at that moment and pays once.
+ */
+/** 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/judgement/runs/default-run-id.d.ts

@@ -0,0 +1,8 @@
+import { type RunId } from '@reticlehq/core';
+/**
+ * The default run-id generator — a branded uuid.
+ *
+ * A leaf on purpose: `verification-sync.ts` wants this one function, and reaching it through the
+ * flow-replay stack would be a cycle.
+ */
+export declare function defaultRunId(): RunId;

package/dist/judgement/runs/default-run-id.js

@@ -0,0 +1,11 @@
+import { randomUUID } from 'node:crypto';
+import { asRunId } from '@reticlehq/core';
+/**
+ * The default run-id generator — a branded uuid.
+ *
+ * A leaf on purpose: `verification-sync.ts` wants this one function, and reaching it through the
+ * flow-replay stack would be a cycle.
+ */
+export function defaultRunId() {
+    return asRunId(randomUUID());
+}