@reticlehq/server 2.14.0 → 3.2.0

package/dist/judgement/runs/drive-run.d.ts

@@ -0,0 +1,61 @@
+/**
+ * A live drive is a verification, and until now it left no artifact.
+ *
+ * Reported from the field, and confirmed in the transcript: a session drove the app hard, many
+ * `reticle_act_and_wait` and `reticle_assert` calls, every one producing a verdict — and the
+ * dashboard stayed empty, with `lastPushAt: null` throughout. Nothing was broken. `diskSource.runs()` reads `.reticle/runs/`, and
+ * the ONLY writer of that directory was the flow-replay path, so a run artifact existed if and only
+ * if somebody had recorded a flow and replayed it. Every verdict produced by driving the app — which
+ * is the entire product experience — was local and stayed local.
+ *
+ * So this folds the session's journal into the same artifact the replay path writes, and the sync
+ * daemon that was already running picks it up with no other change.
+ *
+ * ── WHAT IT WRITES DOWN ─────────────────────────────────────────────────────────────────────────
+ * Every verdict, in the words it was given. `unknown` ("I could not tell") and `no-fault` ("nothing
+ * was declared to prove") are neither pass nor fail, and this used to drop them, because the check
+ * outcome on disk was binary and had no spelling for either. They were counted in a sentence in the
+ * trigger note instead.
+ *
+ * That was the product's own failure mode wearing our clothes. A reader of the artifact saw only
+ * the verdicts we happened to be able to spell, and "I could not see" left the document. The
+ * outcome is four-valued now, so all four are recorded, and the run verdict counts an undetermined
+ * check as neither a pass nor a failure -- which is what those words already meant everywhere else.
+ */
+import { RunFramework, type JournalAction } from '@reticlehq/core';
+import type { VerificationRunInput } from './artifact/build-verification-run.js';
+export interface DriveRunDeps {
+    runId: string;
+    /** The project this session belonged to, for the dashboard's row. */
+    projectId?: string | undefined;
+    /** The MCP client's own claim from the handshake, when it made one. */
+    agentId?: string | undefined;
+    framework?: RunFramework | undefined;
+    /**
+     * Which round of source edits this drive's evidence belongs to.
+     *
+     * Passed in rather than derived, because the session knows it and a fold over the journal cannot.
+     * Absent when nobody was counting edits, which must not be reported as "the first round".
+     */
+    editEpoch?: number | undefined;
+}
+/**
+ * The run id for a session's drive: stable, so the session rewrites its own row.
+ *
+ * Session teardown fires on every socket close, and a reconnecting tab keeps its session id and
+ * keeps appending to the same journal. A random id per teardown would therefore publish one row per
+ * reload, each a superset of the last, and the dashboard would fill with overlapping copies of one
+ * drive. Derived from the session instead, so the fold is idempotent.
+ *
+ * A session id is a free string on the wire, so the derived id is CHECKED before it becomes a path
+ * segment; anything that would not be a safe one falls back to a random id, which loses idempotence
+ * for that session rather than refusing to record it.
+ */
+export declare function driveRunId(sessionId: string): string;
+/**
+ * Fold a session's journal into a run, or return undefined when there is nothing honest to report.
+ *
+ * Pure: it takes the ledger and returns the artifact input. Reading the ledger and writing the
+ * artifact are the caller's job, which is what keeps the verdict rules testable without a disk.
+ */
+export declare function driveRunFrom(actions: readonly JournalAction[], deps: DriveRunDeps): VerificationRunInput | undefined;

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

@@ -0,0 +1,130 @@
+/**
+ * A live drive is a verification, and until now it left no artifact.
+ *
+ * Reported from the field, and confirmed in the transcript: a session drove the app hard, many
+ * `reticle_act_and_wait` and `reticle_assert` calls, every one producing a verdict — and the
+ * dashboard stayed empty, with `lastPushAt: null` throughout. Nothing was broken. `diskSource.runs()` reads `.reticle/runs/`, and
+ * the ONLY writer of that directory was the flow-replay path, so a run artifact existed if and only
+ * if somebody had recorded a flow and replayed it. Every verdict produced by driving the app — which
+ * is the entire product experience — was local and stayed local.
+ *
+ * So this folds the session's journal into the same artifact the replay path writes, and the sync
+ * daemon that was already running picks it up with no other change.
+ *
+ * ── WHAT IT WRITES DOWN ─────────────────────────────────────────────────────────────────────────
+ * Every verdict, in the words it was given. `unknown` ("I could not tell") and `no-fault` ("nothing
+ * was declared to prove") are neither pass nor fail, and this used to drop them, because the check
+ * outcome on disk was binary and had no spelling for either. They were counted in a sentence in the
+ * trigger note instead.
+ *
+ * That was the product's own failure mode wearing our clothes. A reader of the artifact saw only
+ * the verdicts we happened to be able to spell, and "I could not see" left the document. The
+ * outcome is four-valued now, so all four are recorded, and the run verdict counts an undetermined
+ * check as neither a pass nor a failure -- which is what those words already meant everywhere else.
+ */
+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 { 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';
+/** Every verdict a verification tool recorded on this session's actions, in order. */
+function verdicts(actions) {
+    const out = [];
+    for (const action of actions) {
+        const parsed = JournalVerdictEffectSchema.safeParse(action.effect);
+        if (parsed.success)
+            out.push(parsed.data);
+    }
+    return out;
+}
+/**
+ * The elapsed span the drive covered, from the journal's own clock.
+ *
+ * Journal timestamps are elapsed-ms from session start, so the last one IS the duration. Zero when
+ * nothing was recorded — never `Date.now()`, which is not this session's clock and would report the
+ * age of the process.
+ */
+function spanOf(actions) {
+    return actions.reduce((max, action) => (action.at > max ? action.at : max), 0);
+}
+/** Marks a run as the fold of a live drive rather than a flow replay, and keeps ids from colliding. */
+const DRIVE_RUN_PREFIX = 'drive-';
+/**
+ * The run id for a session's drive: stable, so the session rewrites its own row.
+ *
+ * Session teardown fires on every socket close, and a reconnecting tab keeps its session id and
+ * keeps appending to the same journal. A random id per teardown would therefore publish one row per
+ * reload, each a superset of the last, and the dashboard would fill with overlapping copies of one
+ * drive. Derived from the session instead, so the fold is idempotent.
+ *
+ * A session id is a free string on the wire, so the derived id is CHECKED before it becomes a path
+ * segment; anything that would not be a safe one falls back to a random id, which loses idempotence
+ * for that session rather than refusing to record it.
+ */
+export function driveRunId(sessionId) {
+    const candidate = `${DRIVE_RUN_PREFIX}${sessionId}`;
+    return isValidRunId(candidate) ? candidate : defaultRunId();
+}
+/**
+ * Fold a session's journal into a run, or return undefined when there is nothing honest to report.
+ *
+ * Pure: it takes the ledger and returns the artifact input. Reading the ledger and writing the
+ * artifact are the caller's job, which is what keeps the verdict rules testable without a disk.
+ */
+export function driveRunFrom(actions, deps) {
+    const found = verdicts(actions);
+    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.
+            ...(verdict.declaredBeforeActing === undefined
+                ? {}
+                : { declaredBeforeActing: verdict.declaredBeforeActing }),
+            ...(verdict.grade === undefined ? {} : { grade: verdict.grade }),
+            ...(verdict.couldNotSee === undefined ? {} : { couldNotSee: verdict.couldNotSee }),
+            // Kept so the fold below can tell a question that is still open from one that was never
+            // answerable. Both are `unknown`; only one of them can be corrected later.
+            ...(verdict.reason === undefined ? {} : { reason: verdict.reason }),
+        });
+    }
+    // A session that never verified anything has nothing to report, and saying so on a dashboard every
+    // time somebody opens an app would be noise. A session that DID verify and resolved none of it is
+    // the opposite: it is the thing they most need to see -- and those checks are now in the list
+    // rather than counted in a sentence, so the row shows what happened instead of alluding to it.
+    if (0 === checks.length)
+        return undefined;
+    // A verdict that was open because the outcome had not arrived, and a later verdict on the same
+    // claim that decided it, become a correction: the second cites the first and the first is left
+    // exactly as it was given. See late-answer.ts for what does and does not count as an answer.
+    const corrected = withCorrections(deps.runId, checks);
+    return {
+        runId: deps.runId,
+        durationMs: spanOf(actions),
+        profile: RunProfile.DEV,
+        project: {
+            name: deps.projectId ?? UNNAMED_AGENT,
+            framework: deps.framework ?? RunFramework.OTHER,
+        },
+        agent: { id: deps.agentId ?? UNNAMED_AGENT, kind: RunAgentKind.CODING_AGENT },
+        trigger: {
+            kind: RunTrigger.EDIT,
+            note: 'driven live through the Reticle tools',
+        },
+        ...(deps.editEpoch === undefined ? {} : { editEpoch: deps.editEpoch }),
+        changedFiles: [],
+        flows: [],
+        checks: corrected,
+        risks: [],
+        // Empty rather than harvested. The journal holds the events, but the evidence block is a claim
+        // about what was WRONG, and a fold that guessed at anomalies would be inventing findings — the
+        // failure this artifact is supposed to make impossible. Checks are the evidence here.
+        evidence: { consoleErrors: [], networkAnomalies: [], stateAssertions: [], timeline: [] },
+    };
+}

package/dist/judgement/runs/late-answer.d.ts

@@ -0,0 +1,55 @@
+import { Verified, type RunCheck } from '@reticlehq/core';
+/**
+ * A verdict that was open, and a later one that answers it.
+ *
+ * The specification says a verdict may be superseded when late evidence lands, and until now
+ * nothing in this codebase ever produced one. The mechanism existed in core, the fields reached
+ * the exported artifact, and no code path called any of it -- which is a rule written down and
+ * not followed, the shape this repository has already been caught in twice.
+ *
+ * ── WHAT COUNTS AS AN ANSWER, AND WHAT DOES NOT ─────────────────────────────────────────────────
+ *
+ * Only a verdict that was open BECAUSE THE OUTCOME HAD NOT ARRIVED can be answered later. That is
+ * the whole reason the journal now records a reason: `unknown` covers both "the write was
+ * accepted and has not finished" and "the capture was dirty so I could not see", and only the
+ * first is a question that waiting can settle. Superseding the second would be claiming that a
+ * later, unrelated observation resolved a blind spot -- inventing evidence about evidence.
+ *
+ * The later verdict must be about **the same claim**. Matching on anything looser -- the same
+ * action, the same window, the nearest verdict in time -- would attach an answer to a question
+ * nobody asked, and it would do it silently, because both records look perfectly well-formed.
+ *
+ * And it must actually DECIDE. A second `unknown` is not an answer; it is the same question
+ * asked again, and recording it as a correction would turn a run into a chain of verdicts that
+ * never resolves while looking like progress.
+ */
+/** The reason a verdict stays open because the truth has not arrived yet. */
+export declare const OUTCOME_PENDING = "outcome_pending";
+/** A verdict, as the fold sees it: a claim, an answer, and why. */
+export interface Answered {
+    readonly claim: string;
+    readonly verified: Verified;
+    readonly reason?: string | undefined;
+}
+/** Did this verdict leave a question open that a later observation could settle? */
+export declare function isAwaitingOutcome(verdict: Answered): boolean;
+/** Does this verdict actually decide something? A second `unknown` answers nothing. */
+export declare function decides(verdict: Answered): boolean;
+/**
+ * For each check, the index of the earlier check it corrects, if any.
+ *
+ * Returned as indices rather than as rewritten checks so the caller keeps both records. A
+ * correction never edits the verdict it replaces: both stand, and a reader can see that the
+ * first answer was given, when it changed, and why. Rewriting in place would erase the fact that
+ * the question was ever open, and "we always knew" is the shape of the problem this whole
+ * system exists to prevent.
+ *
+ * The FIRST open verdict for a claim is the one corrected. A claim asked three times -- pending,
+ * pending, then answered -- has one question and one answer, not two corrections; taking the
+ * latest would silently drop the middle record from the chain a reader follows back.
+ */
+export declare function correctionsAmong(checks: readonly Answered[]): ReadonlyMap<number, number>;
+/** The citation a correction carries, as the protocol spells it. */
+export declare function citeCheck(runId: string, index: number): string;
+/** Stamp the checks that correct an earlier one, leaving the earlier ones untouched. */
+export declare function withCorrections(runId: string, checks: readonly RunCheck[]): RunCheck[];

package/dist/judgement/runs/late-answer.js

@@ -0,0 +1,81 @@
+import { Verified } from '@reticlehq/core';
+/**
+ * A verdict that was open, and a later one that answers it.
+ *
+ * The specification says a verdict may be superseded when late evidence lands, and until now
+ * nothing in this codebase ever produced one. The mechanism existed in core, the fields reached
+ * the exported artifact, and no code path called any of it -- which is a rule written down and
+ * not followed, the shape this repository has already been caught in twice.
+ *
+ * ── WHAT COUNTS AS AN ANSWER, AND WHAT DOES NOT ─────────────────────────────────────────────────
+ *
+ * Only a verdict that was open BECAUSE THE OUTCOME HAD NOT ARRIVED can be answered later. That is
+ * the whole reason the journal now records a reason: `unknown` covers both "the write was
+ * accepted and has not finished" and "the capture was dirty so I could not see", and only the
+ * first is a question that waiting can settle. Superseding the second would be claiming that a
+ * later, unrelated observation resolved a blind spot -- inventing evidence about evidence.
+ *
+ * The later verdict must be about **the same claim**. Matching on anything looser -- the same
+ * action, the same window, the nearest verdict in time -- would attach an answer to a question
+ * nobody asked, and it would do it silently, because both records look perfectly well-formed.
+ *
+ * And it must actually DECIDE. A second `unknown` is not an answer; it is the same question
+ * asked again, and recording it as a correction would turn a run into a chain of verdicts that
+ * never resolves while looking like progress.
+ */
+/** The reason a verdict stays open because the truth has not arrived yet. */
+export const OUTCOME_PENDING = 'outcome_pending';
+/** Did this verdict leave a question open that a later observation could settle? */
+export function isAwaitingOutcome(verdict) {
+    return Verified.UNKNOWN === verdict.verified && OUTCOME_PENDING === verdict.reason;
+}
+/** Does this verdict actually decide something? A second `unknown` answers nothing. */
+export function decides(verdict) {
+    return Verified.YES === verdict.verified || Verified.NO === verdict.verified;
+}
+/**
+ * For each check, the index of the earlier check it corrects, if any.
+ *
+ * Returned as indices rather than as rewritten checks so the caller keeps both records. A
+ * correction never edits the verdict it replaces: both stand, and a reader can see that the
+ * first answer was given, when it changed, and why. Rewriting in place would erase the fact that
+ * the question was ever open, and "we always knew" is the shape of the problem this whole
+ * system exists to prevent.
+ *
+ * The FIRST open verdict for a claim is the one corrected. A claim asked three times -- pending,
+ * pending, then answered -- has one question and one answer, not two corrections; taking the
+ * latest would silently drop the middle record from the chain a reader follows back.
+ */
+export function correctionsAmong(checks) {
+    const openFor = new Map();
+    const corrections = new Map();
+    for (const [index, check] of checks.entries()) {
+        if (isAwaitingOutcome(check)) {
+            if (!openFor.has(check.claim))
+                openFor.set(check.claim, index);
+            continue;
+        }
+        if (!decides(check))
+            continue;
+        const earlier = openFor.get(check.claim);
+        if (earlier !== undefined) {
+            corrections.set(index, earlier);
+            openFor.delete(check.claim);
+        }
+    }
+    return corrections;
+}
+/** The citation a correction carries, as the protocol spells it. */
+export function citeCheck(runId, index) {
+    return `${runId}#c${String(index + 1)}`;
+}
+/** Stamp the checks that correct an earlier one, leaving the earlier ones untouched. */
+export function withCorrections(runId, checks) {
+    const corrections = correctionsAmong(checks.map((c) => ({ claim: c.predicate, verified: c.status, reason: c.reason })));
+    return checks.map((check, index) => {
+        const earlier = corrections.get(index);
+        return earlier === undefined
+            ? { ...check, checkId: `c${String(index + 1)}` }
+            : { ...check, checkId: `c${String(index + 1)}`, supersedes: citeCheck(runId, earlier) };
+    });
+}

package/dist/judgement/runs/reticle-runner.d.ts

@@ -0,0 +1,60 @@
+/**
+ * ReticleRunner — the programmatic Replay/Verify API a host platform (OEM/design partner) or CI drives
+ * from its own pipeline, with no MCP stdio and no human. It reuses the existing flow-replay machinery
+ * and the verification-run assembler, returning a stable ReticleVerificationRun.
+ *
+ * Everything it needs from the live world is injected through RunnerPort, so the core orchestration is
+ * fully testable without a CDP browser. The live adapter (wrapping ToolDeps: replayNamedFlow,
+ * flows.list, the drive/CDP preview boot) and the token-guarded HTTP endpoint are thin layers built on
+ * top of this — the orchestration and the verdict live here so the MCP path and the API produce the
+ * same artifact byte-for-byte.
+ */
+import { type FlowReplayResult, type ReticleVerificationRun, type RunId, type VerifyProgressEvent } from '@reticlehq/core';
+import { type VerificationRunInput } from './artifact/build-verification-run.js';
+import { type ChangedFileInput, type RiskPolicy } from './risk-classify.js';
+/** The live capabilities ReticleRunner needs. Injected so tests pass fakes (no CDP, no session). */
+export interface RunnerPort {
+    /** Saved flow names to verify when the caller doesn't pass an explicit subset. */
+    listFlows(): Promise<string[]>;
+    /** Replay one saved flow against the live/preview app, returning the existing replay contract. */
+    replayFlow(name: string): Promise<FlowReplayResult>;
+    /** Injected clock — the single time source (no Date.now in logic, rule 7). */
+    now(): number;
+    /** Injected run-id generator (no Math.random in logic) — the live adapter supplies a branded uuid. */
+    newRunId(): RunId;
+}
+/**
+ * Narration for a run in flight. Optional, and never load-bearing.
+ *
+ * A verification is silent for its whole duration, so anything watching from outside cannot tell a
+ * run that is working from one that has died. This is the seam that makes the difference visible.
+ * It reports what is HAPPENING; the artifact remains the only record of what was PROVED.
+ */
+export type VerifyProgressListener = (event: VerifyProgressEvent) => void;
+/** Run metadata the caller supplies; flows + verdict are produced by verify. */
+export interface VerifyOptions {
+    names?: string[];
+    project: VerificationRunInput['project'];
+    agent: VerificationRunInput['agent'];
+    trigger: VerificationRunInput['trigger'];
+    profile: VerificationRunInput['profile'];
+    /** The change set under test — classified into risk surfaces (auth/payment/db/…). */
+    changedFiles?: ChangedFileInput[];
+    /** Which touched surfaces block the verdict (require human confirmation). */
+    policy?: RiskPolicy;
+    /**
+     * Called as each flow starts and finishes. Best-effort by contract: a listener that throws is
+     * swallowed, because a REPORTER must never be able to fail the thing it is reporting on.
+     */
+    onProgress?: VerifyProgressListener;
+}
+export declare class ReticleRunner {
+    #private;
+    constructor(port: RunnerPort);
+    /**
+     * Replay the named flows (or every saved flow), map each outcome into the artifact, and assemble a
+     * verdict. Sequential by design — flows share the one live app and parallel replay would race the
+     * DOM (the same reason reticle_flow_verify is sequential).
+     */
+    verify(opts: VerifyOptions): Promise<ReticleVerificationRun>;
+}

package/dist/judgement/runs/reticle-runner.js

@@ -0,0 +1,95 @@
+/**
+ * ReticleRunner — the programmatic Replay/Verify API a host platform (OEM/design partner) or CI drives
+ * from its own pipeline, with no MCP stdio and no human. It reuses the existing flow-replay machinery
+ * and the verification-run assembler, returning a stable ReticleVerificationRun.
+ *
+ * Everything it needs from the live world is injected through RunnerPort, so the core orchestration is
+ * fully testable without a CDP browser. The live adapter (wrapping ToolDeps: replayNamedFlow,
+ * flows.list, the drive/CDP preview boot) and the token-guarded HTTP endpoint are thin layers built on
+ * top of this — the orchestration and the verdict live here so the MCP path and the API produce the
+ * same artifact byte-for-byte.
+ */
+import { reportRunTelemetry } from '../../telemetry/run-telemetry.js';
+import { boundFlowName, RunFlowStatus, VerifyPhase, } from '@reticlehq/core';
+import { buildVerificationRun, } from './artifact/build-verification-run.js';
+import { mapReplayToFlowResult } from './artifact/replay-mapping.js';
+import { buildRepairPackets } from './repair-prompt.js';
+import { buildRisks, classifyChangedFiles, } from './risk-classify.js';
+export class ReticleRunner {
+    #port;
+    constructor(port) {
+        this.#port = port;
+    }
+    /**
+     * Replay the named flows (or every saved flow), map each outcome into the artifact, and assemble a
+     * verdict. Sequential by design — flows share the one live app and parallel replay would race the
+     * DOM (the same reason reticle_flow_verify is sequential).
+     */
+    async verify(opts) {
+        const names = opts.names ?? (await this.#port.listFlows());
+        /*
+         * Emitting NEVER throws into the run. A dashboard, a log or an editor is watching, and none of
+         * them is worth failing a verification for — so a listener that blows up is dropped here rather
+         * than unwinding a suite somebody is waiting on.
+         */
+        const emit = (event) => {
+            try {
+                opts.onProgress?.(event);
+            }
+            catch {
+                /* a reporter cannot fail the thing it reports on */
+            }
+        };
+        const total = names.length;
+        // Announced BEFORE the loop: "step 3" without "of 12" does not answer the only question a
+        // person watching is actually asking, which is whether to keep waiting.
+        emit({ phase: VerifyPhase.FLOWS_FOUND, total, at: this.#port.now() });
+        const replays = [];
+        const flows = [];
+        for (const [index, name] of names.entries()) {
+            const start = this.#port.now();
+            emit({
+                phase: VerifyPhase.FLOW_STARTED,
+                index,
+                total,
+                name: boundFlowName(name),
+                at: start,
+            });
+            const replay = await this.#port.replayFlow(name);
+            replays.push(replay);
+            const mapped = mapReplayToFlowResult(replay, this.#port.now() - start);
+            flows.push(mapped);
+            emit({
+                phase: VerifyPhase.FLOW_FINISHED,
+                index,
+                total,
+                name: boundFlowName(name),
+                // A convenience for colouring a row while the run is live. The VERDICT is computed from the
+                // graded artifact below and never from this.
+                ok: mapped.status === RunFlowStatus.PASS,
+                at: this.#port.now(),
+            });
+        }
+        emit({ phase: VerifyPhase.GRADING, total, at: this.#port.now() });
+        const changedFiles = classifyChangedFiles(opts.changedFiles ?? []);
+        const risks = buildRisks(changedFiles, opts.policy);
+        const failurePackets = buildRepairPackets(replays);
+        const input = {
+            runId: this.#port.newRunId(),
+            durationMs: flows.reduce((sum, f) => sum + f.durationMs, 0),
+            profile: opts.profile,
+            project: opts.project,
+            agent: opts.agent,
+            trigger: opts.trigger,
+            changedFiles,
+            flows,
+            checks: [],
+            risks,
+            evidence: { consoleErrors: [], networkAnomalies: [], stateAssertions: [], timeline: [] },
+            ...(failurePackets.length > 0 ? { repair: { failurePackets } } : {}),
+        };
+        const run = buildVerificationRun(input, () => this.#port.now());
+        reportRunTelemetry(run);
+        return run;
+    }
+}

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

@@ -0,0 +1,17 @@
+import type { ToolDef } from '../../surface/tools/tool-kit.js';
+/**
+ * The verification-run export tool. `reticle_run_export` reads a persisted ReticleVerificationRun artifact
+ * from .reticle/runs/ — the stable verdict a host platform (OEM/design partner) or CI consumes. With a
+ * runId it returns that run; without one it returns the most recent. With format:"report" it returns a
+ * legible ✓/✗ text report instead of raw JSON. The RunStore is built inline from the injected fs +
+ * reticleRoot (it is stateless), so this needs no new ToolDeps wiring.
+ *
+ * format:"open-verification" is where the protocol leaves this tool. `toArtifact` had been built, tested
+ * and exported with no caller anywhere -- a run could be exported in Reticle's own shape and in no
+ * other, so the specification this repository publishes could be implemented by everybody except
+ * us. It surfaces HERE rather than as a new tool or a file written beside the run, because the
+ * question "give me this run in a format somebody else can read" is the one this tool already
+ * answers three ways; a fourth format is a smaller surface than a fourth tool, and a consumer who
+ * already knows `reticle_run_export` needs to learn nothing.
+ */
+export declare const RUN_TOOLS: ToolDef[];

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

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { RunReadError } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { asString } from '@reticlehq/core';
+import { sessionIdShape } from '../../surface/tools/tool-kit.js';
+import { isValidRunId } from '../../memory/project/dir/reticle-dir.js';
+import { RunStore } from './artifact/run-store.js';
+import { renderRunReport } from './artifact/render-report.js';
+import { diffRuns } from './artifact/run-diff.js';
+import { toArtifact } from './artifact/to-artifact.js';
+/**
+ * The verification-run export tool. `reticle_run_export` reads a persisted ReticleVerificationRun artifact
+ * from .reticle/runs/ — the stable verdict a host platform (OEM/design partner) or CI consumes. With a
+ * runId it returns that run; without one it returns the most recent. With format:"report" it returns a
+ * legible ✓/✗ text report instead of raw JSON. The RunStore is built inline from the injected fs +
+ * reticleRoot (it is stateless), so this needs no new ToolDeps wiring.
+ *
+ * format:"open-verification" is where the protocol leaves this tool. `toArtifact` had been built, tested
+ * and exported with no caller anywhere -- a run could be exported in Reticle's own shape and in no
+ * other, so the specification this repository publishes could be implemented by everybody except
+ * us. It surfaces HERE rather than as a new tool or a file written beside the run, because the
+ * question "give me this run in a format somebody else can read" is the one this tool already
+ * answers three ways; a fourth format is a smaller surface than a fourth tool, and a consumer who
+ * already knows `reticle_run_export` needs to learn nothing.
+ */
+export const RUN_TOOLS = [
+    {
+        name: ReticleTool.RUN_EXPORT,
+        description: 'Export a verification-run artifact (the OEM/CI-consumable verdict) from .reticle/runs/. With { runId } returns that specific run; without it returns the most recent. With { format: "report" } returns a legible ✓/✗ text summary; with { format: "diff" } returns the run-to-run delta between the two most-recent runs (per-flow duration deltas past a noise floor, status changes, new/removed flows, verdict change, headline). Returns { run } | { report } | { diff } or { error, reason } when none exists.',
+        inputSchema: {
+            runId: z
+                .string()
+                .optional()
+                .describe('The run id to export. Omit to return the most recent run.'),
+            format: z
+                .enum(['json', 'report', 'diff', 'open-verification'])
+                .optional()
+                .describe('json (default) returns the full run; report returns a legible text summary; diff returns the delta vs the previous run; open-verification returns the run as an OpenVerification (OVP) artifact a non-Reticle consumer can read.'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            run: z.unknown().optional(),
+            report: z.string().optional(),
+            diff: z.unknown().optional(),
+            artifact: z.unknown().optional(),
+            error: z.string().optional(),
+        },
+        handler: async (deps, args) => {
+            const store = new RunStore(deps.fs, sessionRoot(deps, asString(args['sessionId'])));
+            // format:"diff" is a whole-history operation (two most-recent runs), not a single-run read.
+            if ('diff' === asString(args['format'])) {
+                const pair = await store.latestTwo();
+                if (pair === undefined) {
+                    return {
+                        error: 'need at least two verification runs to diff — produce another with the verify flow',
+                        reason: RunReadError.MISSING,
+                    };
+                }
+                return { diff: diffRuns(pair[0], pair[1]) };
+            }
+            const runId = asString(args['runId']);
+            let run;
+            if (runId !== undefined) {
+                if (!isValidRunId(runId)) {
+                    return { error: `no run '${runId}' in .reticle/runs/`, reason: RunReadError.MISSING };
+                }
+                const read = await store.read(runId);
+                if (!read.ok) {
+                    return {
+                        error: read.reason === RunReadError.MISSING
+                            ? `no run '${runId}' in .reticle/runs/`
+                            : `run '${runId}' is malformed`,
+                        reason: read.reason,
+                    };
+                }
+                run = read.run;
+            }
+            else {
+                const latest = await store.latest();
+                if (latest === undefined) {
+                    return {
+                        error: 'no verification runs yet — produce one with the verify flow first',
+                        reason: RunReadError.MISSING,
+                    };
+                }
+                run = latest;
+            }
+            const format = asString(args['format']);
+            if ('report' === format)
+                return { report: renderRunReport(run) };
+            if ('open-verification' === format)
+                return { artifact: toArtifact(run) };
+            return { run };
+        },
+    },
+];

package/dist/judgement/runs/runner-port.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The live adapter: build a RunnerPort from the real ToolDeps so ReticleRunner drives actual flow
+ * replays against the connected app. Thin glue — it wires deps.flows.list, replayNamedFlow, deps.now,
+ * and a uuid generator. The ReticleRunner core (tested with a fake port) holds all the orchestration and
+ * verdict logic, so this layer carries no decisions.
+ */
+import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+import type { RunnerPort } from './reticle-runner.js';
+export { defaultRunId } from './default-run-id.js';
+/** Wire a RunnerPort to the live session. Pass sessionId to disambiguate when several tabs are open. */
+export declare function createRunnerPort(deps: ToolDeps, sessionId?: string): RunnerPort;

package/dist/judgement/runs/runner-port.js

@@ -0,0 +1,18 @@
+/**
+ * The live adapter: build a RunnerPort from the real ToolDeps so ReticleRunner drives actual flow
+ * replays against the connected app. Thin glue — it wires deps.flows.list, replayNamedFlow, deps.now,
+ * and a uuid generator. The ReticleRunner core (tested with a fake port) holds all the orchestration and
+ * verdict logic, so this layer carries no decisions.
+ */
+import { replayAndLearn } from '../../language/flows/flow-learning.js';
+import { defaultRunId } from './default-run-id.js';
+export { defaultRunId } from './default-run-id.js';
+/** Wire a RunnerPort to the live session. Pass sessionId to disambiguate when several tabs are open. */
+export function createRunnerPort(deps, sessionId) {
+    return {
+        listFlows: () => deps.flows.list(),
+        replayFlow: (name) => replayAndLearn(deps, sessionId !== undefined ? { flowName: name, sessionId } : { flowName: name }),
+        now: () => deps.now(),
+        newRunId: defaultRunId,
+    };
+}

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

@@ -0,0 +1,13 @@
+import { type ProjectId, 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;
+}
+/**
+ * Persist the suite's run artifact and best-effort mirror it to the cloud. Never throws into the verify
+ * tool — a disk or network failure is logged and swallowed so the verdict the agent asked for is
+ * unaffected. Returns the runId (for logging/tests); undefined if nothing was produced (empty suite).
+ */
+export declare function persistAndSyncVerificationRun(deps: ToolDeps, timed: TimedReplay[], projectId: ProjectId | undefined): Promise<string | undefined>;