@reticlehq/server 3.6.0 → 3.7.0

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

@@ -41,24 +41,40 @@ function recordingOf(flow) {
         ? { recordingOmitted: true }
         : { recording };
 }
+/** The first contradiction a replay recorded, on a step or across them. */
+function firstContradiction(replay) {
+    for (const step of replay.steps) {
+        const found = step.contradictions?.[0];
+        if (found !== undefined)
+            return found;
+    }
+    return replay.crossStep?.[0];
+}
 /** Map one replay (plus its measured duration) into a RunFlowResult for the artifact's flows[]. */
 export function mapReplayToFlowResult(replay, durationMs, flow) {
     // A replay that could not start or complete returns UNVERIFIABLE (or carries an unverifiable caveat).
     // Nothing was verified, so it is SKIPPED — which every reader of a run (the verdict, the gate)
     // refuses to count as a pass.
-    const status = replay.status === ReplayStatus.UNVERIFIABLE || replay.unverifiable !== undefined
+    // A pass whose channels disagreed is the suite's `unverifiable`, and the run says the same: the
+    // CLI printed "unverifiable" and exited 1 while the dashboard listed the run as Passed.
+    const disagreed = replay.status === ReplayStatus.OK ? firstContradiction(replay) : undefined;
+    const status = replay.status === ReplayStatus.UNVERIFIABLE ||
+        replay.unverifiable !== undefined ||
+        disagreed !== undefined
         ? RunFlowStatus.SKIPPED
         : runFlowStatusOf(replay.status);
     const failureReason = replay.unverifiable !== undefined
         ? replay.unverifiable.reason
-        : status === RunFlowStatus.FAIL
-            ? (replay.decision?.whatChanged ??
-                replay.decision?.summary ??
-                replay.error?.message ??
-                'flow failed')
-            : status === RunFlowStatus.SKIPPED
-                ? 'flow could not be graded'
-                : undefined;
+        : disagreed !== undefined
+            ? clip(`a channel disagreed (${disagreed.kind}): ${disagreed.counter} — ${disagreed.detail}`)
+            : status === RunFlowStatus.FAIL
+                ? (replay.decision?.whatChanged ??
+                    replay.decision?.summary ??
+                    replay.error?.message ??
+                    'flow failed')
+                : status === RunFlowStatus.SKIPPED
+                    ? 'flow could not be graded'
+                    : 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.

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

@@ -5,7 +5,7 @@
  * 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 { RunReadError, type ReticleVerificationRun, type RunId, type RunScreenshot } from '@reticlehq/core';
 import type { FileSystemPort } from '../../../memory/project/fs/fs-port.js';
 /** Never-throws read result (mirrors ReadProjectResult). */
 export type ReadRunResult = {
@@ -51,4 +51,16 @@ export declare class RunStore {
      */
     latestTwo(): Promise<[ReticleVerificationRun, ReticleVerificationRun] | undefined>;
 }
+/** Remember a capture that has not landed yet, so a run written now can wait for it. */
+export declare function noteLanding(dir: string, land: Promise<void>): void;
+/** Wait for this run's screenshots still landing, so a run written now can list them. Bounded. */
+export declare function shotsLanded(root: string, runId: string): Promise<void>;
+/** Every screenshot a run has landed, in the order they were taken (by seq). Never throws. */
+export declare function readStepShots(fs: FileSystemPort, root: string, runId: string): Promise<RunScreenshot[]>;
+/**
+ * The run with its screenshots: every one in `screenshots`, each replayed step's pinned to that
+ * step (matched as `<flow>#<step>`), and each verdict's to its check. Pure. A run with none comes
+ * back unchanged.
+ */
+export declare function withScreenshots(run: ReticleVerificationRun, taken: readonly RunScreenshot[]): ReticleVerificationRun;
 export {};

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

@@ -5,14 +5,17 @@
  * 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 { asRunId, ReticleVerificationRunSchema, RUN_RETENTION, RUN_RETENTION_SLACK, RunReadError, RunScreenshotSchema, STEP_SCREENSHOT, } from '@reticlehq/core';
 import { PromptContextSchema } from '@reticlehq/core/artifacts';
-import { reticleDirPaths, isValidRunId, runPath } from '../../../memory/project/dir/reticle-dir.js';
+import { reticleDirPaths, isValidRunId, runPath, stepShotDir, } from '../../../memory/project/dir/reticle-dir.js';
+import { join } from 'node:path';
 const JSON_INDENT = 2;
 const JSON_EXT = '.json';
 const TMP_EXT = '.tmp';
 /** A request older than this is about some other task, not the run being written now. */
 const REQUEST_RELEVANT_MS = 6 * 60 * 60 * 1000;
+/** Which run a recorded request was attached to, written into the request file. */
+const REQUEST_RUN_KEY = 'answeredByRun';
 export class RunStore {
     #fs;
     #root;
@@ -37,9 +40,12 @@ export class RunStore {
             throw new Error(`refusing to write run with unsafe runId: ${JSON.stringify(run.runId)}`);
         }
         await this.#fs.mkdir(reticleDirPaths(this.#root).runs);
-        const context = run.context ?? (await this.#recentRequest(run.createdAt));
+        const context = run.context ?? (await this.#recentRequest(run.createdAt, run.runId));
         if (context !== undefined)
             run = { ...run, context };
+        // The step screenshots taken for this run, the last of which may still be landing.
+        await shotsLanded(this.#root, run.runId);
+        run = withScreenshots(run, await readStepShots(this.#fs, this.#root, run.runId));
         // 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);
@@ -60,15 +66,23 @@ export class RunStore {
      * The user's request this run answers, when the agent relayed one recently enough to be about it.
      * Read from .reticle/intent/request.json (written by `reticle_intent { declare, request }`).
      */
-    async #recentRequest(at) {
+    async #recentRequest(at, runId) {
         try {
-            const parsed = PromptContextSchema.safeParse(JSON.parse(await this.#fs.readFile(reticleDirPaths(this.#root).request)));
+            const path = reticleDirPaths(this.#root).request;
+            const raw = JSON.parse(await this.#fs.readFile(path));
+            const parsed = PromptContextSchema.safeParse(raw);
             if (!parsed.success)
                 return undefined;
             const given = parsed.data.at;
-            return given !== undefined && 0 <= at - given && at - given <= REQUEST_RELEVANT_MS
-                ? parsed.data
-                : undefined;
+            if (given === undefined || at - given < 0 || REQUEST_RELEVANT_MS < at - given)
+                return undefined;
+            // The first run written for a request answers it; a later run (the next agent session in the
+            // same tab) inherited it and showed a goal it never had. Its own rewrite keeps it.
+            const answeredBy = raw[REQUEST_RUN_KEY];
+            if ('string' === typeof answeredBy)
+                return answeredBy === runId ? parsed.data : undefined;
+            await this.#fs.writeFile(path, `${JSON.stringify({ ...raw, [REQUEST_RUN_KEY]: runId }, null, JSON_INDENT)}\n`);
+            return parsed.data;
         }
         catch {
             return undefined; // no request recorded: the common case
@@ -173,3 +187,156 @@ export class RunStore {
         return [previous, current];
     }
 }
+/*
+ * A run's step screenshots, as its artifact records them. The images are written beside the run
+ * (`.reticle/visual/runs/<runId>/`) with one record line each in `shots.jsonl` by
+ * `features/visual/step-shots.ts`; this is the reading half.
+ */
+/** How long a run write waits for screenshots still landing. A capture is never worth a stuck run. */
+const LANDING_WAIT_MS = 10_000;
+/** Captures still landing, per run directory. */
+const landing = new Map();
+/** Remember a capture that has not landed yet, so a run written now can wait for it. */
+export function noteLanding(dir, land) {
+    const pending = landing.get(dir) ?? new Set();
+    landing.set(dir, pending);
+    pending.add(land);
+    void land.finally(() => pending.delete(land));
+}
+/** Wait for this run's screenshots still landing, so a run written now can list them. Bounded. */
+export async function shotsLanded(root, runId) {
+    if (!isValidRunId(runId))
+        return;
+    const pending = landing.get(stepShotDir(root, runId));
+    if (pending === undefined || 0 === pending.size)
+        return;
+    let timer;
+    await Promise.race([
+        Promise.allSettled([...pending]),
+        new Promise((resolve) => {
+            timer = setTimeout(resolve, LANDING_WAIT_MS);
+        }),
+    ]);
+    if (timer !== undefined)
+        clearTimeout(timer);
+}
+/** One line of a run's record, read back; anything malformed is skipped. */
+function parseLine(line) {
+    try {
+        const parsed = RunScreenshotSchema.safeParse(JSON.parse(line));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every screenshot a run has landed, in the order they were taken (by seq). Never throws. */
+export async function readStepShots(fs, root, runId) {
+    if (!isValidRunId(runId))
+        return [];
+    try {
+        const text = await fs.readFile(join(stepShotDir(root, runId), STEP_SCREENSHOT.MANIFEST_FILE));
+        return (text
+            .split('\n')
+            .filter((line) => line.length > 0)
+            .map(parseLine)
+            .filter((shot) => shot !== undefined)
+            // In the order they were TAKEN: captures land in whatever order they finish.
+            .sort((a, b) => a.seq - b.seq));
+    }
+    catch {
+        return [];
+    }
+}
+/** The four facts a step records about its picture, out of the run-wide entry. */
+function stepShotOf(shot) {
+    const { file, source, width, height, sha256 } = shot;
+    return { file, source, width, height, sha256 };
+}
+/** An id that occurs once in the list; a repeated one (a reload restarts the count) pairs nothing. */
+function uniqueIds(ids) {
+    const seen = new Map();
+    for (const id of ids)
+        if (id !== undefined)
+            seen.set(id, (seen.get(id) ?? 0) + 1);
+    return new Set([...seen].filter(([, n]) => 1 === n).map(([id]) => id));
+}
+/**
+ * Pair by the journal action each was taken for, when both sides name it. A check that took no
+ * picture (a `steps` call, an answer refused as an error) then costs only its own picture, where the
+ * ordinal pairing below lost every picture in the run.
+ */
+function pairByAction(run, shots) {
+    const verdictShots = shots.filter((shot) => true === shot.verdict && shot.actionId !== undefined);
+    if (0 === verdictShots.length || run.checks.every((check) => check.actionId === undefined))
+        return undefined;
+    const okChecks = uniqueIds(run.checks.map((check) => check.actionId));
+    const okShots = uniqueIds(verdictShots.map((shot) => shot.actionId));
+    const shotOf = new Map(verdictShots.flatMap((shot) => shot.actionId !== undefined && okShots.has(shot.actionId) && okChecks.has(shot.actionId)
+        ? [[shot.actionId, shot]]
+        : []));
+    const checkIdOf = new Map();
+    const checks = run.checks.map((check) => {
+        const shot = check.actionId === undefined ? undefined : shotOf.get(check.actionId);
+        if (shot === undefined)
+            return check;
+        if (check.checkId !== undefined)
+            checkIdOf.set(shot, check.checkId);
+        return { ...check, screenshot: stepShotOf(shot) };
+    });
+    return {
+        checks,
+        shots: shots.map((shot) => {
+            const checkId = checkIdOf.get(shot);
+            return checkId === undefined ? shot : { ...shot, checkId };
+        }),
+    };
+}
+/**
+ * Pair each verdict's picture with the check it produced: the n-th verdict picture is the n-th check,
+ * because both are written in the order the verdicts were given. Only when the counts agree — a
+ * verdict this run did not fold, or one taken while the capture failed, would shift every pairing
+ * after it, and an unpaired picture is better than one shown beside the wrong check.
+ */
+function pairWithChecks(run, shots) {
+    const byAction = pairByAction(run, shots);
+    if (byAction !== undefined)
+        return byAction;
+    const verdictShots = shots.filter((shot) => true === shot.verdict);
+    if (0 === verdictShots.length ||
+        verdictShots.length !== run.checks.length ||
+        run.checks.some((check) => check.checkId === undefined))
+        return { checks: run.checks, shots: [...shots] };
+    const checkIdOf = new Map(verdictShots.map((shot, i) => [shot, run.checks[i]?.checkId]));
+    return {
+        checks: run.checks.map((check, i) => {
+            const shot = verdictShots[i];
+            return shot === undefined ? check : { ...check, screenshot: stepShotOf(shot) };
+        }),
+        shots: shots.map((shot) => {
+            const checkId = checkIdOf.get(shot);
+            return checkId === undefined ? shot : { ...shot, checkId };
+        }),
+    };
+}
+/**
+ * The run with its screenshots: every one in `screenshots`, each replayed step's pinned to that
+ * step (matched as `<flow>#<step>`), and each verdict's to its check. Pure. A run with none comes
+ * back unchanged.
+ */
+export function withScreenshots(run, taken) {
+    if (0 === taken.length)
+        return run;
+    const { checks, shots } = pairWithChecks(run, taken);
+    const byStep = new Map(shots.flatMap((shot) => (shot.step === undefined ? [] : [[shot.step, shot]])));
+    const flows = run.flows.map((flow) => flow.stepResults === undefined
+        ? flow
+        : {
+            ...flow,
+            stepResults: flow.stepResults.map((result) => {
+                const shot = byStep.get(`${flow.name}#${String(result.step)}`);
+                return shot === undefined ? result : { ...result, screenshot: stepShotOf(shot) };
+            }),
+        });
+    return { ...run, checks, flows, screenshots: shots };
+}

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

@@ -6,6 +6,8 @@ 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';
+import { resumeFromDisk, resumeLines } from './resume.js';
+import { sessionRoot } from '../../memory/project/session-root.js';
 /**
  * What this run has established, asked for by the one party that knows when it is needed.
  *
@@ -19,21 +21,30 @@ import { asString } from '@reticlehq/core';
  */
 /** What the run has established, and where each part of it came from. */
 const CONTEXT_OUTPUT_SCHEMA = {
+    resume: z
+        .string()
+        .optional()
+        .describe('Only with `compact: true`: the whole answer in under ~1k tokens — the tab and route, the request, every claim that FAILED or is NOT PROVED (by its latest verdict), what held, open intents, app notes and the rules. Read it after a compaction instead of trusting your summary.'),
     step: z
         .number()
+        .optional()
         .describe('How many actions this run has dispatched. Counted off the journal, not a counter of its own.'),
     established: z
         .array(z.unknown())
+        .optional()
         .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())
+        .optional()
         .describe('Claims a verdict already settled, each `{ claim, verified, source?, doc?, epoch? }`. Read this before re-driving something: re-proving it is slow, and assuming it is a false green.'),
     gap: z
         .object({})
         .passthrough()
+        .optional()
         .describe('The distance between what was claimed and what held, over THIS session: `{ claims, held, failed, undecided, nothingToProve, undecidedBy, falseGreensCaught, failures }`. `undecidedBy` says WHO can act on each unknown — environment (wait), code (fix the app), harness (fix Reticle or the call), could-not-see (look again). Folded from the same journal as everything else here, so it cannot disagree with it.'),
     remaining: z
         .array(z.string())
+        .optional()
         .describe('The intents from .reticle/intent/ that no verdict has discharged. Derived from the ledger, never a guess at what you meant to do next.'),
 };
 /** The ledger and the live page state this run is folded out of. `[]`/undefined when nothing is connected. */
@@ -59,16 +70,63 @@ async function evidenceFor(deps, sessionId) {
         };
     }
 }
+/** The resume block for the live session, or the newest one on disk when none is connected. */
+async function resumeFor(deps, sessionId, actions) {
+    let live;
+    try {
+        const session = deps.sessions.resolve(sessionId);
+        live = { id: session.id, url: session.url, cursor: session.elapsed() };
+    }
+    catch {
+        live = undefined;
+    }
+    let root;
+    try {
+        root = sessionRoot(deps, live?.id);
+    }
+    catch {
+        // No project can be named for this call: the live journal is all there is to fold.
+        return resumeLines({ actions, openIntents: [], notes: [] });
+    }
+    return resumeFromDisk({
+        root,
+        now: deps.now(),
+        fs: deps.fs,
+        // The live journal; with nothing connected there is no live one to fold, and the CLI's
+        // `reticle context --compact` is the reader for a session that has gone.
+        readActions: () => Promise.resolve(actions),
+        ...(live === undefined
+            ? {}
+            : { sessionId: live.id, route: routeOf(live.url), cursor: live.cursor }),
+    });
+}
+/** The path of a page URL, or the URL as given. */
+function routeOf(url) {
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        return url;
+    }
+}
 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/ 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 },
+        inputSchema: {
+            compact: z
+                .boolean()
+                .optional()
+                .describe('After a compaction: one bounded `resume` text instead of the structured fold.'),
+            ...sessionIdShape,
+        },
         outputSchema: CONTEXT_OUTPUT_SCHEMA,
         handler: async (deps, args) => {
             const sessionId = asString(args['sessionId']);
             const evidence = await evidenceFor(deps, sessionId);
+            if (true === args['compact'])
+                return { resume: (await resumeFor(deps, sessionId, evidence.actions)).join('\n') };
             const context = runContextFor({
                 ...evidence,
                 intents: await openSessionIntents(deps, sessionId),

package/dist/judgement/runs/default-run-id.d.ts

@@ -6,3 +6,6 @@ import { type RunId } from '@reticlehq/core';
  * flow-replay stack would be a cycle.
  */
 export declare function defaultRunId(): RunId;
+export declare function withShotRun<T>(runId: string, fn: () => Promise<T>): Promise<T>;
+/** The run being replayed now, or undefined outside a verify. */
+export declare function currentShotRun(): string | undefined;

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

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
 import { asRunId } from '@reticlehq/core';
 /**
@@ -9,3 +10,18 @@ import { asRunId } from '@reticlehq/core';
 export function defaultRunId() {
     return asRunId(randomUUID());
 }
+/**
+ * The run a replay's step screenshots belong to, carried across every await under it.
+ *
+ * A suite's run id used to be minted after its flows had replayed, so a screenshot taken during a
+ * step had no run to be filed under. The verify paths now mint the id first and run the replays
+ * inside it; a capture outside any of them belongs to the session's own drive run.
+ */
+const current = new AsyncLocalStorage();
+export function withShotRun(runId, fn) {
+    return current.run(runId, fn);
+}
+/** The run being replayed now, or undefined outside a verify. */
+export function currentShotRun() {
+    return current.getStore();
+}

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

@@ -22,9 +22,11 @@
  * 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 { RunFramework, type VerdictStatus, type JournalAction, type RunDisparity } from '@reticlehq/core';
 import type { VerificationRunInput } from './artifact/build-verification-run.js';
 export interface DriveRunDeps {
+    /** The project's folder name, for a tab that reported no project id. */
+    projectName?: string | undefined;
     runId: string;
     /** The project this session belonged to, for the dashboard's row. */
     projectId?: string | undefined;
@@ -38,7 +40,24 @@ export interface DriveRunDeps {
      * Absent when nobody was counting edits, which must not be reported as "the first round".
      */
     editEpoch?: number | undefined;
+    /** Where each agent session in the tab ended (`agentEndCounts`): each is folded on its own. */
+    agentEnds?: readonly number[];
+    /** What the agent claimed at each of those ends (`agentEndClaims`), by the same index. */
+    agentClaims?: readonly (VerdictStatus | undefined)[];
+    /** The agent's own claim for this run, carried beside the graded verdict. */
+    agentClaim?: VerdictStatus | undefined;
 }
+/**
+ * What a verdict required and what it saw, as the journal keeps them for its check. One place, so
+ * the act and assert paths cannot keep different halves.
+ */
+export declare function checkWords(verdict: {
+    expected?: string;
+    observed?: string;
+}): {
+    expected?: string;
+    observed?: string;
+};
 /**
  * The run id for a session's drive: stable, so the session rewrites its own row.
  *
@@ -52,6 +71,26 @@ export interface DriveRunDeps {
  * for that session rather than refusing to record it.
  */
 export declare function driveRunId(sessionId: string): string;
+/** The run the agent's session now open in this tab is kept under. */
+export declare function agentRunId(sessionId: string): string;
+/**
+ * The run the current call lands in: the flow being replayed, else the Harness drive, else the
+ * agent session open in the tab. One answer for a call's screenshot and an intent its check proves.
+ */
+export declare function runIdOfCall(sessionId: string): string;
+/** The ends recorded for a tab, as counts of the agent's own actions, for the fold. */
+export declare function agentEndCounts(sessionId: string): number[];
+/** What the agent claimed at each end of a tab, by the index `agentEndCounts` uses. */
+export declare function agentEndClaims(sessionId: string): (VerdictStatus | undefined)[];
+/**
+ * An agent session ends: its own actions since the previous end, the run they are kept under, and
+ * how long it ran. Recorded, so what the agent drives next is the next session's.
+ */
+export declare function endAgentSession(sessionId: string, actions: readonly JournalAction[], at: number | undefined, claim?: VerdictStatus): {
+    actions: JournalAction[];
+    runId: string;
+    wallMs?: number;
+};
 /**
  * Fold a session's journal into a run, or return undefined when there is nothing honest to report.
  *
@@ -67,12 +106,21 @@ export declare function harnessAgentId(driver: string): string;
  */
 export declare function harnessRunId(harness: string): string | undefined;
 /**
- * What the Harness judged of a drive's goal, noted the moment the drive finishes, before its
- * session ends and is graded. A drive whose checks held but whose goal was not reached synced as
- * "Proved" while the drive itself said it had failed. Unmet once is unmet: a later journey of the
- * same drive reaching its goal does not undo it.
+ * Hear about every Harness note. A drive is graded after its last verdict, and the run that verdict
+ * flushed never carried the grade: live, the platform filed a failed check instead of "Hard to find".
+ */
+export declare function onHarnessNoted(listener: () => void): () => void;
+/**
+ * The drive's own measure of how long it ran. The span of one tab's journal is not it: a lane in a
+ * leased browser left only the grade's assert in the tab, and its run read "Took 0 ms".
  */
+export declare function noteHarnessSpan(harness: string, ms: number): void;
 export declare function noteHarnessGoal(harness: string, met: boolean | undefined): void;
+/**
+ * Noted when a drive is graded, like its goal: its run artifact carries the comparison, so the
+ * platform can file a goal the agent proved and the Harness could not find.
+ */
+export declare function noteHarnessDisparity(harness: string, found: readonly RunDisparity[]): void;
 /**
  * Every run a session's journal holds: the connected agent's drive, and one per Harness drive.
  *